A chapter is a version with an end: a named list that is finished, tagged and closed, while the next one waits its turn #11660

Chapters work end to end in the forge's code and are pushed. Some of what the issue asks for is not done (listed under "Not done"). The final checks (gate.ts, tsc, and the cross and related test files) are green locally. I ran the tests I judged relevant, not the whole suite. The forge's own check runs on the push.

What changed

• Data: a new migration, with its pin, adds chapter and chapter_item. A unique partial index allows one open chapter per repository. src/core/chapters.ts holds the rules: draft, open, items, the done test, the pace and the crew gate. src/core/chapter_notes.ts writes the notes.
• Crew gate: queueAgentRun starts no builder or reviewer run on an issue outside the open chapter, for assigned runs too. A pull is held only if every issue it closes is outside the chapter.

- With no chapter nothing changes. - After a chapter closes and none is open, the crew rests. - The planner's runs and runs carrying on after a pause are exempt.

• Planner scope: while a chapter is open, the planner's new issue waits in the next drafted chapter, or behind the Later gate if none is drafted.

- An issue that says Defect of #N for an item in the chapter joins it. - Parts of a split stay in the parent's chapter. - Only a human admin adds or removes items, and each change is a chapter.* event.

• Done: an item is struck only when its issue is closed and a merged pull that closes it has a passing production proof, meaning a passing row for that pull in the release table. A merge alone shows as "building".
• Ship it: actions/chapters.ts close tags the default branch tip with the chapter's name, writes the grouped notes (who built what, what it cost), moves unfinished items to the next chapter (drafting v2.0.0 if none), and marks the chapter closed.

- A closed chapter can't be reopened or edited. - Opening a patch chapter (v1.0.0 becomes v1.0.1) is one click.

• Doors: the page /:owner/:name/chapters and /chapters/:chapter is linked from /queue. It shows the crossed-off list, the finish date, and a finished page for closed chapters. The API is GET and POST /api/v1/repos/:owner/:name/chapters, plus POST …/:chapter/:verb. I also added the openapi entries, a tag alias and the event audience entries. The how-to is in docs/features/chapters.md.
• Tests: test/chapters.test.ts covers:

- the dispatcher holding and the planner placing issues; - the proof rule; - Ship it moving items, tagging, writing notes and closing; - rest after close, and a patch chapter opening from a closed one; - an HTTP walk of open → cross off → ship → finished page, including a cross-origin refusal; - the query plans.

Not done

• Browser test: the walk is over HTTP with a token, not headless Chromium.
• Terminal screen: none. The commit carries a No door: line.
• Working ahead: the "later chapter on its own branch or fork" and the budget-share setting are not built. Drafted chapters simply wait.
• First-ask "make this v1?" suggestion: not added.
• Seeding v1.0.0 from #334: I didn't. #334 is prose, not a list of issues, so the owner drafts it from the page.
• Dragging on /queue: I used add and remove forms on the chapter page instead.
• keep_plan tool: it wasn't available to me here, so the plan on the issue was not kept.
• MCP tool: not added.

One performance note: the done test finds closing pulls with a LIKE over the repository's issue bodies, as the existing cost reader does. It is bounded by chapter size.

To try it, open /<owner>/<name>/chapters on the preview, draft v1.0.0, add an issue, open it, then press Ship it.

Closes #11603

Chapters work end to end in the forge's code and are pushed. Some of what the issue asks for is not done (listed under "Not done"). The final checks (gate.ts, tsc, and the cross and related test files) are green locally. I ran the tests I judged relevant, not the whole suite. The forge's own check runs on the push.

What changed

• Data: a new migration, with its pin, adds chapter and chapter_item. A unique partial index allows one open chapter per repository. src/core/chapters.ts holds the rules: draft, open, items, the done test, the pace and the crew gate. src/core/chapter_notes.ts writes the notes.
• Crew gate: queueAgentRun starts no builder or reviewer run on an issue outside the open chapter, for assigned runs too. A pull is held only if every issue it closes is outside the chapter.

- With no chapter nothing changes. - After a chapter closes and none is open, the crew rests. - The planner's runs and runs carrying on after a pause are exempt.

• Planner scope: while a chapter is open, the planner's new issue waits in the next drafted chapter, or behind the Later gate if none is drafted.

- An issue that says Defect of #N for an item in the chapter joins it. - Parts of a split stay in the parent's chapter. - Only a human admin adds or removes items, and each change is a chapter.* event.

• Done: an item is struck only when its issue is closed and a merged pull that closes it has a passing production proof, meaning a passing row for that pull in the release table. A merge alone shows as "building".
• Ship it: actions/chapters.ts close tags the default branch tip with the chapter's name, writes the grouped notes (who built what, what it cost), moves unfinished items to the next chapter (drafting v2.0.0 if none), and marks the chapter closed.

- A closed chapter can't be reopened or edited. - Opening a patch chapter (v1.0.0 becomes v1.0.1) is one click.

• Doors: the page /:owner/:name/chapters and /chapters/:chapter is linked from /queue. It shows the crossed-off list, the finish date, and a finished page for closed chapters. The API is GET and POST /api/v1/repos/:owner/:name/chapters, plus POST …/:chapter/:verb. I also added the openapi entries, a tag alias and the event audience entries. The how-to is in docs/features/chapters.md.
• Tests: test/chapters.test.ts covers:

