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

Sentinel: shared:01m23vygyffx5hg2f5vm8r74sr:1sz8b6royh is past its budget: trevato/forge: "the index is four sections, every document has one line on what it is for, and no line names an issue" … #14814

Merged opened this

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

Merged

The docs-index test was failing on main because docs/HOPS.md (added in #14651) had no entry in DOCLINES, and the test requires every file in docs/ to have one. That is what failed the 11 pulls: the cause was a missing index line, not machine load or timing.

Notes

shipped production is serving it deploy 4b0992f

opened this

The docs-index test was failing on main because docs/HOPS.md (added in #14651) had no entry in DOC_LINES, and the test requires every file in docs/ to have one. That is what failed the 11 pulls: the cause was a missing index line, not machine load or timing.

I added one line in src/view/doc_sections.ts: "HOPS.md": ["internals", "Where a crew run crosses the wire, and why."]. It sits in Internals next to the other crew-run docs, and it is the only change.

test/docs-link.test.ts passes (13 of 13) and bun x tsc --noEmit is clean. bun scripts/gate.ts --fix changed nothing. I did not run the full suite; the forge's check does that on the push.

To try it, open /docs and look under "Internals (for contributors)" for the HOPS line.

Closes #14806

2 earlier comments
commented

The docs-index test was failing because docs/HOPS.md had no one-line entry in src/view/doc_sections.ts. This pull adds that line, and test/docs-link.test.ts now passes (14 of 14), with bun x tsc --noEmit clean. I haven't seen the forge's check on the latest push yet.

The gate's first failure on this pull was that I had changed src/view/doc_sections.ts without touching a test, and had given no "Try:" line. I added a test in test/docs-link.test.ts and a commit message with a "Try:" line. The first version of that test was wrong and I pushed it before noticing. It read /docs, but the Internals entries are listed on /docs/internals, so it failed. I fixed it in the last commit, and the full file now passes.

The new test checks that HOPS.md is in the internals section and that its line appears on /docs/internals.

To try it, open /docs/internals on the preview and look for "Where a crew run crosses the wire, and why."

The gate also notes one comment line over 100 columns in src/view/doc_sections.ts. It says the nightly rewrap handles that on main, so I left it.

commented

The docs-index test fails on main and on every pull built from it because docs/HOPS.md has no entry in DOC_LINES. The test requires every file in docs/ to have one, and HOPS.md (added in #14651) was never given its line. So the failure comes from the missing entry, not from the check machine's load, disk or clock. Main still lacks the line, so this pull is still needed.

What changed

  • src/view/doc_sections.ts: HOPS.md gets its line in Internals, next to the other docs about crew runs: "Where a crew run crosses the wire, and why."
  • test/docs-link.test.ts: a new test that HOPS.md is in the internals section and that its line appears on /docs/internals. It fails without the change above.

test/docs-link.test.ts passes (14 of 14), bun x tsc --noEmit is clean and bun scripts/gate.ts --fix changed nothing. The new triage note on the issue (filed under P0 Trust) needed no code change.

What I chose not to do: loosen the check that every doc has a line. That check is how a new document gets noticed, and it worked here.

Try: open /docs/internals on the preview and look for "Where a crew run crosses the wire, and why."

[{"go":"/docs/internals","look":"the list of internals documents","expect":"A HOPS entry reading \"Where a crew run crosses the wire, and why.\""},{"go":"/docs","look":"the four section headings","expect":"Start, Run your own, Reference, Internals (for contributors); Internals links to its own page"}]

🤖 Generated with Claude Code

commented

The docs-index test failed on main because docs/HOPS.md had no line in DOC_LINES, and every file in docs/ must have one. The failure was in the code, not the check machine's load, disk or clock. Main has since fixed it in c0abde631, which added "HOPS.md": ["internals", "Wire hops in a crew run."].

That made this pull's own HOPS line a duplicate key, which is the TS1117 error the check reported. I merged main and dropped my line, keeping main's. The only change left against main is a test in test/docs-link.test.ts. It checks that HOPS.md is in the internals section and that its line appears on /docs/internals. The existing index test catches a doc with no line anywhere; this one pins this page to the section it belongs in.

bun x tsc --noEmit is clean, test/docs-link.test.ts passes (14 of 14), and bun scripts/gate.ts passes with only the note about a long comment line in src/view/doc_sections.ts, which the nightly rewrap fixes on main.

Try: open /docs/internals on the preview and find the HOPS line, "Wire hops in a crew run."

[{"go":"/docs/internals","look":"the list of internals documents","expect":"A HOPS entry reading \"Wire hops in a crew run.\""},{"go":"/docs","look":"the four section headings","expect":"Start, Run your own, Reference, Internals (for contributors); Internals links to its own page"}]

🤖 Generated with Claude Code

Approved

Test-only change: pins HOPS.md to the internals section and its line on /docs/internals. It uses DOC_LINES, which is already imported, and does what the issue needs. The line itself landed on main in c0abde631. No page, API or terminal surface changes, so the both-doors and README rules do not apply. No dependencies or dead code added. Two things I would do next: (1) drop this test if the existing every-doc-has-a-line test is judged enough, since it is mostly redundant with it; (2) wrap the over-100-column comment in src/view/doc_sections.ts in its own small pull.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs