From 5134c306d0475698b6bfc3324f9716e98809ef5a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 14:14:36 -0700 Subject: [PATCH 1/2] docs(quest): plan follow-ups from the 2026-10-21 merge wave Six new quests (kix epic branches, inbox accuracy, job recovery; upstream claims, wait gaps, guard in CI) and real-device and live-read checks in operator setup. Co-Authored-By: Claude Opus 5.5 --- quest/m0/helpers/README.md | 3 +++ quest/m0/helpers/ci-guard.md | 19 +++++++++++++++++++ quest/m0/helpers/claims.md | 32 ++++++++++++++++++++++++++++++++ quest/m0/helpers/wait-gaps.md | 25 +++++++++++++++++++++++++ quest/m0/kix/README.md | 3 +++ quest/m0/kix/epic-branches.md | 26 ++++++++++++++++++++++++++ quest/m0/kix/inbox-accuracy.md | 32 ++++++++++++++++++++++++++++++++ quest/m0/kix/operator-setup.md | 8 ++++++++ quest/m0/kix/recovery.md | 31 +++++++++++++++++++++++++++++++ 9 files changed, 179 insertions(+) create mode 100644 quest/m0/helpers/ci-guard.md create mode 100644 quest/m0/helpers/claims.md create mode 100644 quest/m0/helpers/wait-gaps.md create mode 100644 quest/m0/kix/epic-branches.md create mode 100644 quest/m0/kix/inbox-accuracy.md create mode 100644 quest/m0/kix/recovery.md diff --git a/quest/m0/helpers/README.md b/quest/m0/helpers/README.md index 9bf1e552..391f3bd7 100644 --- a/quest/m0/helpers/README.md +++ b/quest/m0/helpers/README.md @@ -50,6 +50,9 @@ commands from Sep-Oct. Session counts in each child come from that window. - [PR state commands](/quest/m0/helpers/pr-states.md) - `quest iterate`, `ready`, `merge`, and `release` label the one owner of a PR - [Headless agents](/quest/m0/helpers/headless-agents.md) - `/quest-spawn api` launches, resumes, and stops billed agents through one command auto mode allows +- [Upstream claims](/quest/m0/helpers/claims.md) - claims and readiness read from the upstream tree, ignoring merged branches +- [Wait gaps](/quest/m0/helpers/wait-gaps.md) - `quest wait` reports every event after its starting point exactly once +- [Guard in CI](/quest/m0/helpers/ci-guard.md) - pull request CI runs the landed-quest guard ## Related diff --git a/quest/m0/helpers/ci-guard.md b/quest/m0/helpers/ci-guard.md new file mode 100644 index 00000000..69c7ca38 --- /dev/null +++ b/quest/m0/helpers/ci-guard.md @@ -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/ --branch ` (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. diff --git a/quest/m0/helpers/claims.md b/quest/m0/helpers/claims.md new file mode 100644 index 00000000..1920e0d3 --- /dev/null +++ b/quest/m0/helpers/claims.md @@ -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. diff --git a/quest/m0/helpers/wait-gaps.md b/quest/m0/helpers/wait-gaps.md new file mode 100644 index 00000000..ced7ad96 --- /dev/null +++ b/quest/m0/helpers/wait-gaps.md @@ -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. diff --git a/quest/m0/kix/README.md b/quest/m0/kix/README.md index 4c8ccef2..0438fedb 100644 --- a/quest/m0/kix/README.md +++ b/quest/m0/kix/README.md @@ -98,6 +98,9 @@ operator-paid-hosting decisions: - [Deploy kix.quest](/quest/m0/kix/deploy.md) - the operator registers the App and deploys the Worker with GitHub sign-in at kix.quest - [Operator setup](/quest/m0/kix/operator-setup.md) - fork namespace, pilot installations, and a verified test PR - [Per-project forks](/quest/m0/kix/forks.md) - each project publishes through its own fork, recorded by repository ID +- [Epic branches](/quest/m0/kix/epic-branches.md) - kix starts and links an epic on its `quest//README` branch +- [Inbox accuracy](/quest/m0/kix/inbox-accuracy.md) - draft claims, unknown merge states, and paged, pruned activity +- [Job recovery](/quest/m0/kix/recovery.md) - retries keep their answers, and blocked branches can start over - [Runner](/quest/m0/kix/runner.md) - `quest runner` on Linux and macOS with Nix devShells, accounts, and the Claude Code adapter - [Job sandbox](/quest/m0/kix/sandbox.md) - OS-sandboxed commands, with untrusted PR devShells built in a VM on Linux runners - [opencode adapter](/quest/m0/kix/opencode.md) - OpenCode Go, ChatGPT plans, and API-key providers through opencode diff --git a/quest/m0/kix/epic-branches.md b/quest/m0/kix/epic-branches.md new file mode 100644 index 00000000..dcb17174 --- /dev/null +++ b/quest/m0/kix/epic-branches.md @@ -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//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/` 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//README` + back to the epic, and a bare directory branch matching nothing. diff --git a/quest/m0/kix/inbox-accuracy.md b/quest/m0/kix/inbox-accuracy.md new file mode 100644 index 00000000..3e26f1f5 --- /dev/null +++ b/quest/m0/kix/inbox-accuracy.md @@ -0,0 +1,32 @@ +# [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. Treat it as not yet known: keep the item's previous + state and do not mark it unread until a definite state arrives. +- **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. diff --git a/quest/m0/kix/operator-setup.md b/quest/m0/kix/operator-setup.md index 329d9b2c..6b5f0388 100644 --- a/quest/m0/kix/operator-setup.md +++ b/quest/m0/kix/operator-setup.md @@ -20,6 +20,14 @@ and a bounded test PR verify the integration before contributors are invited. upstream commit pushed after the fork was made, GitHub's signature on the App's API commits, and an iteration pushing an upstream pull request head under branch rules. Disable Actions on the service forks. +- Install the PWA and receive a push notification on real Android, iOS, and + desktop devices (from + [kixelated/quest#165](https://github.com/kixelated/quest/pull/165), whose + tests use fakes). +- Read a deleted issue by number against a real installation, which the + background reconcile from + [kixelated/quest#170](https://github.com/kixelated/quest/pull/170) only + tests against the fake. - Rehearse on the operator's own runner and an explicitly selected operator account. - Record nonsecret setup/run instructions and deployment identifiers. diff --git a/quest/m0/kix/recovery.md b/quest/m0/kix/recovery.md new file mode 100644 index 00000000..69578e69 --- /dev/null +++ b/quest/m0/kix/recovery.md @@ -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`). From f11e84be7220db6a103e1bb90469092bdc92d31f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 14:56:26 -0700 Subject: [PATCH 2/2] docs(quest): surface new UNKNOWN PRs in inbox-accuracy Co-Authored-By: Claude Opus 5.5 --- quest/m0/kix/inbox-accuracy.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/quest/m0/kix/inbox-accuracy.md b/quest/m0/kix/inbox-accuracy.md index 3e26f1f5..f24377e3 100644 --- a/quest/m0/kix/inbox-accuracy.md +++ b/quest/m0/kix/inbox-accuracy.md @@ -18,8 +18,10 @@ Decided 2026-10-21 from the follow-ups of 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. Treat it as not yet known: keep the item's previous - state and do not mark it unread until a definite state arrives. + 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