ci(docs-truth): machine-check R-15 gate status across the contract and the ledger (#933) - #934
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. Warning Review limit reachedEnable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. Next included review available in 10 minutes. View limit detailsLimit details: You’ve used the included review currently available. Your 79 included PR review attempts over the past 7 days set your current allowance at 1 review per hour. Review configuration: ⚙️ Run configurationConfiguration used: Repository: qnbs/WorldScript-Studio/.coderabbit.yaml Review profile: CHILL Plan: Essentials Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughThe pull request adds machine-readable R-15 gate statuses and checks their consistency with the migration ledger and current contract wording. It also extends README test-metric synchronization and updates the displayed test totals. ChangesR-15 Gate-Status Consistency
README Test Metrics
Priority: ⬇️ Low Severity of issue fixed: Low Merge Risk: 🟡 Moderate · up to The new documentation check can accept inconsistent statuses and reject valid wording. Correct these parsing defects before merging; the established impact is documentation enforcement, not storage runtime behavior.
Comment |
🏁 CodeAnt Quality Gate ResultsCommit: ✅ Overall Status: PASSEDQuality Gate Details
|
Reviewer's GuideThis PR replaces hand-maintained R-15 status consistency with a machine-checked contract-to-ledger truth model, including targeted detection of contradictory current prose and regression tests for the previously recurring drift patterns. It also closes a README metric synchronization gap and updates generated documentation metrics. Sequence diagram for R-15 documentation truth validationsequenceDiagram
participant CI as Existing CI or ci:prepush
participant Check as docs:check
participant Contract as Contract §20
participant Ledger as Core Migration Ledger
participant Guard as scanR15GateStatusTruth
CI->>Check: run docs:check
Check->>Contract: read R15-SECURE-STORAGE-CONTRACT.md
Check->>Ledger: read CORE-MIGRATION-LEDGER.md
Check->>Guard: scanR15GateStatusTruth(contract, ledger)
Guard->>Guard: parseR15GateTokens(contract)
Guard->>Guard: parseR15GateTokens(ledger)
Guard-->>Check: findings or empty result
Check-->>CI: pass or fail
Flow diagram for R-15 consistency rulesflowchart TD
Start[Read contract and ledger] --> Block{R15_GATE_STATUS block present?}
Block -->|No| Fail[Report documentation finding]
Block -->|Yes| Compare[Compare ledger R15_GATE tokens with canonical block]
Compare --> Rules[Check non-NOT_ADMITTED gates are present in ledger]
Rules --> Prose[Scan current contract and ledger prose]
Prose --> Contradiction{Implemented or partial gate called not admitted?}
Contradiction -->|Yes, without the rest-of exemption| Fail
Contradiction -->|No or exempt| Pass[docs:check passes]
File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
 |
|
Overall Grade |
Security Reliability Complexity Hygiene |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Docker |  |
Oct 1, 2026 11:42a.m. | Review ↗ |
| Python | |
Oct 1, 2026 11:42a.m. | Review ↗ |
| Rust | |
Oct 1, 2026 11:42a.m. | Review ↗ |
| Shell | |
Oct 1, 2026 11:42a.m. | Review ↗ |
Important
AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
🤖 CodeAnt AI — Review Status
|
Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
the
size:L
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="scripts/check-doc-metrics.mjs" line_range="1289-1293" />
<code_context>
+ /\b(?:(the (?:rest|remainder) of )?Gates? ([1-7])(?:[ab])?(?:\s*[–-]\s*([1-7]))?)/gi;
+
+/** `{ gate → status }` from every `R15_GATE<id>=<STATUS>` token in `text`. */
+export function parseR15GateTokens(text) {
+ const tokens = new Map();
+ for (const [, gate, status] of text.matchAll(R15_GATE_TOKEN)) tokens.set(gate, status);
+ return tokens;
+}
+
+function r15GateKind(status) {
</code_context>
<issue_to_address>
**issue (bug_risk):** Duplicate `R15_GATE*` tokens are silently collapsed into one map entry, so a ledger containing both a stale and a current value for the same gate passes whenever the last occurrence matches the canonical block. The guard therefore does not enforce that every ledger token equals the canonical status.
**Triggers:** When a duplicated gate token is introduced in the ledger or canonical status block.
**Suggested fix:** Reject duplicate gate IDs or report every token occurrence instead of overwriting earlier values in the `Map`.
```suggestion
export function parseR15GateTokens(text) {
const tokens = new Map();
for (const [, gate, status] of text.matchAll(R15_GATE_TOKEN)) {
if (tokens.has(gate)) throw new Error(`duplicate R15 gate ID: ${gate}`);
tokens.set(gate, status);
}
return tokens;
}
```
</issue_to_address>
### Comment 2
<location path="scripts/check-doc-metrics.mjs" line_range="1282-1286" />
<code_context>
+export const R15_CONTRACT_DOC = 'docs/native/R15-SECURE-STORAGE-CONTRACT.md';
+export const R15_LEDGER_DOC = 'docs/native/CORE-MIGRATION-LEDGER.md';
+export const R15_GATE_IDS = ['1A', '1B', '2', '3', '4', '5', '6', '7'];
+const R15_GATE_TOKEN = /\bR15_GATE([0-9][A-Z]?)=([A-Z0-9_+]+)/g;
+const R15_STATUS_BLOCK = /```text\nR15_GATE_STATUS\n([\s\S]*?)```/;
+const R15_NOT_ADMITTED = /\b(?:not admitted|unadmitted)\b/i;
+const R15_GATE_REF =
+ /\b(?:(the (?:rest|remainder) of )?Gates? ([1-7])(?:[ab])?(?:\s*[–-]\s*([1-7]))?)/gi;
+
+/** `{ gate → status }` from every `R15_GATE<id>=<STATUS>` token in `text`. */
</code_context>
<issue_to_address>
**issue (bug_risk):** The token parser accepts arbitrary gate identifiers and arbitrary uppercase status values, while validation only checks that the eight expected IDs exist and that ledger entries agree with whatever the block says. A canonical block can therefore contain an invalid status such as `R15_GATE4=IMPLEMENTED_TYPO`, and the guard classifies it as implemented and accepts it rather than rejecting the malformed status.
**Triggers:** When a status block contains a typo or an unsupported status value.
**Suggested fix:** Validate canonical IDs and statuses against an explicit allowlist, and reject unknown or malformed `R15_GATE*` entries.
</issue_to_address>Sourcery assessment
Approval pending. 2 findings to address first.
Blocking findings: scripts/check-doc-metrics.mjs:1293, scripts/check-doc-metrics.mjs:1286
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: qnbs/WorldScript-Studio/.coderabbit.yaml
Review profile: CHILL
Plan: Essentials
Run ID: 5970014f-28c9-4ce5-9238-167d429353e5
📒 Files selected for processing (7)
CHANGELOG.mdREADME.mddocs/native/R15-SECURE-STORAGE-CONTRACT.mdscripts/check-doc-metrics.d.mtsscripts/check-doc-metrics.mjsscripts/sync-readme-metrics.mjstests/unit/checkR15GateStatus.test.ts
Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f16586d24a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 7 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
There was a problem hiding this comment.
cubic analysis
Review completed against the latest diff
Linked issue analysis
| Status | Acceptance criteria | Notes |
|---|---|---|
| ✅ | Add a canonical machine-readable R-15 gate-status block to the contract. | The contract adds an `R15_GATE_STATUS` block with entries for Gates 1A–7. |
| Require the ledger’s R15_GATE tokens to match the contract block, detecting missing, extra, or different values. | Different and extra ledger tokens are detected, and missing progressed-gate tokens are detected. However, missing `NOT_ADMITTED` tokens are allowed, so the implementation does not enforce full token equality as specified. | |
| ✅ | Detect current prose that calls a gate range not admitted when the canonical block marks a gate in that range partial or implemented, while ignoring historical sections. | The scanner checks current contract and ledger prose for the specified contradiction, allows the documented “rest of” partial-gate wording, and strips historical sections. |
| Add unit tests for agreement, token mismatch, missing gates, range contradictions, and historical-section handling. | Tests cover agreement, mismatches, a missing gate from the block, missing progressed gates from the ledger, contradictions, and historical sections. They do not cover omission of a `NOT_ADMITTED` ledger token, which the implementation also permits. | |
| ✅ | Run the guard through the existing docs:check path and reconcile the live documents. | The checker invokes the guard on both live documents, and a live-repository test asserts they produce no findings. The PR reports docs:check passes. |
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
[check-pr-size] PR size is over the target tier (normal profile): 10 files, 567 meaningful lines, 2 commits — limit ≤8 files / ≤400 lines / ≤6 commits. Consider splitting into smaller, independently reviewable PRs. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 900c31cf52
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
All reported issues were addressed across 9 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
…d the ledger (#933) The contract's single R15_GATE_STATUS block is canonical. scripts/check-r15-gate-status.mjs requires it to be well formed (every gate once, fixed statuses or a slice of the same gate), ledger row 10 to agree with it, and no current prose to call a gate or a delivered slice not admitted. Runs in pnpm docs:check and ci:prepush, outside the protected merge-admission evaluator graph.
900c31c to
59ee541
Compare
There was a problem hiding this comment.
Gates Passed
See analysis details in CodeScene
Quality Gate Profile: The Bare Minimum
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59ee5411b3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
All reported issues were addressed across 4 files (changes from recent commits).
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
2 participants
Summary
Resolves #933 (Linear QNB-177; parent learning lane #780 / QNB-90). This is the recurrence-prevention mechanism for a validated defect class.
Recurring defect: R-15 gate status was hand-maintained in three places (contract header §0, contract §21, Core Migration Ledger row 10). Reviewers caught contradictions between them in four consecutive PRs: #917, #928, #929 and #930, for example "Gates 3–7 not admitted" next to "Gate 3 slice 3A implemented". Each one cost a correction wave.
Mechanism: the gate status becomes executable instead of prose-only.
R15_GATE_STATUSblock (R15_GATE1A…R15_GATE7)scripts/check-r15-gate-status.mjs, chained intopnpm docs:check(CI) and its ownci:prepushstage. It is deliberately outside the protected merge-admission evaluator graph:check-doc-metrics.mjschanges only through a base-owned protected transition, and it is byte-identical to base here.NOT_ADMITTEDSLICE_*) without "the rest of" that gateThe current docs pass. Each seeded contradiction fails, including both shapes reviewers caught.
Tests (
tests/unit/checkR15GateStatus.test.ts, 12 tests)The parser keeps gate references with their status across commas and soft wraps, separates sentences and contrastive clauses, resolves
Gate 1a/1band slice references (Gate 3B,Gate 3 slice 3B) exactly, and ignores historical sections, code fences and HTML comments. After the first review epoch it also rejects conflicting duplicates (in either order), extra tokens and typo statuses.Also
sync:readmenow also updates the project-tree line "Vitest unit tests (the N+ total …)", whichdocs:checkalready verified but no synchronizer rule covered. README metrics stay generated, not hand-edited.Scope
Not included: gate decisions themselves (gate PRs still update the block), public-doc parity (#724/#932), roadmap reset (#559), and required-check or branch-protection changes.
Local proof
docs:checkOK;checkDocMetricsandcheckR15GateStatustests pass (142 total);pnpm run ci:prepushpasses.Fixes #933
Part of #780
Summary by Sourcery
Enforce synchronized R-15 gate status across the storage contract and migration ledger through automated documentation validation.
New Features:
Bug Fixes:
Enhancements:
CI:
Documentation:
Tests:
Chores:
Summary by cubic
Machine-checks R-15 gate status so the storage contract and Core Migration Ledger can't drift. Gate status was hand-maintained in three places and reviewers caught contradictions across four consecutive PRs; the contract's §20
R15_GATE_STATUSblock is now the single source, enforced by a new standalone guard run fromdocs:checkandci:prepush.R15_GATE*tokens differ from the block, when the ledger omits a gate that isn'tNOT_ADMITTED, or when current prose calls an implemented or partial gate "not admitted".sync:readmenow also updates the project-tree "Vitest unit tests (the N+ total …)" line, and the changelog records the guard, so README and changelog metrics stay generated.Written for commit 59ee541. Summary will update on new commits.
Summary by CodeRabbit