docs(spec): #6000 引入的活文档同步到分片路径 (#5837)

merge 带进来的 #4723/#6000 新增了几处描述「check:docs 曾重写两个 tracked 投影」的散文,
它们指的是当前机制而不是历史叙述,所以路径随分片一起更新:build-docs.ts、AGENTS.md、
check-regen-pending.mjs、check-generated-ledger.test.ts、schema-tree-freshness.test.ts。
另外 build-schemas.ts 里把 api-surface 说成「另一个见证者」的两处、以及
migrations/spec-changes.ts 的 Release 工作流描述,同属活文档。

⛔ 有意不动的:所有 `src/**` 与测试里追述「当年这个 key 怎么出账」的历史叙述
(http-server.zod.ts / theme.zod.ts / data-engine.zod.ts / retry-policy.* / …),
以及 ADR 正文 —— 后者按 AGENTS.md #13 用顶部 Amended 行声明路径迁移,不改写决策记录。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY

Author: claude

AGENTS.md

@@ -417,7 +417,7 @@ regenerate those.
 
 **No `check:` script regenerates anything — that is the point of the split, not an
 oversight.** `check:docs` used to begin with `pnpm gen:schema`, which rewrites two
-*tracked* files (`json-schema.manifest.json`, `authorable-surface.json`) whenever they
+*tracked* files (`json-schema.manifest/`, `authorable-surface/`) whenever they
 are behind: running the gate edited your working tree and reported nothing, so a
 `check:generated` run on a stale manifest printed a red `check:authorable-surface`
 over a file the gate two lines below had already quietly fixed (#4711, #4723). The

packages/spec/scripts/build-docs.ts

@@ -73,7 +73,7 @@ const UPDATE_IMPORT_BASELINE = process.argv.includes('--update-import-baseline')
 // Until #4723 the question could not come up: `check:docs` was
 // `pnpm gen:schema && tsx scripts/build-docs.ts --check`, so the tree was rebuilt
 // on every run. That first step is what made a script called `check:` WRITE two
-// TRACKED files — `json-schema.manifest.json` and `authorable-surface.json` are
+// TRACKED files — `json-schema.manifest/` and `authorable-surface/` are
 // projections `gen:schema` repairs whenever they are behind — so running the gate
 // silently edited the tree of whoever ran it and left the staleness unreported.
 // #4711 removed exactly that from `--check`; this was the same defect at a

packages/spec/scripts/build-schemas.ts

@@ -614,12 +614,12 @@ if (manifestChanged && !CHECK) {
 // inside them — and for a metadata-driven platform those keys ARE the
 // third-party API: what an author (very often an AI, ADR-0033) may write.
 //
-// Both existing witnesses look elsewhere. `api-surface.json` records exported
+// Both existing witnesses look elsewhere. `api-surface/` records exported
 // `name (kind)`, and `api-surface-signatures.json` hashes each `defineX`
 // factory's type as TypeScript PRINTS it — a reference (`z.input<typeof
 // ActionSchema>`), never structurally expanded, so member-level narrowing does
 // not reach the hash. `spec-changes.json` inherits the same blind spot: its
-// added/removed arrays are a diff of `api-surface.json`. So #3883 removed three
+// added/removed arrays are a diff of `api-surface/`. So #3883 removed three
 // authorable keys with all three witnesses green, and #3733 did the same by
 // ACCIDENT — `dataQuality` / `cached` outlived their keys and were silently
 // stripped. ADR-0059 §5 deferred this gate "until a narrowing actually slips

packages/spec/scripts/check-generated-ledger.test.ts

@@ -123,8 +123,8 @@ describe('check:generated --reconcile-only', () => {
   // `turbo run test` leaves this package in — see root-index.test.ts).
   //
   // `check:docs` was `pnpm gen:schema && tsx scripts/build-docs.ts --check`. The
-  // first half is a GENERATOR: on a stale tree it rewrites `json-schema.manifest.json`
-  // and `authorable-surface.json`, both TRACKED. So running the gate edited the
+  // first half is a GENERATOR: on a stale tree it rewrites `json-schema.manifest/`
+  // and `authorable-surface/`, both TRACKED. So running the gate edited the
   // working tree of whoever ran it, and — because `check:generated` runs
   // `check:authorable-surface` first and does not stop on failure — a single
   // aggregate run produced a red report about a manifest that the gate two lines

packages/spec/scripts/schema-tree-freshness.test.ts

@@ -6,7 +6,7 @@
 //
 // `check:docs` used to be `pnpm gen:schema && tsx scripts/build-docs.ts --check`.
 // That first step is a GENERATOR, and on a stale tree it rewrites two TRACKED
-// files (`json-schema.manifest.json`, `authorable-surface.json`), so a script
+// files (`json-schema.manifest/`, `authorable-surface/`), so a script
 // called `check:` edited the working tree of whoever ran it and left the
 // staleness unreported — #4711's defect at a different entry point.
 //

packages/spec/src/migrations/spec-changes.ts

@@ -3,7 +3,7 @@
 /**
  * The machine-readable-first change manifest, `spec-changes.json` (ADR-0087 D4).
  *
- * The Release workflow diffs the current `api-surface.json` against the
+ * The Release workflow diffs the current api-surface snapshot against the
  * previously published one (reusing the ADR-0059 §3 gate artifact instead of
  * discarding it), then joins the conversion table (D2) and the migration set
  * (D3) into a single `{ from, to, added, converted, migrated, removed }` record.

scripts/check-regen-pending.mjs

@@ -74,8 +74,8 @@ export function distIsStale(specDir = SPEC_DIR) {
  * rendered from — and the tree is gitignored, so nothing in a checkout carries
  * it. Until #4723 the question could not arise: `check:docs` ran `gen:schema` as
  * its first step, so the tree was regenerated on every run. That is also what
- * made `check:docs` a "check" that WROTE two tracked files (json-schema.manifest.json
- * and authorable-surface.json, whenever they were behind), which is the defect
+ * made `check:docs` a "check" that WROTE two tracked artifacts (json-schema.manifest/
+ * and authorable-surface/, whenever they were behind), which is the defect
  * #4711 removed from `--check` and #4723 removed from this composition. With the
  * generation gone, the freshness it silently guaranteed has to be ASSERTED, or
  * `check:docs` reports a verdict about a tree that predates the edit under test —