hygiene(hwLedger): preserve canonical ahead commits#96
Conversation
Expand the journey traceability placeholder into an FR/NFR-to-docs-code-tests scaffold with rich media stubs and acceptance gates for future journey evidence. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
Warning Review limit reached
More reviews will be available in 54 minutes and 37 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (3)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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 |
codeant-ai
Bot
added
the
size:L
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Journey elsewhere check never fails
- The elsewhere check now searches traceability text with RICH-MEDIA-STUB markers removed, so journey slugs must appear outside stub attributes.
Or push these changes by commenting:
@cursor push 0501ce0ba1
Preview (0501ce0ba1)
diff --git a/docs/scripts/validate-rich-media-stubs.mjs b/docs/scripts/validate-rich-media-stubs.mjs
--- a/docs/scripts/validate-rich-media-stubs.mjs
+++ b/docs/scripts/validate-rich-media-stubs.mjs
@@ -52,7 +52,8 @@
}
const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean));
-const missingJourneyNames = [...journeys].filter((journey) => !text.includes(journey));
+const textWithoutStubs = text.replace(/<!-- RICH-MEDIA-STUB\s+[^>]*-->/g, '');
+const missingJourneyNames = [...journeys].filter((journey) => !textWithoutStubs.includes(journey));
for (const journey of missingJourneyNames) {
failures.push(`journey ${journey}: not referenced elsewhere in ${relative(docsRoot, traceabilityPath)}`);
}You can send follow-ups to the cloud agent here.
Reviewed by Cursor Bugbot for commit ac0085d. Configure here.
| const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean)); | ||
| const missingJourneyNames = [...journeys].filter((journey) => !text.includes(journey)); | ||
| for (const journey of missingJourneyNames) { | ||
| failures.push(`journey ${journey}: not referenced elsewhere in ${relative(docsRoot, traceabilityPath)}`); |
There was a problem hiding this comment.
Journey elsewhere check never fails
Medium Severity
The linter treats a journey as “referenced elsewhere” when its slug appears anywhere in journey-traceability.md, but every stub already embeds that slug in its journey attribute. The check therefore never reports missing cross-references (for example in the flows table or manifest section), so journey:lint can pass while journeys are only named in the stub block.
Reviewed by Cursor Bugbot for commit ac0085d. Configure here.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a journey traceability model and adds rich media stubs to the documentation, along with a validation script (validate-rich-media-stubs.mjs) and a corresponding lint script in package.json. Feedback on the changes includes: (1) using fileURLToPath to ensure cross-platform path resolution on Windows, (2) fixing a logical bug in the validation script where journey references are falsely matched against their own stub definitions, and (3) adding closing <!-- END-RICH-MEDIA-STUB --> tags to adhere to rich media conventions.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| #!/usr/bin/env node | ||
| import { readFileSync } from 'node:fs'; | ||
| import { relative, resolve } from 'node:path'; | ||
|
|
||
| const docsRoot = resolve(new URL('..', import.meta.url).pathname); |
There was a problem hiding this comment.
Using new URL('..', import.meta.url).pathname can cause issues on Windows platforms because the returned pathname may contain a leading slash before the drive letter (e.g., /C:/path/to/docs), which path.resolve might not handle correctly.
Using fileURLToPath from node:url is the standard, cross-platform way to convert file URLs to file paths in ES modules.
| #!/usr/bin/env node | |
| import { readFileSync } from 'node:fs'; | |
| import { relative, resolve } from 'node:path'; | |
| const docsRoot = resolve(new URL('..', import.meta.url).pathname); | |
| #!/usr/bin/env node | |
| import { readFileSync } from 'node:fs'; | |
| import { relative, resolve } from 'node:path'; | |
| import { fileURLToPath } from 'node:url'; | |
| const docsRoot = fileURLToPath(new URL('..', import.meta.url)); |
| const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean)); | ||
| const missingJourneyNames = [...journeys].filter((journey) => !text.includes(journey)); |
There was a problem hiding this comment.
The check !text.includes(journey) will always evaluate to true (meaning no missing journeys will ever be detected) because the journey name is already present in the text within the RICH-MEDIA-STUB comment itself.
To correctly check if the journey is referenced elsewhere in the document (e.g., in the image paths or tables), you should strip the stub comments from the text before performing the inclusion check.
const textWithoutStubs = text.replace(stubPattern, '');
const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean));
const missingJourneyNames = [...journeys].filter((journey) => !textWithoutStubs.includes(journey));| <!-- RICH-MEDIA-STUB type="annotated-screenshot" subject="Capacity planner result with explainability callouts" journey="capacity-fit-estimate" status="TODO" --> | ||
|  | ||
|
|
||
| *Expected capture: run the planner against a known fixture device and annotate the model-fit result, headroom calculation, warning states, and the CLI/UI command that reproduces it.* | ||
|
|
||
| <!-- RICH-MEDIA-STUB type="animated-gif" subject="Fleet ledger device comparison flow" journey="fleet-ledger-compare" status="TODO" --> | ||
|  | ||
|
|
||
| *Expected capture: add or load two fixture devices, compare their usable inference capacity, and show provenance for each measured field.* | ||
|
|
||
| <!-- RICH-MEDIA-STUB type="journey-eval" subject="Inference runtime health verdict" journey="local-runtime-health" status="TODO" --> | ||
|  | ||
|
|
||
| *Expected capture: start the local runtime, verify health/constraint reporting, and attach a pass/fail eval verdict that maps back to FR-HWL-INFERENCE-001 and NFR-HWL-OBSERVABILITY-001.* |
There was a problem hiding this comment.
According to the organization's rich media convention in RICH_MEDIA.md, stubs must be inserted using the exact HTML-comment pair, which includes a closing <!-- END-RICH-MEDIA-STUB --> tag. This ensures that automated fill-agents can correctly identify the boundaries of the stub and replace the placeholder content without corrupting the rest of the document.
| <!-- RICH-MEDIA-STUB type="annotated-screenshot" subject="Capacity planner result with explainability callouts" journey="capacity-fit-estimate" status="TODO" --> | |
|  | |
| *Expected capture: run the planner against a known fixture device and annotate the model-fit result, headroom calculation, warning states, and the CLI/UI command that reproduces it.* | |
| <!-- RICH-MEDIA-STUB type="animated-gif" subject="Fleet ledger device comparison flow" journey="fleet-ledger-compare" status="TODO" --> | |
|  | |
| *Expected capture: add or load two fixture devices, compare their usable inference capacity, and show provenance for each measured field.* | |
| <!-- RICH-MEDIA-STUB type="journey-eval" subject="Inference runtime health verdict" journey="local-runtime-health" status="TODO" --> | |
|  | |
| *Expected capture: start the local runtime, verify health/constraint reporting, and attach a pass/fail eval verdict that maps back to FR-HWL-INFERENCE-001 and NFR-HWL-OBSERVABILITY-001.* | |
| <!-- RICH-MEDIA-STUB type="annotated-screenshot" subject="Capacity planner result with explainability callouts" journey="capacity-fit-estimate" status="TODO" --> | |
|  | |
| *Expected capture: run the planner against a known fixture device and annotate the model-fit result, headroom calculation, warning states, and the CLI/UI command that reproduces it.* | |
| <!-- END-RICH-MEDIA-STUB --> | |
| <!-- RICH-MEDIA-STUB type="animated-gif" subject="Fleet ledger device comparison flow" journey="fleet-ledger-compare" status="TODO" --> | |
|  | |
| *Expected capture: add or load two fixture devices, compare their usable inference capacity, and show provenance for each measured field.* | |
| <!-- END-RICH-MEDIA-STUB --> | |
| <!-- RICH-MEDIA-STUB type="journey-eval" subject="Inference runtime health verdict" journey="local-runtime-health" status="TODO" --> | |
|  | |
| *Expected capture: start the local runtime, verify health/constraint reporting, and attach a pass/fail eval verdict that maps back to FR-HWL-INFERENCE-001 and NFR-HWL-OBSERVABILITY-001.* | |
| <!-- END-RICH-MEDIA-STUB --> |
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
| import { readFileSync } from 'node:fs'; | ||
| import { relative, resolve } from 'node:path'; | ||
|
|
||
| const docsRoot = resolve(new URL('..', import.meta.url).pathname); |
There was a problem hiding this comment.
Suggestion: Building file paths from new URL(...).pathname is not portable: URL-encoded characters remain escaped and Windows drive paths get a leading slash form that can break readFileSync. Convert the URL with fileURLToPath before resolving paths to avoid runtime ENOENT/path errors on different environments. [api mismatch]
Severity Level: Major ⚠️
- ❌ journey:lint fails on Windows due to invalid docsRoot path.
- ⚠️ Contributors with encoded paths cannot run docs validations.Steps of Reproduction ✅
1. On a Windows machine, clone the repository into a path containing spaces or non-ASCII
characters (for example `C:\Users\Name\Source Repos\hwLedger`).
2. From the `docs` directory, run `npm run journey:lint`, which executes `node
scripts/validate-rich-media-stubs.mjs` through the `journey:lint` script configured in
`docs/package.json:7-12`.
3. In `docs/scripts/validate-rich-media-stubs.mjs:5-7`, `docsRoot` is computed via
`resolve(new URL('..', import.meta.url).pathname)` and `traceabilityPath` is built from
that; on Windows, this pathname retains a leading `/` (e.g. `/C:/Users/...`) and any
URL-encoded characters such as `%20` for spaces.
4. `readFileSync(traceabilityPath, 'utf8')` at
`docs/scripts/validate-rich-media-stubs.mjs:7` then attempts to open a non-existent path
like `/C:/Users/.../hwLedger/docs/operations/journey-traceability.md` or one with literal
`%20`, leading to an `ENOENT` error and causing `journey:lint` to fail; using
`fileURLToPath(new URL('..', import.meta.url))` would produce a correct filesystem path on
all platforms.Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is a comment left during a code review.
**Path:** docs/scripts/validate-rich-media-stubs.mjs
**Line:** 5:5
**Comment:**
*Api Mismatch: Building file paths from `new URL(...).pathname` is not portable: URL-encoded characters remain escaped and Windows drive paths get a leading slash form that can break `readFileSync`. Convert the URL with `fileURLToPath` before resolving paths to avoid runtime ENOENT/path errors on different environments.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix| if (!/!\[[^\]]+\]\([^)]+\)/.test(after)) { | ||
| failures.push(`line ${line}: expected image/media markdown immediately after stub`); | ||
| } |
There was a problem hiding this comment.
Suggestion: The validator only accepts image markdown () even though allowed stub types include recording-mp4, which is commonly represented as a normal link or embedded HTML video. This will incorrectly fail valid media stubs for non-image types. Make the accepted markdown pattern conditional on type (or allow both image and link/video forms). [incomplete implementation]
Severity Level: Major ⚠️
- ⚠️ Valid MP4 or video embeds fail journey:lint checks.
- ⚠️ Authors forced to misuse types or workaround linter restrictions.Steps of Reproduction ✅
1. Edit `docs/operations/journey-traceability.md` to add a new `RICH-MEDIA-STUB` with
`type="recording-mp4"` and place a plain media link or `<video>` embed immediately after
it, for example `[Capacity planner
walkthrough](../assets/rich-media/hwledger/capacity-fit-estimate.mp4)` instead of image
markdown.
2. Run `cd docs && npm run journey:lint`, which calls `node
scripts/validate-rich-media-stubs.mjs` through the `journey:lint` script in
`docs/package.json:7-12`.
3. In `docs/scripts/validate-rich-media-stubs.mjs:26-47`, the validator parses the new
stub, computes `after` as the next four lines of markdown, and proceeds to validate the
media block.
4. At `docs/scripts/validate-rich-media-stubs.mjs:43-45`, the validator requires `after`
to match the strict image regex `/!\[[^\]]+\]\([^)]+\)/`; because a normal link or
`<video>` tag for an MP4 does not match this pattern, it records `line X: expected
image/media markdown immediately after stub` and exits with failure, even though the media
representation is valid for a `recording-mp4` type.Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is a comment left during a code review.
**Path:** docs/scripts/validate-rich-media-stubs.mjs
**Line:** 43:45
**Comment:**
*Incomplete Implementation: The validator only accepts image markdown (``) even though allowed stub types include `recording-mp4`, which is commonly represented as a normal link or embedded HTML video. This will incorrectly fail valid media stubs for non-image types. Make the accepted markdown pattern conditional on `type` (or allow both image and link/video forms).
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix| const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean)); | ||
| const missingJourneyNames = [...journeys].filter((journey) => !text.includes(journey)); |
There was a problem hiding this comment.
Suggestion: The journey-reference check is currently ineffective because it searches the full document text, which already contains each journey name inside its own RICH-MEDIA-STUB comment. As a result, a journey can be missing from the actual narrative/table and still pass validation. Compare against text with stub comments removed, or require at least one additional occurrence outside the stub block. [incorrect condition logic]
Severity Level: Major ⚠️
- ⚠️ Docs journey:lint cannot detect missing journey references.
- ⚠️ Journey names may only exist inside hidden stub comments.Steps of Reproduction ✅
1. Open `docs/operations/journey-traceability.md` and observe the three `RICH-MEDIA-STUB`
blocks at lines 26–37, where each has a `journey` attribute (`capacity-fit-estimate`,
`fleet-ledger-compare`, `local-runtime-health`) that does not appear anywhere else in the
document body or table.
2. From the repository root, run `cd docs && npm run journey:lint`, which invokes `node
scripts/validate-rich-media-stubs.mjs` via the `journey:lint` script defined in
`docs/package.json:7-12`.
3. In `docs/scripts/validate-rich-media-stubs.mjs:26-47`, the validator parses each stub,
collects `journey` attribute values into `stubs`, and then derives the `journeys` set from
those attributes.
4. At `docs/scripts/validate-rich-media-stubs.mjs:54-58`, `missingJourneyNames` is
computed as `[...]filter((journey) => !text.includes(journey))`; because `text` includes
each journey string inside its own stub comment, `text.includes(journey)` is always true
and no `journey ... not referenced elsewhere` failures are added, even though the journeys
are not referenced anywhere else in the document.Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is a comment left during a code review.
**Path:** docs/scripts/validate-rich-media-stubs.mjs
**Line:** 54:55
**Comment:**
*Incorrect Condition Logic: The journey-reference check is currently ineffective because it searches the full document text, which already contains each journey name inside its own `RICH-MEDIA-STUB` comment. As a result, a journey can be missing from the actual narrative/table and still pass validation. Compare against text with stub comments removed, or require at least one additional occurrence outside the stub block.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
| const journeys = new Set(stubs.map((stub) => stub.journey).filter(Boolean)); | ||
| const missingJourneyNames = [...journeys].filter((journey) => !text.includes(journey)); | ||
| for (const journey of missingJourneyNames) { | ||
| failures.push(`journey ${journey}: not referenced elsewhere in ${relative(docsRoot, traceabilityPath)}`); |
There was a problem hiding this comment.
🟠 Architect Review — HIGH
The "journey referenced elsewhere" validation is ineffective: journey slugs are collected from the same file and then checked with text.includes(journey) on that file content, which is always true because each slug appears in its own stub line, so this check can never fail.
Suggestion: Make the cross-reference check meaningful by excluding the stub regions from the search scope or, more robustly, validating journey slugs against an external source such as manifest filenames under docs/journeys/manifests/, so missing or orphaned references are actually detected.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** docs/scripts/validate-rich-media-stubs.mjs
**Line:** 54:57
**Comment:**
*HIGH: The "journey referenced elsewhere" validation is ineffective: journey slugs are collected from the same file and then checked with `text.includes(journey)` on that file content, which is always true because each slug appears in its own stub line, so this check can never fail.
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished reviewing your PR. |
|
Preservation-only PR. The canonical ahead commits on this branch are historical records of fleet state on 2026-06-05; do not merge into main. Use this PR to inspect the preserved diff via |
|
Kilo Code Review could not run — your account is out of credits. Add credits or switch to a free model to enable reviews on this change. |
1 participant
User description
Preserves 2 local canonical commits before resetting to clean origin/main.
Note
Low Risk
Documentation and a docs-only validation script; no application runtime, auth, or data-path changes.
Overview
Expands journey traceability documentation to match the phenotype-infra standard: a six-layer traceability model, a table mapping three user flows to FR/NFR IDs, implementation crates, autograder gates, and stubbed evidence status.
Adds rich media placeholders (
RICH-MEDIA-STUBcomments plus image markdown) for capacity planning, fleet comparison, and local runtime health journeys, plus sections on manifest expectations, autograder gates, and an updated completion checklist.Introduces a docs autograder via
docs/scripts/validate-rich-media-stubs.mjsand wires it asnpm run journey:lintindocs/package.json. The script checks stub attributes, allowed types/statuses, following image markdown, presence of stubs, journey name references, and key FR requirement IDs injourney-traceability.md.Reviewed by Cursor Bugbot for commit ac0085d. Bugbot is set up for automated code reviews on this repo. Configure here.
CodeAnt-AI Description
Add journey traceability guidance and rich media stub checks for docs
What Changed
Impact
✅ Clearer journey documentation✅ Fewer missing evidence links✅ Safer docs validation before release💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.