Repository navigation
docs(quest): plan follow-ups from the 2026-10-21 merge wave #179
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # [XS] Run the landed-quest guard in CI | ||
|
|
||
| ## Goal | ||
|
|
||
| This repository's pull request CI fails when a PR would leave its quest | ||
| inaccurate, so merges that skip `/quest-merge` are checked too. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 as a follow-up of | ||
| [kixelated/quest#169](https://github.com/kixelated/quest/pull/169): | ||
|
|
||
| - Run `quest check --base origin/<base> --branch <head>` (README, "Check a | ||
| quest's PR") in `.github/workflows/check.yml` on pull requests, using a | ||
| trusted `quest` built from the base branch, never the head's code or | ||
| runtime config, as the merge skill requires. | ||
| - Non-quest branches already pass, so no extra filtering is needed. | ||
| - Confirm it passes on a planning PR and fails on a PR that finishes a quest | ||
| without deleting or updating it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # [S] Read claims from the upstream tree | ||
|
|
||
| ## Goal | ||
|
|
||
| `quest unblocked --unclaimed` and `quest start` agree with GitHub about which | ||
| quests are ready and claimed, even when the local checkout is behind or the | ||
| repository keeps merged branches. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 from the follow-ups of | ||
| [kixelated/quest#164](https://github.com/kixelated/quest/pull/164) and | ||
| [kixelated/quest#167](https://github.com/kixelated/quest/pull/167), and a | ||
| spawn on 2026-10-21 where two quests that had partly landed were skipped as | ||
| "held by branch ..., with no open PR": | ||
|
|
||
| - **Merged heads (user).** A branch whose tip is the head of a merged PR no | ||
| longer counts as a claim: its work landed. A closed, unmerged PR's branch | ||
| still counts, since it may hold abandoned work someone wants back. | ||
| Repositories without GitHub's "Automatically delete head branches" keep | ||
| every merged branch; kixelated/quest turned that setting on and deleted | ||
| 115 such branches the same day. | ||
| - **Upstream tree.** Check readiness against the fetched upstream default | ||
| branch's tree, not the local checkout, so a stale checkout cannot report a | ||
| finished prerequisite as open or a deleted quest as ready. The landed-quest | ||
| guard from [kixelated/quest#169](https://github.com/kixelated/quest/pull/169) | ||
| already loads a tree from a ref; reuse it. | ||
| - **Head repository.** Derive the head repository from the remote's push URL | ||
| (which may differ from its fetch URL), parsing SSH and HTTPS remote URLs | ||
| through one helper in `src/cli/github.ts`. | ||
| - Test a merged-head branch, a closed-PR branch, a checkout behind upstream, | ||
| and a remote whose push URL differs from its fetch URL. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| # [S] Never miss events in quest wait | ||
|
|
||
| ## Goal | ||
|
|
||
| Every review, comment, and check result after the wait's starting point is | ||
| reported exactly once, however long after a push the wait starts and however | ||
| close to its timeout the event lands. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 from merge agents' reports that day: | ||
|
|
||
| - A wait started without `--since` about a minute after a push timed out after | ||
| 540 s without reporting a Codex review that landed in that window | ||
| ([kixelated/quest#127](https://github.com/kixelated/quest/pull/127)). Waits | ||
| started with `--since` from before the push reported it every time. | ||
| Reproduce it, find the root cause (for example the default point resolving to | ||
| the wrong push time, or update-time filtering), and fix it. | ||
| - Check that an event landing in the last poll interval before the timeout is | ||
| either reported or left for the returned cursor, never dropped. | ||
| - A merge agent saw the resume cursor as `Q1.` while the CLI accepts only | ||
| `q1.` ([kixelated/quest#172](https://github.com/kixelated/quest/pull/172)). | ||
| Confirm whether `quest wait` ever prints it that way; if not, record it as a | ||
| display quirk and change nothing. | ||
| - Add regression tests for each confirmed cause. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # [S] Start epics on their README branch | ||
|
|
||
| ## Goal | ||
|
|
||
| kix starts, claims, and links an epic on the same branch the CLI uses: | ||
| `quest/<path>/README`, its README's path without `.md`. An epic with claimed | ||
| children starts like any other quest. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 as a follow-up of | ||
| [kixelated/quest#169](https://github.com/kixelated/quest/pull/169), which made | ||
| an epic's branch its README's path without `.md` (user decision on that PR): | ||
|
|
||
| - kix still uses the directory form. The start job in | ||
| `cloudflare/src/jobs/routes.ts` strips `/README.md`, `associatedQuest` in | ||
| `cloudflare/src/github/state.ts` maps branches back to quests, and | ||
| `questHref` in `cloudflare/src/board/model.ts` builds board links. Git | ||
| cannot create `quest/m0/foo` while any `quest/m0/foo/<child>` branch exists, | ||
| so kix cannot start an epic once a child is claimed. | ||
| - Use the CLI's rule (`questBranch` in `src/cli/claims.ts`) rather than a | ||
| second copy; if the Worker cannot import it, share the mapping from the core. | ||
| - kix has no production data, so stored directory-form branches need no | ||
| migration. | ||
| - Test starting an epic whose child is claimed, mapping `quest/<path>/README` | ||
| back to the epic, and a bare directory branch matching nothing. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # [M] Keep the inbox accurate on busy projects | ||
|
|
||
| ## Goal | ||
|
|
||
| The board and decision inbox show each quest and PR in its real state, mark | ||
| items unread only when something a maintainer would act on changed, and stay | ||
| fast on repositories with long histories. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 from the follow-ups of | ||
| [kixelated/quest#132](https://github.com/kixelated/quest/pull/132), | ||
| [kixelated/quest#157](https://github.com/kixelated/quest/pull/157), and | ||
| [kixelated/quest#163](https://github.com/kixelated/quest/pull/163): | ||
|
|
||
| - **Draft claims.** The board classifies a draft PR without a | ||
| `## Decisions needed` section as claimed work in progress, owned by its | ||
| starter, and a draft with that section as waiting on the maintainer, as the | ||
| guide defines. Today a draft without the section can show as Accepted. | ||
| - **Unknown merge state.** GitHub reports `mergeStateStatus` `UNKNOWN` while it | ||
| computes mergeability. On an already-recorded PR, treat it as not yet known: | ||
| keep the item's previous state and do not mark it unread until a definite | ||
| state arrives. A newly seen PR still surfaces as unread, since GitHub may | ||
| send no further event once the computation finishes. | ||
| - **Retention (user).** Page every activity read (`readState` in | ||
| `cloudflare/src/github/state.ts` reads every row on each `/board`, `/state`, | ||
| `/data`, and inbox view), and prune a closed entity's activity rows once it | ||
| has been closed for a fixed period. Choose the period from measured row | ||
| counts on a busy pilot repository and record it here. Rejected: paging | ||
| without pruning (unbounded storage) and dropping rows on close (the board | ||
| loses closed history). | ||
| - Extend the seeded dev server (`cloudflare/dev/seed.ts`) with a claimed | ||
| draft, a draft that hands back decisions, and an `UNKNOWN` PR, so | ||
| `test/seed.test.ts` covers each state. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # [M] Recover jobs from lost and blocked publications | ||
|
|
||
| ## Goal | ||
|
|
||
| A maintainer can always get a failed or blocked kix job moving again from | ||
| the inbox, without visiting GitHub, and without losing answers already given. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-21 from the follow-ups of | ||
| [kixelated/quest#171](https://github.com/kixelated/quest/pull/171) and | ||
| [kixelated/quest#172](https://github.com/kixelated/quest/pull/172): | ||
|
|
||
| - **Retry continuity.** A retried planning job's decision record includes | ||
| earlier jobs' answers only when they delivered the same pull request | ||
| (`store.decisions`). A failed job that pushed commits but never opened a PR | ||
| loses its answered rounds on retry. Record which job a retry continues when | ||
| the retry is created (`createJob`) and follow that chain instead. | ||
| - **Start over (user).** A blocked-branch decision ("changed outside this | ||
| job", `cloudflare/src/jobs/publish.ts`) gains a "Start over" choice: kix | ||
| resets the service-owned fork branch to the base and restarts the job. | ||
| Today answering only resumes the agent, which cannot clear the branch. The | ||
| same path clears leftover branches from completed or cancelled work. | ||
| Rejected: pausing with instructions to fix the branch on GitHub. | ||
| - **Unrecorded pull requests.** A failed job can open its pull request but | ||
| fail before recording the number. Its retry is then refused, because | ||
| `deliver` adopts only PRs created since the current job and observations | ||
| lack the PR's head repository (a Codex finding declined on | ||
| [kixelated/quest#171](https://github.com/kixelated/quest/pull/171)). Adopt that | ||
| PR on retry when it is the only open PR from the job's branch. | ||
| - Test each path with the seeded fake GitHub (`cloudflare/dev/github.ts`). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The directory form is intentional for
questHref: the board route resolves/board/quest/m0/footoquest/m0/foo/README.md, while/board/quest/m0/foo/READMEresolves to neither an existing.mdfile nor an epic README. Applying the new branch rule to this function would therefore turn epic links into 404s; restrict the/READMEmapping to branch creation and branch-to-quest association.Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Declining:
/READMEpage URLs do not 404. The board route (cloudflare/src/index.tsx:315) resolves pages throughfindDocincloudflare/src/board/model.ts, which tries${page}.mdfirst, soquest/m0/foo/READMEresolves toquest/m0/foo/README.md; its doc comment listsquest/m0/epic/READMEas a supported form.questHrefis in scope because its comment defines a page as "its path without.md, like its branch name", so it should follow the same rule as the branch.(Written by Claude Opus 5.5)