Ticket #262: documentation freshness — verification
- Date: 2026-11-12
- Branch:
ticket/262-docs-freshness - Base:
integration/prod-partialsat188fe5e(merge of #258) - Spec: parent #255, P7; ticket #262
- Unit gate:
npm run verify(strict typecheck + full test suite) - Docs gate:
npm run docs:check - Host: Linux/tmux, Node 26.12.1, npm 12.2.1
Canonical sources
scripts/docs-check.mjs imports the current constants instead of restating them:
ENSEMBLE_BLOCK_VERSIONfromsrc/v2/init-block.ts(currently7).SUPPORTED_OPENCODE_VERSIONSandOPENCODE_PLUGIN_PEER_RANGEfromsrc/v2/host-compatibility.ts(currently2.2.6,2.2.7, and2.2.6 || 2.2.7).MINIMUM_NODE_VERSIONandTESTED_NODE_LINESfromsrc/v2/node-version.ts(currently22.23.4and22.23.4, 24.x, and 26.x).- The live Node line comes from
.github/workflows/verify.yml(NODE_VERSION), so the docs follow the CI matrix rather than a private copy.
Docs updates
- README. Status now states the v7 contract, the OpenCode 2.2.6/2.2.7 range, the Node 22.23.4 floor, the tested Node lines, and the pending package/license boundary. The upgrade note says contract v7 instead of v4. The macOS/Herdr limit links the manual checklist. The stale live-record link now points at the two current E2E records. A new Known limitations section records distribution/license, host support, platform-bound live evidence, terminal accessibility, native-only surfaces, and host page lifetime.
- Docs index. Added the missing current records: native ingestion state and AGENTS v7 E2E, the #231 state record, the terminal-turn E2E, and the #217, #218, #226, #249, and #251 records. ADR 0011 now links the v7 roster contract.
- Implementation. Status records contract v7 and the Node floor. Stale "native-first target / current path until #214" language now describes the shipped conversation binding and direct sessions. The known-limitations tail no longer pins v5.8 or says the package has no version.
- ADR 0011. Updated to contract v7, including the terminal-turn workflow; the v6 validation note stays historical.
- Scripts guide. Node floor is
22.23.4+and the Vera regression checks the v7 roster table.
docs:check behavior
The check exits 1 and names the file for any of these stale or missing claims:
- A
contract vNclaim that is not the current block version (README). - A bold
OpenCode **X**claim outside the supported host set (README). - A
Node X+orNode X or newerfloor that is not22.23.4. - A missing current README/implementation/ADR/host-range claim.
- A current verification record (dated 2026-11-11 or later) that is not linked from
docs/README.md. package.jsonengines.nodeor a CI matrix that disagrees with the canonical constants.
It exits 0 with one line naming the current contract, hosts, Node floor, and live Node line. It exits 2 for usage errors. It reads relative paths only; it prints no absolute paths, conversation content, credentials, or file bytes.
src/v2/docs-check.test.ts runs the CLI against a temporary copy of the docs and asserts that the current tree passes, a stale contract claim fails, a stale Node floor fails, an untested host fails, and an unlinked current record fails.
Results
| Command | Result |
|---|---|
npm run verify | Pass — strict typecheck; 1982 tests passed, 0 failed, 0 skipped (50.3 s). |
npm run docs:check | Pass — contract v7; OpenCode 2.2.6, 2.2.7; Node >=22.23.4; live Node 26.12.1. |
node --test --experimental-strip-types src/v2/docs-check.test.ts | Pass — 5/5 on Node 26.12.1 and 5/5 on Node 22.23.4. |
npm run docs:check against the stale-claim fixtures | Fail — each case exits 1 and names the file and stale claim. |
CI
.github/workflows/docs.yml runs npm run docs:check on Node 26.12.1 for pushes and pull requests. It is separate from the Node and host matrices so docs freshness is cheap and independently visible. The docs-check tests also run inside npm run verify through the normal src/v2/*.test.ts glob.
Scope
Docs, the docs-check script, its test, and CI only. No product behavior, TUI, native ingestion, or dispatch code changed. No license or published package is claimed; the package remains private at 0.1.0.
Privacy
No conversation content, credentials, file bytes, or private paths were added. The check reads repository docs and prints relative paths only.
Reproduce
source ~/.nvm/nvm.sh && nvm use 26.12.1
npm run verify
npm run docs:check
node --test --experimental-strip-types src/v2/docs-check.test.ts