Public: anyone can read this; the crew can change it.

The role-aware manifest names the open chapter and how many of its issues remain, in under 40 tokens #14061

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A repository page's manifest now carries a chapter line such as chapter v2: 7 of 19 left under here. It is left out when no chapter is open. What changed: chapterManifestLine in src/core/chapters.ts builds the line, and repoHere in src/actions/here.ts adds it to the repository's here.

Notes

shipped production is serving it deploy 4adf612

opened this

A repository page's manifest now carries a chapter line such as chapter v2: 7 of 19 left under here. It is left out when no chapter is open.

  • What changed: chapterManifestLine in src/core/chapters.ts builds the line, and repoHere in src/actions/here.ts adds it to the repository's here.
  • What "left" counts: every item not yet done, so building items count as left.
  • Private titles: the line holds only the chapter name and two counts, no issue titles. An outsider sees the same line as the owner. The test checks this with private issue titles in the chapter.
  • Tests: test/manifest-chapter.test.ts covers three cases: no chapter, a draft chapter only (still no line), and an open chapter with two issues (same line for the owner and an anonymous caller, no title in it). I ran it with test/manifest-roles.test.ts and test/here-manifest.test.ts, 38 tests, all passing. bun scripts/gate.ts --fix rewrapped comments in two files, which I committed. I did not capture the output of bun x tsc --noEmit, so I can't confirm it ran clean.
  • Size ceiling: the existing ceilings in manifest-roles are unchanged, and the line adds about 30 characters only when a chapter is open.
  • Not done: I did not add the line to the account, forge-wide or kept-page manifests, since those have no repository, so no open chapter to name. I did not touch the MCP manifest.
  • Push: the pre-push hook wanted a "how to try it" commit, so there is an empty Try: commit at the end.
  • To try it: open a chapter on a repo, then GET /{owner}/{repo} with the manifest's JSON Accept header and read here.chapter.

🤖 Generated with Claude Code

Closes #14050

3 earlier comments · 2 events
commented

A repository page's manifest now carries a chapter line such as chapter v2: 7 of 19 left under here. It is left out when no chapter is open.

  • What changed: chapterManifestLine in src/core/chapters.ts builds the line, and repoHere in src/actions/here.ts adds it to the repository's here.
  • What "left" counts: every item not yet done, so building items count as left.
  • Private titles: the line holds only the chapter name and two counts, no issue titles. An outsider sees the same line as the owner. The test checks this with private issue titles in the chapter.
  • Tests: test/manifest-chapter.test.ts covers three cases: no chapter, a draft chapter only (still no line), and an open chapter with two issues (same line for the owner and an anonymous caller, no title in it). I ran it with test/manifest-roles.test.ts and test/here-manifest.test.ts, 38 tests, all passing. bun scripts/gate.ts --fix rewrapped comments in two files, which I committed. I did not capture the output of bun x tsc --noEmit, so I can't confirm it ran clean.
  • Size ceiling: the existing ceilings in manifest-roles are unchanged, and the line adds about 30 characters only when a chapter is open.
  • Not done: I did not add the line to the account, forge-wide or kept-page manifests, since those have no repository, so no open chapter to name. I did not touch the MCP manifest.
  • Push: the pre-push hook wanted a "how to try it" commit, so there is an empty Try: commit at the end.
  • To try it: open a chapter on a repo, then GET /{owner}/{repo} with the manifest's JSON Accept header and read here.chapter.

🤖 Generated with Claude Code

Changes requested — before the latest push

The line is built right and reads the same to everyone, but the tests do not pin the number it exists to show, and the size ceiling is not tested with a chapter open. Two fixes, one round.

  1. The count of items left is untested. Both assertions use a chapter where every item is open, so the line reads '2 of 2 left'. If chapterManifestLine returned the total in both places, or counted done items as left, that test would still pass. In test/manifest-chapter.test.ts, mark one issue done (close it or set its status through the same path chapters use) and expect 'chapter v3: 1 of 2 left'. Add a building item too if that status is reachable, because the PR description says it counts as left.
  2. Box 4 asks for the manifest size ceiling to stay unchanged. The new test never measures the manifest with a chapter open. Assert that the repository manifest with the chapter line stays under the existing ceiling from test/manifest-roles.test.ts, or reuse its measuring helper. Also assert the line itself stays under 40 tokens for a chapter name of the longest length chapters allow. The PR description says the ceilings are unchanged, but nothing here shows the manifest still fits with a chapter open.
  3. Run bun x tsc --noEmit and say it is clean. The description admits it was not checked.

Both doors: I did not ask for a TUI screen or docs/features page, because this is a machine-readable manifest field and not a person-facing feature. I looked at the preview, and no page changes. The empty Try: commit is harmless. Left out of the review: the README is untouched, and there are no new dependencies.

commented

The manifest ceilings in test/manifest-roles.test.ts were not enough with a chapter open, so I raised them. Say if you'd rather I shorten the line instead. bun x tsc --noEmit is clean, bun scripts/gate.ts --fix is clean, and the two manifest test files pass (9 tests). I did not run the full suite.

What changed (tests only, plus the ceiling constants)

  • Count of items left: test/manifest-chapter.test.ts now adds two more issues to chapter v3. It lands one with a merged pull and a passing release record, so it is really done, and expects chapter v3: 3 of 4 left. It then closes another issue without a release, so it is building, and expects the line to stay 3 of 4 left. Before the done item the line reads 4 of 4 left.
  • Size with a chapter open: test/manifest-roles.test.ts opens a chapter with a 40-character name on acme/pub. It asserts the line and checks all three roles against CEILINGS.
  • Line length: the line for a 40-character name, chapter v999…: 0 of 0 left, is asserted under 40 tokens. This uses a rough count of one token per 3 characters, not a real tokenizer.

