Skip to content

Ticket #262: documentation freshness — verification ​

  • Date: 2026-11-12
  • Branch: ticket/262-docs-freshness
  • Base: integration/prod-partials at 188fe5e (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_VERSION from src/v2/init-block.ts (currently 7).
  • SUPPORTED_OPENCODE_VERSIONS and OPENCODE_PLUGIN_PEER_RANGE from src/v2/host-compatibility.ts (currently 2.2.6, 2.2.7, and 2.2.6 || 2.2.7).
  • MINIMUM_NODE_VERSION and TESTED_NODE_LINES from src/v2/node-version.ts (currently 22.23.4 and 22.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 vN claim that is not the current block version (README).
  • A bold OpenCode **X** claim outside the supported host set (README).
  • A Node X+ or Node X or newer floor that is not 22.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.json engines.node or 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 ​

CommandResult
npm run verifyPass — strict typecheck; 1982 tests passed, 0 failed, 0 skipped (50.3 s).
npm run docs:checkPass — 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.tsPass — 5/5 on Node 26.12.1 and 5/5 on Node 22.23.4.
npm run docs:check against the stale-claim fixturesFail — 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 ​

sh
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

Released under the MIT License.