Repository navigation
docs: fix three documentation drifts and declare what verifies each doc - #42
Merged
Merged
Conversation
The "Architecture at a glance" tree enumerated four skills; plugin/skills/ has five. capability-tour shipped in #34 without updating the diagram. The line is an exhaustive list, not shorthand: e927c24 (#22) expanded it from one entry to four when skills were added, and the sibling bin/ line enumerates all three files in plugin/bin/. The same README already depends on capability-tour as an existing feature further down.
Two findings from a full doc-surface audit. README's proof-command list omitted `prove:harness-install`, the only prove:* script missing from it. It runs inside `prove:all` and is the named authority in docs/native-capability-qualification.md for package, declaration, and installed-byte proof. capability-tour/SKILL.md enumerates the portable skills in prose with no generation step behind it, so a new skill silently falsifies the line. That is the same drift that left capability-tour out of README's architecture tree until 24102bc. Adds a test deriving the expected inventory from plugin/skills/ and runtime/skill-catalog.json. Sensitivity proven: planting a sixth skill directory turns the guard RED on the missing name; removing it returns GREEN.
Maps each doc to the artifact that settles its claims, so a docs audit reads release.yml when checking publishing.md instead of hoping a scanner finds it. Four docs specify workflow behaviour in roughly 130 assertions between them; without the map those go unread. Also declares what this repo cannot check about itself. installing.md is ~90 claims about external Claude and Codex CLI surface, native-capability- qualification.md rests on human receipts, canary-qualification.md needs a hosted run. Scanning those returns nothing whether they are accurate or wrong, so they are marked unverifiable and reported rather than silently passing. Superseded ADRs 0002 and 0004 and docs/plans/ are frozen - they record history correctly. Consumed by the docs-drift skill. Every path verified to resolve.
myagentdojo
deployed
to
hosted-canary-qualification
August 13, 2026 03:57 — with 
GitHub Actions
Active
GitHub Actions
Active
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughChangesCapability documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Mergeability Score: ⚪ Minimal · up to This PR updates documentation and drift-detection tests without introducing an actionable merge-blocking risk; it is merge-ready after normal checks and review. Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![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 `@docs/agents/doc-targets.yml`:
- Around line 67-70: Update the README.md target in the documentation targets
configuration to include plugin/skills/capability-tour/SKILL.md and
scripts/prove-harness-install.ts as primary artifacts. If README validation
covers the full architecture tree, also add the primary artifacts for its
remaining entries, preserving the existing package.json and
runtime/runtime.lock.json entries.
In `@scripts/native-capability-surface.test.ts`:
- Around line 191-205: Strengthen the inventory assertions around the
portable-skills prose: parse all backticked skill identifiers from inventory and
require the exact set to equal shipped, rejecting extra or missing names. Split
the parsed identifiers into the Bun-backed prefix and model-only suffix, and
assert those groups exactly match bunBacked and modelOnly respectively; also
verify every catalog skill is present in shipped.
🪄 Autofix
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 Plus
Run ID: 5a7b0d03-b167-4fb4-83f6-dc631c68d419
📒 Files selected for processing (3)
README.mddocs/agents/doc-targets.ymlscripts/native-capability-surface.test.ts
…rift The tree enumerates every skill and launcher by hand with nothing generating those lines, which is how capability-tour stayed missing between #34 and 24102bc. Derives both expected lists from plugin/skills/ and plugin/bin/. Closes the same defect class the capability-tour inventory guard covers in e4c6ea4; the README half was left open there. Sensitivity proven both ways: planting a sixth skill directory turns it RED on the skills line, planting a fourth launcher turns it RED on the bin line, and removing each returns GREEN.
myagentdojo
deployed
to
hosted-canary-qualification
August 13, 2026 04:37 — with
GitHub Actions
Active
GitHub Actions
Active
- Parse the skill inventory instead of probing for each name. The containment loop passed while the prose named a skill that does not ship, and passed with a model-only skill inside the Bun-backed prefix; both reproduced before the change and both now fail. Also asserts every catalog entry ships, which is drift in the other direction. - Add plugin/skills/capability-tour/SKILL.md and scripts/prove-harness-install.ts to the README manifest entry. The architecture tree claims capability-tour ships and the proof list describes what prove:harness-install checks; neither package.json nor runtime.lock.json can settle those.
myagentdojo
deployed
to
hosted-canary-qualification
August 13, 2026 10:03 — with
GitHub Actions
Active
GitHub Actions
Active
This branch was successfully deployed
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
2 participants
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.
What
Three drift fixes plus a manifest that makes future drift findable.
Fixes
README.md:136— architecture tree listed four skills;plugin/skills/has five.capability-tourshipped in feat: add native plugin capability tour with lifecycle hook proof #34 without updating the diagram.README.mdproof commands — omittedprove:harness-install, the onlyprove:*script missing from the list. It runs insideprove:alland is the named authority indocs/native-capability-qualification.md.plugin/skills/capability-tour/SKILL.md:42— enumerates the portable skills in prose with nothing generating it. Adds a test deriving the expected inventory fromplugin/skills/andruntime/skill-catalog.json.New
docs/agents/doc-targets.yml— maps each doc to the artifact that settles its claims.Why the manifest
Four docs specify
.github/workflows/*.ymlbehaviour in roughly 130 assertions between them. An audit that isn't told where to look reads the top-level docs and never opensrelease.yml, so those claims go unchecked while the run reports clean.It also declares what this repo cannot check about itself.
docs/installing.mdis ~90 claims about external Claude and Codex CLI surface;native-capability-qualification.mdrests on human receipts;canary-qualification.mdneeds a hosted run. Scanning those returns nothing whether they are accurate or wrong, so they are marked unverifiable and reported rather than silently passing.Superseded ADRs 0002 and 0004 and
docs/plans/are frozen — they record history correctly.Verification
bun run generate:check: generated files currentNotes
No file overlap with #41 — disjoint sets, both can land independently.
The three fixes were found by running a documentation-drift audit against this repo. Two of them are the same defect class: a prose enumeration with no generator behind it. The new test closes that class for
capability-tour;README.md:136remains unguarded and is a reasonable follow-up.Summary by CodeRabbit
Documentation
Tests