fix(hooks): treat planned suite siblings as suggestions, not broken links#51
Conversation
…inks
The post-write consistency hook flagged any internal link to a missing
file as a broken-link issue. During incremental suite generation a document
can legitimately link to a sibling that is declared in a suite manifest but
not yet written, producing false-positive "Broken link" issues.
check_internal_links now loads every manifest output_path via the new
hook_utils.load_suite_output_paths() helper and routes missing-but-planned
targets to non-blocking suggestions ("Planned sibling not yet generated"),
while genuinely unknown missing targets remain broken-link issues. Adds
smoke coverage for both the planned-sibling and genuine-broken paths.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThe PR extends the ChangesPlanned-sibling link differentiation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 5 |
| Duplication | 0 |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Anthony Johnson II (AJ-EthereaLogic-ai)
merged commit b728160
into
main
Anthony Johnson II (AJ-EthereaLogic-ai)
deleted the
fix/planned-sibling-link-classification
branch
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4d27d0fff6
ℹ️ 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 (@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 (@codex) address that feedback".
| for doc in data.get("documents", []): | ||
| output_path = doc.get("output_path") | ||
| if output_path: | ||
| planned.add(os.path.normpath(str(project_dir / output_path))) |
There was a problem hiding this comment.
The documented writer behavior redirects manifest output_path values that start with docs/ into spec_driven_docs/rough_draft/ (.claude/commands/doc/doc-write.md:253), but this helper records only the literal /project/docs/... path. For suites following the documented manifest style, a generated draft linking to a pending sibling such as api/auth.md resolves under /project/spec_driven_docs/rough_draft/..., so candidates & planned_paths misses and the post-write hook still reports a broken link instead of the intended planned-sibling suggestion.
Useful? React with 👍 / 👎.
| for doc in data.get("documents", []): | ||
| output_path = doc.get("output_path") | ||
| if output_path: | ||
| planned.add(os.path.normpath(str(project_dir / output_path))) |
There was a problem hiding this comment.
Because every manifest output_path is added regardless of document status, a missing target for a suite document already marked completed is now downgraded to a planned-sibling suggestion. In a suite where a completed generated file is deleted, moved incorrectly, or otherwise missing, links to it should remain real broken-link issues; filter this set to statuses that can legitimately be not-yet-generated, such as pending or writing.
Useful? React with 👍 / 👎.
Summary
Resolves the deferred open item from the hook review: links to planned-but-not-yet-generated suite siblings were reported as
Broken linkconsistency issues during incremental suite generation (false positives).The post-write hook now distinguishes the two cases (Policy A — warn vs error):
output_pathin any suite manifest → non-blocking suggestion (Planned sibling not yet generated).Broken linkissue, preserving genuine broken-link detection (cross_reference_rules.validate_internal_links, doc-review/doc-sync intent).Changes
hook_utils.py: newload_suite_output_paths(project_dir)helper (globs.claude/docs/suites/*/manifest.json, resolvesoutput_pathvalues to normalized absolute paths), mirroring the existingload_quality_profilesload-with-fallback idiom.doc_post_write.py:check_internal_linksreturns(issues, suggestions); planned-path set loaded once per call; caller routes both buckets.tests/smoke.sh: two regression tests — planned-sibling → suggestion, genuine-missing → broken-link issue (using the real_examplemanifest fixtureapi/reference.md).Verification
npm testgreen (40/40 locally withjsonschema>=4.18; schema checks skip without it).python3 -m py_compile .claude/hooks/*.py,bash -n tests/smoke.sh,git diff --checkclean.api/reference.md(planned) andnope.md(unknown) splits correctly — suggestion vs issue..codex/hooks/(gitignored local mirror) kept byte-for-byte in sync; parity test skips cleanly in CI.Out of scope (intentional)
validate_internal_linkson/off gate, anchor-existence checks, doc_id-based matching.🤖 Generated with Claude Code
Summary by CodeRabbit
Bug Fixes
Tests