Repository navigation
fix(docs): route library.md at live work, and stop calling it a catalog - #767
Conversation
library.md is a sixteen-rule task router and every rule pointed at finished work: eleven PR-integration and critic-rework routes for windows that closed when #500, #490 and #512 merged. An agent routed there arrived at a plan describing completed work and had to work out it was history. Two route classes are treated differently, as #686 sets out. The eleven dead integration routes are removed. The fixture-oracle and #326 corpus routes are kept because their targets still exist and are still consulted, but they are reworded from review tasks into reference pointers, which is what they are. The specialist-agent route is kept unchanged; soul.md and memory.md both still exist. The workspace index also told agents to read this file for 'the full repo path/subject catalog'. That is not what it is, and no such catalog exists for the backend or frontend trees, so an agent followed that instruction and found neither a catalog nor a live route. Both the file itself and the routing line in .Clairvoyance/library.md now say what it is: a route list. The historical plans remain reachable through one pointer rather than eleven. Every remaining target resolves; git diff --check is clean.
|
@coderabbitai review |
|
Warning Review limit reachedYour organization has reached its usage spending cap. Adjust your spending cap in the billing tab. Next included review available in 13 minutes. View limit detailsLimit details: You’ve used all 10 included reviews currently available. Your 28 included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour. Review configuration: ⚙️ Run configuration
📒 Files selected for processing (2)
Comment |
|
#767 rewrites library.md's routes. The note this branch added said the routes point only at finished work and should be regenerated, which is what #767 does, so the note would be wrong as soon as #767 merges. Dropping it here also removes the conflict between the two PRs. The memory.md, soul.md and ADR-005 corrections are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Final independent charter review covers c6f9c6c: no substantive findings. Final diff only corrects library.md and .Clairvoyance/library.md routing descriptions and removes completed historical task routes while retaining corpus/oracle and historical-plan routes. All six required checks pass at this head, current signature is verified valid, and there are no review threads. Owner authorizes independent review in place of CodeRabbit approval for this backlog. Pending current main CI, this PR is second in the explicitly authorized disjoint documentation pair #679/#767; it will be rechecked against the actual first merge tree, with normal expected-head squash and signed single-parent verification, followed by full combined main CI. |
* docs: correct four checkpoint rows whose work merged weeks ago `memory.md` and `soul.md` both carry a "Verified Checkpoints" table, and every row is stale: all four issues merged weeks ago while the tables still say NOT merge-ready, hold the PR until clean, full gate pending, findings outstanding. | Issue | Table said | Verified 2026-09-24 | |---|---|---| | #320 client health | NOT merge-ready | merged via #340, issue closed 2026-08-05 | | #329 DP lifecycle | P1 open, hold PR | merged via #385 | | #330 SUP coverage | full gate pending | merged via #377 | | #366 Intune CP | findings to address | merged via #460 | The rows are not wrong about the *commits* — those SHAs are preserved on origin branches — only about whether the work landed, which is the one thing the table exists to say. `soul.md` prefixes it with "Always verify state before acting"; the instruction was right and unheeded for seven weeks, including by the session that found this. Also notes the failure mode in `memory.md`, so the next reader knows the table tracks pointers rather than state. * docs: the recovery branches are accurate; their targets have landed Verified rather than assumed, since this table gives instructions rather than just describing state: - **All six branches are still present on `origin`** with the SHAs listed, so the "preserve refs" instruction has held — the second artifact today that checks out exactly as written. - **Their targets have landed.** `#365` and `#360` are done, `intune/apps/macos` and `intune/portal/{macos,ios_ipados}` exist on main, and the epic tracker marks the corresponding rows complete. So the second instruction — "check merged equivalents for closed macOS/iOS issues before any PR" — is answered rather than open. The branches stay as evidence, which is what the heading already calls them. The note records why, so the next reader does not treat them as pending work the way the checkpoint table above invited. * docs: the worktree forest is ~65, not 450+ Measured rather than read, since the line gives a number: | Location | Count | |---|---| | `.worktrees/` | 34 (35 registered with `git worktree list`) | | `~/.codex/worktrees/` | 28 | | `/private/tmp/cmtraceopen-*` | 1 | | repo `.claude/worktrees/` | 1 | | `~/.claude/worktrees/` | 1 | The forest is real — the description below the number holds, including the deep branches and the parallel work — but it is a seventh of the size claimed. A count nobody retakes decays in one direction only, and cleaning up merged lanes is exactly what shrinks it. Not updated: the "246 SCCM branches" line. My count matched 211 branches against a looser pattern, which is not the same measurement, and a mismatched instrument is what produced two wrong findings earlier today. It needs counting properly or being marked as approximate. * docs: the charter this table cites is not readable here `memory.md` sources the checkpoint SHAs from `~/.hermes/cmtrace-pm-charter.md`, and the CEO charter treats that path as required: "Main reads this charter ... If the contract is absent or unreadable, Main fails closed before orchestration." Checked 2026-09-24: **the path does not exist on this workstation**. So the citation cannot be followed by a session that reads this table, which is a second reason the SHAs need to be quoted in full rather than referenced — the first being that four of them were stale. The line now says the source is unreadable here and why the table stands alone. If the charter is provisioned on the operator's machine only, this line should say that instead of naming a path a session cannot open. * docs: the routing index routes only into the past `library.md` is what a session reads to find context: sixteen "IF <task> → read <plan>" rules. Checked today, and **all thirteen issues and pull requests it names are closed or merged** (#317, #490, #500, #512, #409, #441, #410, #414, #506, #507, #326, #321, #333). The plan files themselves still exist, so nothing is broken — but nothing here is current either. `docs/superpowers/plans/` holds 40 files, several of them months newer (through 2026-08-30), and the index mentions none of them. So an agent following it is routed exclusively into finished work, which is worse than an empty index: it looks like guidance. Flagged rather than rewritten. Regenerating the rules from the plans directory is mechanical — one rule per file, date included — but deciding which subjects still matter is a judgement about this repository's live work, and that is the owner's. * docs(adr): ADR-005 is accepted; its own confirm-at-merge condition is met The status line read "Proposed — recorded as the resolution of issue #635. Confirm at merge." All three of those are now satisfied rather than pending: - the resolution landed as `a7a21428` on `main` ("stop control and honest coverage for large explicit loads"); - PR #639 merged 2026-09-19; - issue #635 is closed. So the ADR asked to be confirmed at merge and was never advanced afterwards — the same shape as the checkpoint table, one document class over: a normative record whose status lags the work it governs. The revisit criteria keep their role; they are the trigger for reopening, not a reason to leave the status proposed. Checked the rest of the chain while I was here, and it is well maintained: ADR-004's base, revision 1 and revision 2 each state what they supersede and what remains in force. * docs: the gate list was understated in three files, not two `CONTRIBUTING.md` and `CLAUDE.md` both said three checks where seven jobs run. So did `memory.md`, in a one-line summary whose own heading names `CLAUDE.md` as its source — which is the mechanism: a file copies a summary, the summary drifts, and the copies keep its authority because each looks like a local statement rather than a citation. Found by grepping for the phrase rather than assuming the pair I had already fixed was all of them. The correction names the seven jobs, so the next copy has something to copy that is right. * docs: cite the landing PR for the merged checkpoints, and recount the worktrees CodeRabbit review 5, three threads: the checkpoint rows named preparation PRs that landed on codex/parser-family-skeleton (#340, #385, #377) rather than #490, which merged into main and closed #320/#329/#330 within seconds; the worktree counts contradicted the layout block below them and both were stale; and library.md called Aug 30 months newer than Aug 4-5 plans, which is about four weeks. * docs(library): leave library.md to #767 #767 rewrites library.md's routes. The note this branch added said the routes point only at finished work and should be regenerated, which is what #767 does, so the note would be wrong as soon as #767 merges. Dropping it here also removes the conflict between the two PRs. The memory.md, soul.md and ADR-005 corrections are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(memory): distinguish unreconciled historical worktree counts * docs: preserve recovery history and correct SCCM landing references --------- Co-authored-by: Adam Gell <adam@cmtraceopen.dev> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Closes #686.
What
library.mdis a sixteen-rule task router, and every rule pointed at finished work:Every target still resolved, but the rules read as live tasks — "IF integrating SCCM advanced capture PR #500 with current main", "IF reworking Graph API authentication after the PR #512 critic gate". An agent routed here arrived at a plan describing completed work and had to work out it was history.
Two classes, two fixes
Dead — removed (11 routes). The PR-integration and critic-rework routes. Their windows closed when #500, #490 and #512 merged; there is nothing left to integrate.
Still useful — reworded, not removed (2 routes).
tests/fixtures/sccm/correlation/README.mddocuments fixture oracles that exist and are still consulted, and the #326 corpus is reference material, not an integration plan. They were misleading only because they were phrased as work to start, so "IF reviewing …" became "IF working with …" / "IF referencing …".Kept unchanged. The specialist-agent route to
soul.mdandmemory.md. Both files exist and the route is live.Added one pointer.
[[docs/superpowers/plans/]]as a single route to historical work, rather than eleven routes to specific finished windows.The second half of #686
The workspace index told agents to read this file for "the full repo path/subject catalog". That is not what it is, and no such catalog exists for the backend or frontend trees — so an agent following that instruction found neither the catalog it was promised nor any live route.
Both places now say what the file is. In
library.mditself, and in the routing line in.Clairvoyance/library.md:Verification
All five surviving route targets resolve:
git diff --checkis clean. The original→and—characters are preserved rather than replaced with ASCII.Provenance
Recovered from
7cb10808on #696, whose branchfix/issue-686was deleted on the remote and can therefore never merge; authorship is preserved on this commit. Two defects in that commit are fixed here: it deleted the still-validsoul.md/memory.mdroute, and its file had no trailing newline.