ci(docs): enforce governed knowledge records

[testikun]

Problem

Issue #198 established the forward-only knowledge and evidence contract, but new Research and Benchmark records still have no repository check for required metadata, category-index reachability, or local link integrity. A complete-looking Benchmark can therefore omit frozen identities, accounting, failure classification, limitations, or a retrievable evidence reference without failing CI.

Value

• Makes future governed Research and Benchmark records reviewable from a clean checkout.
• Keeps legacy documents untouched until an explicit migration.
• Fails visibly on structural evidence gaps without claiming that a well-formed record is independently validated.

Approach

• Add a dependency-free check-knowledge-contract.mjs for governed records under docs/research and docs/benchmarks.
• Treat frontmatter as the explicit opt-in boundary; only explicitly enumerated historical records without it remain legacy; new frontmatter-less records fail closed.
• Require shared lifecycle/provenance metadata, Research fact/inference/recommendation/unknown sections, and Benchmark source/model/task/verifier/accounting/failure/limitations/evidence/rerun fields.
• Verify every governed record is linked from its category index and that repository-relative Markdown links resolve inside the checkout.
• Add Research and Benchmark templates, wire the check into bun run check, and append the Decision-0001-backed promise to the discipline ledger.
• Keep this complementary to ci: validate decision document metadata #309, whose open PR validates Decision-only metadata.

Validation

• bun run check — passed.
• bun run test — passed: 1246 Node tests passed, 1 platform test skipped; 30/30 Vitest tests passed.
• Focused knowledge-contract tests — 5/5 passed, covering valid records, legacy exclusion, missing Benchmark evidence fields, unindexed records, and broken links.
• git diff --check — passed.

Impact

• User-visible behavior: none.
• Model-visible context/tools: none.
• Runtime/lifecycle: none; CI/documentation validation only.
• Persisted config/data: none.
• Compatibility/risk: low. Only explicitly enumerated historical records without frontmatter remain exempt; new frontmatter-less records fail closed, and no ignored/local evidence is scanned or published.

Refs #198.

[tt-a1i]

方向对，覆盖面不够

docs/README.md 治理的是 research、design、architecture、Decision、benchmarks。检查器只扫了 docs/research 和 docs/benchmarks。#386/#382 这种 validated 的 architecture/design 记录现在不会被拦。

请扩到 design / architecture / Decision，或明确写「其余类别暂不强制」并改 README。#309 是 Decision-only 且 Windows 路径 fail-open，请吸收进来，不要并排合。

frontmatter 选择加入、「结构 ≠ 验证」是对的。

[tt-a1i]

Exact-head review: 81320b2

[P1] The new CI contract is opt-out, so it does not enforce the forward-only policy for new records. scripts/check-knowledge-contract.mjs:136-142 classifies every frontmatter-less research/benchmark Markdown file as legacy and skips it. A contributor can therefore add a brand-new record without frontmatter and bypass required metadata, index reachability, links, frozen identities, accounting, failures, limitations, and evidence checks while bun run check remains green.

Decision 0001 says documents from that Decision forward are governed; legacy is a fixed historical set, not a property a new file may claim by omitting metadata. Please encode an immutable legacy allowlist or baseline and fail closed for every new unlisted record. Add a regression proving that a newly added frontmatter-less record fails, while the enumerated pre-Decision records remain accepted.

Verification boundary: exact-head checker/policy review. Existing tests intentionally assert the bypass as legacy exclusion, so their green result confirms rather than mitigates the issue.

[tt-a1i]

Follow-up review of 3dd872b: the previously reported frontmatter opt-out P1 is addressed by the fixed LEGACY_RECORDS allowlist and the new rejection regression. I reran node --test --experimental-strip-types tests/scripts/knowledge-contract.test.ts in an isolated exact-head worktree: 6 passed, 0 failed (exit 0). This does not constitute full approval or evidence validation.

Please synchronize the remaining opt-in wording in the PR description and Research index with the implementation. The checker currently covers research/benchmarks only; retain an explicit statement of that enforcement scope. The required Windows CI is still red: job 101235332304 reports Timed out waiting for local git info in tests/extensions/git-info/index.test.ts. I have not established that failure as a product regression or a flake; refresh against main and obtain a green required matrix before merge.

[testikun]

@tt-a1i 已明确 scope：checker 只治理 docs/research 与 docs/benchmarks；其他文档不受影响，Decision-only/Windows fail-open 仍由 #309 覆盖。

[testikun]

@tt-a1i 已修复 P1：legacy 仅来自不可变显式 allowlist，新建无 frontmatter 记录 fail closed，并补回归与 CI。

[testikun]

@tt-a1i 已同步 PR 说明与 Research index：仅显式列出的历史记录可免 frontmatter；新记录 fail closed，checker scope 仍为 research/benchmarks。

[testikun]

已推送 166645d，同步最新 main 并修复合并后知识契约失败：为 main 新增的 9 条 research 记录补齐 frontmatter、分类章节和索引治理；Research README 明确 checker 当前只强制 research/benchmarks 范围。node scripts/check-knowledge-contract.mjs 通过（9 governed records），知识契约测试 6/6 通过。

[tt-a1i]

Reviewed exact head 166645d.

This is a high-value, low-runtime-risk CI guard, but its central fail-closed evidence promise is still bypassable:

• [P1] evidence-reference and rerun-entry-point are checked only for non-empty strings. Markdown body links are resolved separately, but those metadata values are never resolved. A validated Benchmark with evidence-reference: missing-evidence.json, rerun-entry-point: missing-command, and no body link passes with zero problems. Require a resolvable repository target or valid external/archive identity and add a missing-evidence regression.
• [P1] README.md and TEMPLATE.md are exempted by basename at every depth. A new docs/research/topic/README.md without frontmatter is silently omitted. Restrict exemptions to the explicit category-root files or a fixed path allowlist.
• [P2] Index reachability is a raw substring check, so a target appearing only inside an HTML comment is accepted as indexed. Parse actual Markdown links outside comments/code.
• [P2] Migrated values such as related-issues: #428 parse as comments/null under standard YAML even though the bespoke parser accepts them. Quote them or explicitly define a non-YAML format.

Focused tests, bun run check, hosted CI, and the current-main merge-tree are green, but adversarial fixtures reproduce the P1 bypasses. After these narrow fixes, this PR is worth merging.