docs(site): VitePress site with static SVG diagrams (no Mermaid runtime)#64
docs(site): VitePress site with static SVG diagrams (no Mermaid runtime)#64flyingrobots merged 129 commits intomainfrom
Conversation
Fix a Mermaid diagram syntax error. Signed-off-by: James Ross <james@flyingrobots.dev>
Adds hyperlinks to Echo and to Ch 9 Signed-off-by: James Ross <james@flyingrobots.dev>
Fix a Mermaid diagram Signed-off-by: James Ross <james@flyingrobots.dev>
Add footer Signed-off-by: James Ross <james@flyingrobots.dev>
Add footer Signed-off-by: James Ross <james@flyingrobots.dev>
Footer Signed-off-by: James Ross <james@flyingrobots.dev>
Footer Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
Signed-off-by: James Ross <james@flyingrobots.dev>
…ing (git gatos vs gatosd) in diagrams\n- Add hello guides, audience, glossary to README\n- CH1: fix Next link, reorder planes, add refs legend\n- CH2: adopt DAG-CBOR, Event-CID, signing and update-ref docs\n- CH3: checkpoint trailers, policy_root⇒state_root, DPO example; https Echo link\n- CH4: key management section; quorum example with PoC\n- CH5: refine attestation cost; mirror handling; 3-layer enforcement; dual remotes\n- CH6: at-least-once semantics; single claim lock ref; retention guidance; PoE specimen\n- CH7: worked mind-meld example; schemas path; ADR cites\n- CH8: normative APIs, error framing, keepalives; end-to-end flow; ADR-0010\n- CH9: policy dependency note; independence predicate; quick-ref\n- CH10: PoE clarifications; opaque pointer privacy fix; BAA; ZK envelope stub\n- CH11: fix typo; cache keys; explorer checksum; git config; invalidation & indexing\n- CH12: operationalize TimeCube (Aion, Kairos, Confluence)
…emantics; single job claim lock ref; opaque pointer privacy note; JSONL error/keepalive frames
…gy note; add Mermaid version note for gitGraph
…TOS into two full walkthroughs and link from guide README
…-SPEC, and guide README
…(SPEC/TECH-SPEC § linking)
…GH Pages workflow; prebuild linkify/anchors; modern theme
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Summary by CodeRabbitNew Features
Documentation
Chores
WalkthroughAdds a VitePress docs site and theme, many new and reorganized Markdown docs (guide, SPEC/TECH‑SPEC, CLI, ADRs, ROADMAP), three fence‑aware Python prebuild scripts for anchors/TOC/linking, npm config tweaks, GitHub Actions for Pages deploy/preview, and related repo housekeeping. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant Repo as Git
participant GHA as GitHub Actions
participant Scripts as Prebuild Scripts
participant VP as VitePress
participant Pages as gh-pages
Dev->>Repo: push to main / open PR
Repo->>GHA: trigger pages-deploy / pages-preview
GHA->>GHA: checkout + setup Node 20.x
GHA->>Scripts: run linkify_chapters / linkify_refs / anchors_and_toc
Scripts->>Scripts: modify docs (anchors, links, TOC)
GHA->>VP: build docs (DOCS_BASE set)
VP->>VP: mermaidToImg() resolves pre-generated assets or falls back
VP->>GHA: produce docs/.vitepress/dist
GHA->>Pages: deploy dist → gh-pages (or PR preview)
sequenceDiagram
participant MD as Markdown
participant VP as VitePress parser
participant FS as Filesystem
MD->>VP: parse file, encounter ```mermaid fence
VP->>FS: lookup diagrams/generated/{hash|legacy}_{file}_{n}.{light,dark}.svg
alt asset exists
FS-->>VP: return asset URLs
VP->>VP: inject <figure> with theme-aware image URLs
else
VP->>VP: fallback to default mermaid renderer
end
VP->>VP: render HTML output
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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.
ℹ️ 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".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (9)
.github/workflows/docs.yml(1 hunks).npmrc(1 hunks)docs/.vitepress/config.ts(1 hunks)docs/.vitepress/theme/index.ts(1 hunks)docs/.vitepress/theme/vars.css(1 hunks)package.json(1 hunks)scripts/anchors_and_toc.py(1 hunks)scripts/linkify_chapters.py(1 hunks)scripts/linkify_refs.py(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (4)
scripts/linkify_refs.py (2)
scripts/anchors_and_toc.py (1)
process(35-66)scripts/linkify_chapters.py (1)
process(7-21)
docs/.vitepress/config.ts (1)
scripts/mermaid/generate.mjs (2)
files(139-139)rel(129-129)
scripts/linkify_chapters.py (2)
scripts/anchors_and_toc.py (1)
process(35-66)scripts/linkify_refs.py (1)
process(9-17)
scripts/anchors_and_toc.py (2)
scripts/linkify_chapters.py (1)
process(7-21)scripts/linkify_refs.py (1)
process(9-17)
🪛 Ruff (0.14.4)
scripts/linkify_refs.py
12-12: Multiple statements on one line (semicolon)
(E702)
12-12: Multiple statements on one line (semicolon)
(E702)
14-14: Multiple statements on one line (colon)
(E701)
14-14: Multiple statements on one line (semicolon)
(E702)
14-14: Multiple statements on one line (semicolon)
(E702)
15-15: Multiple statements on one line (colon)
(E701)
15-15: Multiple statements on one line (semicolon)
(E702)
16-16: Multiple statements on one line (semicolon)
(E702)
16-16: Multiple statements on one line (semicolon)
(E702)
17-17: Multiple statements on one line (colon)
(E701)
scripts/linkify_chapters.py
9-9: Missing return type annotation for private function repl
Add return type annotation: str
(ANN202)
13-13: Multiple statements on one line (semicolon)
(E702)
13-13: Multiple statements on one line (semicolon)
(E702)
15-15: Multiple statements on one line (colon)
(E701)
15-15: Multiple statements on one line (semicolon)
(E702)
15-15: Multiple statements on one line (semicolon)
(E702)
16-16: Multiple statements on one line (colon)
(E701)
16-16: Multiple statements on one line (semicolon)
(E702)
scripts/anchors_and_toc.py
6-6: Multiple statements on one line (semicolon)
(E702)
10-10: Multiple statements on one line (semicolon)
(E702)
17-17: Multiple statements on one line (semicolon)
(E702)
21-21: Multiple statements on one line (colon)
(E701)
22-22: Multiple statements on one line (semicolon)
(E702)
23-23: Multiple statements on one line (colon)
(E701)
29-29: Multiple statements on one line (colon)
(E701)
31-31: Multiple statements on one line (semicolon)
(E702)
33-33: Multiple statements on one line (semicolon)
(E702)
36-36: Multiple statements on one line (semicolon)
(E702)
36-36: Boolean positional value in function call
(FBT003)
37-37: Multiple statements on one line (semicolon)
(E702)
37-37: Multiple statements on one line (semicolon)
(E702)
37-37: Multiple statements on one line (semicolon)
(E702)
37-37: Multiple statements on one line (semicolon)
(E702)
41-41: Multiple statements on one line (semicolon)
(E702)
41-41: Multiple statements on one line (semicolon)
(E702)
41-41: Multiple statements on one line (semicolon)
(E702)
45-45: Multiple statements on one line (semicolon)
(E702)
47-47: Multiple statements on one line (colon)
(E701)
52-52: Multiple statements on one line (semicolon)
(E702)
53-53: Multiple statements on one line (semicolon)
(E702)
54-54: Multiple statements on one line (semicolon)
(E702)
61-61: Multiple statements on one line (colon)
(E701)
61-61: Multiple statements on one line (semicolon)
(E702)
65-65: Multiple statements on one line (semicolon)
(E702)
65-65: Multiple statements on one line (semicolon)
(E702)
66-66: Multiple statements on one line (colon)
(E701)
🪛 YAMLlint (1.37.1)
.github/workflows/docs.yml
[warning] 3-3: truthy value should be one of [false, true]
(truthy)
[error] 5-5: too many spaces inside brackets
(brackets)
[error] 5-5: too many spaces inside brackets
(brackets)
[error] 40-40: too many blank lines (1 > 0)
(empty-lines)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Link Check (xtask links)
- GitHub Check: Mermaid Diagrams Generate + Verify
- GitHub Check: audit
🔇 Additional comments (2)
.github/workflows/docs.yml (1)
10-13: LGTM! Permissions follow least privilege principle.The permissions are correctly scoped for GitHub Pages deployment: read-only content access, write access for Pages, and id-token for OIDC authentication. This follows GitHub's recommended security practices.
docs/.vitepress/config.ts (1)
72-76: LGTM! Markdown configuration correctly applies custom renderer.The markdown configuration properly invokes
mermaidToImg()to customize the fence renderer. The structure is clean and follows VitePress conventions.Note: This assumes the issues flagged in the
mermaidToImg()function (lines 20-39) are addressed.
|
PR Preview (canonical) |
There was a problem hiding this comment.
Actionable comments posted: 21
♻️ Duplicate comments (8)
docs/STAKEHOLDERS.md (2)
99-99: Minor: Fix grammar—use noun form "denials" not verb "denies".Line 99 uses a verb form that breaks the noun-phrase pattern of the Goals Synopsis bullets.
- - `SEC`: artifacts-as-law, explainable denies, signatures everywhere. + - `SEC`: artifacts-as-law, explainable denials, signatures everywhere.
10-10: CRITICAL: Two broken TOC navigation links—anchor ID fragments do not resolve.Verification confirms the mismatch:
Line 10 (TOC): references
#sre-ops-sre(single dash)
Line 56 (anchor): definesid="sre--ops-sre"(double dash) ← BROKENLine 12 (TOC): references
#auditor-grc-aud(single dash)
Line 73 (anchor): definesid="auditor--grc-aud"(double dash) ← BROKENClicking these TOC items produces silent failures—no scroll, no visual feedback. All other 10 anchors correctly use single dashes; these two are inexplicable anomalies.
Also flagged: Line 99 grammar error.
explainable denies→ must beexplainable denials(requires noun form).Fix required:
- <a id="sre--ops-sre"></a> + <a id="sre-ops-sre"></a>- <a id="auditor--grc-aud"></a> + <a id="auditor-grc-aud"></a>- `SEC`: artifacts-as-law, explainable denies, signatures everywhere. + `SEC`: artifacts-as-law, explainable denials, signatures everywhere.Then test: click each fixed TOC link in a browser and verify the page scrolls to the correct section heading.
docs/TASKS.md (1)
3-3: ---CRITICAL: Duplicate anchor IDs throughout document — multiple violations of HTML spec.
The file contains three locations with duplicate anchor tags that violate HTML validity and create fragile fragment navigation:
Line 3 (document header):
-<a id="gatos--task-breakdown"></a><a id="gatos-task-breakdown"></a> +<a id="gatos-task-breakdown"></a>Line 71 (EPIC-6 section):
-<a id="epic-6-cas--opaque-pointers"></a><a id="epic-6-cas-opaque-pointers"></a> +<a id="epic-6-cas-opaque-pointers"></a>Line 80 (EPIC-7 section):
-<a id="epic-7-epochs--compaction"></a><a id="epic-7-epochs-compaction"></a> +<a id="epic-7-epochs-compaction"></a>Each location has a malformed double-dash variant (from
&character handling) and a correct single-dash variant. Remove the double-dash anchors on all three lines. Ensure the single-dash versions match TOC links.docs/USE-CASES.md (1)
17-17: 🔴 CRITICAL: Duplicate anchor ID violates HTML spec—line 17 repeats line 3.Lines 3 and 17 both define
<a id="gatos-use-cases"></a>. This violates HTML ID uniqueness and causes unpredictable anchor resolution in browsers and VitePress navigation. The anchor at line 17 (orphaned after TOC) is redundant and must be removed.<!-- AUTOGENERATED TOC END --> -<a id="gatos-use-cases"></a> - > *Have **you** tried GATOS yet?*This issue was flagged in past reviews but remains unfixed. Verify that the prebuild script (
scripts/anchors_and_toc.py) is not reintroducing duplicate anchors on rebuild.docs/cli/pox.md (1)
7-15: 🛑 CRITICAL: Orphaned H1 anchor duplicate after TOC block.Line 7 correctly places the H1 anchor
<a id="git-gatos-pox-proof-of-experiment"></a>immediately after the heading. Line 15 repeats the identical anchor after the TOC block, creating a duplicate ID violation.Remove line 15 entirely:
<!-- AUTOGENERATED TOC END --> -<a id="git-gatos-pox-proof-of-experiment"></a> Create, show, verify, and reproduce PoX bundles...docs/cli/foldc.md (1)
7-16: 🛑 CRITICAL: Orphaned H1 anchor duplicate after TOC block.Line 7 correctly anchors the heading. Line 16 repeats the identical ID after the TOC, creating a duplicate ID violation in the DOM.
Remove line 16:
<!-- AUTOGENERATED TOC END --> -<a id="git-gatos-foldc-compile-echolua-to-elc"></a> Compiles EchoLua source...docs/cli/policyc.md (1)
7-16: 🛑 CRITICAL: Orphaned H1 anchor duplicate after TOC block.Line 7 correctly anchors the heading. Line 16 repeats the identical ID after the TOC, creating a duplicate.
Remove line 16:
<!-- AUTOGENERATED TOC END --> -<a id="git-gatos-policyc-compile-.rgs-policy-to-rgcelc"></a> Compiles the declarative policy DSL...docs/TECH-SPEC.md (1)
210-210: Fix capitalization: "macos" → "macOS".Apple's operating system is officially capitalized as "macOS", not "macos". While minor, this matters in professional technical documentation for a normative specification.
- - Golden vectors across linux/macos/windows/wasm; integer and fixed‑point cases; poison tests for NaNs/signed zero/table iteration. + - Golden vectors across linux/macOS/windows/wasm; integer and fixed‑point cases; poison tests for NaNs/signed zero/table iteration.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (23)
docs/FAQ.md(26 hunks)docs/FEATURES.md(8 hunks)docs/ROADMAP-XTASK.md(2 hunks)docs/ROADMAP.md(1 hunks)docs/SPEC.md(28 hunks)docs/STAKEHOLDERS.md(2 hunks)docs/TASKS.md(4 hunks)docs/TECH-SPEC.md(17 hunks)docs/USE-CASES.md(2 hunks)docs/cli/export.md(1 hunks)docs/cli/foldc.md(1 hunks)docs/cli/lint.md(1 hunks)docs/cli/policyc.md(1 hunks)docs/cli/pox.md(1 hunks)docs/decisions/ADR-0001/DECISION.md(4 hunks)docs/decisions/ADR-0001/flyingrobots.md(2 hunks)docs/decisions/ADR-0002/DECISION.md(9 hunks)docs/decisions/ADR-0003/DECISION.md(7 hunks)docs/decisions/README.md(2 hunks)docs/deterministic-lua.md(1 hunks)docs/diagrams/api_endpoints.md(2 hunks)docs/diagrams/architecture.md(1 hunks)docs/diagrams/data_flow.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/FAQ.md
[grammar] ~532-~532: Use a hyphen to join words.
Context: ...ecution must be pure, total, side-effect free. Same inputs ⇒ same bytes. --- ##...
(QB_NEW_EN_HYPHEN)
docs/STAKEHOLDERS.md
[grammar] ~99-~99: Ensure spelling is correct
Context: ... - SEC: artifacts-as-law, explainable denies, signatures everywhere. - SRE: exactl...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/TECH-SPEC.md
[uncategorized] ~210-~210: The operating system from Apple is written “macOS”.
Context: ...Testing: - Golden vectors across linux/macos/windows/wasm; integer and fixed-point c...
(MAC_OS)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Mermaid Diagrams Generate + Verify
- GitHub Check: Schema validation (v1)
- GitHub Check: audit
🔇 Additional comments (8)
docs/diagrams/data_flow.md (1)
3-3: ****The SVG file is present and correctly mapped. Verification found
docs_diagrams_data_flow__559f0c180d__mermaid_1.svgcommitted indocs/diagrams/generated/, with a legacy-compatible naming fallback (docs__diagrams__data_flow__mermaid_1.svg). The build system indocs/.vitepress/config.tsperforms explicit SVG discovery viafs.existsSyncchecks (lines 46–47) with dual-naming lookup (hashed and legacy paths, lines 65–66), eliminating any silent failure modes. No action required.Likely an incorrect or invalid review comment.
docs/STAKEHOLDERS.md (1)
25-25: ✅ Duplicate anchor fix confirmed—no regression.Verification confirms zero duplicate anchor IDs. All 11 anchors are unique (count=1 each), and total tags match total unique IDs. The fix from commit 66c0e65 persists across all stakeholder sections (lines 3, 25, 29, 38, 47, 56, 65, 73, 80, 87, 95).
docs/cli/lint.md (1)
1-40: ✅ Anchor deduplication verified—file is clean.Unlike FEATURES.md and deterministic-lua.md, this file shows no duplicate anchor IDs, no orphaned anchors after TOC, and no inline anchor variants. Each heading has exactly one canonical anchor with consistent kebab-case formatting.
Past commit 49c0bff appears to have successfully resolved the anchor duplication for this file.
docs/cli/export.md (1)
1-40: ✅ Anchor deduplication verified—file is clean.Like lint.md, this file shows no duplicate anchor IDs, no orphaned anchors, and no inline anchor variants. Each heading has a single canonical anchor with consistent kebab-case formatting.
Past commit f7ebd70 appears to have successfully resolved the anchor issues for this file.
docs/diagrams/architecture.md (1)
3-3:⚠️ CRITICAL VERIFICATION NEEDED: H1 anchor duplication on architecture diagram.Line 3 shows
<a id="gatos-system-architecture"></a>. Past reviews documented this file had 5 identical duplicate anchor IDs on the H1 heading at lines 3, 6, 8, 10, and 12. The provided annotation only shows lines 1–59, so full-file verification is required.If duplicates still exist, regenerate immediately:
python scripts/anchors_and_toc.py --write --paths docs/diagrams/architecture.mdVerify:
grep -c '<a id="gatos-system-architecture"></a>' docs/diagrams/architecture.md # Must return exactly 1; prior state showed 5docs/SPEC.md (1)
3-3: INCORRECT REVIEW COMMENT—Zero duplicate anchors detected.Evidence from verification:
- Total anchor tags in file: 142
- Unique anchor IDs: 142
- Duplicate IDs: 0 (0.0% corruption rate)
The file is not corrupted. Every single anchor ID is unique. The fixes from commits
9f8eae7,c5bb1c7, and4fd428aalready resolved genuine duplication issues and normalized the file.Why the review is wrong:
The original review conflated two distinct concepts:
- Multiple different anchor IDs on the same line (e.g.,
<a id="gatos--spec-v03-draft"></a><a id="gatos-spec-v0.3-draft"></a>) — this is a deliberate backwards-compatibility pattern, not corruption.- Duplicate/repeated IDs (e.g., the same
id="foo"appearing twice) — this was the actual defect, already fixed.The sample violations shown (lines 3, 76, 95, 174) all exhibit different ID values, not repeated ones. The grep verification confirms: 142 tags = 142 unique IDs. No repeats.
The claims in the review are factually impossible:
- Claims "302 duplicates" but provides zero shell script proof
- File currently has zero duplicate IDs
- All three cited commits demonstrably exist and fixed the real issue
The normative specification is fit for citation and use.
Likely an incorrect or invalid review comment.
docs/TECH-SPEC.md (2)
51-65: Clarify Mermaid→SVG transform scope for TECH-SPEC.md.Per PR objectives, a markdown renderer transform maps Mermaid code fences to pre-rendered SVG files at
docs/diagrams/generated/**. This file contains ~14 Mermaid code fences (lines 51–65, 82–135, 167–173, 219–224, 232–243, 252–262, 273–288, 308–323, 332–342, 351–367, 387–394, 403–409, 418–430, 453–468, 528–554).Questions:
- Is
docs/TECH-SPEC.mdin scope for the VitePress markdown transform, or is it a static spec file that should retain Mermaid code fences as-is?- If in scope: Do corresponding SVG files exist at
docs/diagrams/generated/for all Mermaid diagrams in this file?- If not in scope: Is it acceptable that these Mermaid fences render as code blocks (not diagrams) in the VitePress output?
Without clarity, readers may see unfamiliar code blocks where diagrams are expected.
Also applies to: 82-135, 167-173, 219-224, 232-243, 252-262, 273-288, 308-323, 332-342, 351-367, 387-394, 403-409, 418-430, 453-468, 528-554
3-527: 🚨 REVIEW COMMENT CONTAINS CRITICAL FACTUAL ERRORS—DISMISS MOST CLAIMS.Empirical verification reveals the review dramatically mischaracterizes the actual state:
Claim in Review Actual Measurement Delta ~213 total anchors 52 Off by 4× ~67 unique IDs 51 Off by 30% 69% duplication 1.9% Off by 36× ~50 duplicate pairs 1 Off by 50× Real findings:
- Only 1 true duplicate ID:
gatos-tech-spec-v0.3appears on lines 3 AND 37 (should exist exactly once).- Multiple IDs per heading are intentional design:
scripts/anchors_and_toc.pydocstring explicitly states it generates multiple anchor variants per heading for backward compatibility (e.g., numeric forms"5","5.3", slug form"5-title"). Lines 182, 329, 527, etc. showing 2–3 IDs per line are NOT bugs—they are features.- macOS capitalization issue is real: Line 210 incorrectly reads "linux/macos" (should be "linux/macOS").
Verdict: The review conflates "multiple distinct intentional IDs per heading" with "duplicate IDs." Severity and scope are wildly overstated. The "CRITICAL BLOCKER" framing is unjustified; only a minor single-duplicate edge case and a capitalization fix are needed.
Likely an incorrect or invalid review comment.
…umbered goals/deliverables/done-when), deterministic-lua, ADR-0001/flyingrobots; remove internal ROADMAP comment; lint fixes
|
PR Preview (canonical) |
…stic-lua/pox/ADR-0001(flyingrobots); script enforces single id; STAKEHOLDERS ids + grammar; ROADMAP numbered ids
|
PR Preview (canonical) |
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/decisions/ADR-0001/flyingrobots.md (1)
1-50: DUPLICATE ANCHORS CONFIRMED ACROSS MULTIPLE ADR FILES — GENERATION SCRIPT HAS FAILED TO RESOLVE THE SYSTEMATIC ISSUE.The audit definitively exposes that the anchor-generation problem is not fixed and is systemic:
- ADR-0001/flyingrobots.md:
<a id="adr-0001"></a>appears twice (visible in the code snippet itself: line 3 and line 32)- ADR-0001/DECISION.md:
<a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a>duplicated- ADR-0002/DECISION.md:
<a id="adr-0002-distributed-compute-via-a-job-plane"></a>duplicated- ADR-0003/DECISION.md: Clean (single anchor IDs)
The
scripts/anchors_and_toc.pyscript exists but has demonstrably failed to prevent or strip duplicate anchor generation. Either the script logic is still flawed, or regeneration was not executed on all affected ADR files post-fix.Required fixes:
- Audit the anchor-generation script logic—it's still inserting dual anchors for
adr-XXXXIDs- Regenerate all ADR files (ADR-0001, ADR-0002, and any others with autogenerated sections) using the corrected script
- Re-run this audit to confirm zero duplicates across all ADR files
This violates HTML standards and breaks anchor-based navigation. Non-negotiable.
♻️ Duplicate comments (2)
docs/USE-CASES.md (1)
17-17: 🔴 CRITICAL (REGRESSED): Duplicate anchor ID—violates HTML spec and breaks VitePress navigation.Line 17 contains an orphaned
<a id="gatos-use-cases"></a>immediately after the TOC block. This is a duplicate of the canonical anchor at line 3 (correctly placed after the H1 heading). Multipleidattributes with the same value violate the HTML specification, and VitePress will unpredictably bind to whichever occurrence it encounters first, silently ignoring all others.Past feedback flagged this exact issue and it was marked addressed (commits 53aa883–dc3fb1c), but the violation persists in the current state. This represents either a regression or an oversight in applying the fix.
Required fix: Remove the orphaned duplicate:
<!-- AUTOGENERATED TOC END --> -<a id="gatos-use-cases"></a> > *Have **you** tried GATOS yet?*Keep only the canonical anchor at line 3.
docs/deterministic-lua.md (1)
7-7: ---🚨 CRITICAL: Duplicate H1 anchor violates HTML5 spec—blocks merge.
Lines 7 and 21 both contain
<a id="deterministic-lua-echolua-profile"></a>. This is a hard HTML5 spec violation (duplicate IDs). Line 21 is an orphaned duplicate after the TOC block—it has no function and breaks VitePress anchor resolution.Worse: Commit 9041247 explicitly deduped anchors and strengthened
anchors_and_toc.pyto prevent reinsertion, yet this duplicate persists. Either the fix skipped this file or the duplicate was reintroduced post-fix.Fix required: Delete line 21 and the blank line that follows it. Keep only the anchor at line 7.
<!-- AUTOGENERATED TOC END --> -<a id="deterministic-lua-echolua-profile"></a> - EchoLua defines a deterministic execution profile for Lua used in GATOS policies and folds.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (10)
docs/FEATURES.md(8 hunks)docs/ROADMAP-XTASK.md(2 hunks)docs/ROADMAP.md(1 hunks)docs/SPEC.md(28 hunks)docs/TASKS.md(4 hunks)docs/USE-CASES.md(2 hunks)docs/decisions/ADR-0001/flyingrobots.md(2 hunks)docs/decisions/ADR-0003/DECISION.md(7 hunks)docs/deterministic-lua.md(1 hunks)docs/diagrams/api_endpoints.md(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: audit
- GitHub Check: Schema validation (v1)
🔇 Additional comments (21)
docs/USE-CASES.md (2)
4-15: TOC structure and section anchor alignment look correct.The autogenerated TOC uses consistent single-dash-normalized fragment IDs (
#1-programmable-git-policy-enforced-repos, etc.) and each entry aligns with its corresponding section heading and anchor below. No issues identified in TOC construction or reference integrity, pending confirmation that section 4, 7, and 8 anchors have no triple-anchor or hyphenation-variant remnants (see previous comment).
60-60: All anchor deduplication concerns resolved—no action required.Verification confirms complete remediation across all three flagged sections:
- Section 4 (line 60):
<a id="4-supply-chain-deploy-attestation"></a>— single, normalized ID ✓- Section 7 (line 93):
<a id="7-knowledge-graph-for-code-ops"></a>— single, normalized ID ✓- Section 8 (line 104):
<a id="8-regulated-feature-flags-config"></a>— single, normalized ID ✓Zero double-dash anchor hyphenation variants detected anywhere in the file. No triple-anchor patterns, no numeric ID duplicates stacked alongside long-form IDs. All section anchors are now clean, properly deduplicated, and correctly formatted. The file meets the required standard.
docs/diagrams/api_endpoints.md (1)
1-57: No issues found. Diagram transformation pipeline is correctly configured and operational.All verification points pass:
SVG files committed:
docs/diagrams/generated/docs__diagrams__api_endpoints__mermaid_1.svgandmermaid_2.svgboth present (plus legacy hashed variants).Build-time transform wired: VitePress config.ts contains
mermaidToImg()function that pre-scans the diagrams directory and replaces Mermaid code fences with SVG image references at render time, with fallback to code fence rendering if SVG is absent.CI pipeline validates:
.github/workflows/ci.ymlincludes a dedicateddiagramsjob that runsscripts/diagrams.sh --alland enforcesgit diff --exit-codeto ensure diagrams stay in sync.The Mermaid code blocks in your markdown file (lines 18–37, 50–56) are correct as-is. They are source artifacts; the transform converts them to SVG refs during build. No action required.
docs/deterministic-lua.md (5)
52-63: Approve: Deterministic Runtime Profile table is comprehensive and well-structured.The table correctly delineates EchoLua constraints from default Lua across all critical areas: OS/time access (removed), random (seed-based only), numbers (fixed-point Q32.32), iteration (deterministic sort), table hashing (fixed seed), coroutines (disallowed), metamethods (restricted), FFI (forbidden), math lib (pinned). The notation is clear and unambiguous.
64-68: Approve: Invariants section correctly specifies canonical JSON and resource limits.Line 66 correctly mandates "canonical JSON: UTF-8 NFC; lexicographic key sort; fixed number encoding (no -0, no trailing zeros)." Line 67 adds resource caps (fuel/step counters for termination guarantee). Both are essential for determinism and correctly stated.
75-76: Approve: Math library restrictions correctly defer transcendentals to PoE (Proof of Execution).Line 75 correctly prohibits transcendentals (sin/exp/log) in v1 folds and directs them to jobs/PoE instead. This is the right design for determinism (transcendentals have platform/library variance). Rounding mode "toward zero" for division is explicitly stated as correct.
84-85: Approve: RNG normative algorithm (pcg32@1) and seed derivation are properly specified.Line 84 mandates
pcg32@1with version tracking viaFold-Enginetrailer. Line 85 specifies canonical seed derivation:trunc64(blake3(inputs_root || policy_root || fold_root)). Both are deterministic, reproducible, and properly versioned for future algorithm upgrades. Excellent.
100-103: Approve: Proof/Trailer Integration section correctly specifies state checkpoints and verification.Line 100: Mandatory
Fold-Root: sha256:<hex>trailer is correct. Lines 101–102: Recommended trailers (Fold-Math, Fold-RNG) and verifier-side recomputation policy are sound. PoF (Proof of Fold) envelope inclusion is a best-practice security measure. 👍docs/decisions/ADR-0003/DECISION.md (2)
3-22: ✅ Anchor and TOC scaffolding is clean and well-structured.No duplicate anchors detected. All section anchor IDs (scope, rationale, decision, etc.) appear exactly once. TOC entries correctly reference fragment links. The H1 root anchor at line 3 is isolated and not duplicated.
Metadata escaping (lines 28-42) handles square brackets and backslashes correctly to prevent Markdown parsing issues.
142-148: Table formatting looks good; alignment is correct.Markdown table at lines 142-148 has proper header alignment and state entries are clearly tabulated. No issues.
docs/ROADMAP.md (4)
4-50: ✓ H1 anchor and TOC structure are correct—past anchor duplication defects have been resolved.The single H1 anchor at line 4 is canonical (no format variants), and the autogenerated TOC block correctly references all 9 Goals sections via numbered IDs (goals-0 through goals-8). This resolves the prior systemic issue of 9 duplicate generic
<a id="goals"></a>anchors that broke VitePress navigation.Verify CI is enforcing TOC and anchor regeneration (via
anchors_and_toc.pyornormalize.mjs) as a mandatory prebuild step before commit to prevent manual edits from degrading anchor uniqueness.
112-433: ✓ All milestone sections (M0–M9) have properly numbered, unique anchors with no duplication.Each subsection anchor follows a consistent "occurrence index" scheme:
- Goals: 9 sections (M0–M7, M9; M8 omitted) → goals-0 through goals-8 ✓
- Deliverables: 10 sections (all milestones) → deliverables-0 through deliverables-9 ✓
- Done When: 10 sections (all milestones) → done-when-0 through done-when-9 ✓
M8 intentionally has no Goals subsection (only Deliverables + Done When at lines 387, 396), which correctly shifts subsequent numbering. M9's
goals-8is the 8th Goals section overall—logically correct per this scheme.All TOC references (lines 11–48) correctly target these numbered anchors. No format inconsistencies, no orphaned IDs, no ordering corruption detected.
117-145: ✓ Anchor placement pattern is consistent and follows markdown/VitePress convention.All 29 subsection anchors follow uniform structure: heading → blank line → anchor → blank line → content (verified across M0–M9). This placement is optimal for markdown-to-HTML rendering and ensures VitePress correctly associates anchors with their target headings.
11-48: ✓ All 29 TOC entries correctly reference existing, uniquely-numbered anchors; no broken links detected.Verified across M0–M9: every TOC reference (M-heading, Goals, Deliverables, Done When) resolves to its corresponding anchor in the document. M8 correctly omits Goals from both TOC and content. All 10 milestone anchors, 9 Goals anchors, 10 Deliverables anchors, and 10 Done When anchors are accounted for with zero orphans or duplicates.
docs/ROADMAP-XTASK.md (4)
3-3: ✓ H1 anchor is canonical and single—past triple-anchor duplication defect is resolved.Line 3 contains
<a id="roadmap-xtask-and-ci-tooling"></a>, a single, canonical kebab-case anchor with no format variants. Prior reviews flagged triple adjacent anchors on this H1 heading; that defect is now resolved.
4-44: ✓ TOC block and section anchors are consistent, unique, and properly placed.All 4 TOC entries (lines 6–9) correctly reference their corresponding section anchors (goals, landed, near-term, backlog at lines 17, 25, 36, 44). Each anchor is placed in the standard position (after heading, before content) and no duplicates exist. Past reviews flagged triple adjacent anchors on every section heading; that defect is now resolved—each section has exactly one anchor.
23-47: ✓ Content updates (Linkcheck, Makefile shims, issue labeler, backfill) are correctly formatted and relevant to tooling roadmap.New Landed items (lines 30–32) and Backlog items (lines 46–47) follow consistent bullet formatting, contain no typos, and logically extend the xtask/CI tooling roadmap. Anchor structure is unaffected by content additions.
1-459: ⚠ Confirm CI is enforcing anchor/TOC regeneration as a required prebuild step.Both docs/ROADMAP.md and docs/ROADMAP-XTASK.md are marked
AUTOGENERATED TOCand contain machine-generated anchor IDs (numbered subsections, canonical H1 anchors). This implies a build-time generator (anchors_and_toc.py or normalize.mjs) is responsible for maintaining these markers and IDs.Critical for regression prevention: Verify that your CI/build pipeline:
- Runs the generator before markdown linting/building
- Fails the build if auto-generated content is out of sync with source
- Regenerates all affected docs/**/*.md files as part of the prebuild step
Past review cycles indicate repeated anchor corruption when the generator was bypassed or not enforced in CI. Wire in CI validation now to prevent future regressions, especially when adding M10+ milestones to ROADMAP.md or extending xtask sections in ROADMAP-XTASK.md.
docs/FEATURES.md (2)
129-129: Verify: line 129 reads "linux/macOS/windows" after past macOS casing fix.Past review noted incorrect spelling "macos" (all lowercase), flagged as CRITICAL, and was fixed in commit 55e5a16. The current code correctly shows "macOS" (Apple's branding). ✓ No action needed.
1-42: TOC/anchor verification COMPLETE: All 35 subsection anchors present, aligned, unique, properly scoped. No defects.Systematic audit confirms past CRITICAL issues are resolved:
- ✓ All 35 TOC entries reference valid anchors (zero missing)
- ✓ Single orphaned anchor (
gatos-features-derived-from-spec-v0.3) is the intentional h1 header- ✓ All 35 subsection anchors follow strict f[1-8]-(descriptor) naming convention
- ✓ Zero duplicate IDs
- ✓ Zero inline anchor pairs (
</a><a id=)- ✓ Zero malformed or non-conforming anchors
The file is navigation-safe and SSR-compatible. Past triple-anchor chains and orphaned subsection references are gone.
Unresolved architectural concern (flagged but not addressed in prior reviews): Explicit
<a id>anchors appear redundant with VitePress's automatic heading-based slug generation. This creates maintenance coupling toscripts/anchors_and_toc.py. Not a blocker for this PR, but consider future simplification: either commit fully to explicit anchors with documented governance, or remove them and rely on VitePress auto-slugs. Current hybrid approach is technical debt.docs/TASKS.md (1)
3-3: ✅ VERIFICATION COMPLETE—ALL SYSTEMS OPERATIONAL.The script is solid and robust, not broken or incomplete:
- Deduplication logic:
slugify_kebab()produces single canonical IDs; collision detection viaused_idsset + suffix suffixing (base, base-2, base-3, ...)- Anchor generation: Exactly ONE
<a id="..."></a>per heading (enforced inmake_anchor_line())- Idempotency confirmed:
--checkreturns exit code 0 → no changes needed → file is already in sync with script expectationsThe anchor structure in
docs/TASKS.mdis definitively correct. No regression risk.
There was a problem hiding this comment.
Actionable comments posted: 6
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (5)
docs/STAKEHOLDERS.md(2 hunks)docs/USE-CASES.md(2 hunks)docs/cli/pox.md(1 hunks)docs/decisions/ADR-0001/flyingrobots.md(2 hunks)docs/deterministic-lua.md(1 hunks)
🔇 Additional comments (13)
docs/USE-CASES.md (1)
3-15: All past anchor violations resolved—file is now HTML spec compliant.Prior reviews flagged multiple critical issues: triple-anchor duplication, double-dash naming variants, orphaned anchors after TOC, and inconsistent ID patterns. The current state shows all violations fixed:
- Line 3: H1 anchor is single and canonical—no triple duplicates, no orphaned duplicate after TOC.
- Lines 25, 36, 47, 58, 69, 80, 91, 102: Each section has exactly one unique anchor with consistent single-dash naming (no
--variants).- TOC (lines 6–13): All 8 references point to correct section anchors; linkability verified.
- HTML uniqueness: No duplicate IDs anywhere in document.
Navigation integrity ✓ | Spec compliance ✓ | Backward compatibility (if any docs linked to old IDs) ✓ verified
Also applies to: 25-25, 36-36, 47-47, 58-58, 69-69, 80-80, 91-91, 102-102
docs/STAKEHOLDERS.md (1)
1-104: ✅ All past critical issues successfully resolved—anchor integrity restored.Verification confirms this file has been properly corrected:
Duplicate anchors eliminated (past issues at lines 34–194): Each section now contains exactly one anchor tag, not five. Duplicate anchor blocks that violated HTML5 uniqueness constraints have been removed.
Mismatched TOC references fixed (lines 10, 12):
#sre--ops-sreand#auditor--grc-audnow match their target anchor IDs precisely; internal links will resolve correctly.Grammar corrected (line 99): "explainable denies" → "explainable denials" ✓
Anchor placement consistent: All section anchors follow the same pattern—placed after their heading with a blank line separator.
HTML5 compliance restored: No duplicate IDs; all 10 section anchors are unique and valid.
The autogenerated TOC (lines 4–17) cross-references all 10 section anchors without collision or mismatch. Document navigation is now unbroken.
docs/deterministic-lua.md (7)
1-108: 📋 Verify past anchor fixes remain intact after latest commits.Past review comments claim anchor duplication was fixed in multiple commits. Need to confirm the current annotated code has no duplicate IDs and no inline variants (the script output will confirm).
25-32: ✅ Goals section is clear and well-structured.The three goals are concise and directly aligned with the deterministic execution profile intent. The "side-effect-free" hyphenation is correct (per past review).
50-61: ✅ Deterministic Runtime Profile table is technically sound.Q32.32 format specifies 32 bits of integer and 32 bits of fraction, which aligns with the fixed-point choice for determinism. The restrictions on time/OS, global RNG state, coroutines, and FFI are well-justified for enforcing deterministic semantics. The "ties-to-even" rounding mode is the correct terminology for banker's rounding and ensures reproducibility across platforms.
62-66: ✅ Invariants section correctly specifies determinism constraints.UTF-8 NFC, lexicographic sorting, and fixed number encoding (no
-0, no trailing zeros) are the correct choices for canonical JSON. Resource caps with fuel/step counters ensure termination and bounded compute. All invariants are necessary and sufficient.
77-85: ✅ RNG section correctly specifies deterministic seeding with PCG32.Requiring explicit seed material and using blake3 with inputs_root || policy_root || fold_root ensures reproducibility and cryptographic soundness. The advice to discourage RNG usage in folds is pragmatic given the additional complexity it introduces.
86-93: ✅ Linter/Compiler rules comprehensively enforce determinism constraints.All hard-fail conditions (pairs, coroutines, forbidden metamethods, OS/IO/debug/package modules) are justified and align with the runtime profile section. The semantic bans (non-canonical numerics, non-deterministic traversal) round out the enforcement strategy.
102-108: ✅ Open Implementation Notes provide pragmatic guidance.Forward-looking recommendations on transcendental handling (versioned libraries) and performance optimizations (native intrinsics) are appropriate closing commentary without being prescriptive. Maintains flexibility for implementers.
docs/cli/pox.md (1)
45-45: All cross-references verified as valid—no action required.Both
docs/proofs/proof-of-experiment.mdand the SPEC anchor#10.x-proof-of-experiment-poxexist:
- Proof file confirmed at
docs/proofs/proof-of-experiment.md- SPEC file at
docs/SPEC.mdwith anchor explicitly defined at line 609- VitePress route
/SPECcorrectly configured to servedocs/SPEC.md- Anchor ID matches link reference exactly
Links will render without breakage at build time.
docs/decisions/ADR-0001/flyingrobots.md (3)
4-10: ✅ TOC scaffolding correctly generated and all links match anchor IDs.Each TOC entry (lines 6–8) links to the corresponding section anchor:
#it-directly-implements-the-four-planes-from-spec.md↔ line 18 anchor ✓#it-strengthens-the-nostd-and-portability-goal↔ line 29 anchor ✓#it-refines-the-original-tech-spec.md-layout↔ line 37 anchor ✓Slug generation (
SPEC.md→spec.md,no_std→nostd) is consistent and follows markdown conventions.
16-43: ✅ Section-level anchors correctly placed and uniquely identified.Each H2 section heading has exactly one anchor immediately preceding it:
- Line 16 H2 → Line 18 anchor (unique ID)
- Line 27 H2 → Line 29 anchor (unique ID)
- Line 35 H2 → Line 37 anchor (unique ID)
No duplicate heading anchors detected. Anchor placement and format follow VitePress navigation conventions.
3-11: ✅ Anchor deduplication confirmed. File passes validation.All four anchor IDs are unique and present:
adr-0001(root, count: 1)it-directly-implements-the-four-planes-from-spec.md(count: 1)it-strengthens-the-nostd-and-portability-goal(count: 1)it-refines-the-original-tech-spec.md-layout(count: 1)The anchor script includes explicit duplicate-collapse logic (lines 119–130 of
scripts/anchors_and_toc.py), and validation confirms the file matches the script's expected state. The critical duplicate anchor bug from prior cycles is not present and the script is hardened against regression.
…d separator; regenerate pox and api_endpoints (canonical ids); normalize SPEC/FEATURES TOC
…ep link targets unchanged
…meta migration (SPEC §7)
…IBUTING): clarify pre-push skip flags and Mermaid --verify semantics
|
PR Preview (canonical) |
1 similar comment
|
PR Preview (canonical) |
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
.github/workflows/ci.yml (2)
127-136: Redundant npm cache configuration in schemas job.The
schemasjob has both a manual cache step (lines 127–131) andcache: npminsetup-node(line 136). Thesetup-nodeaction withcache: npmautomatically manages npm caching—the manual step is redundant and should be removed.This is the recommended pattern per GitHub Actions best practices.
Apply this diff:
- uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2.8.1 - - name: Cache npm (global) - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 - with: - path: ~/.npm - key: ${{ runner.os }}-node-20-ajv-cache-v1 - name: Setup Node.js
158-167: Redundant npm cache configuration in diagrams job.The
diagramsjob has a manual npm cache step (lines 158–162) that conflicts withcache: npminsetup-node(line 167). Thesetup-nodeaction handles npm caching automatically; the manual step wastes CI resources and duplicates that logic.Keep the Puppeteer cache (lines 153–157), but remove the redundant npm cache.
Apply this diff:
key: ${{ runner.os }}-puppeteer-chromium-${{ env.CHROMIUM_REVISION }} - - name: Cache npm (npx) - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0 - with: - path: ~/.npm - key: ${{ runner.os }}-node-20-npx-cache-v1 - name: Setup Node.jsdocs/decisions/ADR-0003/DECISION.md (1)
971-972: Clarify PoC storage immutability to prevent drift.Recommend stating PoC envelope object under refs/gatos/audit/proofs/governance/ is immutable; updates require a new envelope and updated Grant.
- PoC envelope SHOULD be stored canonically under `refs/gatos/audit/proofs/governance/<proposal-id>`; the Grant’s `Proof-Of-Consensus` trailer MUST equal `blake3(envelope_bytes)`. + PoC envelope SHOULD be stored canonically under `refs/gatos/audit/proofs/governance/<proposal-id>` as an immutable blob; corrections require a new envelope and updated Grant. The Grant’s `Proof-Of-Consensus` trailer MUST equal `blake3(envelope_bytes)`.
♻️ Duplicate comments (4)
docs/SPEC.md (4)
236-239: Bundle-id allows two incompatible schemes—mandate deterministic, content-addressed ID.ULID here breaks cross-node dedup/citation. Pick one scheme.
- `refs/gatos/policies/<bundle-id>`, where `<bundle-id>` is a stable identifier - (e.g., `blake3(policy_tree)` or a ULID). The commit’s tree contains the + `refs/gatos/policies/<bundle-id>`, where `<bundle-id>` **MUST** be a deterministic + content identifier: `blake3(canonical_policy_tree)` (DAG‑CBOR, sorted keys; see ADR‑0001). + The commit’s tree contains the
326-331: sig_alg registry/validation rules are vague—define REQUIRED set and verifier behavior.State what’s mandatory, what’s optional, and how unknown/mismatched algorithms are handled.
- - `sig_alg` — algorithm identifier; for v1, implementations **MUST** support - `ed25519`; other algorithms (e.g., `ecdsa-p256`) **MAY** be accepted by - agreement. When omitted, verifiers **MUST** infer the algorithm from the - signature material or commit metadata. + - `sig_alg` — algorithm identifier (OPTIONAL). For v1, verifiers **MUST** support `ed25519` (RFC 8032). + Additional algorithms (e.g., `ecdsa-p256`, FIPS 186‑4) **MAY** be enabled by policy. + Unknown `sig_alg` **MUST** cause rejection (or explicit policy override). + When omitted, verifiers **MUST** infer the algorithm from signature material. + If `sig_alg` contradicts the inferred algorithm, verifiers **MUST NOT** accept the envelope.
256-260: Promotion workflow lacks CAS semantics and retry guidance—define atomicity and backoff.If active ref CAS fails, state is inconsistent. Specify CAS + retries.
- - Mutation workflow: Promote a candidate bundle by fast-forwarding - `refs/gatos/policies/<bundle-id>` and then atomically updating - `refs/gatos/policies/active` to that commit (both operations FF-only). + - Mutation workflow: + 1) Fast‑forward `refs/gatos/policies/<bundle-id>` to the candidate commit. + 2) Atomically update `refs/gatos/policies/active` via CAS (`git update-ref <old> <new>`). + 3) On CAS mismatch, refetch and retry with jittered exponential backoff (base≈25 ms, max≈500 ms), cap at 5 attempts. + 4) If retries exhaust, surface an error; the candidate bundle remains published but not active.
345-349: Canonicalization is under-specified—cite RFC 8949/DAG-CBOR and mandate key ordering.Without explicit key-sorting and normative refs, cross-impl signatures will diverge. Fix now.
- Canonicalization and signing: - -- Encode the envelope (with `sig` omitted) as **DAG-CBOR** to produce canonical bytes. -- Content addressing: `Event-CID = cidv1(dag-cbor, blake3(canonical_bytes))`. -- Sign `canonical_bytes` with `sig_alg` (e.g., `ed25519`); record signature in commit trailers. -- Recommended trailers: `Event-CID`, `Sig-Alg`, `Sig`. + Canonicalization and signing (Normative): + - Encode the envelope (with `sig` omitted) as **DAG-CBOR** per the IPLD DAG‑CBOR spec (maps use RFC 8949 deterministic encoding; map keys MUST be sorted lexicographically by their encoded bytes; no indefinite‑length items). + - Content addressing: `Event-CID = cidv1(dag-cbor, blake3(canonical_bytes))` (BLAKE3 per spec; multihash extension as deployed). + - Sign `canonical_bytes` with `sig_alg` (e.g., `ed25519`); record signature in commit trailers. + - Recommended trailers: `Event-CID`, `Sig-Alg`, `Sig`. + - See ADR-0001 for canonicalization test vectors.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (7)
.github/workflows/ci.yml(3 hunks)CONTRIBUTING.md(2 hunks)docs/FEATURES.md(8 hunks)docs/SPEC.md(28 hunks)docs/cli/pox.md(1 hunks)docs/decisions/ADR-0003/DECISION.md(9 hunks)docs/diagrams/api_endpoints.md(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: audit
🔇 Additional comments (4)
.github/workflows/ci.yml (1)
103-116: Thecontinue-on-error: trueon markdownlint is intentional architectural design, not an oversight.Git history confirms this deliberate choice across multiple commits (862fc9e: "make markdownlint advisory…add dedicated AST normalize job as the gating check"). The xtask md command is functional—it enforces MD009, MD012, MD022, MD032, and Unicode hyphen rules, properly exiting with error on violations. The actual hard gates are: editorconfig, fmt, clippy, test, audit, msrv, schemas, diagrams, and linkcheck. Markdown linting is intentionally advisory at the CI level while enforced locally via pre-push hooks (PREPUSH_LINT flag).
Likely an incorrect or invalid review comment.
CONTRIBUTING.md (2)
101-103: Mermaid verification documentation is clear and complete.The
--verifyflag is now explicitly documented with clear semantics: non-destructive validation, exit behavior, and CI implications. This addresses the prior review concern. LGTM for this segment.
125-128: The review comment's suggested change is factually incorrect and must be rejected.The core premise is false: the
npm run docs:buildscript executesvitepress build docsdirectly, with no prebuild integration. Your suggested clarification would mislead readers by claiming the build command "includes prebuild steps (normalization, linkification, anchors/TOC)" when it does not.Reality check:
- Docs normalization is explicitly optional, not a bundled prebuild step.
- Normalization runs via separate npm scripts (
docs:normalize,docs:normalize:check), not as part ofnpm run docs:build.- In the pre-push hook, docs build runs separately from the normalization check—they are not combined into a single step.
- Linkify scripts exist as separate tooling, not invoked by the build command.
What's actually correct:
The two sections (Docs Normalization and Docs build system) are properly separated because they document distinct concerns. Readers learn:
- Normalization is optional tooling for manual cleanup (lines 83–104)
- VitePress build is the actual production build (lines 125–128)
- Pre-push hook orchestrates them separately (lines 96–98, already documented)
Adding your proposed sentence would be adding misinformation. The docs are clear as-is.
Likely an incorrect or invalid review comment.
docs/diagrams/api_endpoints.md (1)
17-36: SVGs are generated but not embedded in markdown; fences remain untouched.The mermaid generation pipeline (
scripts/mermaid/generate.mjs) extracts code fences, renders them to SVGs, and stores them indocs/diagrams/generated/. However, the markdown fileapi_endpoints.mdis not transformed to link these SVGs—it retains raw ```mermaid code fences at lines 17 and 49.The generated SVGs (
docs__diagrams__api_endpoints__mermaid_1.svgandmermaid_2.svg) exist and are current, but they are unused artifacts. CI has no step that converts fence references to<img>tags. Consumers (GitHub, markdown viewers) will render the code fence, not the static SVG, which undermines the stated goal of "no Mermaid runtime."Either:
- Update
api_endpoints.mdto use<img src="docs/diagrams/generated/docs__diagrams__api_endpoints__mermaid_1.svg">tags, or- Clarify whether relying on platform-native mermaid rendering is acceptable.
…h‑prefixing + example vector; tighten policy bundle id (blake3), CAS/backoff; strengthen DAG‑CBOR canonicalization and sig_alg semantics; opaque pointer schema + migration note; regenerate anchors/TOC and fix TOC spacing
|
PR Preview (canonical) |
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/decisions/ADR-0003/DECISION.md (1)
187-198: Build pipeline incomplete: ADR-0003 Mermaid diagrams lack static SVG mappings.The two Mermaid fences in ADR-0003 (lines 187–198 and 203–228) have no corresponding SVG files generated. The
docs/diagrams/generated/directory contains 21 SVGs, all originating fromdocs/SPEC.mdonly (naming pattern:docs__SPEC__mermaid_*.svg). ADR-0003 diagrams, which should generate SVGs with stemdocs_decisions_ADR_0003_DECISION__*, are missing entirely.Per PR objectives requiring static SVGs with no runtime rendering, these diagrams currently fall back to code fence rendering in violation of that constraint. The build pipeline exists but processes only
docs/SPEC.md—other files including ADR-0003 are not being picked up.Action: Verify the build process correctly scans and converts all Mermaid fences across the docs tree, not just SPEC.md. Ensure SVGs are generated for both ADR-0003 diagrams before merge.
♻️ Duplicate comments (3)
docs/diagrams/api_endpoints.md (1)
4-9: Remove blank lines inside AUTOGENERATED TOC block for stable diffs.Lines 5 and 8 are blank and introduce noise on every TOC regeneration. The block should be compact—TOC START/END comments adjacent to entries with no blank lines between.
<!-- AUTOGENERATED TOC START --> - - [Request/Response Flow](#request-response-flow) - [Error Responses](#error-responses) - <!-- AUTOGENERATED TOC END -->docs/cli/pox.md (2)
20-35: ✅ Command examples use consistent flag interface.Both
git gatos pox verify --id <ulid>(line 31) andgit gatos reproduce --id <ulid>(line 34) consistently use the--idflag syntax. The interface is uniform across examples.
20-35: ✅ Command examples use a consistent flag interface.Both
git gatos pox verify --id <ulid>(line 31) andgit gatos reproduce --id <ulid>(line 34) consistently use the--idflag. The interface is uniform across examples and documented behavior is coherent.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/diagrams/generated/docs_SPEC__0679d036ea__mermaid_8.svgis excluded by!**/*.svg,!**/generated/**
📒 Files selected for processing (10)
.github/workflows/ci.yml(3 hunks).github/workflows/pages-preview.yml(1 hunks).tmp/unresolved_ids.txt(1 hunks)CONTRIBUTING.md(2 hunks)docs/FEATURES.md(8 hunks)docs/SPEC.md(28 hunks)docs/cli/pox.md(1 hunks)docs/decisions/ADR-0003/DECISION.md(9 hunks)docs/deterministic-lua.md(1 hunks)docs/diagrams/api_endpoints.md(2 hunks)
🧰 Additional context used
🪛 actionlint (1.7.8)
.github/workflows/pages-preview.yml
61-61: input "body-includes" is not defined in action "peter-evans/create-or-update-comment@v4". available inputs are "append-separator", "body", "body-file", "body-path", "comment-id", "edit-mode", "issue-number", "reactions", "reactions-edit-mode", "repository", "token"
(action)
🪛 LanguageTool
CONTRIBUTING.md
[style] ~98-~98: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...scripts/diagrams.sh --verify --all). - Set PREPUSH_SKIP_LINT=1` to skip Markdown ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~99-~99: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...H_SKIP_LINT=1to skip Markdown lint. - SetPREPUSH_SKIP_NORMALIZE=1` to skip the ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~100-~100: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...eck (npm run docs:normalize:check). - Set PREPUSH_SKIP_RUST=1 to skip Rust chec...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Link Check (xtask links)
- GitHub Check: MSRV check (1.81.0)
🔇 Additional comments (19)
docs/diagrams/api_endpoints.md (3)
1-9: Anchor and TOC structure is sound.All anchor IDs are unique, consistently kebab-cased, and placed deterministically after headings. TOC lists both H2 sections and links are accurate. Prior issues (duplicate IDs, inconsistent slug formats, orphaned anchors) have been resolved. Only the blank lines within the TOC block (noted above) remain.
15-37: Mermaid fence syntax is well-formed.Both sequence diagrams (Request/Response Flow and Error Responses) are syntactically correct and clearly illustrate the JSONL RPC protocol. Per PR objectives, these fences will be mapped to static SVGs at build time via the markdown renderer transform in
.vitepress/config.ts.
11-57: Document structure and content are clear and well-organized.The progression from JSONL RPC protocol explanation → happy-path sequence diagram → error handling diagram is pedagogically sound. Text is concise, free of errors, and aligns with the reference documentation objective. The error response example at lines 44–46 is concrete and helpful.
docs/decisions/ADR-0003/DECISION.md (5)
6-19: Confirm all 14 autogenerated TOC entries have matching anchor IDs in document.The TOC block (lines 6–19) declares 14 section links. Verification confirms all corresponding anchors are present and unique in the document:
- ✓
#scope(line 48)- ✓
#rationale(line 53)- ✓
#decision(line 60)- ✓
#security-considerations(line 174)- ✓
#diagrams(line 182)- ✓
#proposal-lifecycle-state(line 186)- ✓
#standard-workflow-sequence(line 202)- ✓
#consequences(line 232)- ✓
#pros(line 236)- ✓
#cons(line 244)- ✓
#alternatives-considered(line 251)- ✓
#future-work(line 258)- ✓
#why-this-adr-matters(line 266)- ✓
#terminology-and-references(line 276)No duplicate anchor IDs detected. Previous critical issue (duplicate anchors at lines 3 vs. 23) is resolved.
34-39: Schema file references consistently use inline code formatting without redundant escaping.All seven schema references properly use Markdown inline code blocks:
- Lines 34–39 (and repeated at 75, 92, 105, 116, 124, 151)
- No backslash-escaped underscores (e.g.,
proof\_of\_...removed)- Format:
`schemas/v1/governance/filename.schema.json`Previous minor inconsistency issue resolved.
Also applies to: 75-75, 92-92, 105-105, 116-116, 124-124, 151-151
41-42: Verify Supersedes/Superseded-By escaping is intentional and correctly renders in Markdown.Lines 41–42 escape empty arrays:
Supersedes: \[] Superseded-By: \[]Confirm this escaping prevents Markdown parsers from misinterpreting
[]as link syntax and that it renders as literalSupersedes: []in HTML output. If intended, this is correct; if not, remove backslashes to render as plain arrays.
1-276: Comprehensive ADR structure well-organized with all expected sections properly anchored.The enriched ADR now covers:
- Governance system design (Decision section: items 1–11)
- Security posture (new Security Considerations section, line 174)
- Lifecycle state machine (new Diagrams section with Mermaid FSM, line 187)
- Workflow choreography (new Standard Workflow sequence diagram, line 203)
- Risk/benefit analysis (new Consequences section with Pros/Cons, line 232)
- Design alternatives (new Alternatives Considered section, line 251)
- Implementation roadmap (new Future Work section, line 258)
- Justification & terminology (new sections at lines 264 and 274)
All sections are properly anchored, linked in TOC, and hierarchically structured. Inline code formatting for schema references is consistent.
34-39: ---All schema file paths verified—no action required.
Script execution confirms all 6 schema file references exist in the repository and are accessible at build time. Combined with prior verification that all 14 TOC–anchor alignments are correct (no duplicates) and schema formatting is consistent throughout the ADR, the file is production-ready.
docs/cli/pox.md (7)
7-7: Inconsistent anchor naming: H1 uses full kebab-case slug, but subsections use bare names.Anchor IDs mix conventions:
- Line 7:
git-gatos-pox-proof-of-experiment(full heading-derived slug)- Line 19:
synopsis(simple name)- Line 39:
behavior(simple name)This inconsistency is fragile: if the heading-generation script is re-run with a consistent convention, the subsection anchors may be regenerated to
git-gatos-pox-synopsisandgit-gatos-pox-behavior, breaking existing links. Verify thatscripts/anchors_and_toc.pyenforces a single anchor-naming scheme across all headings (or document the intentional mixed strategy if so).Also applies to: 19-19, 39-39
45-45: ✅ Link syntax is correct.The SPEC reference is properly formatted as a Markdown link with the label inside brackets and href in parentheses. Anchor target
#10.x-proof-of-experiment-poxis clear.
1-5: ✅ Frontmatter and heading structure correct.YAML frontmatter is properly formatted and the H1 heading matches the documented title. This is correct practice for VitePress.
5-5: 📋 H1 is excluded from autogenerated TOC—verify this is intentional.Line 5 defines the H1 heading
# git gatos pox — Proof-of-Experiment, but the TOC on lines 10–11 includes only subsections (Synopsis, Behavior). Standard documentation practice includes the top-level heading as the first TOC entry for return-to-top navigation.Verify: Does
scripts/anchors_and_toc.pyintentionally exclude H1 entries? If so, add an inline comment explaining why; if not, ensure the script includes all heading levels (H1–H2/H3) in TOC output.Also applies to: 10-11
45-45: ✅ Link syntax is correct.The cross-reference
[SPEC §10.x PoX](/SPEC#10.x-proof-of-experiment-pox)is properly formatted Markdown with text in brackets, href in parentheses, and a valid anchor target. The anchor slug10.x-proof-of-experiment-poxis clear.
1-5: ✅ Frontmatter and H1 structure are correct.YAML frontmatter is valid and the H1 title matches the document's
titlefield. Proper VitePress practice.
7-7: ****The review conflates slug length with naming convention inconsistency. The script applies uniform
slugify_kebab()transformation to all heading levels, generating kebab-case IDs consistently. "git-gatos-pox-proof-of-experiment" vs "synopsis" vs "behavior" are not mixed conventions—they're the same kebab-case rule applied to different heading text. Across the codebase, longer headings naturally produce longer slugs (e.g., "adr-0002-distributed-compute-via-a-job-plane") and shorter headings produce shorter slugs (e.g., "scope", "rationale", "decision"). No special casing, no re-run risk, no documentation needed. The anchors are correct.Likely an incorrect or invalid review comment.
.github/workflows/ci.yml (1)
130-131: LGTM: Node pinned + npm cache is correct and consistent.Pinning to "20.14.0" with
cache: npmmatches other jobs and improves determinism.Also applies to: 156-157
docs/SPEC.md (2)
261-267: LGTM: promotion uses CAS + bounded backoff.The CAS + jittered exponential backoff (up to 5 attempts) closes the partial‑update hole. Solid.
334-341: LGTM:sig_algregistry + validation semantics.Explicit RFC 8032 reference, unknown‑algo rejection, and contradiction handling are correct.
CONTRIBUTING.md (1)
126-129: LGTM: explicit VitePress build command called out.The build entrypoint is discoverable; good developer ergonomics.
| markdownlint: | ||
| runs-on: ubuntu-latest | ||
| name: Markdownlint (xtask) | ||
| continue-on-error: true |
There was a problem hiding this comment.
Don’t silently mask markdownlint failures.
continue-on-error: true hides regressions. Prefer a non-blocking job with explicit allow-failure semantics (separate job), or gate on a matrix flag and surface “neutral” status, not green. At minimum, add an issue link explaining why soft-failing is acceptable.
🤖 Prompt for AI Agents
.github/workflows/ci.yml around line 106: the workflow uses "continue-on-error:
true" which silently masks markdownlint regressions; remove the soft-fail and
instead either (A) create a separate non-blocking job dedicated to markdownlint
that is marked as allowed-to-fail (so regressions are visible but don't gate
CI), or (B) gate the step behind a matrix flag and report a neutral status when
disabled so the main job isn't green-masked; if you must keep a soft-fail for
now, add a clear comment and an issue/PR link explaining the justification and
timeline for fixing so failures are auditable.
| - name: Comment/update canonical preview URL (idempotent) | ||
| uses: peter-evans/create-or-update-comment@v4 | ||
| with: | ||
| issue-number: ${{ github.event.number }} | ||
| body: | | ||
| PR Preview (canonical) | ||
| https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/ | ||
| edit-mode: replace | ||
| body-includes: "PR Preview (canonical)" |
There was a problem hiding this comment.
🧩 Analysis chain
Broken step: create-or-update-comment doesn’t support “body-includes”.
This input is invalid and the step will fail. Use peter-evans/find-comment@v3 to locate an existing comment and pass its comment-id to create-or-update-comment, or just create a new comment each run. Example fix:
- name: Comment/update canonical preview URL (idempotent)
- uses: peter-evans/create-or-update-comment@v4
- with:
- issue-number: ${{ github.event.number }}
- body: |
- PR Preview (canonical)
- https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/
- edit-mode: replace
- body-includes: "PR Preview (canonical)"
+ uses: peter-evans/find-comment@v3
+ id: find_preview_comment
+ with:
+ issue-number: ${{ github.event.number }}
+ body-includes: "PR Preview (canonical)"
+ - name: Create or update comment
+ uses: peter-evans/create-or-update-comment@v4
+ with:
+ issue-number: ${{ github.event.number }}
+ comment-id: ${{ steps.find_preview_comment.outputs.comment-id }}
+ edit-mode: replace
+ body: |
+ PR Preview (canonical)
+ https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/🏁 Script executed:
#!/bin/bash
# actionlint syntax check (if available) and grep for invalid inputs
rg -n "body-includes" .github/workflows/pages-preview.ymlLength of output: 52
🌐 Web query:
peter-evans/create-or-update-comment@v4 supported inputs parameters
💡 Result:
Supported inputs for peter-evans/create-or-update-comment@v4
- token — GitHub token (defaults to GITHUB_TOKEN). [1]
- repository — target repository (owner/repo). [1]
- issue-number — issue or PR number (for creating a new comment). [1]
- comment-id — id of an existing comment (for updating). [1]
- body — comment body (cannot be used with body-path). [1]
- body-path — path to file containing comment body (cannot be used with body). [1]
- edit-mode — update mode: "replace" or "append" (default: append). [1]
- append-separator — separator when appending: "newline", "space", or "none" (default: newline). [1]
- reactions — comma/newline-separated reactions to add (e.g. +1, -1, laugh, confused, heart, hooray, rocket, eyes). [1]
- reactions-edit-mode — reaction update mode: "replace" or "append" (default: append). [1]
Sources: Official repository README/action inputs. [1]
Workflow will fail—body-includes is not a supported input for create-or-update-comment@v4.
The official action supports: token, repository, issue-number, comment-id, body, body-path, edit-mode, append-separator, reactions, and reactions-edit-mode—body-includes is absent. The step needs a two-step approach: use peter-evans/find-comment@v3 (which supports body-includes) to locate the comment, then pass its ID to create-or-update-comment.
- name: Comment/update canonical preview URL (idempotent)
- uses: peter-evans/create-or-update-comment@v4
- with:
- issue-number: ${{ github.event.number }}
- body: |
- PR Preview (canonical)
- https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/
- edit-mode: replace
- body-includes: "PR Preview (canonical)"
+ uses: peter-evans/find-comment@v3
+ id: find_preview_comment
+ with:
+ issue-number: ${{ github.event.number }}
+ body-includes: "PR Preview (canonical)"
+ - name: Create or update comment
+ uses: peter-evans/create-or-update-comment@v4
+ with:
+ issue-number: ${{ github.event.number }}
+ comment-id: ${{ steps.find_preview_comment.outputs.comment-id }}
+ edit-mode: replace
+ body: |
+ PR Preview (canonical)
+ https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - name: Comment/update canonical preview URL (idempotent) | |
| uses: peter-evans/create-or-update-comment@v4 | |
| with: | |
| issue-number: ${{ github.event.number }} | |
| body: | | |
| PR Preview (canonical) | |
| https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/ | |
| edit-mode: replace | |
| body-includes: "PR Preview (canonical)" | |
| - name: Comment/update canonical preview URL (idempotent) | |
| uses: peter-evans/find-comment@v3 | |
| id: find_preview_comment | |
| with: | |
| issue-number: ${{ github.event.number }} | |
| body-includes: "PR Preview (canonical)" | |
| - name: Create or update comment | |
| uses: peter-evans/create-or-update-comment@v4 | |
| with: | |
| issue-number: ${{ github.event.number }} | |
| comment-id: ${{ steps.find_preview_comment.outputs.comment-id }} | |
| edit-mode: replace | |
| body: | | |
| PR Preview (canonical) | |
| https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ github.event.number }}/ |
🧰 Tools
🪛 actionlint (1.7.8)
61-61: input "body-includes" is not defined in action "peter-evans/create-or-update-comment@v4". available inputs are "append-separator", "body", "body-file", "body-path", "comment-id", "edit-mode", "issue-number", "reactions", "reactions-edit-mode", "repository", "token"
(action)
🤖 Prompt for AI Agents
In .github/workflows/pages-preview.yml around lines 53 to 61, the workflow uses
the unsupported input body-includes on peter-evans/create-or-update-comment@v4;
replace this single-step approach with a two-step approach: first add a step
using peter-evans/find-comment@v3 with body-includes set to "PR Preview
(canonical)" and issue-number to locate the existing comment and output its id,
then update the current create-or-update-comment step to remove body-includes
and instead supply comment-id: ${{ steps.<find-step-id>.outputs.comment-id }}
(or omit comment-id to create if not found), keeping body, edit-mode and other
inputs unchanged so the action is compatible and idempotent.
| ### Docs Normalization (AST pipeline) | ||
|
|
||
| We run a deterministic Markdown normalizer (unified/remark) as a prebuild check. It parses Markdown to an AST, applies project transforms (anchors, TOC, link fixes), and stringifies back. This keeps anchors and spacing lint-clean and idempotent. | ||
|
|
||
| Manual runs: | ||
|
|
||
| ```bash | ||
| npm run docs:normalize # write normalized Markdown | ||
| npm run docs:normalize:check # fail if normalization would change files | ||
| ``` | ||
|
|
||
| Pre-push hook (opt-out flags; each step runs by default): | ||
|
|
||
| - Set `PREPUSH_SKIP_DOCS=1` to skip the VitePress docs build. | ||
| - Set `PREPUSH_SKIP_MERMAID=1` to skip Mermaid diagram verification (`scripts/diagrams.sh --verify --all`). | ||
| - Set `PREPUSH_SKIP_LINT=1` to skip Markdown lint. | ||
| - Set `PREPUSH_SKIP_NORMALIZE=1` to skip the Markdown normalizer check (`npm run docs:normalize:check`). | ||
| - Set `PREPUSH_SKIP_RUST=1` to skip Rust checks (`cargo fmt --check`, `cargo check`, `dprint`). | ||
|
|
||
| Mermaid verification mode: | ||
|
|
||
| - `scripts/diagrams.sh --verify --all` performs a non-destructive validation of all committed SVGs (metadata/tool pin checks). It exits non-zero on failures, which fails CI and pre-push unless you set `PREPUSH_SKIP_MERMAID=1`. | ||
|
|
||
| ## xtask quickstart (CI parity) |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
LGTM: clear prebuild story and consistent skip flags.
Docs normalization + pre‑push flags are coherent and VitePress‑aware. Minor style nit: vary the “Set …” lead‑ins for readability.
-- Set `PREPUSH_SKIP_DOCS=1` to skip the VitePress docs build.
-- Set `PREPUSH_SKIP_MERMAID=1` to skip Mermaid diagram verification (`scripts/diagrams.sh --verify --all`).
-- Set `PREPUSH_SKIP_LINT=1` to skip Markdown lint.
-- Set `PREPUSH_SKIP_NORMALIZE=1` to skip the Markdown normalizer check (`npm run docs:normalize:check`).
-- Set `PREPUSH_SKIP_RUST=1` to skip Rust checks (`cargo fmt --check`, `cargo check`, `dprint`).
+- Skip the VitePress docs build: `PREPUSH_SKIP_DOCS=1`.
+- Skip Mermaid verification (`scripts/diagrams.sh --verify --all`): `PREPUSH_SKIP_MERMAID=1`.
+- Skip Markdown lint: `PREPUSH_SKIP_LINT=1`.
+- Skip the Markdown normalizer check (`npm run docs:normalize:check`): `PREPUSH_SKIP_NORMALIZE=1`.
+- Skip Rust checks (`cargo fmt --check`, `cargo check`, `dprint`): `PREPUSH_SKIP_RUST=1`.🧰 Tools
🪛 LanguageTool
[style] ~98-~98: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...scripts/diagrams.sh --verify --all). - Set PREPUSH_SKIP_LINT=1` to skip Markdown ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~99-~99: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...H_SKIP_LINT=1to skip Markdown lint. - SetPREPUSH_SKIP_NORMALIZE=1` to skip the ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~100-~100: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...eck (npm run docs:normalize:check). - Set PREPUSH_SKIP_RUST=1 to skip Rust chec...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
In CONTRIBUTING.md around lines 83 to 106, the pre-push hook bullet points use
repetitive "Set `PREPUSH_...` to skip ..." phrasing and should be varied for
readability; update each bullet to use a more varied and consistent lead-in (for
example alternate between "To skip ..., set `PREPUSH_...`" and "Skip ... by
setting `PREPUSH_...`" or rephrase some bullets to active voice like "Skip the
VitePress docs build: set `PREPUSH_SKIP_DOCS=1`"), keeping the same env var
names and actions, preserving the order and meaning of flags.
| --- | ||
| title: git gatos pox — Proof-of-Experiment | ||
| --- | ||
|
|
||
| # git gatos pox — Proof-of-Experiment | ||
|
|
||
| <a id="git-gatos-pox-proof-of-experiment"></a> | ||
| <!-- AUTOGENERATED TOC START --> | ||
|
|
||
| - [Synopsis](#synopsis) | ||
| - [Behavior](#behavior) | ||
|
|
||
| <!-- AUTOGENERATED TOC END --> |
There was a problem hiding this comment.
🧩 Analysis chain
The file has autogenerated markers but line 9 contains a blank line immediately after <!-- AUTOGENERATED TOC START -->, which likely diverges from what scripts/anchors_and_toc.py produces. This causes the script to flag the file as out-of-sync and must be regenerated before merge.
Run the prebuild script to synchronize:
python scripts/anchors_and_toc.py --write --paths docs/cli/pox.mdVerify no divergence remains:
python scripts/anchors_and_toc.py --check --paths docs/cli/pox.md
# Must exit with 0
---
🏁 Script executed:
```shell
#!/bin/bash
# Comprehensive verification of docs/cli/pox.md state
echo "=== Step 1: Check if TOC needs regeneration ==="
python scripts/anchors_and_toc.py --check --paths docs/cli/pox.md
TOC_CHECK_EXIT=$?
echo "Exit code: $TOC_CHECK_EXIT (0=sync, 1=needs update)"
echo ""
echo "=== Step 2: Search for duplicate anchor IDs ==="
echo "Looking for duplicate <a id=\"...\"> tags..."
grep -n '<a id=' docs/cli/pox.md | sort
echo ""
echo "Count of total IDs:"
grep -o '<a id="[^"]*"' docs/cli/pox.md | wc -l
echo "Count of unique IDs:"
grep -o '<a id="[^"]*"' docs/cli/pox.md | sort -u | wc -l
echo ""
echo "=== Step 3: Verify H1 presence and TOC content ==="
echo "H1 heading:"
sed -n '5p' docs/cli/pox.md
echo ""
echo "TOC section (lines 8-13):"
sed -n '8,13p' docs/cli/pox.md | cat -A
echo ""
echo "=== Step 4: Check blank line after TOC START ==="
echo "Line 9 content (should show if blank):"
sed -n '9p' docs/cli/pox.md | cat -A
echo "Line 9 byte length:"
sed -n '9p' docs/cli/pox.md | wc -c
Length of output: 714
Regenerate the TOC—blank lines are breaking sync, not critical data corruption.
The verification confirms the TOC is out of sync (script returned "would change"), but the scope is far narrower than the original review suggests:
- Blank line exists: Line 9 is blank after
<!-- AUTOGENERATED TOC START --> - No duplicate anchors: All 3 IDs are unique (
git-gatos-pox-proof-of-experiment,synopsis,behavior)—past duplicate warnings are stale - Script expects regeneration: The
--checkflag confirms divergence
Run the regeneration command to synchronize:
python scripts/anchors_and_toc.py --write --paths docs/cli/pox.mdThen verify:
python scripts/anchors_and_toc.py --check --paths docs/cli/pox.mdThe H1 exclusion from the TOC appears intentional (tool behavior), so no action needed there.
🤖 Prompt for AI Agents
In docs/cli/pox.md around lines 1 to 13 the autogenerated TOC is out of sync due
to a blank line after the `<!-- AUTOGENERATED TOC START -->` token (line 9), so
run the TOC/anchors regeneration script to rewrite the file and remove the blank
line: execute `python scripts/anchors_and_toc.py --write --paths
docs/cli/pox.md` then verify with `python scripts/anchors_and_toc.py --check
--paths docs/cli/pox.md`; commit the updated docs/cli/pox.md if the check passes
(no other changes are required, H1 exclusion is intentional).
| - No ambient RNG. Provide `rng(seed_bytes)` which expands a user-supplied seed into a deterministic stream. | ||
| - Normative algorithm: `pcg32@1`. Implementations MUST record RNG id and version via the `Fold-Engine` string and SHOULD include `Fold-RNG` trailer when RNG is used. | ||
| - Canonical seed helper: `seed64 = trunc64(blake3(inputs_root || policy_root || fold_root))`. | ||
| - Use discouraged in folds; if used, caller MUST pass explicit seed material. |
There was a problem hiding this comment.
🧩 Analysis chain
Specify the exact RNG variant and include a test vector.
“pcg32@1” is ambiguous (stream init, state/advance, endian). Pin the exact algorithm variant and provide a short test vector to ensure identical streams across implementations. Cross‑link where the RNG id/version registry lives.
🌐 Web query:
Best-practice reference for PCG32 variant identification and test vectors.
💡 Result:
Short answer — use the official PCG references plus the reference implementations (they contain canonical test vectors).
Recommended authoritative references
- PCG family paper / specification (authoritative description and notation for variants). [1]
- PCG website (implementation notes and links to reference code). [1][2]
How to identify the PCG32 variant
- "pcg32" ≡ Lcg64Xsh32 (aka XSH-RR 64/32). In PCG C++ this is exposed as pcg_engines::setseq_xsh_rr_64_32 (sometimes shortened to pcg32 / Lcg64Xsh32). Use those canonical names when labeling variants. [2][3]
Where to get canonical test vectors / reference implementations
- Official PCG reference code and examples on the PCG site and linked repositories (C/C++ reference implementation includes the preferred 32-bit variant). Use the reference implementation to produce test vectors (seed → state → known outputs). [2][1]
- Language-specific, well-tested implementations that include unit tests against reference vectors: Rust rand_pcg crate (tests/reference vectors), other community implementations on GitHub (many include test vectors and demo programs). Use their test suites as additional vectors. [4][5]
Practical best-practice checklist
- Refer to the paper for the exact permutation name and parameterization (XSH-RR 64/32). [1]
- Use the official/reference C/C++ implementation to generate and publish test vectors (seed, initial state, and first N outputs). [2]
- Cross-check with well-maintained implementations (e.g., rand_pcg) and their unit tests. [4]
- Include explicit seed/state, bit-widths (state_type and result_type), and the exact variant name (Lcg64Xsh32 / XSH-RR 64/32) alongside vectors so others can reproduce results. [2][3][4]
Sources
[1] PCG paper / spec and PCG site.
[2] Using the PCG C++ implementation / pcg-random.org documentation.
[3] PCG reference implementations and examples (C implementations mentioning pcg32 / xsh_rr).
[4] rand_pcg (Rust) — crate docs and tests referencing Pcg32 / Lcg64Xsh32.
[5] Community GitHub implementations (example pcg-dxsm / pcg32 sources).
Would you like me to fetch and produce a small canonical test-vector block (seed → first 8 uint32 outputs) from the official reference implementation?
🏁 Script executed:
#!/bin/bash
# Inspect the documentation file and search for RNG registry references
echo "=== File content around lines 81-84 ==="
sed -n '75,90p' docs/deterministic-lua.md
echo ""
echo "=== Search for RNG registry references ==="
rg -i "rng.*registry|registry.*rng|rng.*id.*version" --type=md
echo ""
echo "=== Search for test.*vector or reference.*impl references ==="
rg -i "test.*vector|reference.*impl|canonical.*test" --type=md docs/
echo ""
echo "=== Check for Fold-RNG trailer or existing variant specs ==="
rg -i "lcg64xsh32|xsh-rr|fold-rng|fold-engine" --type=mdLength of output: 2520
🏁 Script executed:
#!/bin/bash
# Check for ADR files and RNG registry documentation
echo "=== Search for ADR files ==="
fd -e md "ADR|adr" docs/
echo ""
echo "=== Check for RNG registry or registry docs ==="
rg -i "registry|rng.*algorithm.*id|canonical.*rng" docs/ --type=md
echo ""
echo "=== Look for test vector definitions ==="
rg -i "seed.*output|test.*vector.*pcg|reference.*output" docs/ --type=mdLength of output: 740
Specify exact PCG32 variant name, include test vector, and document RNG registry location.
"pcg32" is the short form; the exact variant is "Lcg64Xsh32" (XSH-RR 64/32). The current notation pcg32@1 is ambiguous on stream initialization, state/advance, and endianness—implementations diverge. Replace with explicit variant name and parameterization.
Include a canonical test vector (seed, initial state, and first N uint32 outputs) using the official reference C/C++ implementation or well-tested community implementations like Rust's rand_pcg. This is essential for cross-implementation verification.
No RNG registry file or cross-link currently exists in the codebase—add reference to where the registry of variant definitions and versions lives.
Changes required in docs/deterministic-lua.md lines 83–84:
- Replace
pcg32@1withLcg64Xsh32@1(orXSH-RR 64/32@1) - Add inline or linked test vector block (seed → first 8 outputs)
- Cross-link registry location
🤖 Prompt for AI Agents
In docs/deterministic-lua.md around lines 81–84, replace the ambiguous "pcg32@1"
with the exact variant name "Lcg64Xsh32@1" (aka XSH-RR 64/32@1), add a canonical
test vector block showing a concrete seed/initial state and the first 8 uint32
outputs produced by the official reference implementation (use the C/C++
reference or rust rand_pcg to generate values and cite the source), and add a
cross-link to the RNG registry location (create docs/rng-registry.md or point to
the repository path where RNG variant definitions and versions will be
maintained) so implementations can verify stream initialization, state layout,
advance behavior, and endianness against the provided vector and registry.
| <a id="gatos-features-derived-from-spec-v0.3"></a> | ||
| <!-- | ||
| NOTE: The Table of Contents and anchor IDs in this file are auto-generated by | ||
| scripts/anchors_and_toc.py. Do not edit the TOC or <a id="…"></a> blocks by hand. | ||
| To regenerate after editing headings: | ||
|
|
||
| python3 scripts/anchors_and_toc.py --write --paths docs/FEATURES.md | ||
|
|
||
| This prebuild step is also executed in CI before the VitePress build to keep | ||
| anchors/TOC stable and idempotent. | ||
| --> | ||
|
|
||
| <a id="gatos-features-derived-from-spec-v0.3"></a> |
There was a problem hiding this comment.
🧩 Analysis chain
CRITICAL: Duplicate DOM IDs from manual <a id> + VitePress auto-anchors.
Every heading already gets an id from VitePress; adding a separate <a id="…"></a> with the same slug produces duplicate ids (invalid HTML, brittle nav/search). Remove all HTML anchor lines and rely on auto-slugs, or switch to native heading IDs (## Heading {#custom-id}) and stop emitting <a> tags. Update the generator accordingly.
Also applies to: 62-67, 75-76, 101-110, 119-124, 131-140, 149-154, 160-170, 179-184, 191-200, 209-214, 221-230, 239-244, 251-260, 269-274, 281-290, 299-304, 311-320
🏁 Script executed:
#!/bin/bash
# Quick sanity: count manual anchors (should become 0)
grep -c '<a id="' docs/FEATURES.mdLength of output: 2
Verifying the VitePress auto-anchor claim—searching for its actual behavior:
CRITICAL: Remove 38 duplicate DOM IDs from manual <a id> tags conflicting with VitePress auto-anchors.
VitePress automatically applies anchor IDs to headers; to specify custom IDs, use the heading suffix syntax {#custom-id} instead of separate HTML anchor elements. The current file contains 38 instances of <a id="…"></a> tags that duplicate the auto-generated IDs, violating HTML semantics and breaking navigation/search functionality.
Required changes:
- Remove all 38
<a id>blocks fromdocs/FEATURES.md - Update
scripts/anchors_and_toc.pyto emit heading IDs using the{#id}syntax instead of HTML anchor tags - Verify the generator no longer outputs
<a id>elements
This applies to the header comment section (lines 3-15) and all subsequent anchor blocks throughout the file.
| - Content addressing: `Event-CID = cidv1(dag-cbor, blake3(canonical_bytes))` | ||
|
|
||
| (BLAKE3 per spec; multihash extension as deployed). | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Define the multihash/multicodec for BLAKE3 in CIDv1.
“blake3 (multihash extension as deployed)” is vague. State the exact multicodec name/code and multihash code used for cidv1(dag-cbor, …) so CIDs interoperate across stacks. If non‑standard, document the extension and fallback.
🌐 Web query:
What multicodec/multihash code is used for BLAKE3 in CIDv1?
💡 Result:
The multihash code for BLAKE3 (used for CIDv1 multihash) is 0x1e (named "blake3"). [1][2]
Sources:
- IETF draft multihash table listing "blake3" = 0x1e. [1]
- multihash/multiformats implementations that include BLAKE3 (e.g. Rust docs showing Blake3_256 support). [2]
Specify BLAKE3 multihash/multicodec codes explicitly in the spec.
Web search confirms BLAKE3 multihash code is 0x1e (multicodec name: blake3, per IETF draft multihash table). The spec must state these codes directly—not as "(multihash extension as deployed)"—for CIDv1 CID generation to interoperate across stacks. Update line 361 to: Event-CID = cidv1(dag-cbor, multihash(0x1e, blake3(canonical_bytes))) or equivalent precision.
🤖 Prompt for AI Agents
In docs/SPEC.md around lines 360 to 363, the spec mentions "Event-CID =
cidv1(dag-cbor, blake3(canonical_bytes))" with a vague parenthetical about a
multihash extension; update this to explicitly state the multihash/multicodec
code for BLAKE3 so implementations can interoperate. Replace the line with an
explicit form such as "Event-CID = cidv1(dag-cbor, multihash(0x1e,
blake3(canonical_bytes)))" (or equivalent wording that documents the multihash
code 0x1e and the multicodec name "blake3") and ensure any related text notes
the use of multihash code 0x1e for BLAKE3.
| `encrypted_meta` (Normative) — object fields: | ||
|
|
||
| - `enc`: string — cipher suite id, e.g., `aes-256-gcm` or `chacha20poly1305`. | ||
| - `iv`: base64url — initialization vector/nonce bytes. | ||
| - `salt`: base64url — KDF salt when deriving keys (RECOMMENDED when using passphrase KDFs). | ||
| - `aad`: base64url — additional authenticated data bound to encryption (OPTIONAL; empty if unused). | ||
| - `tag`: base64url — AEAD tag if not appended to ciphertext (omit when suite appends tag). | ||
|
|
||
| `ciphertext_hash` is an integrity hint only. Authenticity comes from the | ||
| envelope signature and repository trust rules (see Sections 3 and 6). Verifiers | ||
| **MUST** treat `ciphertext_hash` as unauthenticated unless covered by a | ||
| signature. | ||
|
|
||
| Compatibility note: previous drafts used `cipher_meta`. Parsers **SHOULD** | ||
| accept inputs with `cipher_meta`; emit `encrypted_meta` going forward. A simple | ||
| migration heuristic is: if `cipher_meta` exists and `encrypted_meta` is absent, | ||
| rename `cipher_meta` → `encrypted_meta` (see `scripts/migrate_opaque_pointers.py`). | ||
|
|
||
| Before/after example: | ||
|
|
||
| ```jsonc | ||
| // legacy | ||
| { "kind":"opaque", "algo":"aes-256-gcm", "ciphertext_hash":"blake3:…", | ||
| "cipher_meta": {"enc":"aes-256-gcm","iv":"…","salt":"…"} } | ||
|
|
||
| // normalized | ||
| { "kind":"opaque", "algo":"aes-256-gcm", "ciphertext_hash":"blake3:…", | ||
| "encrypted_meta": {"enc":"aes-256-gcm","iv":"…","salt":"…"} } | ||
| ``` |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Nice: encrypted_meta schema + migration note.
Consider adding a minimal JSON Schema (types/required) for encrypted_meta and clarifying whether ciphertext_hash is also captured in any signed envelope for authenticity.
🤖 Prompt for AI Agents
In docs/SPEC.md around lines 547 to 575, add a minimal JSON Schema for the
`encrypted_meta` object (specifying types for `enc`, `iv`, `salt`, `aad`, `tag`
and which fields are REQUIRED vs OPTIONAL) and append a short clarification
about `ciphertext_hash` authenticity (explicitly state whether it is captured in
the signed envelope or must be treated as unauthenticated unless separately
covered by a signature, and recommend signing it or including it in the envelope
when authenticity is required).
| Canonical serialization for `Explorer-Root` (Normative): | ||
|
|
||
| Let `ledger_head`, `policy_root`, and `fold_root` be lowercase hex digests. Let | ||
| `extractor_version` be a UTF-8 string. Serialize as a concatenation of 32-bit | ||
| big-endian length prefixes and raw bytes, in this exact order: | ||
|
|
||
| ``` | ||
| BE32(len(ledger_head_bytes)) || ledger_head_bytes || | ||
| BE32(len(policy_root_bytes)) || policy_root_bytes || | ||
| BE32(len(fold_root_bytes)) || fold_root_bytes || | ||
| BE32(len(version_bytes)) || version_bytes | ||
| ``` | ||
|
|
||
| Where `*_bytes` for digests are obtained by hex-decoding the string, and | ||
| `version_bytes` is the UTF-8 encoding of `extractor_version`. Then: | ||
|
|
||
| ``` | ||
| Explorer-Root = blake3(serialized_bytes) | ||
| ``` | ||
|
|
||
| For raw ledger exports, drop the 3rd line (fold_root length and value). | ||
|
|
||
| Worked example (derived export): | ||
|
|
||
| ``` | ||
| ledger_head (hex): 1111111111111111111111111111111111111111 # 20 bytes | ||
| policy_root (hex): 2222222222222222222222222222222222222222 # 20 bytes | ||
| fold_root (hex): aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa # 32 bytes | ||
| version (utf8): v1.2.3+linux-x86_64 | ||
|
|
||
| serialized hex (BE32 prefix + fields): | ||
| 00000014111111111111111111111111111111111111111100000014222222222222222222222222222222222222222200000020aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa0000001376312e322e332b6c696e75782d7838365f3634 | ||
|
|
||
| BLAKE3(serialized) = e4cbbcc02698608bb59ed39d715ffd6e74c2865f473daf7cb861f9da33565d9d | ||
| ``` | ||
|
|
||
| The `gatos export verify` command **MUST** recompute `Explorer-Root` against | ||
| the repository and report mismatches. | ||
|
|
There was a problem hiding this comment.
Explorer‑Root example: call out SHA‑1 vs SHA‑256 commit OIDs.
The example shows 20‑byte commit OIDs; Git SHA‑256 repos produce 32‑byte OIDs. Add a note that BE32 length‑prefixing covers both, and that ledger_head/policy_root bytes are the raw hex‑decoded commit IDs (20 or 32 bytes). Prevents implementer confusion.
🤖 Prompt for AI Agents
docs/SPEC.md around lines 777 to 815: the worked example uses 20‑byte commit
OIDs (SHA‑1) but modern Git can use 32‑byte SHA‑256 OIDs, which can confuse
implementers; update the text to explicitly state that ledger_head and
policy_root are the raw hex‑decoded commit IDs and may be either 20 or 32 bytes
depending on repository OID format, and add a short clarifying note that the
BE32 length prefixes allow both sizes (so implementations must hex‑decode the
commit OID string and use the resulting raw bytes and their length when
serializing); optionally annotate the worked example to say “example uses
20‑byte (SHA‑1) OIDs” so readers understand it is not representative of SHA‑256
repos.
…le slug id; compact TOC END); repo-wide normalization
|
PR Preview (canonical) |
There was a problem hiding this comment.
Actionable comments posted: 22
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (9)
docs/decisions/ADR-0002/DECISION.md (1)
84-93: Nit: Link targets—use relative canonical paths already used elsewhere.The schema links look correct; consider adding “(normative)” labels where referenced in prose to reduce ambiguity.
Also applies to: 145-153
docs/TASKS.md (1)
1-165: Add CI anchor lint.Automate detection:
#!/bin/bash # Fail if any consecutive duplicate anchors exist if grep -R -n '</a><a id="' docs/TASKS.md >/dev/null; then echo "Duplicate anchors found"; exit 1 fi # Fail if any id occurs >1 ids=$(rg '<a id="([^"]+)"></a>' -o '$1' docs/TASKS.md | sort) dupes=$(echo "$ids" | uniq -d) test -z "$dupes" || { echo "Duplicate id(s):"; echo "$dupes"; exit 1; }docs/SPEC.md (3)
151-158: H1/H2 link pollution around top sections.Multiple redundant anchors around “Git As The Operating Surface” — same fix as overall dedupe.
1-1309: CI guardrail for anchors (repo‑wide).Add a workflow step to regenerate anchors then fail on dupes:
#!/bin/bash python3 scripts/anchors_and_toc.py --write --paths docs || exit 1 # No consecutive anchors if rg -n '</a><a id="' docs/ | grep -v node_modules; then exit 1; fi # No duplicated IDs per file while read -r f; do ids=$(rg '<a id="([^"]+)"></a>' -o '$1' "$f" | sort) d=$(echo "$ids" | uniq -d | wc -l) test "$d" -eq 0 || { echo "Duplicate ids in $f"; exit 1; } done < <(fd -e md docs)
1163-1164: Convert ADR references to markdown links matching the established pattern.Lines 1163-1164 contain plain text ADR references that should be markdown links. The same file uses the canonical format elsewhere (lines 1093, 1174). Convert to:
See [ADR-0002](./decisions/ADR-0002/DECISION.md) for the normative PoE requirements and [ADR-0001](./decisions/ADR-0001/DECISION.md) for the definition of `content_id` and canonical serialization.docs/FAQ.md (1)
509-575: Anchor/link hygiene: duplicate anchors under comparison sections.Consolidate to a single anchor; also ensure secondary “gatos-1/2” anchors don’t collide with “gatos”.
Also applies to: 549-556, 567-575, 583-588, 593-600
docs/TECH-SPEC.md (3)
319-343: JSONL protocol: good normalization; ensure ping/pong kinds are documented.If
kindis reserved for heartbeats, call it out once (allowed values).Also applies to: 345-355
1-647: CI: enforce dedupe after generation for all three primary specs.Add a docs job that runs anchor generation and fails on duplicates (same script as SPEC comment), and a link-check step (e.g., lychee) to catch malformed links.
547-555: Reconcile conflicting job claim ref paths across documentation.Verification confirms material inconsistency: ADR‑0002 normatively defines per‑worker claim refs (
refs/gatos/jobs/<job-id>/claims/<worker-id>), but TECH‑SPEC.md (lines 547–567), CHAPTER‑006.md, ROADMAP.md, and sections of SPEC.md use the single‑lock pattern (refs/gatos/jobs/<job-id>/claim). SPEC.md itself contradicts itself (line 994 vs. line 1126).Decide: adopt the per‑worker ADR‑0002 scheme (supports worker auditing, aligns with decision documentation) or revert to single‑lock and update ADR‑0002 accordingly. Update all occurrence sites to enforce a single normative path.
♻️ Duplicate comments (23)
docs/diagrams/data_flow.md (1)
3-7: 🚨 CRITICAL: Regression—duplicate anchor IDs persist despite previous fixes.Lines 3, 5, and 7 all define
<a id="gatos-data-flow-example"></a>. This is invalid HTML;idattributes must be unique within a document. Duplicate IDs break anchor navigation and violate the HTML standard.Past review comments explicitly flagged this issue and marked it resolved, yet the current code shows three identical anchors—either a regression or the automation script (
scripts/anchors_and_toc.py) is inserting duplicates instead of a single anchor.Immediate fix: Remove the redundant anchors, leaving only one:
# GATOS Data Flow Example <a id="gatos-data-flow-example"></a> - -<a id="gatos-data-flow-example"></a> - -<a id="gatos-data-flow-example"></a>Root cause analysis: Verify that
scripts/anchors_and_toc.pyis not inserting multiple anchors per heading. If it is, fix the script logic to ensure idempotency and uniqueness.docs/decisions/ADR-0003/DECISION.md (3)
140-144: DUPLICATE COMMENT: Duplicate generic anchor ID "goals" repeats across milestones—breaks uniqueness.
1-8: 🛑 CRITICAL: H1 heading contains triple identical anchor IDs—HTML spec violation kills navigation.Lines 3, 5, 7 all contain
<a id="adr-0003-consensus-governance-for-gated-actions"></a>. In HTML, anchor IDs must be globally unique per document. VitePress will bind to the first occurrence and silently discard all others. This breaks every intra-page link to the H1.This triple-anchor defect is identical to issues flagged in prior reviews (existing_comments) and supposedly fixed in commits f7ebd70–9f8eae7. The fact it persists here proves:
- Either the deduplication logic in
scripts/anchors_and_toc.pyis broken, or- The script was never regenerated on this file post-prior-fix, or
- Someone manually edited the file after regeneration, reintroducing the defect.
Unacceptable. Remove duplicates now:
# ADR-0003: Consensus Governance for Gated Actions <a id="adr-0003-consensus-governance-for-gated-actions"></a> - -<a id="adr-0003-consensus-governance-for-gated-actions"></a> - -<a id="adr-0003-consensus-governance-for-gated-actions"></a>
51-65: 🛑 CRITICAL: Systemic generic anchor ID collision—nine identical "goals" anchors across M0–M9 break document semantics.Each milestone subsection (M0 Goals at line 53, M1 Goals at line 62, etc.) defines an anchor with the same non-unique ID:
<a id="scope"></a>. This pattern repeats for deliverables and done-when across all nine milestones. You have effectively created 9 identical anchor IDs in a single document.HTML spec: anchor IDs are globally unique. Period. Browsers cannot disambiguate which "scope" you mean; they bind to the first one (line 53) and render all other identical-ID anchors inert. Every link to
#scope,#deliverables, or#done-whenpoints only to M0's sections. M1–M9 equivalents become unreachable via anchor links.This is not a minor oversight—this completely breaks VitePress in-page navigation for 80% of the Roadmap sections.
Fix required: Use numbered anchor IDs to enforce uniqueness:
## Scope - <a id="scope"></a> + <a id="scope-0"></a> Define a system...Apply identical change for all M0–M9 subsection anchors (every "Goals", "Deliverables", "Done When" heading). Ensure TOC entries are updated to reference the numbered IDs.
docs/cli/export.md (2)
24-28: 🛑 CRITICAL: Section "Synopsis" contains triple identical anchors.Lines 24, 26, 28 all define
<a id="synopsis"></a>. Remove duplicates—keep one:## Synopsis <a id="synopsis"></a> - -<a id="synopsis"></a> - -<a id="synopsis"></a>Apply identical fix to "Behavior" (lines 40, 42, 44).
7-11: 🛑 CRITICAL: H1 heading triple anchors with conflicting slug variants.Lines 7, 9, 11 contain two distinct anchor IDs:
- Lines 7 & 9:
git-gatos-export--explorer-off-ramp(double-dash)- Line 11:
git-gatos-export-explorer-off-ramp(single-dash)Multiple conflicting IDs on same heading. Prior review flagged this (existing_comments); the "fix" was incomplete.
Keep only the canonical single-dash anchor:
# git gatos export — Explorer Off-Ramp -<a id="git-gatos-export--explorer-off-ramp"></a> - -<a id="git-gatos-export--explorer-off-ramp"></a> - <a id="git-gatos-export-explorer-off-ramp"></a>docs/cli/lint.md (2)
25-29: 🛑 CRITICAL: Section "Synopsis" has triple identical anchor IDs—blocks intra-page navigation.Lines 25, 27, 29 all contain
<a id="synopsis"></a>. Duplicate IDs violate HTML spec. TOC entry at line 15 correctly links to#synopsis, but the triple anchor creates undefined browser behavior.Remove the duplicate anchors—keep ONE:
## Synopsis <a id="synopsis"></a> - -<a id="synopsis"></a> - -<a id="synopsis"></a>Apply identical fix for "Forbidden patterns (fail)" (lines 37, 39, 41) and "Warnings (configurable)" (lines 49, 51, 53).
7-11: 🛑 CRITICAL: H1 heading has triple anchors with format inconsistency—violates HTML uniqueness.Lines 7, 9, 11 contain conflicting anchor IDs:
- Line 7 & 9:
git-gatos-lint--deterministic-lua-linter(double-dash variant)- Line 11:
git-gatos-lint-deterministic-lua-linter(single-dash, DIFFERENT ID)Two distinct anchor IDs on the same H1 heading. VitePress will arbitrarily bind to one and ignore the other. This is HTML spec violation.
Past review (existing_comments) flagged this identical defect and claimed fix (commit 49c0bff). The defect persists, proving the fix was incomplete or the file was never regenerated.
Remove all duplicates—keep ONE canonical single-dash anchor:
# git gatos lint — Deterministic Lua Linter -<a id="git-gatos-lint--deterministic-lua-linter"></a> - -<a id="git-gatos-lint--deterministic-lua-linter"></a> - <a id="git-gatos-lint-deterministic-lua-linter"></a>docs/USE-CASES.md (1)
3-7: 🛑 CRITICAL: H1 heading triple anchors with double-dash non-canonical variant.Lines 3, 5, 7:
- Lines 3 & 5:
<a id="gatos--use-cases"></a>(double-dash, NON-CANONICAL)- Line 7:
<a id="gatos-use-cases"></a>(canonical single-dash)Remove non-canonical double-dash variants—keep only the canonical single-dash anchor:
-<a id="gatos--use-cases"></a> - -<a id="gatos--use-cases"></a> - <a id="gatos-use-cases"></a>docs/diagrams/api_endpoints.md (2)
51-55: 🛑 CRITICAL: Section "Error Responses" triple identical anchor IDs.Lines 51, 53, 55 all contain
<a id="error-responses"></a>. Remove duplicates—keep one:## Error Responses <a id="error-responses"></a> - -<a id="error-responses"></a> - -<a id="error-responses"></a>
3-7: 🛑 CRITICAL: H1 heading triple identical anchor IDs.Lines 3, 5, 7 all contain
<a id="gatos-api-interaction-model"></a>. Duplicate IDs violate HTML spec. Remove duplicates—keep one:# GATOS API Interaction Model <a id="gatos-api-interaction-model"></a> - -<a id="gatos-api-interaction-model"></a> - -<a id="gatos-api-interaction-model"></a>docs/decisions/README.md (1)
3-16: 🛑 CRITICAL: H1 heading triple anchor + orphaned duplicate after TOC.Lines 3, 5, 7 contain triple identical
<a id="gatos-architecture-decision-records"></a>.Additionally, line 16 contains an orphaned duplicate anchor after the TOC block with no associated heading—this is doubly wrong.
Prior review (existing_comments lines 3-3 and 3-16) flagged these exact defects; supposedly fixed but persist uncorrected.
Remove all duplicates—keep only the anchor on line 3 (after H1):
# GATOS Architecture Decision Records <a id="gatos-architecture-decision-records"></a> - -<a id="gatos-architecture-decision-records"></a> - -<a id="gatos-architecture-decision-records"></a> <!-- AUTOGENERATED TOC START --> ... <!-- AUTOGENERATED TOC END --> -<a id="gatos-architecture-decision-records"></a> This directory contains the Architecture Decision Records...docs/SPEC.md (4)
405-423: Good: Canonicalization cites DAG‑CBOR + RFC 8949 and clarifies key sorting.This addresses prior portability issues. LGTM.
3-12: Blocker: Duplicate anchors (numeric + slug variants) persist — must be deduped.E.g., Lines 88–91 show
id="0",id="0-conventions",id="0.-conventions". Keep one canonical slug per heading; remove numeric/variant IDs.Regenerate anchors across SPEC to eliminate duplicates.
Also applies to: 86-91, 109-113, 196-201, 305-317, 322-327, 355-360, 455-466, 495-500, 537-545, 797-823, 1297-1309
412-415: Specify multihash/multicodec for BLAKE3 in CIDv1 explicitly.Replace vague “multihash extension” with the exact multihash code/name to ensure interoperable CIDs.
Proposed text: “Event‑CID = cidv1(dag‑cbor, multihash(0x1e, blake3(canonical_bytes)))”.
What is the multihash/multicodec code for BLAKE3 used in CIDv1?
910-948: Explorer‑Root: Nice canonicalization (BE32 + hex‑decoded bytes + example).Add one note: Git SHA‑256 repos produce 32‑byte OIDs; your BE32 prefix supports both—call this out once near 912–921 for clarity (if not already in surrounding text).
docs/decisions/ADR-0002/DECISION.md (1)
20-47: Blocker: Duplicate and orphaned anchor IDs across the document.Multiple consecutive
<a id>for the same heading (including numeric and variant slugs). This violates HTML, breaks links, and confuses SSG.Fix: emit exactly one normalized slug per heading, drop numeric/variant duplicates, keep anchor immediately under the heading.
Example patch (apply pattern throughout):
-# ADR-0002: Distributed Compute via a Job Plane - -<a id="adr-0002-distributed-compute-via-a-job-plane"></a> -<a id="adr-0002-distributed-compute-via-a-job-plane"></a> -<a id="adr-0002-distributed-compute-via-a-job-plane"></a> +# ADR-0002: Distributed Compute via a Job Plane +<a id="adr-0002-distributed-compute-via-a-job-plane"></a>Enforce with a prebuild dedupe or regenerate via your anchors tool.
Also applies to: 53-67, 73-78, 96-101, 110-115, 156-161, 170-175, 187-200, 217-222, 248-295
docs/TASKS.md (1)
3-7: Blocker: Triple/duplicate anchors (incl. double-dash variants) — fix generator and regenerate.Every section shows 2–3 anchors; some use both
--and-for&. Normalize slugging so&→ single-, collapse multiple-, and emit one anchor per heading. Update TOC to match.Patch pattern:
-<a id="epic-6-cas--opaque-pointers"></a> -<a id="epic-6-cas--opaque-pointers"></a> -<a id="epic-6-cas-opaque-pointers"></a> +<a id="epic-6-cas-opaque-pointers"></a>Add a CI guard to fail on consecutive
</a><a id=".Also applies to: 27-47, 96-101, 109-114, 121-162
docs/FAQ.md (2)
3-8: Blocker: Massive duplicate anchors and variant slugs (some triple on same line).Keep one slug per heading, remove numeric and duplicate variants, regenerate TOC.
Example:
-<a id="1"></a><a id="1-fold-compilation--interpreted-yaml-or-compiled"></a><a id="1-fold-compilation-interpreted-yaml-or-compiled"></a> +<a id="1-fold-compilation-interpreted-yaml-or-compiled"></a>Apply across the file.
Also applies to: 76-92, 142-149, 165-171, 229-236, 445-452, 457-465, 471-476, 483-488, 495-500
425-426: Admonition syntax not supported (no adapter yet).Replace
> [!faq] …with a plain blockquote or a styled tip once the adapter lands.Patch:
-> [!faq] “Are we missing any big pieces?” (Short list) +> “Are we missing any big pieces?” (Short list)Also applies to: 660-661
docs/TECH-SPEC.md (2)
3-8: Blocker: Duplicate anchors across sections and variant slugs — regenerate and dedupe.Same remediation as other files: one normalized slug per heading, no numeric “N” or “N.” variants.
Also applies to: 42-63, 58-63, 97-103, 189-193, 213-218, 233-239, 392-393
249-249: Brand capitalization: “macOS”, not “macos”.Patch:
-- Golden vectors across linux/macos/windows/wasm; +- Golden vectors across linux/macOS/windows/wasm;docs/STAKEHOLDERS.md (1)
3-7: 🔴 CRITICAL: Duplicate anchor IDs across all sections violate HTML5 spec and break navigation.Your file contains 31 duplicate
idattributes across 11 sections, not just the main heading. Multiple identical IDs per section cause undefined browser behavior for internal links:
- Lines 3–7: Main heading has 2×
gatos--stakeholders--goals+ 1×gatos-stakeholders-goals- Lines 30–34, 38–42, 51–55, 64–68, 77–81, 90–94, 102–106, 113–117, 124–128, 136–140: Each stakeholder section has 3× identical anchors (e.g.,
stakeholders,app-developer-dev,sre--ops-sre,auditor--grc-aud, etc.)Fix: Run
scripts/anchors_and_toc.py --writeto regenerate with single canonical anchor per heading. The script correctly deduplicates, but the current file still contains remnants of prior injections. Verify the script executed in--writemode (not--check) and committed the result.# GATOS — STAKEHOLDERS & GOALS -<a id="gatos--stakeholders--goals"></a> - -<a id="gatos--stakeholders--goals"></a> - -<a id="gatos-stakeholders-goals"></a> +<a id="gatos-stakeholders-goals"></a>Apply the same pattern to all 11 sections: collapse 3 anchors → 1 per heading.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (23)
docs/FAQ.md(26 hunks)docs/FEATURES.md(8 hunks)docs/ROADMAP-XTASK.md(2 hunks)docs/ROADMAP.md(1 hunks)docs/SPEC.md(28 hunks)docs/STAKEHOLDERS.md(2 hunks)docs/TASKS.md(4 hunks)docs/TECH-SPEC.md(17 hunks)docs/USE-CASES.md(2 hunks)docs/cli/export.md(1 hunks)docs/cli/foldc.md(1 hunks)docs/cli/lint.md(1 hunks)docs/cli/policyc.md(1 hunks)docs/cli/pox.md(1 hunks)docs/decisions/ADR-0001/DECISION.md(4 hunks)docs/decisions/ADR-0001/flyingrobots.md(2 hunks)docs/decisions/ADR-0002/DECISION.md(9 hunks)docs/decisions/ADR-0003/DECISION.md(8 hunks)docs/decisions/README.md(2 hunks)docs/deterministic-lua.md(1 hunks)docs/diagrams/api_endpoints.md(2 hunks)docs/diagrams/architecture.md(1 hunks)docs/diagrams/data_flow.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/TECH-SPEC.md
[uncategorized] ~249-~249: The operating system from Apple is written “macOS”.
Context: ...Testing: - Golden vectors across linux/macos/windows/wasm; integer and fixed-point c...
(MAC_OS)
docs/FAQ.md
[grammar] ~702-~702: Use a hyphen to join words.
Context: ...ecution must be pure, total, side-effect free. Same inputs ⇒ same bytes. --- ##...
(QB_NEW_EN_HYPHEN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: audit
- GitHub Check: Schema validation (v1)
🔇 Additional comments (4)
docs/ROADMAP.md (1)
3-7: 🛑 CRITICAL: H1 heading contains triple anchors with non-canonical leading-dash variants—violates HTML spec.Lines 3, 5, 7 define THREE conflicting anchor IDs:
- Lines 3 & 5:
<a id="-gatos-roadmap"></a>(leading-dash, NON-CANONICAL)- Line 7:
<a id="gatos-roadmap"></a>(canonical)Prior reviews (existing_comments multiple entries) flagged this identical defect; claimed fixes in commits 53aa883–c05da95 have NOT resolved the issue. The leading-dash variants persist, creating duplicate and non-canonical IDs.
Remove non-canonical variants—keep ONLY the canonical single-dash anchor:
-<a id="-gatos-roadmap"></a> - -<a id="-gatos-roadmap"></a> - <a id="gatos-roadmap"></a>Likely an incorrect or invalid review comment.
docs/decisions/ADR-0002/DECISION.md (1)
202-245: SVGs for both Mermaid diagrams are already committed.Verification confirms that both the "Job Lifecycle" and "Job Discovery and Execution Flow" diagrams have matching pre-generated SVGs in
docs/diagrams/generated/:
docs__decisions__ADR-0002__DECISION__mermaid_1.svg(Job Lifecycle)docs__decisions__ADR-0002__DECISION__mermaid_2.svg(Job Discovery and Execution Flow)Additional versioned variants exist with content hashes, indicating the build pipeline correctly processed these diagrams. No action required.
docs/STAKEHOLDERS.md (2)
9-22: TOC structure approved; will resolve when duplicate anchors are fixed.The TOC is correctly formatted and anchor references match section headings. Navigation will function once duplicate anchor tags are removed from each section.
144-144: Grammar correction approved.Line 144 correctly uses "explainable denials" (noun form) instead of the earlier "explainable denies" (verb form). Grammar issue is resolved.
| <a id="git-gatos-foldc--compile-echolua-to-elc"></a> | ||
|
|
||
| <a id="git-gatos-foldc--compile-echolua-to-elc"></a> | ||
|
|
||
| <a id="git-gatos-foldc-compile-echolua-to-elc"></a> |
There was a problem hiding this comment.
🧩 Analysis chain
🛑 CRITICAL: Systemic triple-anchor duplication across ALL section headings—HTML spec violation.
Every heading (H1 and all H2/H3 subsections) contains three identical consecutive anchor lines:
Lines 7, 9, 11 (H1): All define git-gatos-foldc-compile-echolua-to-elc (with variant double-dash format)
Lines 27, 29, 31 (Synopsis): All define synopsis (three times)
Lines 39, 41, 43 (Behavior): All define behavior (three times)
Lines 51, 53, 55 (Notes): All define notes (three times)
This violates HTML spec. Duplicate id attributes are invalid, breaking in-page link resolution and accessibility tools. The scripts/anchors_and_toc.py script is either:
- Not being run on this file, OR
- Inserting anchors without detecting/removing duplicates from previous runs
Mandatory regeneration:
python scripts/anchors_and_toc.py --write --paths docs/cli/foldc.mdVerify single anchor per heading:
grep -n '<a id=' docs/cli/foldc.md | awk -F: '{print $1}' | sort | uniq -d
# Must return empty (no duplicate line numbers)Also applies to: 27-31, 39-43, 51-55
🏁 Script executed:
#!/bin/bash
# Verify triple-anchor duplication in docs/cli/foldc.md
echo "=== Lines 7-11 (H1 anchor region) ==="
sed -n '7,11p' docs/cli/foldc.md
echo -e "\n=== Lines 27-31 (Synopsis anchor region) ==="
sed -n '27,31p' docs/cli/foldc.md
echo -e "\n=== Lines 39-43 (Behavior anchor region) ==="
sed -n '39,43p' docs/cli/foldc.md
echo -e "\n=== Lines 51-55 (Notes anchor region) ==="
sed -n '51,55p' docs/cli/foldc.md
echo -e "\n=== All <a id=> lines in file ==="
grep -n '<a id=' docs/cli/foldc.md | head -20
echo -e "\n=== Check for duplicate IDs (uniq -d on line numbers) ==="
grep -n '<a id=' docs/cli/foldc.md | awk -F: '{print $1}' | sort | uniq -d
echo -e "\n=== Check if scripts/anchors_and_toc.py exists ==="
ls -la scripts/anchors_and_toc.py 2>&1 || echo "File not found"Length of output: 1185
🛑 CRITICAL: Systemic duplicate anchor IDs across ALL section headings—HTML spec violation confirmed.
Every heading contains three identical consecutive anchor tags with duplicate id attribute values, breaking the HTML5 spec which mandates unique IDs per document:
- Lines 7–11 (H1): Anchors share ID
git-gatos-foldc--compile-echolua-to-elc(lines 7, 9) or variant single-dashgit-gatos-foldc-compile-echolua-to-elc(line 11), plus duplicate at line 21 - Lines 27–31 (Synopsis): All three anchors share ID
synopsis - Lines 39–43 (Behavior): All three anchors share ID
behavior - Lines 51–55 (Notes): All three anchors share ID
notes
Duplicate IDs break in-page link resolution and accessibility crawlers. This must be regenerated.
Mandatory fix:
python scripts/anchors_and_toc.py --write --paths docs/cli/foldc.mdVerify (one anchor per ID):
grep '<a id=' docs/cli/foldc.md | awk -F'"' '{print $2}' | sort | uniq -d
# Must return empty🤖 Prompt for AI Agents
docs/cli/foldc.md lines 7–11: the file contains repeated identical anchor
tags/IDs for multiple headings causing duplicate HTML IDs; regenerate the
anchors by running the repository's anchors_and_toc.py script with the write
option for docs/cli/foldc.md to rewrite unique anchor IDs, then verify no
duplicate IDs remain by listing anchor id attributes and ensuring no duplicates
are reported.
| <a id="git-gatos-policyc--compile-rgs-policy-to-rgcelc"></a> | ||
|
|
||
| <a id="git-gatos-policyc--compile-rgs-policy-to-rgcelc"></a> | ||
|
|
||
| <a id="git-gatos-policyc-compile-.rgs-policy-to-rgcelc"></a> |
There was a problem hiding this comment.
🧩 Analysis chain
🛑 CRITICAL: Identical triple-anchor duplication pattern—systemic prebuild failure across CLI docs.
This file exhibits the exact same triple-anchor defect found in docs/cli/pox.md and docs/cli/foldc.md:
Lines 7, 9, 11 (H1): Three anchors with ID format inconsistency (git-gatos-policyc--compile-rgs-policy-to-rgcelc vs git-gatos-policyc-compile-.rgs-policy-to-rgcelc)
Lines 27, 29, 31 (Synopsis): synopsis duplicated 3x
Lines 39, 41, 43 (Behavior): behavior duplicated 3x
Lines 51, 53, 55 (Requirements): requirements duplicated 3x
Root cause: The anchor-generation script (scripts/anchors_and_toc.py referenced in PR objectives) was not executed on these files before commit, or the script's deduplication logic is broken.
Evidence of systemic failure: All three CLI doc files (pox.md, foldc.md, policyc.md) share identical triple-anchor pattern—this cannot be coincidental; it indicates the script never ran post-file-generation.
Mandatory fix:
python scripts/anchors_and_toc.py --write --paths docs/cli/policyc.mdThen commit:
git add docs/cli/policyc.md
git commit -m "docs(cli/policyc): regenerate anchors—fix duplicate IDs"Apply identical fix to docs/cli/pox.md and docs/cli/foldc.md.
Also applies to: 27-31, 39-43, 51-55
🏁 Script executed:
#!/bin/bash
# Verify triple-anchor pattern in all three CLI docs at claimed line ranges
echo "=== docs/cli/policyc.md lines 7-11, 27-31, 39-43, 51-55 ==="
sed -n '7,11p;27,31p;39,43p;51,55p' docs/cli/policyc.md | cat -n
echo ""
echo "=== docs/cli/pox.md structure (line count check) ==="
wc -l docs/cli/pox.md
echo ""
echo "=== docs/cli/foldc.md structure (line count check) ==="
wc -l docs/cli/foldc.md
echo ""
echo "=== Anchor pattern in pox.md (lines 7-11) ==="
sed -n '7,11p' docs/cli/pox.md | cat -n
echo ""
echo "=== Anchor pattern in foldc.md (lines 7-11) ==="
sed -n '7,11p' docs/cli/foldc.md | cat -n
echo ""
echo "=== Check if scripts/anchors_and_toc.py exists ==="
ls -lh scripts/anchors_and_toc.py 2>&1 || echo "FILE NOT FOUND"
echo ""
echo "=== Inspect scripts/anchors_and_toc.py (first 50 lines) ==="
head -50 scripts/anchors_and_toc.py 2>&1 || echo "CANNOT READ FILE"Length of output: 3179
🏁 Script executed:
#!/bin/bash
# Deep inspect the anchor generation logic in the script
echo "=== Full scripts/anchors_and_toc.py (focus on anchor generation) ==="
grep -n "def.*anchor\|<a id\|unless present\|dedup" scripts/anchors_and_toc.py | head -30
echo ""
echo "=== Search for function that generates anchors ==="
sed -n '/def.*anchor/,/^def /p' scripts/anchors_and_toc.py | head -80
echo ""
echo "=== Check git history of these files (last 5 commits) ==="
git log --oneline -5 -- docs/cli/policyc.md docs/cli/pox.md docs/cli/foldc.md 2>&1 | head -20
echo ""
echo "=== Check if script was recently run (git log of script) ==="
git log --oneline -3 -- scripts/anchors_and_toc.py 2>&1Length of output: 2599
🛑 CRITICAL: Confirmed—triple-anchor defect is systemic and violates repo policy.
Evidence:
scripts/anchors_and_toc.pyexplicitly generates single canonical id only per heading- Commit 2b56dd2: "script enforces single id"
- Commit 486e660: repo-wide normalization to "single slug id" policy
- Yet
docs/cli/policyc.md,docs/cli/pox.md, anddocs/cli/foldc.mdall contain triple anchors (2× double-dash + 1× single-dash variant)
This proves the files were NOT processed by the anchor script during the recent normalization cycle, or were regenerated afterward by another tool that bypassed deduplication.
Mandatory remediation:
Lines 7–11, 27–31, 39–43, 51–55 in docs/cli/policyc.md (and identical ranges in docs/cli/pox.md and docs/cli/foldc.md) must be regenerated by running:
python scripts/anchors_and_toc.py --write --paths docs/cli/policyc.md docs/cli/pox.md docs/cli/foldc.mdThen commit the corrected files to enforce the single-id policy.
🤖 Prompt for AI Agents
In docs/cli/policyc.md around lines 7 to 11 (and similar ranges 27–31, 39–43,
51–55), there are triple-anchor duplicates that violate the repo’s
single-slug-id policy; regenerate the anchors for these ranges by running the
repository anchor script to produce canonical single IDs: run python
scripts/anchors_and_toc.py --write --paths docs/cli/policyc.md docs/cli/pox.md
docs/cli/foldc.md, verify the triple anchors are replaced with single canonical
ids, then add and commit the updated files.
| <a id="git-gatos-pox--proof-of-experiment"></a> | ||
|
|
||
| <a id="git-gatos-pox--proof-of-experiment"></a> | ||
|
|
||
| <a id="git-gatos-pox-proof-of-experiment"></a> |
There was a problem hiding this comment.
🧩 Analysis chain
🛑 CRITICAL: Triple-anchor duplication on H1 heading—HTML spec violation blocking merge.
Lines 7, 9, 11 inject three anchor variants on the same heading with ID inconsistency:
- Lines 7 & 9:
git-gatos-pox--proof-of-experiment(double-dash, duplicated) - Line 11:
git-gatos-pox-proof-of-experiment(single-dash, different)
HTML spec mandates globally unique IDs. Duplicate IDs violate the standard and will break VitePress fragment navigation. Identical triple-anchor pattern infests every heading (Synopsis at lines 24–28, Behavior at lines 49–53). Past review comments claimed fixes, but verification confirms duplicates persist in current code.
Mandatory action before merge: Regenerate this file using the repository's anchor-generation script:
python scripts/anchors_and_toc.py --write --paths docs/cli/pox.mdThen verify no consecutive duplicates remain:
grep -E '^<a id=.*></a>\n^<a id=.*></a>' docs/cli/pox.md
# Must return emptyCommit with message: docs(cli/pox): regenerate anchors—fix duplicate IDs
🏁 Script executed:
#!/bin/bash
# Verify the actual content and anchor duplication pattern in docs/cli/pox.md
echo "=== Lines 1-60 of docs/cli/pox.md ==="
head -60 docs/cli/pox.md
echo -e "\n=== Count of each anchor ID (all lines) ==="
grep -o '<a id="[^"]*"' docs/cli/pox.md | sort | uniq -c | sort -rn
echo -e "\n=== Check for consecutive duplicate anchors ==="
grep '<a id=' docs/cli/pox.md | awk 'NR>1 && prev==$0 {print "DUPLICATE FOUND: " $0} {prev=$0}'
echo -e "\n=== Verify script existence ==="
ls -la scripts/anchors_and_toc.py 2>/dev/null || echo "Script not found at scripts/anchors_and_toc.py"
echo -e "\n=== Full list of all anchor IDs in order ==="
grep -n '<a id=' docs/cli/pox.mdLength of output: 2289
🛑 CRITICAL: Triple-anchor duplication on all headings—HTML spec violation confirmed.
Script verification of docs/cli/pox.md confirms triple-anchor infestation:
H1 heading (lines 7–11):
- Lines 7 & 9:
git-gatos-pox--proof-of-experiment(identical duplicates, double-dash) - Line 11:
git-gatos-pox-proof-of-experiment(single-dash)—ID inconsistency
## Synopsis (lines 24–28): Three identical <a id="synopsis"></a>
## Behavior (lines 49–53): Three identical <a id="behavior"></a>
HTML spec mandates globally unique IDs. Duplicate IDs violate the standard and break VitePress fragment navigation. Consecutive duplicate detection confirms this is active code defect, not formatting artifact.
Mandatory fix before merge: Run the anchor-generation script:
python scripts/anchors_and_toc.py --write --paths docs/cli/pox.mdVerify duplicates are eliminated:
grep '<a id=' docs/cli/pox.md | awk 'NR>1 && prev==$0 {print "DUPLICATE: " $0} {prev=$0}'
# Must return emptyCommit: docs(cli/pox): regenerate anchors—fix duplicate IDs
🤖 Prompt for AI Agents
In docs/cli/pox.md around lines 7 to 11 (and similarly for Synopsis at 24–28 and
Behavior at 49–53) there are duplicate/triplicate <a id="..."> anchors causing
non-unique IDs and breaking VitePress navigation; run the anchor-generation
script to regenerate unique anchors by executing: python
scripts/anchors_and_toc.py --write --paths docs/cli/pox.md, then verify no
duplicates remain with the provided grep check, and finally stage and commit the
updated file with the message: docs(cli/pox): regenerate anchors—fix duplicate
IDs.
| <a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a> | ||
|
|
||
| <a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a> | ||
|
|
||
| <a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a> |
There was a problem hiding this comment.
❓ Verification inconclusive
🛑 CRITICAL: Systemic triple-anchor + orphaned H1 duplicate—blocks all PRs with this script.
H1 heading (lines 8–12, 25): Four separate anchor elements with duplicate IDs:
- Lines 8, 10, 12: Three anchors for H1 (format inconsistency:
no_stdvsnostd) - Line 25: Orphaned duplicate after TOC block (line 23
<!-- AUTOGENERATED TOC END -->)
All section headings exhibit identical triple-anchor pattern:
- Decision (lines 29–33):
decisionduplicated 3x - Motivation (lines 45–49):
motivationduplicated 3x - Rationale (lines 56–60):
rationaleduplicated 3x - Consequences (lines 100–104), Usage Example (lines 112–116), Opinions (lines 148–152): Same pattern
This is identical to the defect in all 3 CLI docs (pox.md, foldc.md, policyc.md). The anchor script was not invoked or is globally broken.
Past review comments claim fixes in commits 53aa883, dc3fb1c, but duplicates persist. This indicates either:
- Commits don't exist in this branch, OR
- Commits were made but this file was never regenerated afterward
Mandatory regeneration:
python scripts/anchors_and_toc.py --write --paths docs/decisions/ADR-0001/DECISION.mdVerify single anchor per heading and no orphaned duplicates:
grep -n 'id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"' docs/decisions/ADR-0001/DECISION.md | wc -l
# Must output: 1 (currently likely outputs 2)Also applies to: 25-25, 29-33, 45-49, 56-60, 100-104, 112-116, 148-152
#!/bin/bash
# 1. Verify target file exists and examine lines 8-12, 25, 29-33, 45-49, 56-60, 100-104, 112-116, 148-152
echo "=== FILE EXISTENCE CHECK ==="
if [ -f "docs/decisions/ADR-0001/DECISION.md" ]; then
echo "✓ File exists"
wc -l "docs/decisions/ADR-0001/DECISION.md"
else
echo "✗ File NOT found"
exit 1
fi
echo ""
echo "=== LINES 8-12 (H1 section) ==="
sed -n '8,12p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 25 (orphaned H1 anchor) ==="
sed -n '23,27p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 29-33 (Decision heading) ==="
sed -n '29,33p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 45-49 (Motivation heading) ==="
sed -n '45,49p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 56-60 (Rationale heading) ==="
sed -n '56,60p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 100-104 (Consequences heading) ==="
sed -n '100,104p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 112-116 (Usage Example heading) ==="
sed -n '112,116p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== LINES 148-152 (Opinions heading) ==="
sed -n '148,152p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "=== ANCHOR COUNT: adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends ==="
grep -o 'id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"' "docs/decisions/ADR-0001/DECISION.md" | wc -l
echo ""
echo "=== ANCHOR COUNT: decision ==="
grep -o 'id="decision"' "docs/decisions/ADR-0001/DECISION.md" | wc -l
echo ""
echo "=== ALL ANCHOR IDs (with line numbers) ==="
grep -n 'id="' "docs/decisions/ADR-0001/DECISION.md"#!/bin/bash
# 2. Check CLI docs for same triple-anchor pattern
echo "=== CHECKING CLI DOCS FOR TRIPLE-ANCHOR PATTERN ==="
for doc in docs/cli/pox.md docs/cli/foldc.md docs/cli/policyc.md; do
if [ -f "$doc" ]; then
echo ""
echo "File: $doc"
# Count total anchor tags
total_anchors=$(grep -c '<a id=' "$doc" 2>/dev/null || echo "0")
# Count unique IDs
unique_ids=$(grep -o 'id="[^"]*"' "$doc" 2>/dev/null | sort -u | wc -l)
echo "Total anchor tags: $total_anchors"
echo "Unique IDs: $unique_ids"
if [ "$total_anchors" -gt "$unique_ids" ]; then
echo "⚠ DUPLICATE IDs DETECTED"
# Show duplicates
grep -o 'id="[^"]*"' "$doc" | sort | uniq -d
fi
else
echo "✗ $doc NOT found"
fi
done#!/bin/bash
# 3. Check git history for commits 53aa883, dc3fb1c
echo "=== COMMIT HISTORY CHECK ==="
echo "Checking commit 53aa883:"
git log --oneline -1 53aa883 2>&1 | head -1
echo ""
echo "Checking commit dc3fb1c:"
git log --oneline -1 dc3fb1c 2>&1 | head -1
echo ""
echo "Recent commits touching DECISION.md:"
git log --oneline -n 10 -- docs/decisions/ADR-0001/DECISION.md 2>/dev/null || echo "No git history available"#!/bin/bash
# 4. Verify script exists
echo "=== SCRIPT VERIFICATION ==="
if [ -f "scripts/anchors_and_toc.py" ]; then
echo "✓ Script exists: scripts/anchors_and_toc.py"
echo ""
echo "Script preview (first 30 lines):"
head -30 "scripts/anchors_and_toc.py"
else
echo "✗ Script NOT found: scripts/anchors_and_toc.py"
fi#!/bin/bash
# Verify target file exists and examine lines at claimed defect locations
echo "=== FILE EXISTENCE & LINE INSPECTION ==="
if [ -f "docs/decisions/ADR-0001/DECISION.md" ]; then
echo "✓ File exists"
echo ""
echo "Lines 8-12 (H1 section):"
sed -n '8,12p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "Lines 23-27 (TOC end & orphaned H1):"
sed -n '23,27p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "Lines 29-33 (Decision heading):"
sed -n '29,33p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "Lines 45-49 (Motivation heading):"
sed -n '45,49p' "docs/decisions/ADR-0001/DECISION.md"
echo ""
echo "Lines 56-60 (Rationale heading):"
sed -n '56,60p' "docs/decisions/ADR-0001/DECISION.md"
else
echo "✗ CRITICAL: File does not exist"
exit 1
fi
echo ""
echo "=== ANCHOR DUPLICATION COUNT ==="
echo -n "adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends: "
grep -o 'id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"' "docs/decisions/ADR-0001/DECISION.md" 2>/dev/null | wc -l
echo -n "decision: "
grep -o 'id="decision"' "docs/decisions/ADR-0001/DECISION.md" 2>/dev/null | wc -l
echo ""
echo "=== ALL ANCHORS (line numbers) ==="
grep -n '<a id=' "docs/decisions/ADR-0001/DECISION.md" | head -30#!/bin/bash
# Check CLI docs mentioned in review
echo "=== CLI DOCS TRIPLE-ANCHOR CHECK ==="
for doc in docs/cli/pox.md docs/cli/foldc.md docs/cli/policyc.md; do
if [ -f "$doc" ]; then
total=$(grep -c '<a id=' "$doc" 2>/dev/null || echo "0")
unique=$(grep -o 'id="[^"]*"' "$doc" 2>/dev/null | sort -u | wc -l)
echo "$doc: $total anchors, $unique unique IDs"
else
echo "$doc: NOT FOUND"
fi
done#!/bin/bash
# Check git commits and script
echo "=== GIT COMMIT VERIFICATION ==="
git log --oneline -1 53aa883 2>&1 | head -1 || echo "Commit 53aa883 not found"
git log --oneline -1 dc3fb1c 2>&1 | head -1 || echo "Commit dc3fb1c not found"
echo ""
echo "Recent commits to DECISION.md:"
git log --oneline -n 5 -- docs/decisions/ADR-0001/DECISION.md 2>/dev/null || echo "No history"
echo ""
echo "=== SCRIPT VERIFICATION ==="
if [ -f "scripts/anchors_and_toc.py" ]; then
echo "✓ Script exists"
head -20 "scripts/anchors_and_toc.py"
else
echo "✗ Script NOT found"
fi🛑 CRITICAL: Multiple duplicate anchor IDs break navigation and TOC functionality
The provided snippet directly confirms triple anchor tags (lines 8, 10, 12) with identical ID adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends. Duplicate IDs violate HTML semantics and break anchor references.
Confirmed defect (lines 8–12):
<a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a>
<a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a>
<a id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"></a>
Review claims identical patterns exist at lines 25, 29–33, 45–49, 56–60, 100–104, 112–116, 148–152. Regenerate via:
python scripts/anchors_and_toc.py --write --paths docs/decisions/ADR-0001/DECISION.mdThen verify:
grep -o 'id="adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends"' docs/decisions/ADR-0001/DECISION.md | wc -l
# Must output: 1🤖 Prompt for AI Agents
In docs/decisions/ADR-0001/DECISION.md around lines 8–12, multiple duplicate
anchor tags share the same id
"adr-0001-split-gatos-ledger-into-no_std-core-and-std-backends", breaking
navigation and TOC; regenerate unique anchors and TOC by running the provided
script (python scripts/anchors_and_toc.py --write --paths
docs/decisions/ADR-0001/DECISION.md), then verify there is exactly one
occurrence of that id with grep as shown and commit the updated file.
1 participant
This PR adds a modern VitePress site for the GATOS book + reference, using pre-rendered SVG diagrams instead of Mermaid-in-the-browser.\n\nHighlights\n- VitePress scaffolding under docs/.vitepress with a clean theme and brand colors.\n- Sidebar auto-generated from guide/CHAPTER-*.md (reads H1 titles).\n- Mermaid fences are mapped to committed SVGs at docs/diagrams/generated/** via a markdown renderer transform (no client JS).\n- Prebuild doc hygiene: linkify chapters, linkify SPEC/TECH-SPEC § refs, insert/update anchors & ToC.\n- GitHub Pages workflow to build and deploy from main (docs/.vitepress/dist).\n\nWhat’s not included\n- No Mermaid runtime or SSR; all diagrams are static SVGs already in docs/diagrams/generated/. If a fence has no matching SVG, it falls back to code fence rendering and logs nothing (safe default).\n- No search yet; can add Pagefind in a follow-up.\n\nLocal usage\n- npm ci\n- npm run docs:dev # dev server\n- npm run docs:build # prebuild + static build\n- npm run docs:preview\n\nFollow-ups (optional)\n- Add local search (Pagefind).\n- Add admonitions adapter to render [!NOTE]/[!WARNING] as real blocks.\n- Remove chapter footers (Prev/Next) once you’re happy with sidebar nav.\n- Expand renderer to support dark/light SVG variants via.