docs: brief + user-facing currency fixes surfaced by the v0.4.1 release gate - #165
Merged
Conversation
…rface A tier-full brief<->surface cross-check found 22 discrepancies between the development brief's surface docs and the shipped v0.4.1 binary/tree. Correct each doc claim to match ground truth (binary --help, hooks/hooks.json, commands/abcd/, internal/core/audit/rules.go): - 04-surfaces/01-ahoy.md: dry-run JSON envelope now carries a top-level `guard` key; hooks manifest wires a fifth PreToolUse event (`abcd guard hook`, matcher Bash); `ahoy install` gains a `--dev` flag. - 04-surfaces/05-intent.md: `abcd intent [text]` gains a create-time `--impact` flag; bare render emits an ideate-routing line. - 04-surfaces/06-capture.md: `capture resolve` now requires `--impact`; bare render hint is three-way (adds ideate); only 4 of the 7 provenance flags carry a default. - 04-surfaces/07-memory.md: spec-store range spc-2..spc-13 -> spc-2..spc-19. - 04-surfaces/08-abcd.md: commands/abcd/ is 17 files, not 14; add guard, ideate, identity. - 04-surfaces/15-prepare-this-repo.md: audit engine registers six convention rules, not five (identity-positioning). - 05-internals/08-skills.md: fourteen binary-backed commands, not eleven; add guard/ideate/identity and their sub-verbs; identity has a bare status render. - 05-internals/03-configuration.md: hooks.json annotation adds the PreToolUse guard-hook wiring (five events, not four). - commands/abcd/disembark.md: document the probe and coverage sub-verbs and update the argument-hint (resolves ledger issue iss-137). Assisted-by: Claude:claude-opus-4-8
The 04-launch.md sub-verb enumeration and the dry-run argument-hint predated itd-93; add scaffold to both (crosscheck round 3). Assisted-by: Claude:claude-fable-5
docs/README.md and docs/reference/README.md described the generated CLI reference as a 'planned'/'not yet wired' placeholder; it is generated from the Cobra command tree and gated by a drift test (docs-currency review, v0.4.1 release gate). Assisted-by: Claude:claude-fable-5
…e gate Assisted-by: Claude:claude-fable-5
REPPL
enabled auto-merge
July 29, 2026 05:37
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.
Brings
mainthe documentation corrections made during the v0.4.1 release-gate run (they shipped in the v0.4.1 tag but were not on main, which had already advanced past the release commit with itd-101).What this fixes
The tier-full brief↔surface cross-check and the docs-currency review surfaced 29 real discrepancies between the docs and the shipped binary — accumulated staleness, most of it pre-dating v0.4.1:
04-surfaces/*,05-internals/*): stale command counts, unlisted new verbs/flags (guard, ideate, identity,--dev,--impact), the guardPreToolUsehook event, ideate routing lines, thecapture resolve --impactexample, launchscaffoldin the surface enumeration, and theprompt_version1.0.0→0.1.0 correction.docs/README.md,docs/reference/README.md): corrected the claim that the generated CLI reference is "planned / not yet wired" — it is generated from the Cobra command tree and drift-tested.probe/coverageon the plugin surface).Known residual
iss-152 (added here) tracks a small brief-internal residual the non-deterministic cross-check surfaces (a bare-ahoy
guard:line enumeration; the 07-memory launch-gate count vs the twonot_implementedstubs). User-facing docs are current (docs-currency PROMOTE); these are deferred to a brief-currency sweep.Docs-lint, record-lint, and preflight all clean. No release impact — v0.4.1 is already tagged and published.