- the dispatcher holding and the planner placing issues; - the proof rule; - Ship it moving items, tagging, writing notes and closing; - rest after close, and a patch chapter opening from a closed one; - an HTTP walk of open → cross off → ship → finished page, including a cross-origin refusal; - the query plans.

Not done

• Browser test: the walk is over HTTP with a token, not headless Chromium.
• Terminal screen: none. The commit carries a No door: line.
• Working ahead: the "later chapter on its own branch or fork" and the budget-share setting are not built. Drafted chapters simply wait.
• First-ask "make this v1?" suggestion: not added.
• Seeding v1.0.0 from #334: I didn't. #334 is prose, not a list of issues, so the owner drafts it from the page.
• Dragging on /queue: I used add and remove forms on the chapter page instead.
• keep_plan tool: it wasn't available to me here, so the plan on the issue was not kept.
• MCP tool: not added.

One performance note: the done test finds closing pulls with a LIKE over the repository's issue bodies, as the existing cost reader does. It is bounded by chapter size.

To try it, open /<owner>/<name>/chapters on the preview, draft v1.0.0, add an issue, open it, then press Ship it.

This push fixes the failures the check reported on #11660, which came from the chapters work not being registered in the route-coverage lists.

• Route index: the OpenAPI route index was out of date, so I regenerated it with bun scripts/openapi-routes.ts.
• Session phase: GET /api/v1/repos/:owner/:name/chapters now records a session timing phase like the other API reads. It had been answering 200 without one.
• Unseeded pattern: /:owner/:name/chapters/:chapter is now named, with a reason, in the unseeded and walk-skipped lists in test/security-floor-routes.test.ts and test/no-polling.test.ts, because the seed drafts no chapter.

The tests that failed and the lists they check all pass now, and bun x tsc --noEmit and bun scripts/gate.ts are clean. I did not run the full suite, which the forge's check does on this push.

The /mcp routes test ("routes lists the over-budget route first…") passes when run alone. It failed when I ran it together with other test files, so I took that to be cross-file contamination of the shared performance record and changed nothing for it. I did not rerun the shard it failed in.

Two causes fixed on #11603, pushed as 49f2ca792. The tests I ran pass locally, but I have not seen the forge's full check on this push yet.

• Server-Timing sweep: /:owner/:name/chapters answered with app alone. Both chapter pages now record session and render phases the way queuePage does (src/web/pages/chapters.ts). I added the same timing to /:owner/:name/chapters/:chapter as well, though only the list page was flagged.
• Unfixtured routes: the chapter page is a route the fixture cannot fill, and the pin was one short. I raised MAX_UNFIXTURED from 145 to 146 in test/pages-budget.test.ts.
• The two ETag tests: the signed-out flash and the signed-out 404 failed only in the check, in shard 54. They pass locally, and I changed nothing aimed at them. If they fail again, the log will show why.

test/server-timing-sweep.test.ts, test/pages-budget.test.ts and test/etag.test.ts all pass here. bun x tsc --noEmit and bun scripts/gate.ts printed nothing, and I did not check their exit codes.

Sentinel's feedback on #11660 is addressed and pushed as e11d7c408. I ran the chapters, pages-budget, server-timing, no-polling, security-floor, both-doors and etag suites, plus the TUI workspace, palette and command tests where they exist, and they pass. bun x tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts came back clean. scripts/fast.ts called the diff too broad (2180 of 2879 files), so I picked those suites by hand rather than running a computed set.

1. Terminal door. New src/tui/screens/chapters.ts, offered as a palette command ("Chapters") while an app is open.

- Keys: n drafts, o opens, s ships, p patches, and enter shows the list. - In the list, a adds an issue and x takes one out. - It calls the same acts as the page (actions/chapters.ts), so the owner-only gate is the same, and each act is a bus event. - The screen redraws on chapter.* events, so it follows a change made on the web. - I did not touch the web pages' live updates beyond the events the acts already append. The pages are still plain server renders. - Tests cover a non-owner and a guest being refused, and the owner running the full draft → add → open → ship sequence with the events heard.

1. Anonymous read cost. itemsOf now reads the repository's pulls once and its run costs once, so a list no longer scans per item. A closed chapter's list is frozen, so it is kept in process memory (200 at most) and read once. The cache is named in AGENTS.md. A test fails if the LIKE scan runs more than once per read or if a repeat read of a closed chapter hits the database.
2. Tag before transaction. close() still creates the tag first, because update-ref with an empty old value is the atomic guard against two ships racing. Closing in the database now sits in one transaction that only proceeds while the chapter is still open, and drafting the next chapter moved inside it. If the transaction fails, the tag is deleted, so a retry does not answer tag_exists. A test fails the database step with a trigger and checks that the tag is gone and the chapter is still open. It then drops the trigger and closes the book on a retry.
3. Design and format.

- Shipped, took, cost and tag are now dl rows. - I removed the sentence after the Chapters link on /queue. - I removed the draft-chapter paragraph. - The ship explanation is now in the button's label: "Ship it, move N to the next". - The "unfinished" message no longer refers to a button by name. - The brace block in src/actions/issues.ts is formatted like its neighbours.

1. Pipeline-before-feature. I took note of it and did nothing, as Sentinel asked.

Earlier in the thread I also fixed the check's failures: the chapter pages now name session and render in Server-Timing, and the unfixtured-route pin went from 145 to 146 for the unseeded chapter page.