Skip to content

fix(docs): route library.md at live work, and stop calling it a catalog - #767

Merged
adamgell merged 2 commits into
mainfrom
fix/686-library-routes
Oct 3, 2026
Merged

adamgell merged 2 commits into
mainfrom
fix/686-library-routes

Conversation

@adamgell

Copy link
Copy Markdown
Owner

Closes #686.

What

library.md is a sixteen-rule task router, and every rule pointed at finished work:

Referenced State
#500, #490, #512 MERGED
#441, #409, #321, #333, #317, #410, #414, #506, #507, #326 CLOSED

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.md documents 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.md and memory.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.md itself, and in the routing line in .Clairvoyance/library.md:

- IF routing a task to its document (the repo-root router; it is a route list, not a catalog) → read [[library.md]]

Verification

All five surviving route targets resolve:

EXISTS   soul.md
EXISTS   memory.md
EXISTS   crates/cmtraceopen-parser/tests/fixtures/sccm/correlation/README.md
EXISTS   docs/sccm/preparation/issue-326-client-management-corpus.md
EXISTS   docs/superpowers/plans/

git diff --check is clean. The original → and — characters are preserved rather than replaced with ASCII.

Provenance

Recovered from 7cb10808 on #696, whose branch fix/issue-686 was 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-valid soul.md/memory.md route, and its file had no trailing newline.

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.
@adamgell

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 25, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Next included review available in 13 minutes.

Check out review usage here.

View limit details

Limit 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.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Repository: adamgell/cmtraceopen/.coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Team
  • Run ID: 35b9ca53-82f3-438f-a9c2-ea3fe8d77817
📥 Commits

Reviewing files that changed from the base of the PR and between 656ea6b and c6f9c6c.

📒 Files selected for processing (2)
  • .Clairvoyance/library.md
  • library.md
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added bug Something isn't working enhancement New feature or request labels Sep 25, 2026
@coderabbitai

coderabbitai Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

adamgell added a commit that referenced this pull request Sep 25, 2026
#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>
@adamgell
adamgell marked this pull request as ready for review October 2, 2026 23:54
Copilot AI balanced review requested due to automatic review settings October 2, 2026 23:54

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

adamgell commented Oct 3, 2026

Copy link
Copy Markdown
Owner Author

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.

adamgell added a commit that referenced this pull request Oct 3, 2026
* 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>
@adamgell
adamgell merged commit 401df7e into main Oct 3, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

library.md routes all point at completed work and is described as a catalog it is not

3 participants