feat(scripts): the JSON-fence gate reads the published READMEs (objectui#12131, phase 2)

[objectstack-fleet]

Fixes #12131
Clause-②: no

Phase 2 of objectui#12131, the card's last part. Phase 1 landed as PR objectui#12134. This PR widens the scan surface of scripts/check-doc-json-fences.mjs from content/docs to the published READMEs, so the README examples phase 1 repaired stay covered by the strict authoring face. Triage 6106881179 called this a blind-spot repair inside the ruled programme (objectui#5250), not a new gate.

What changed

• One declared scan surface. SCAN_SURFACE in the gate lists three legs in walk order: every .mdx / .md page under content/docs, every packages/NAME/README.md, and the root README.md. listDocuments and the new surfaceLegs both read it, and the summary prints it leg by leg with each leg's page count.
• The README legs come from the doc-gate family. PACKAGE_READMES / packageReadmePages and ROOT_PAGES are imported from scripts/check-doc-component-types.mjs, the same legs the snippet, fence-language and component-type gates walk. This gate does not spell them a second time.
• Every leg proves it read something (H2). Each leg names an anchor page that must contribute a judged node document on every run: content/docs/blocks/forms.mdx (unchanged), packages/plugin-dashboard/README.md and README.md. A README leg that collects nothing cannot hand in its anchor, so the run exits 2 (could not run) instead of printing a green over zero READMEs. analyze takes anchors (default: every leg's anchor) where it took anchor.
• The gate describes itself accurately (H3). The header's first sentence, a new section on the scan surface, the ANTI-IDLE control text, and the list of what the gate does not read now match the code. The summary's surface line comes from SCAN_SURFACE. Its NOT-read line names what stays off. In content/docs/guide/ci-cd-pipeline.md, the gate's table row and its section now say what it reads. The old sentence that pages outside content/docs are not read is replaced by a paragraph that names what is read and what is off.
• Off the surface on purpose: docs/audits/** (triage: point-in-time records), CHANGELOGs and .changeset/ (history), skills/** (objectui#12135 owns that fence), and READMEs below a package root.
• scripts/markdown-test-inputs.mjs: the gate test's ADJUDICATED entry now reads README.md, content/docs/** and packages/**. The agreement test walks the widened surface. The notRead: README.md line is gone, because the root README is now really read.

H1: which reading of "the published READMEs" (measured at 9b755099)

Each reading was judged with the gate's own scanner, predicate and the built strict face:

Reading	Pages	json/jsonc fences	Judged node documents	Newly refused
(a, npm-only) root README.md plus the root README of every package not marked private	38	22	18	0
(a) chosen: root README.md plus every packages/NAME/README.md (the family leg)	40	24	19	0
(b) every tracked README*.md in the tree	56	30	23	1: the object-kanban onCardMove document in packages/components/src/renderers/complex/README-KANBAN.md

• Why (a), not the npm-only spelling. private: true means "not on npm", not "not published". packages/vscode-extension is npm-private, but vsce publish puts its README on the VS Code Marketplace, and that README teaches an authored .objectui.json node document (a div example, accepted). The npm-only spelling would drop that page. The one unpublished page (a) adds, packages/test-support/README.md, holds no json fence. (a) is also the leg the three sibling doc gates already walk.
• Phase 1's three repaired examples are inside (a), judged and accepted: the root README's Contact Form form, its Dashboard grid of statistic tiles, and the object-data-table in packages/plugin-dashboard/README.md.
• Nested READMEs do not ship. npm pack --dry-run --json --ignore-scripts in every package directory lists no README below a package root. @object-ui/components publishes dist, README.md, CHANGELOG.md and LICENSE. So README-KANBAN.md stays off the surface and needs no fragment marker. The gate's header records this as a dated reading that the gate does not re-derive.

Classification: empty. The chosen reading newly refuses no README document, so no README is repaired or declared, and no README file is touched.

Gate run, before and after

• Base 9b755099: 184 pages, 227 fences, 185 judged (179 accepted, 6 declared, 0 refused).
• Head e297f3ad: 224 pages (content/docs 184, package READMEs 39, root README 1), 251 fences, 204 judged (198 accepted, 6 declared, 0 refused). All three anchors read. node scripts/check-doc-json-fences.mjs exit 0.

Reverse verification (one-time ablation, not kept as a test)

From committed head e297f3ad, node ../objectstack/scripts/ablation-replace.mjs deleted both README legs from SCAN_SURFACE. Anchor hits went from 1 to 0, and the blob changed from 62fef312061e to 6b5e3d8793fa. Readings with the mutation on disk:

• The gate printed exactly the base surface (184 pages, 227 fences, 185 judged), with exit 0. A content-only surface is green about the READMEs.
• scripts/__tests__/check-doc-json-fences.test.ts: 5 failed | 27 passed (32). The five that failed are the README tests: the refusal in a package README and the root README; the leg order and page counts; the README fragment declaration; the README anchor control; and the equality with the family's legs.
• Restore was proven by the tool: the blob equals HEAD (62fef312061e) and git diff HEAD is empty. After restore: 34 passed (34).

Tests and gates (all at e297f3ad)

Exit codes were captured by redirect-then-read, never through a pipe. Heavy runs went through os-verify-lock, and each result below is its VERDICT command-exit 0 line.

• pnpm exec vitest run scripts/__tests__/check-doc-json-fences.test.ts scripts/__tests__/markdown-test-inputs.test.ts scripts/__tests__/ci-cd-pipeline-doc.test.ts: 3 files, 147 tests passed.
• pnpm exec vitest run --maxWorkers=2 scripts/__tests__/ plus the two packages/components tests that read the markdown ledger: 182 passed, 2 skipped (184 files); 5562 tests passed, 2 skipped.
• pnpm type-check:scripts: exit 0. --listFiles shows the gate, its test and markdown-test-inputs.mjs in the program.
• pnpm check:doc-types 0 · pnpm docs:check-links 0 · pnpm check:new-line-citations 0 (0 new) · pnpm check:control-bytes 0 · pnpm check:doc-fences 0 and --self-test 0 · pnpm check:test-path-roots 0 · node scripts/markdown-test-inputs.mjs --audit 0 · node scripts/check-lint-coverage.mjs 0 · node scripts/check-vi-mock-override-shape.mjs 0.
• pnpm lint:root: exit 0 (0 errors; 34 warnings, all in files this PR does not touch). eslint --format json on the 3 changed script files: 3 files, 0 errors, 0 warnings.
• node scripts/check-changeset-presence.mjs: exit 0, "no changeset is owed". No package source and no README changed.
• node scripts/check-governed-queue-guard.mjs --test (4 paths): NOT GOVERNED.
• First measured run of ci-cd-pipeline-doc.test.ts: red on command parity. My first wording credited the gate's section with a script path that doc-snippet-types.yml does not run. The page wording was changed, and the parity ledger was not touched.
• Not run locally: pnpm check:doc-snippets and pnpm check:doc-examples (they need the full build closure, and this diff adds no ts/tsx fence), and lychee check-links (CI-only tool). CI runs them.

Acceptance notes

• The refused population outside content/docs, re-derived at 9b755099, not copied: 16 node documents. 4 CHANGELOG fences and 1 pending changeset are history. 1 is a docs/audits record (out by triage). 9 are skills/** fences (objectui#12135's surface). 1 is README-KANBAN.md, which is off the surface and not shipped. None is on the widened surface.
• Stale prose noticed, not changed (carrier: none): the NESTED_PACKAGE_READMES docblock in scripts/check-doc-snippet-types.mjs says packages/types lists the whole of src/ in its manifest files, so packages/types/src/zod/README.md ships. Today packages/types files is dist, README.md, CHANGELOG.md, LICENSE, and npm pack ships no nested README. That file is outside this claim.
• Not changed: the "What the three doc gates own" coverage table in that same file has no column for this gate. That is outside this claim (carrier: none).

The session for this run is https://claude.ai/code/session_01DwLS3LzXyNmyTunMGbpc8W.

---

Generated by Claude Code