fix(docs): close doc-metrics gate's blind spot for open bullets (F-1) - #293
Merged
Conversation
…storical sections (F-1) stripHistoricalSections() blanked every line in a dated/historical section, including genuinely still-open `- ⬜` bullets -- exactly how a stale "Tag v1.24.2" bullet escaped the gate in a same-day doc edit (dc14bc0). DONE_BULLET already had the mirror rule for the opposite polarity (a `- ✅` bullet is historical regardless of section); OPEN_BULLET now gets the same treatment for the "always present-tense" direction. scanForDrift() gains a matching check: a surviving open bullet mentioning tag/release/publish of a version <= the latest git tag is now a drift finding, reusing the existing getLatestReleasedVersion()/semverLte() helpers and the PLANNED check's null-latestVersion skip behavior. Verified the repaired gate actually catches the original defect: reverted TODO.md's already-fixed bullet to ⬜, confirmed the OLD logic passed clean (exit 0) and the NEW logic fails with the exact finding (exit 1), then restored TODO.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedNo new commits to review since the last review. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe documentation metrics checker now preserves ⬜ checklist bullets during historical-section stripping and detects stale version references in open tag, release, or publish bullets. Unit tests cover polarity and latest-version gating. ChangesDocumentation Metrics Drift
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
🏁 CodeAnt Quality Gate ResultsCommit: ✅ Overall Status: PASSEDQuality Gate Details
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/check-doc-metrics.mjs`:
- Around line 42-46: Replace the multiline annotations with exactly one
immediate “QNBS-v3:” comment per change: in scripts/check-doc-metrics.mjs lines
42-46 explain open-bullet preservation; in scripts/check-doc-metrics.mjs lines
200-202 explain stale-release detection; in tests/unit/checkDocMetrics.test.ts
lines 66-68 explain the retention regression test; and in
tests/unit/checkDocMetrics.test.ts lines 127-128 explain version-gating
coverage. Use the required “QNBS-v3:” prefix, not “QNBS-v3 (F-1):”.
- Around line 203-204: Update the action matcher in
scripts/check-doc-metrics.mjs at lines 203-204 to recognize “tagging”,
“releasing”, and “publishing” in addition to the existing forms. Add
corresponding unit cases in tests/unit/checkDocMetrics.test.ts at lines 129-148
covering all three inflected forms.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1c39199f-5f2b-4e74-9ce5-041b3f4cc57c
📒 Files selected for processing (2)
scripts/check-doc-metrics.mjstests/unit/checkDocMetrics.test.ts
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…nflected action forms) - Collapsed 4 multi-line QNBS-v3 comments to the required single-line format (also dropped the ad-hoc "(F-1)" tag to match the plain `// QNBS-v3: <reason>` convention). - The OPEN_BULLET action matcher only matched base verb forms (tag/ release/publish), so a stale bullet phrased "Tagging"/"Releasing"/ "Publishing" would have evaded the new gate — added the inflected forms, with 3 new parameterized test cases. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Owner
Author
|
@coderabbitai review |
✅ Action performedReview finished.
|
2 tasks
qnbs
added a commit
that referenced
this pull request
Jul 30, 2026
…ince v1.24.3 (#295) * docs(changelog): document WS-1 doc-metrics gate fix in Unreleased PR #293 merged into main after the v1.24.3 release but the Unreleased section stayed empty -- back-fill it so the changelog reflects what's actually shipped on main, not just the last tagged release. * docs(changelog): document PR #294's CLAUDE.md merge-discipline codification Second Unreleased entry for what's landed on main since v1.24.3 -- keeps the changelog a complete record of main, not just the last tagged release.
qnbs
added a commit
that referenced
this pull request
Jul 30, 2026
… state Same evidence-based doc-truth pass as the README audit, extended to the most critical remaining user-facing and agent-instruction docs: - AUDIT.md: "Current version" was still v1.24.2 -- two releases (#293, #294 doc-truth/codify work) had already landed on main since. Updated the header chain and current-version summary to v1.24.3. - ROADMAP.md: no v1.24.3 entry existed at all, even though it explicitly said worker-generation-duplication consolidation was "deferred to a dedicated migration sprint" -- that sprint shipped as v1.24.3. Added the release section and removed a stale "Upcoming" bullet asking to "finalise & test RTCDataChannel E2E encryption" -- already shipped (same finding as the TODO.md fix in this PR). - .github/SECURITY.md: supported-versions table said `main (v1.19.0)`, five releases behind actual v1.24.3. - docs/SECURITY-THREAT-MODEL.md: header said "v1.22.0 baseline" while the body already documented the v1.24.2 desktop-crypto fix (F-05/F-06) -- inconsistent self-reference, not a substance error. - AGENTS.md: tech-stack table had six stale pinned versions (TypeScript claimed a nonexistent "~6.0.3" -- the project has no plain `typescript` package, only `@typescript/native-preview` beta/tsgo; Tailwind, Biome, Storybook, Zustand, Vitest, Playwright were all behind actual package.json versions). - CLAUDE.md, .github/copilot-instructions.md, .cursorrules, KIMI-INSTRUCT.md, docs/CODEANT-REVIEW-LOOP.md: all five wrote the PR review-comment policy CodeAnt-centric (re-trigger `@codeant-ai review`), but empirically across every PR in this session's sprint, CodeRabbit was the bot actually posting inline comments (`@coderabbitai review`); CodeAnt only ever appeared as 5 CI status checks. Added a clarifying note to each so a future session doesn't re-trigger the wrong bot and miss real findings -- this already happened once this session. Deliberately NOT touched: docs/history/** session-handoff/sprint archives (point-in-time records, not living docs -- only a factual error about what happened would warrant a fix there, not staleness relative to today); docs/i18n/TRANSLATION_STATUS.md (auto-generated by `pnpm run i18n:status`, but regenerating it silently deletes a manually-maintained "Review & Elevation Log" section the generator script doesn't know about -- a real script gap, left as-is rather than risk destroying that audit trail); AUDIT.md's historical "Markdown corpus" file-count entries (all inside dated audit-log sections, correctly excluded by the doc-metrics gate already).
qnbs
added a commit
that referenced
this pull request
Jul 30, 2026
…audit (#296) * docs(todo): triage 5 stale TODO.md bullets against actual shipped code Manual doc-truth pass (WS-7) -- these claims don't match any of the doc-metrics gate's automated patterns (no version string, no tag/release marker), so drift here can only be caught by checking each claim against the real implementation: - RTCDataChannel E2E encryption (duplicated 3x across old dated sections): already shipped in packages/collab-transport (vendor fork y-webrtc 10.3.0, C-1) -- confirmed via that package's own AUDIT.md. - RTL language support (duplicated 3x): Beta-shipped (ar/he/fa behind enableRtlLayout), redundant with the more detailed/current "C-6" entry. - LoRA fine-tuning support (duplicated 3x): shipped, default-on enableLoraAdapters flag. - Whisper WASM STT: engine + download UI shipped; only E2E test coverage remains open. - Kokoro/Piper TTS: Kokoro shipped and tested; Piper is still just an unimplemented type-level placeholder, not a real engine. * docs(readme): comprehensive audit -- fix drift, add 13 undocumented features Full pass over README.md against actual current repo state: Factual corrections: - Test metrics were stale (2026-07-28 snapshot): badge + 4 in-body mentions said "5807+ tests / 531 files" -- verified via the actual Vitest JSON artifact from a completed CI run (numTotalTests/testResults.length), now correctly "6477 tests / 529 files" (2026-07-30). - Tech-stack table said "TypeScript 6 (strict)" while the version badge and every other TS mention in the file already said "TypeScript 7 (tsgo)" -- package.json confirms tsgo (@typescript/native-preview); fixed the contradiction. - Removed a broken ToC link to "Deutsche Version (German)" -- no such section exists anywhere in the file, so the anchor 404s. - CI job table was missing two real, currently-running jobs: `e2e-deep` (E2E Deep Coverage feature-flag matrix, continue-on-error) and `vrt` (Visual Regression) -- both confirmed present in ci.yml. - Project Structure diagram didn't list `packages/worker-bus`, the central WorkerBus v2 orchestration package (ADR-0015) that DuckDB, local embeddings, and local NLP all now route through. Coverage additions -- 13 shipped, mostly default-on features had zero README mention despite full documentation in CLAUDE.md/featureCatalog.ts: - New "Story Organization & Research" section: Story Objects & Groups, Enhanced Mind Maps, Character Interviews v2, Research Binder, Compile Wizard. - New "Performance, Analytics & Extensibility" section: DuckDB Analytics, WorkerBus v2, Adaptive AI Engine, Compute Shaders, Rust Compute (desktop), Plugin System v0.1, LoRA Adapter Inference, App Health Panel. Every number and file/package reference here was verified against the current codebase, not carried over from the previous README text. * docs: audit critical instruction/security/roadmap docs against actual state Same evidence-based doc-truth pass as the README audit, extended to the most critical remaining user-facing and agent-instruction docs: - AUDIT.md: "Current version" was still v1.24.2 -- two releases (#293, #294 doc-truth/codify work) had already landed on main since. Updated the header chain and current-version summary to v1.24.3. - ROADMAP.md: no v1.24.3 entry existed at all, even though it explicitly said worker-generation-duplication consolidation was "deferred to a dedicated migration sprint" -- that sprint shipped as v1.24.3. Added the release section and removed a stale "Upcoming" bullet asking to "finalise & test RTCDataChannel E2E encryption" -- already shipped (same finding as the TODO.md fix in this PR). - .github/SECURITY.md: supported-versions table said `main (v1.19.0)`, five releases behind actual v1.24.3. - docs/SECURITY-THREAT-MODEL.md: header said "v1.22.0 baseline" while the body already documented the v1.24.2 desktop-crypto fix (F-05/F-06) -- inconsistent self-reference, not a substance error. - AGENTS.md: tech-stack table had six stale pinned versions (TypeScript claimed a nonexistent "~6.0.3" -- the project has no plain `typescript` package, only `@typescript/native-preview` beta/tsgo; Tailwind, Biome, Storybook, Zustand, Vitest, Playwright were all behind actual package.json versions). - CLAUDE.md, .github/copilot-instructions.md, .cursorrules, KIMI-INSTRUCT.md, docs/CODEANT-REVIEW-LOOP.md: all five wrote the PR review-comment policy CodeAnt-centric (re-trigger `@codeant-ai review`), but empirically across every PR in this session's sprint, CodeRabbit was the bot actually posting inline comments (`@coderabbitai review`); CodeAnt only ever appeared as 5 CI status checks. Added a clarifying note to each so a future session doesn't re-trigger the wrong bot and miss real findings -- this already happened once this session. Deliberately NOT touched: docs/history/** session-handoff/sprint archives (point-in-time records, not living docs -- only a factual error about what happened would warrant a fix there, not staleness relative to today); docs/i18n/TRANSLATION_STATUS.md (auto-generated by `pnpm run i18n:status`, but regenerating it silently deletes a manually-maintained "Review & Elevation Log" section the generator script doesn't know about -- a real script gap, left as-is rather than risk destroying that audit trail); AUDIT.md's historical "Markdown corpus" file-count entries (all inside dated audit-log sections, correctly excluded by the doc-metrics gate already). * fix(docs): make CodeRabbit the authoritative re-trigger, close version gaps Addresses 3 CodeRabbit findings on PR #296: 1. The prior commit added a clarifying note that CodeRabbit is the bot actually posting inline comments, but left the primary re-trigger instruction as the stale `@codeant-ai review` in 5 files -- a future session following the primary instruction literally would re-trigger the wrong bot and see no new comments, wrongly concluding the loop is quiescent. Made `@coderabbitai review` the authoritative re-trigger in CLAUDE.md, .github/copilot-instructions.md, .cursorrules, KIMI-INSTRUCT.md (sections 3.6-3.7), and docs/CODEANT-REVIEW-LOOP.md (both the diagram and the actual procedure body, not just its header note) -- CodeAnt AI is now described consistently as CI-status-only. 2. .github/SECURITY.md's supported-versions table had a gap: main is v1.24.3, best-effort ended at 1.23.x, leaving 1.24.0-1.24.2 unclassified. Extended the best-effort range to 1.3.x-1.24.2. 3. AGENTS.md's Project Overview still stated Version: 1.23.0, missed by the previous commit's tech-stack-table-only fix. Updated to 1.24.3.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
WS-1 of the post-recovery audit (per the governing
PROMPT-WSS-v1.24.xprompt).stripHistoricalSections()blanked every line in a dated/historical section, includinggenuinely still-open
- ⬜bullets — exactly how a stale "Tag v1.24.2" bullet escaped the gatein a same-day doc edit (
dc14bc0).DONE_BULLETalready had the mirror rule for the oppositepolarity (a
- ✅bullet is historical regardless of section);OPEN_BULLETnow gets the same"always present-tense" treatment.
scanForDrift()gains a matching check: a surviving open bullet mentioning tag/release/publishof a version
<=the latest git tag is now a drift finding.(temporarily reverted TODO.md's already-fixed bullet, confirmed old logic passed / new logic
fails with the exact finding, then restored it).
Test plan
pnpm run lint— cleanpnpm run typecheck— cleanpnpm exec vitest run tests/unit/checkDocMetrics.test.ts— 26/26 passpnpm run docs:check— OKSummary by CodeRabbit
Bug Fixes
Tests