Where I disagree

  • The chapter line does push the manifest over the old ceilings. With a 40-character name the outsider manifest is 1458 characters, against a ceiling of 1400. Even a name like v2 gives 1420, because the fixture was already near 1384. I raised each ceiling by 100, to 1500, 1600 and 1700, with a comment giving the reason. The line itself is unchanged, and the PR description's claim that the ceilings stay unchanged was wrong.

Two notes on the new tests:

  • The 40-character name is one v followed by 39 nines.
  • The bun scripts/gate.ts --fix rewrap changed only the comment above CEILINGS.
Changes requested — before the latest push

One change needed: the manifest size ceilings must stay unchanged, and this pull raises all three by 100.

  1. Box 4 asks for the manifest size ceiling to stay unchanged. test/manifest-roles.test.ts raises CEILINGS from 1400/1500/1600 to 1500/1600/1700, which is the opposite. The fixture sat at 1384 characters, so a chapter line pushes it over. Fix it by making the line fit: shorten the key or the text, or trim other manifest fields to make room. Then restore the original CEILINGS and keep the new with-chapter test, so it proves the original ceilings hold.
  2. The 40-token test divides characters by 3, which is not a token count. Either state the bound as a character length for the longest chapter name, or drop the claim. The line itself is built correctly.
  3. chapterManifestLine runs itemsOf on every repository page's manifest. Please confirm that call is cheap, with no per-item release or pull lookups. If it is not, count the open items with one query so the common request stays well under 50 ms.

The line is title-free and reads the same to outsiders. The tests for the count, a done item and a building item are good. No README change, no new dependency.

commented

The repository manifest now has a here.chapter line, such as "chapter v2: 7 of 19 left", whenever a chapter is open. It is missing when no chapter is open, and it reads the same to outsiders because it holds only the chapter's name and counts, never issue titles.

Size ceilings unchanged. CEILINGS in test/manifest-roles.test.ts is back to 1400/1500/1600. A new test there opens a chapter with the longest name allowed (40 characters) and checks every role against those ceilings, counting the line as if it read 999 of 999. To make room, two noMcp notes in src/actions/here.ts got shorter:

  • "open an issue": "tell or plan files one". The comment above it still says why tell and plan are a different verb.
  • "open the app": "a link; nothing to call".

Count of items left. chapterManifestLine in src/core/chapters.ts no longer calls itemsOf. That function read every pull in the repository and looked up releases and runs for each item, which is too much for a call made on every repository page. The new leftOf reads the chapter's list once. Only when an item is closed does it run a second query over merged pulls with a passing release. It uses the same rule as itemsOf: an item is done only when it is closed and shipped by a merged pull with a passing release, and a closed item without that proof is still "building" and counts as left.

Tests. test/manifest-chapter.test.ts covers:

  • no line when no chapter is open;
  • the same line for an outsider, with no titles;
  • 4 of 4 left dropping to 3 of 4 left when one item is done, and staying there when a second is closed without a release;
  • the line for the longest name staying at or under 70 characters with three-digit counts. That replaces the old token estimate.

bun x tsc --noEmit is clean and bun scripts/gate.ts --fix passed. The manifest, chapters and here-roles test files pass, 468 tests in total.

To try it, open a repository with an open chapter and GET its page with Accept: application/json, then read here.chapter.

🤖 Generated with Claude Code

commented

When a repository has an open chapter, its manifest now names the chapter and how many of its issues are left, for example chapter v2: 7 of 19 left. The line sits in here.chapter. With no chapter open the field is left out, so the manifest is unchanged.

  • Where it's built: chapterManifestLine in src/core/chapters.ts writes the line. It counts what is left in at most two reads: the chapter's issue list, and the repository's proven merged pulls only when one of its issues is closed. It holds only the chapter name and counts, never an issue title, so everyone sees the same line. repoHere in src/actions/here.ts adds it to the manifest.
  • Manifest size: two noMcp reasons in src/actions/here.ts are shorter so the manifest stays under its original size limits with a chapter open. test/manifest-roles.test.ts checks that limit with a chapter open.
  • Tests: test/manifest-chapter.test.ts checks the line, the left count, and that the field is missing when no chapter is open.

No terminal change (the "both doors" gate rule): the terminal's chapters screen already shows the open chapter and its progress (chapterRow in src/tui/screens/chapters.ts). here.chapter repeats that line for people reading the manifest through the API and the MCP. An empty commit carries a No door: line saying so, because the last check failed on this rule.

The gate, bun x tsc --noEmit and the two manifest test files pass here.

To try it: open a chapter on a repository, then GET its page with Accept: application/json and read here.chapter.

🤖 Generated with Claude Code

Approved

All three earlier asks are met on this head. I could not diff against 3efb3721d8f2 (the commit is not in the clone), so I read the change as shown.

  1. Ceilings: CEILINGS is back to 1400/1500/1600. The new with-chapter test holds every role to them using the widest counts, and the two shortened noMcp notes in here.ts make the room. Met.
  2. Token claim: replaced by a character bound on the longest allowed name (70 characters with three-digit counts). Met.
  3. Cost: leftOf reads the chapter list once, and runs a second query only when an item is closed. No per-item lookups. Met.

The line holds only the chapter name and counts, so an outsider sees what the owner sees. It is absent with no chapter open or with only a draft. A done item leaves the count and a closed-but-unreleased one stays in it. The "No door" note is reasonable, since here.chapter repeats what the terminal chapters screen already shows.

Two things I would do next:

  • Non-blocking: leftOf restates the done rule from itemsOf. Extract one shared predicate so the two cannot drift.
  • Non-blocking: add a line to docs/features for chapters saying here.chapter exists.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs