Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions quest/m0/helpers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,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
- [Complete loop](/quest/m0/helpers/complete-loop.md) - `/quest-complete` re-scans PRs, keeps picks and holds, and counts rounds per 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

Expand Down
19 changes: 19 additions & 0 deletions quest/m0/helpers/ci-guard.md
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.
32 changes: 32 additions & 0 deletions quest/m0/helpers/claims.md
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.
25 changes: 25 additions & 0 deletions quest/m0/helpers/wait-gaps.md
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.
3 changes: 3 additions & 0 deletions quest/m0/kix/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<path>/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
Expand Down
26 changes: 26 additions & 0 deletions quest/m0/kix/epic-branches.md
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
Comment on lines +17 to +18

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the existing epic page URL

The directory form is intentional for questHref: the board route resolves /board/quest/m0/foo to quest/m0/foo/README.md, while /board/quest/m0/foo/README resolves to neither an existing .md file nor an epic README. Applying the new branch rule to this function would therefore turn epic links into 404s; restrict the /README mapping to branch creation and branch-to-quest association.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining: /README page URLs do not 404. The board route (cloudflare/src/index.tsx:315) resolves pages through findDoc in cloudflare/src/board/model.ts, which tries ${page}.md first, so quest/m0/foo/README resolves to quest/m0/foo/README.md; its doc comment lists quest/m0/epic/README as a supported form. questHref is 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)

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.
34 changes: 34 additions & 0 deletions quest/m0/kix/inbox-accuracy.md
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.
8 changes: 8 additions & 0 deletions quest/m0/kix/operator-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
31 changes: 31 additions & 0 deletions quest/m0/kix/recovery.md
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`).
Loading