Chapters: a version with an end
A chapter is a named list of a repository's issues that is finished, tagged and closed (#11603). A name (v1.0.0; it becomes the git tag), one sentence of what done means, and the issues in it.
- One open, any number drafted. A repository has at most one open chapter. Later ones (
v2,v3) are drafted after it and filled with issues that wait. - While one is open the crew builds only what is in it. The dispatcher (
queueAgentRun, throughchapterHoldinsrc/core/chapters.ts) starts no builder or reviewer run on an issue outside it. The planner may split a chapter's issue (the parts stay in the chapter) and may open an issue that saysDefect of #Nfor an item of the chapter (it joins the chapter); every other issue it opens waits in the next chapter, or, with none drafted, behind the Later gate. Adding or removing an issue is the owner's act, recorded aschapter.item_added/chapter.item_removed. - The list being crossed off.
/<owner>/<name>/chapters/<name>: done items struck through with the day they went live, what is building, what is left, and the date it finishes at the pace since it opened. An item is done when it is live and proven (a merged pull that closes it and a passing production release proof), never when the pull merged. - Closing the book. When the last item is done, or when the owner presses Ship it, the forge tags the default branch with the chapter's name, writes the notes from what landed (grouped, with who built what and what it cost), moves what is left to the next chapter and marks the chapter closed. The chapter's page then says it is finished: what shipped, how long it took, what it cost. The crew then rests on that repository until a chapter is opened; nothing starts by itself.
- Closed is forever. A closed chapter stays readable at its own address and cannot be reopened or changed. A fix for something it shipped goes in a patch chapter (
v1.0.1), opened with one click from the closed chapter's page. - No chapter, no change. A repository that never drafted one flows continuously, as before.
Doors: the page (/chapters, linked from /queue), the terminal (src/tui/screens/chapters.ts, the palette's "Chapters" while an app is open: n drafts, o opens, s ships, c closes (nothing moves; refused with the page's sentence naming what is in the way), u undoes a close within 60 seconds, p patches, enter shows the list where a adds an issue and x takes one out) and the API (GET/POST /api/v1/repos/:owner/:name/chapters, POST …/chapters/:chapter/:verb with open, add, remove, ship, patch). Only a person who administers the repository acts; an agent is refused.
The MCP answers too: the repo tool with view: "chapters" lists a repository's chapters (name, what done means, state); adding chapter: "v1" names that chapter's items (done, building or left), its progress (the same sentence the page and the terminal print, from progressSentence) and finishesOn. chapter without view is invalid; a repository the caller cannot read is refused as the page refuses it.
The same tool acts, for the owner: action is open, add, remove or close, with chapter (and an issue number for add and remove). Without confirm: true it changes nothing and answers { done: false, says }: what it would do (for close, also the tag it would write and the into chapter and moves of what is left), made by the same checks the act makes, so a preview never promises what the act refuses. With confirm: true it does it through the page's own functions (open, fill, close with ship, in src/actions/chapters.ts) and answers { done: true }; each is recorded as the page records it. A refusal is the page's: CHAPTER_WORDS under its code (forbidden for a person who does not administer the repository or an agent, already_open, closed, no_issue, tag_exists, …). A token that may only read gets the previews and is refused the confirmed act. The MCP's close always ships: what is left moves on, so unfinished is the page's refusal only for a close that does not ship.
A closed chapter's list is frozen, so itemsOf keeps it in process memory (at most 200, forgetFrozenItems drops them); an open chapter's list is one pass over the repository's pulls and one grouped read of its runs, however many items it holds, so the anonymous page and API read stay cheap.
- On /next (#12288).
/:owner/:name/nexthas a Chapters section: each chapter with issues closed against its list, and, for the repository's owner, Close chapter on the open one (POST …/chapters/:chapter/close, same-origin, nothing moves). A chapter with issues still open says which ones are in its way and refuses the close with the same sentence. A close shows its receipt (name, tag) and an Undo for 60 seconds (…/undo: the tag goes, the chapter is open again); a close that moved items to the next chapter (Ship it) has no undo. The terminal does the same onsrc/tui/screens/chapters.ts(c,u); its acts append the same events, so an open web page follows.
- Next line (#12681). A closed chapter's page ends with
Next: <earliest draft>(linked), or says no chapter is drafted./nextcarries a header line:Ranked for <open chapter>: <progress sentence>, or, when chapters exist and none is open, "No chapter is open" with a link to draft one. A repository with no chapters shows neither. The terminal prints the same words (nextWords,chapterLineWordsinsrc/core/chapters.ts):Next: <name>under a closed chapter on its screen, and the ranked-for line, or "No chapter is open. Draft one.", under the heading on its /next screen; both wrap at narrow widths, and a repository with no chapters shows neither.
The first chapter: v1.0.0
Drafting a chapter named v1.0.0 records the v1 list's issues in it (the issue of every probe in scripts/v1-proven.ts, those that exist in the repository). Closing it (Ship it or Close) runs those read-only probes against the forge's public origin and is refused, naming each probe that does not pass, until every one passes; unproven is not a pass. The close tags the default branch's tip and nothing more: a person cuts the release with scripts/cut-release.ts.
What it has cost (#13261)
An open chapter's page says what it has cost so far and what a chapter of its pace costs, in a line under the progress sentence (costSentence, src/core/chapters.ts). The terminal prints the same sentence after the progress sentence on the chapter's list and on each row of the chapters screen; the MCP repo tool's progress carries it too. A closed chapter keeps its finished page, which already says its cost.
Try it: open /<owner>/<name>/chapters/<open chapter> and read the line under the progress sentence.