[kixelated]

Completes quest/m0/kix/epic-branches.md (plan at d3d721c), a follow-up of kixelated/quest#169.

kix named an epic's branch and board page after its directory (quest/m0/foo). The CLI names it after its README (quest/m0/foo/README). Git can't create refs/heads/quest/m0/foo while any quest/m0/foo/<child> branch exists, so kix couldn't start an epic once one of its children was claimed. kix also didn't recognize claims and PRs on the CLI's /README branch.

Changes

• Core: questBranch(path) moves from src/cli/claims.ts into src/core/doc.ts. Beside it is its inverse, branchQuest(branch), which is the branch plus .md. Both are exported from quest/core. The CLI (main, start, move, landed) imports them from the core, so the CLI and the Worker share one copy of the rule.
• Start job (cloudflare/src/jobs/routes.ts): the branch is now questBranch(target), so an epic starts on quest/<path>/README.
• Claim mapping (associatedQuest in cloudflare/src/github/state.ts): a branch maps only to branchQuest(branch). A bare directory branch such as quest/m0/foo matches nothing.
• Board links: questHref in both cloudflare/src/board/model.ts and cloudflare/src/inbox/model.ts builds the page from questBranch. An epic's page is now .../board/quest/m0/foo/README. findDoc resolves a page only through branchQuest, so each document has one URL.
• quest check (src/core/rules.ts): a quest X.md now collides with any document under X/, not only X/README.md. Git can't hold a branch beside a branch nested under it, so this rejects every tree whose branches would nest. That includes a directory named README under an epic (quest/m0/foo/README/README.md), whose branches would block the epic's quest/m0/foo/README branch.
• Deletes this quest and its entry in quest/m0/kix/README.md. Stored directory-form branches need no migration, because kix has no production data.

Decisions

• Old directory-form board URLs for epics return 404 (settled by the maintainer). findDoc used to accept both .../quest/m0/foo and .../quest/m0/foo/README for an epic; now only the README form resolves. Each page keeps one URL that matches its branch, and with no production data there are no saved links to break. A lenient lookup or a redirect was considered and declined.
• A README directory under an epic is now rejected (settled by the maintainer, from the Codex review thread). This reverses the rule from kixelated/quest#94, which accepted it as having a distinct path from its parent README. That was true for paths, but now that an epic's branch is quest/m0/foo/README, a child branch such as quest/m0/foo/README/README sits under it. Git can't create the epic's branch while a child branch exists, and the merge path leaves head branches behind, so starting the epic would fail on every retry. Rejecting the tree in quest check was chosen over a different branch encoding, which would break the rule that a branch is its path without .md. The test in test/tree.test.ts now expects the rejection.

Validation

• just check: passed.
• just test: passed. Vitest ran 390 tests (2 skipped) and the Worker suite ran 315. The shell suites and the lifecycle checks on both builds passed too.
• Merged main again. Main had moved handedBack into the core in kixelated/quest#182 and added an upstream import. The conflicts were in imports in src/cli/main.ts, src/cli/claims.ts, cloudflare/src/github/state.ts, and cloudflare/test/projects.test.ts, which now import both, and in quest/m0/kix/README.md, which drops both finished entries. associatedQuest keeps branchQuest.
• quest check --base origin/main --branch quest/m0/kix/epic-branches: passed.
• New tests:
  • Starting quest/m0/epic/README.md while quest/m0/epic/child is claimed creates a job on quest/m0/epic/README, and the claimed child stays unstartable.
  • associatedQuest maps quest/epic/README to the epic and a child branch to the child, and maps the bare quest/epic to nothing.
  • An epic's board page is /README, and its directory page no longer resolves.
  • quest check rejects a README directory under an epic, and a quest with any document under its path.
• Updated expectations: the README-directory test in test/tree.test.ts now expects a rejection, and epic links in the board, map, inbox, and Markdown tests.

Suggested follow-ups

• None required. Merging this may conflict with quest/m0/kix/recovery.md, which touches cloudflare/src/github/state.ts. Resolve that conflict by keeping branchQuest.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

[kixelated]

Implementation pushed, and just check, just test, and quest check --base all pass locally. The PR stays a draft for one open decision: whether the old directory-form board URLs for epics should keep resolving. I recommend keeping the 404. The options are under Decisions needed.

(Written by Claude Opus 5.5)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-22T15:48:36.479746Z	e2bafd1	New commits
🔒 Security Review	✅ Completed 2026-10-22T15:48:10.300722Z	e2bafd1	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e2bafd1657

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kixelated]

Enabling squash auto-merge at e3e955f.

• Changes: an epic now starts on and links to its README branch (quest/<path>/README), using questBranch/branchQuest, which now live in quest/core and are shared by the CLI and the Worker. quest check rejects a quest X.md beside any document under X/.
• Decisions (settled by the maintainer): old directory-form board URLs for epics return 404, and a README directory under an epic is now rejected (this reverses kixelated/quest#94).
• Reviews: Codex reviewed e2bafd1 and found one issue, the nested README branch collision. ca4d9be fixed it with the remedy Codex suggested, rejecting the tree in quest check, and the thread is resolved. Codex has not reviewed again since then.
• Checks: all 14 required checks passed on the head. quest check --base origin/main --branch quest/m0/kix/epic-branches, run from a base build, passed (41 documents ok). The PR merges cleanly with the current main.

(Written by Claude Opus 5.5)

[kixelated]

Main moved when kixelated/quest#190 landed, so I merged it into this branch as 9061eb6. The only conflict was in quest/m0/kix/README.md, where both finished entries are now dropped. associatedQuest keeps branchQuest. just check, just test, and quest check --base origin/main passed locally, and all 14 CI checks passed. I'm enabling squash auto-merge at this head.

(Written by Claude Opus 5.5)