ci(docs-truth): machine-check R-15 gate status agreement between the contract and the Core Migration Ledger

[qnbs]

Problem (validated recurrence)

R-15 gate status is maintained by hand in three places that have to agree:

1. docs/native/R15-SECURE-STORAGE-CONTRACT.md header status line (§0);
2. the contract's §21 closing status sentence;
3. docs/native/CORE-MIGRATION-LEDGER.md row 10, both its R15_GATE* tokens and its prose.

Reviewers caught contradictions between them in four consecutive PRs: #917 (cubic), #928 (cubic), #929 (Codex + cubic) and #930 (CodeRabbit + cubic). A typical case: the ledger said "Gates 3–7 not admitted" next to "Gate 3 slice 3A implemented". Every instance cost a correction wave. Learning record: #780 (comment of 2026-10-01).

Root cause

There is no single machine-readable source of gate status, and nothing deterministic compares the three statements. Agreement depends on reviewers noticing.

Scope

• One canonical, machine-readable R-15 gate status block in the binding contract (one token per gate: NOT_ADMITTED, PARTIAL, IMPLEMENTED_HEADLESS, …).
• A pure scanR15GateStatusTruth in scripts/check-doc-metrics.mjs (the existing docs:check, which already runs in CI and ci:prepush) that fails when:
  • the ledger's R15_GATE* tokens differ from the contract block (missing, extra or different values);
  • current, non-historical prose in the contract header, §21 or ledger row 10 calls a gate range "not admitted" or "unadmitted" while the block marks a gate in that range as partial or implemented.
• Unit tests in tests/unit/checkDocMetrics.test.ts for agreement, token mismatch, a missing gate, the range contradiction, and historical sections being ignored.
• Bring the docs to the canonical state in the same PR.

Non-goals

• Deciding gate status (the gate PRs still do that).
• Parsing arbitrary prose beyond the specific contradiction pattern above.
• README/GitBook public-doc parity (docs(authority): keep README.md, GitBook EN/DE and DeepWiki continuously accurate and source-truth aligned #724, docs(release): pre-v1.30 public-doc parity, DEV.to discoverability and bounded housekeeping checkpoint #932).
• Roadmap/TODO reconciliation (docs(roadmap): reconcile root v2 status with native roadmap and Core migration ledger #559).
• Changing required checks or branch protection.

Acceptance

• pnpm docs:check fails on each seeded contradiction and passes on the reconciled docs.
• Unit tests cover every failure mode.
• The guard runs through the existing docs:check CI path, so no workflow change is needed.
• Exact-head review/CI converges, followed by resulting-main proof.

Owners

• Parent learning lane: governance(reviews): adaptive multi-reviewer convergence, authority and repository learning #780.
• Protected subject: security(core/R-15): renderer-neutral encrypted desktop storage, durable migration & identity binding #445 (R-15).
• Related: docs(authority): keep README.md, GitBook EN/DE and DeepWiki continuously accurate and source-truth aligned #724, docs(roadmap): reconcile root v2 status with native roadmap and Core migration ledger #559.
• Scheduled as its own small PR right after feat(core): add Gate 3 slice 3A durable staging and promotion (#445) #930 (Gate 3A) and before Gate 3B, so later slices run under the guard.

[qnbs]

PR #934 first-epoch checkpoint — 2026-10-01

Current head: f16586d24af29fc5ab9cd34a53d3f8ddf69509ac.

The first full reviewer/CI epoch found real guard-correctness gaps that belong in one coherent correction wave:

• preserve Gate 1A / 1B suffix semantics;
• reject duplicate gate tokens;
• reject unknown gate IDs and unsupported status values;
• bind "not admitted" status to the correct sentence/clause across commas and Markdown soft wraps;
• do not let status in one sentence apply to gate references in another;
• distinguish unadmitted sub-slices (for example Gate 3B) from claiming the whole partial Gate 3 is unadmitted;
• strip fenced code / HTML comments from current-prose evaluation;
• require the canonical block in the governed contract location and ledger tokens in the governed ledger row;
• add direct regression coverage for extra/unknown ledger tokens;
• reduce the new nested-conditional code-health findings naturally if practical.

CI/CD failure classification

CI/CD run 36851869000 failed only at Security Audit because Gitleaks identified a synthetic test fixture string in tests/unit/checkR15GateStatus.test.ts as generic-api-key.

Evidence:

• pnpm audit --audit-level=high = clean;
• OSV scanner = No issues found;
• Gitleaks finding = test fixture, commit b20d7e47..., line ~35;
• no real secret is established by this evidence.

Treat this as a test-fixture/secret-scanner compatibility defect to correct in the same wave. Do not weaken Gitleaks or add a broad suppression if a clearly non-secret fixture representation can preserve the test.

After the correction wave: exact-head CI/security/reviewer revalidation, normal merge, resulting-main proof, then return immediately to Gate 3B.

[qnbs]

PR #934 current-head checkpoint — 2026-10-01

Supersedes the first-epoch checkpoint above.

PR = #934
BASE = main@01230de4758208f7b682ef9548720b0fd39ce801
HEAD = 59ee5411b3f5a3642944fddc967349816d551b56
MERGEABLE = YES
MERGE_READY = NO
STATE = current-head epoch; one correction wave still required

Exact-head reviewer classification:

• CodeScene: approved.
• Sourcery: approved.
• CodeRabbit: current commit status success.
• DeepSource: Rust/Python/Shell/Docker success; JS remains intentionally off.
• CodeAnt: Quality/Test Coverage/SCR/SAST/SCA success.
• CodeQL: success.
• Codex: 3 P2 findings on 59ee5411....
• Cubic: 3 P2 findings on 59ee5411...; two overlap Codex.

Four unique material correction clusters remain:

1. canonical R15_GATE_STATUS must be parsed as strict line-based data and reject any non-entry/trailing garbage;
2. fenced-code state must be established before HTML-comment stripping so a literal unterminated <!-- inside a code example cannot hide later current prose;
3. coordinated references such as Gates 4 and 3 must check every named gate;
4. duplicate and unsupported-status diagnostics must be evaluated independently for malformed duplicate entries.

CI/CD 36857035693: Security Audit, policy, size, signatures, Node 22/24, Deep Coverage, Build, Storybook and Browser Quality are green; Playwright E2E is the only job still running at this readback. Vercel Preview for exact head is READY.

Do not micro-push or merge. Complete the epoch, apply the four clusters plus focused regression tests as one bounded correction wave, exact-head revalidate, merge normally only when terminal, prove resulting main, then immediately resume Gate 3B.

[qnbs]

Terminal resulting-main checkpoint — 2026-10-01

PR #934 is merged and #933 is correctly closed.

RESULTING_MAIN = c4240125785df66bb1d298f416c8db6bc965de60
CI/CD = SUCCESS
CODEQL = SUCCESS
GITHUB_PAGES = SUCCESS
VERCEL_PRODUCTION = READY on exact resulting-main SHA
FOLLOW_UP = #935 / PR #936

The canonical R-15 gate-status block and deterministic contract↔ledger/prose guard are therefore terminal. Late P2 parser hardening found on #934's frozen merge head is intentionally isolated in #935/#936; it does not reopen this issue or invalidate the resulting-main proof.