@erclx/canon 4.0.0

package/claude/skills/claude-docs/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: claude-docs
+description: Updates `.claude/` planning docs to reflect decisions made during the session, marks outcomes the diff shipped `[x]`, and archives the plans those tasks cite. Use when asked to "sync the .claude docs", when design or requirements changed mid-cycle, after discussing a pivot, or before shipping. Do NOT use to create a task file or move one out of the live folder. That is `claude-tasks`.
+---
+
+# Claude docs
+
+## Guards
+
+- If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run canon claude init to set up the workflow.`
+
+The skip for a session that changed nothing lives at the end of Step 2, because it needs the diff to decide. It drops the doc rewrite alone. The diff-driven sweeps in Steps 4 and 5 still run.
+
+## Diff baseline
+
+Steps 2, 4, 5, and 7 share one diff on the usable path. An unusable baseline splits them, per the rule below. Resolve the base ref once and reuse it:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD`, and `git ls-files --others --exclude-standard`. Read content with `git diff <base> HEAD` and `git diff HEAD`.
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill goes blind to the work it is meant to read.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base came from local `main` and equals HEAD. Nothing is pushed to compare against, so a narrow read reports no changes rather than admitting it cannot see them.
+
+An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
+
+**Step 2 recovers the committed half.** Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
+
+**Steps 4, 5, and 7 keep the scoped set.** Run them on the working tree and untracked files alone, and skip only when that set comes out empty, each reporting the warning its own step names.
+
+Never substitute the whole tree for a missing baseline, and do not reuse Step 2's commit read in these three for consistency. On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. Step 2 tolerates that because it only reads, and it matches conservatively against outcomes already on the board. Steps 4 and 7 write, so the same set stubs a wireframe for every uncovered surface in the repository and rewrites every context entry that tree touches.
+
+Step 5 only reports, and the whole tree costs it a different way. Every anchored decision cites a path the scaffold commit carries, so the sweep flags the entire record and the reader learns nothing about which number moved.
+
+Widening what a step reads is safe. Widening what a step writes is not, and widening what a step flags spends the reader's attention on entries nothing put in doubt.
+
+## Step 1: read current docs
+
+Read these in parallel from the current worktree root (`pwd`), not the main worktree root. These are tracked files and edits must commit with the branch. Skip any that do not exist:
+
+- `.claude/REQUIREMENTS.md`
+- `.claude/ARCHITECTURE.md`
+- `.claude/DESIGN.md`
+- `.claude/wireframes/index.md` and every `.claude/wireframes/<surface>.md`
+
+Read the task board from the main worktree root instead, per Worktrees in `CLAUDE.md`. It is gitignored scratch and never commits with the branch:
+
+- `.claude/tasks/index.md` first, then the task files this session touched. That narrow read serves the marking step. The scratch sweep reads every file in the folder for its plans sweep and states that where it gives the instruction.
+
+## Step 2: identify what changed
+
+Two sources feed this step. The session carries judgments no diff can show. The diff carries facts about the repository the session may never have mentioned.
+
+Review the session for decisions that diverged from the original plan:
+
+- Requirements added, removed, or changed scope
+- Architecture or technical decisions made or revised
+- Design or UX decisions that differ from DESIGN.md or any `.claude/wireframes/<surface>.md`
+- Tasks blocked or newly identified
+
+Then resolve the diff baseline and match it against the board. From `.claude/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths and read the ones Step 1 skipped.
+
+Path matching only chooses which files to open. Behavior decides each outcome. For each unchecked outcome, decide whether the diff shipped the behavior that outcome names.
+
+Completion is the one judgment here that is a fact about the repository rather than a fact about the conversation, so the diff decides it and the session does not. Requirements, architecture, and design stay session-sourced.
+
+Keep the match conservative:
+
+- Mark only outcomes already written on the board. Never infer a new task from the diff.
+- Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
+- Leave an outcome `[ ]` when the diff is ambiguous. An unmarked shipped outcome costs one manual edit, while a wrongly marked one hides work that never happened.
+
+Skip Step 3 when the session shows no divergence **and** the diff matches no queued outcome, reporting `✅ No doc updates needed. Session matched the original plan.` Both conditions have to hold. Shipping a queued task exactly as planned is the ordinary case and it reads as no divergence, so a session-only skip would drop the marking step with it.
+
+Then run Steps 4 through 9. Step 3 is the only one this skips, because it is the only one driven by the session rather than by the diff or the board. A project with an empty task board making a mechanical change satisfies both conditions above, and stopping here would put an uncovered surface out of reach in every such project.
+
+The steps that follow reach past the session, so each earns the reach separately:
+
+- Step 4 stubs against the diff. That is why the skip is not a stop. A session that changed no docs is exactly when an uncovered surface goes unnoticed.
+- Step 5 reads the architecture record against the diff. A run that amended no decision is the one where an anchored number moves under a reasoning nobody reread, which is the case the marker exists to surface.
+- Step 7 rewrites context entries against the diff and against the facts `claude-memory-capture` routed. The Diff baseline section above groups its diff half with Steps 4 and 5 as a scoped-set step, so a quiet session is no different from any other for it. The routed half reads a named file and runs whatever the diff shows.
+- The scratch sweep reads the board rather than the session. Its board-wide scan exists to clear a plan an earlier run stranded, and a run that stops at Step 2 can never reach one.
+
+This changes which steps the skill reaches. It does not widen what any of them reads. Steps 4, 5, and 7 still take the same scoped set the Diff baseline section defines, and that section's rule is about the input a step is handed rather than about which steps run.
+
+## Step 3: update
+
+For each doc with relevant changes, apply updates following these rules. Read a standard this skill names, here or in a later step, from `${CLAUDE_SKILL_DIR}/../../standards/` when the project does not have it.
+
+**`.claude/tasks/`**
+
+- Mark completed outcomes `[x]` in the task's own file through `canon tasks outcome <stem> --close <n> --json`, repeating `--close` for each. Positions count every outcome checkbox in file order from 1, which the read above already gives. Do not move or archive the file.
+- Write a newly identified task as its own file, following `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` for the filename and frontmatter.
+- Do not touch task files this session did not change.
+- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it.
+
+The verb resolves the board at the main worktree root in-process, which is the route because this is an edit inside an existing file and the file-editing tools refuse that path from a linked worktree.
+
+Read `ok` and `reason` out of that record rather than the exit, for the reason the plans sweep below states at length. A refusal arriving as success leaves the outcome unmarked while the chain moves on, so the board reports shipped work as open and the next session re-plans it.
+
+**REQUIREMENTS.md, ARCHITECTURE.md, DESIGN.md, `.claude/wireframes/<surface>.md`**
+
+- Update only the sections affected by session decisions.
+- Do not rewrite sections unrelated to what changed.
+- Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` and the `write-human` skill for all edits.
+- Close a decision entry in `.claude/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` fixes the sentence.
+- Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 5 reports a stale anchor and no step writes one on an entry it did not amend.
+
+Write each updated file immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+## Step 4: wireframe coverage sweep
+
+Skip this step silently when `.claude/wireframes/` does not exist or has no surface files. When the baseline is unusable, scope it to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the wireframe sweep.`
+
+Reuse the diff from the baseline above and filter for UI-affecting paths. UI-affecting paths are framework-dependent. Default heuristic: any file under a `components/`, `features/`, `pages/`, `app/`, `routes/`, or `screens/` folder, plus any `*.tsx`, `*.jsx`, `*.vue`, or `*.svelte` file anywhere in the diff.
+
+Skip silently when the filter leaves nothing, which is every branch touching no UI. Otherwise read `${CLAUDE_SKILL_DIR}/references/wireframe-sweep.md` for the slug derivation, the two findings it reports, the stub it writes, and the output lines.
+
+## Step 5: architecture anchor sweep
+
+Skip this step silently when `.claude/ARCHITECTURE.md` does not exist at `pwd` or carries no decision entry with a verification anchor. A record written before the rule holds none, and a project is not told on every ship that nothing has been checked when the standard calls that state correct. When the baseline is unusable, scope the sweep to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the anchor sweep.`
+
+This step reports and never writes. The record carries no frontmatter, so an anchor is a sentence sharing a paragraph with the claim it marks, and a pass editing prose to mark prose has no structural guard against editing the claim beside it. A surface whose marker sits in YAML gets that separation for free and this one cannot.
+
+Step 3 holds the writer, and the two never meet. Anchoring fires when this run amends a decision, and this sweep fires when the diff moves a path under one, so a single step covering both would gate the anchor obligation on a signal that has nothing to do with it.
+
+Follow `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` for the anchor sentence this step matches on.
+
+Past the skip above, read `${CLAUDE_SKILL_DIR}/references/anchor-sweep.md` for how an entry's cited paths are collected, the finding the diff fires, and the report line.
+
+## Step 6: flag CLAUDE.md drift
+
+If this session established or changed a cross-cutting behavior rule that belongs in root `CLAUDE.md` (a new always-on convention, a revised workflow rule), surface a one-line warning:
+
+`⚠ CLAUDE.md may need a rule from this session. Review and edit by hand.`
+
+Do not edit `CLAUDE.md` inline. Every `CLAUDE.md` change goes through the show-diff-and-approve gate, so this step only flags. Skip silently when the session made no cross-cutting behavior decision.
+
+## Step 7: refresh context entries
+
+Read `.claude/context/index.md` at `pwd` to see which domain entries exist. Skip this step silently if the directory does not exist or has no entries.
+
+Two sources feed this step, the same split Step 2 runs on. The diff carries what the repository changed. The routed facts carry what the session learned, which a diff cannot show.
+
+**Routed facts.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.claude/.tmp/memory-routing/<slug>.md` at the main worktree root. `claude-memory-capture` writes it, one H2 per target entry naming the path, with the fact underneath. Fold each fact into the entry its heading names, then delete the handoff file so a later run does not fold it twice.
+
+This half is not diff-scoped and must not be. A gotcha a session hit while working is exactly the fact the diff never shows, and scoping it to changed files would drop the entries worth keeping. The handoff is a named input rather than a scan, so the reach stays bounded to what capture decided.
+
+Skip this half silently when the file is absent, which is every run where nothing routed.
+
+**The diff.** When the baseline is unusable, scope this half to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.` The routed half still runs, since it reads a file rather than a diff.
+
+Reuse the diff from the baseline above, names and content both. For each existing `.claude/context/<domain>.md`:
+
+- Map the entry's section headings to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
+- For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections.
+- Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/../../standards/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
+
+### When the diff removes a capability
+
+The mapping above is scoped by file, and a removal invalidates claims that mapping cannot reach. Run this only when the diff deletes a command, a flag, a constant, or a folder. Ordinary feature work takes the narrow rule alone, since widening it on every ship churns prose nothing put in doubt.
+
+Grep the tree for the name that went, rather than for the paths the diff carries. A capability removed by name is cited by that name, which reaches a file the diff never touched.
+
+- An entry this run already rewrote is read whole before it is left. A refresh that updates the top and leaves a contradicting claim below reads worse than an untouched entry, because the current opening lends authority to the stale remainder. This is the one case that overrides "do not touch unrelated sections", and it overrides it only inside an entry the run edited anyway.
+- A claim comparing two surfaces is checked even where its file is outside the diff. Such a claim holds only while both surfaces do, so moving one inverts it with nobody editing the file it sits in.
+
+Report each hit as an ordinary rewrite.
+
+Do not create new entries automatically. New entries are a deliberate decision: the user invokes `claude-docs --new-context <domain>` (future flag) or hand-creates the file following `${CLAUDE_SKILL_DIR}/../../standards/context.md`. Auto-creation risks padding `.claude/context/` with low-signal entries.
+
+Write each updated entry immediately. Output one line per file:
+
+`✅ Context: .claude/context/<domain>.md`
+
+Add a line naming the handoff when one was consumed:
+
+`🧹 Folded: .claude/.tmp/memory-routing/<slug>.md`
+
+The base lint-staged config runs `canon indexes regen` on every committed `*.md`, so `.claude/context/index.md` refreshes automatically on commit. No manual step needed.
+
+## Step 8: fold promoted pages
+
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.claude/.tmp/teach-promotion/<slug>.md` at the main worktree root. `claude-teach` writes it, one H2 per destination naming the path, with a source line under the heading and the page body in a fenced block below that. Read the body out of the fence rather than off the heading level, since a reference page carries headings of its own and only the fence separates them from the next destination. Skip this step silently when the file is absent, which is every run where nothing was promoted.
+
+Each block is a page an operator already confirmed a destination for, so this step lands it rather than judging it again. Write to the destination the heading names, at `pwd` rather than at the main root, since every destination here is a tracked file that commits with the branch:
+
+- A wiki page and a public doc arrive as a whole file. Write it as the block gives it, and stop with the block unfolded when the destination path already holds a file, since overwriting a page someone else wrote is not a fold.
+- A context entry is merged into rather than created. Fold the body into the sections it belongs under, the same way the routed facts above are folded, and never add an entry the catalog does not already carry.
+
+Then delete the handoff file so a later run does not fold it twice, and regenerate the index of any folder that carries one.
+
+Output one line per page landed:
+
+`✅ Promoted: <destination path>`
+
+Add a line naming the handoff when one was consumed:
+
+`🧹 Folded: .claude/.tmp/teach-promotion/<slug>.md`
+
+Report a block left unfolded rather than dropping it:
+
+`⚠ Skipped: <destination path> already exists. Merge by hand.`
+
+## Step 9: sweep consumed scratch
+
+Sweep reviews this session consumed, and sweep plans across the whole board. Resolve all paths at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
+
+Every move and delete below is a shell operation, so send each as a plain single `Bash` command rather than joining a `mkdir -p` to the `mv` with `&&`, which is refused as compound from a linked worktree. The one edit inside an existing file is the `Plan:` retarget, and no verb covers it: read the task file and write it back whole with a heredoc, which the file-editing tools refuse from a linked worktree and no shell stream editor may do.
+
+### Plans
+
+Scan every file in `.claude/tasks/`, not only the ones this session touched. For each task file whose outcomes are now all `[x]`, check for a `Plan:` line directly under the title and parse the target.
+
+The line carries a markdown link, so read the target out of the parentheses rather than taking the rest of the line. A task still carrying the older bare-path form parses the same way once the link is absent, so accept both. Resolve the target against `.claude/tasks/` before routing on it, which lands `../plans/x.md` and `.claude/plans/x.md` on the same file.
+
+The bullets below name resolved locations, so an unresolved target falls to the last one and no plan is ever archived. Never delete a plan. `${CLAUDE_SKILL_DIR}/../../standards/plan.md` owns the archive destination and why a shipped plan is moved rather than removed.
+
+Board-wide scope is the one place this sweep reaches past Step 3's rule against touching task files the session did not change. A board carrying a task that closed while an earlier run missed its archive is the defect this exists to clear, and skipping those tasks would preserve it. Reaching them is safe because the archive moves the plan and points the task at the new path, so a task from unrelated work ends up with a working pointer rather than a broken one.
+
+Before moving anything, count the other citations. Scan every `.claude/tasks/*.md` file except the one being processed for a `Plan:` line naming the same plan. Compare the resolved target from the parse above, never the raw target string and never the filename alone.
+
+A board carrying one task written `../plans/x.md` and another written `.claude/plans/x.md` cites one plan, and a raw string comparison reads two, counts zero, and archives the file out from under a live task. Comparing filenames swaps that for the opposite error, since a live plan and an archived one share a basename whenever a closed task still points into `.claude/plans/archive/`, and the count then reads a citation that does not exist and archives nothing.
+
+Exclude the closing task explicitly. It sits on the board and cites the plan itself, so a scan that counts it never reaches zero and no plan is ever archived.
+
+`canon tasks plan-citations <stem> --json` answers this same question, and the archive gate already reads it. This body states the rule anyway rather than calling the verb, because a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes, so a target whose installed `canon` predates the verb gets no record back and routes on nothing. Measured against the `claude:docs` `board-sweep` arm, where calling the verb archived neither plan and created no `.claude/plans/archive/`.
+
+Nothing in the exit code reports that. Branch on the record's `ok` and `reason` fields and never on the exit, which is the rule every task verb already carries: an operator's shell profile may wrap `canon` in a function that runs the binary and then another command, taking its status from the second, and one measured here masks every non-zero exit rather than only an absent verb. The binary itself exits 1 for an unknown subcommand and 1 for an ordinary refusal alike. Switching this body to the verb needs a release that carries it and a read of the record rather than the exit, which together retire the duplication.
+
+A plan can serve more than one task, and archiving on the first task to close strands every other task's pointer at a path that has moved. `.claude/plans/` is gitignored, so that retarget would be the only record and there is nothing to recover it from.
+
+- Target resolves inside `.claude/plans/`, the file exists, and no other task file cites it: create `.claude/plans/archive/`, move the file there under its original name, overwriting any file already sitting at that name. Then rewrite the task file's `Plan:` line to the archive path, so a completed task still leads to the reasoning behind it.
+- Target resolves inside `.claude/plans/` and at least one other task file cites it: leave the plan where it is and retarget nothing. Report the shared citation.
+- Target resolves inside `.claude/plans/archive/`: skip silently. The plan was archived by an earlier pass and the task file is already correct.
+- Any other resolved target outside `.claude/plans/`: warn and skip.
+
+Write the retarget as a markdown link, `Plan: [feature-<slug>](../plans/archive/feature-<slug>.md)`, updating both halves so the text and the target stay in step. This branch is the only writer that produces a `Plan:` line nobody authored by hand, so a retarget that emits a bare path converts every task to the old form as it closes and drifts the board back to two shapes on its own.
+
+### Reviews
+
+Leave the current branch's review receipt where it is. `claude-autoship` Step 6 keeps minor findings in `.claude/review/branch/review-<slug>.md` and its closing block hands the reader that path, so deleting it here removes the file the chain that invoked this skill is still citing. Seven runs recorded that collision across two days before a sandbox fixture asserted the receipt and could pass only on a run the chain stopped early.
+
+The body that writes a receipt owns its lifetime. This skill sweeps on behalf of whatever called it and has no way to read whether a file is still in use, where the chain that wrote this one cites it in its own output and knows. What reaps it is the branch sweep below, one branch later, once the branch it names is gone.
+
+Sweep the branch reports this session never opened. List `.claude/review/branch/review-*.md`, run the slug transform in `${CLAUDE_SKILL_DIR}/../../standards/slug.md` over every name `git branch --format='%(refname:short)'` prints, and delete a report whose slug matches none of them. Take the names from that format rather than from `git branch --list`, which marks the current branch with `* ` and a branch checked out in another worktree with `+ `, so a transform reading the marked lines as written turns a live branch into a slug nothing matches and sweeps a report a sibling worktree is still working from. A branch report is read once, by the session addressing it, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so a report outliving its branch is holding nothing. Skipping this leaves them accumulating for the life of the checkout, since a slug is unique per feature and no later branch ever looks for one.
+
+What that removes is a local-only review on a branch deleted before it opened a pull request. `claude-review` says so where a reader meets the report, and the sweep runs anyway rather than keeping every report against the one case, since nothing else ever clears them.
+
+Memory receipts sweep board-wide, like both halves of this step above them. Scan every `.claude/review/memory/memory-review-*.md`, not only the one matching this slug. `claude-memory-review` writes its receipt after this skill has run in every ship chain, so a sweep keyed on the current slug looks for a file that does not exist yet, and no later branch looks for it either because a slug is unique per feature. Scanning the folder is what makes the sweep fire at all.
+
+For each receipt, count the H2 items still marked 📝 pending:
+
+- No pending item: fold it per the collection rule in `${CLAUDE_SKILL_DIR}/../../standards/memory.md`, then delete the receipt.
+- Any pending item: leave it and report the count. Pending items are decision state, and a branch shipping is not an operator deciding them.
+
+That standard owns what a fold writes and which entry types take one. `claude-memory-review` collects a receipt on the same rule, so neither body restates it.
+
+Do not sweep `ui-checklist-*.md` (pending human verification), `ux-audit-*.md`, or `ux-measure-*.md` (standalone deliverables). Those sit at `.claude/review/` itself rather than under a producer folder, so the two globs above never reach them.
+
+Output one line per file swept:
+
+- `📦 Archived: <path>` for a plan moved into `.claude/plans/archive/`
+- `⏭ Kept: <path>, still cited by <task-file>` for a plan another live task shares
+- `🧹 Deleted: <path>, branch gone` for a branch report whose branch no longer exists
+- `🧹 Deleted: <path>, folded <n> skips` for a swept memory receipt
+- `⏭ Kept: <path>, <n> items pending` for a memory receipt still holding decisions
+
+If nothing qualifies, skip this step silently.
+
+## After completion
+
+Output one line per file updated:
+
+`✅ Updated: .claude/<filename>`
+
+If no files were updated and nothing was swept, output:
+
+`✅ No changes needed.`
+
+Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

package/claude/skills/claude-docs/references/anchor-sweep.md

@@ -0,0 +1,58 @@
+---
+title: Architecture anchor staleness sweep
+description: How an anchored decision's cited paths are collected, the finding the diff fires, and the report line
+---
+
+# Architecture anchor staleness sweep
+
+Mechanics for Step 5 of `claude-docs`. The body owns the skip conditions, the report-only constraint, and the standard citation, and this file owns what the sweep does once the diff touches a path an anchored decision cites.
+
+## Anchored entries
+
+Read `.claude/ARCHITECTURE.md` and take the H3 entries under `## Key technical decisions`. An entry is anchored when its reasoning closes on the marker the standard fixes:
+
+```plaintext
+Measured at <short-sha> on <YYYY-MM-DD>.
+```
+
+Skip every entry without one. An unanchored entry either predates the rule or cites no measured number, and the standard calls both correct, so the sweep has nothing to say about either.
+
+For each anchored entry, collect the backticked code paths its reasoning cites. Same read the diagram sweep runs over an explanation, against a paragraph instead of a diagram.
+
+Most of these name a folder rather than a file, because the number an entry anchors is usually a count over a tree. Match accordingly:
+
+- A citation naming a file matches when the diff carries that file, wherever it sits. A file at the repository root such as `CLAUDE.md` is a file citation like any other.
+- A folder citation, which is one ending in a slash, matches when the diff carries any path under it.
+- A folder citation of a single segment matches nothing and is skipped.
+
+The third rule reaches folders alone, which is what keeps it off `CLAUDE.md`. Breadth is the whole reason it exists, and a root file has none: it names one path the diff either carries or does not.
+
+What it does stop is a citation of `.claude/` matching every branch. `src/`, `scripts/`, and `.claude/` each name a tree a project organizes most of its work under, so a prefix match on one fires constantly and rebuilds the ignored warning this sweep exists to avoid. Measured against this repository's record at `87b11e87`, the skip drops 13 of the 26 folder citations and keeps the ones carrying a signal, among them `src/tooling/`, `.claude/rules/`, and `governance/rules/`.
+
+A decision whose folder citations are all a single segment, and which cites no file, therefore never fires. That is the correct outcome rather than a gap: a count over a whole tree moves on nearly every branch, so flagging it every time tells a reader that time has passed and nothing else.
+
+## The finding
+
+Report an entry when the diff touches one of its cited paths, however it was touched. A delete, a rename, and an edit inside the file all move a count of what sits under that path, and the entry's number was read before any of them landed. The diagram sweep narrows to deletes because a diagram survives a body edit, and a number does not.
+
+The anchor's own SHA settles nothing here. A branch is compared against its merge base rather than against the commit the anchor names, so an entry anchored at a commit this branch already contains is still due a read once the branch moves what it counted.
+
+Report an entry once however many of its cited paths the diff carries. Name the first as the evidence and leave the rest, since the reader opens the entry either way and a line per path buries the entry it is about.
+
+What this misses is a claim whose number moved with no matching citation in the diff, whether because the branch never touched the tree it counts or because the entry cites nothing narrower than one segment. That is the recall this trades for precision, and the alternative is re-running an arbitrary measurement read out of prose, which no sweep does reliably.
+
+## What the sweep never does
+
+- Write into the entry. The record carries no frontmatter, so the marker and the claim share one paragraph and an edit reaching one reaches the other.
+- Refresh an anchor. Re-reading the number is the act the marker records, so a date written by a pass that measured nothing is the false confidence the marker exists to prevent.
+- Flag an unanchored entry. The standard scopes the rule forward, and an entry written before it is dated by blame rather than by a read.
+
+The session amending a decision writes its anchor, which Step 3 already requires.
+
+## Output
+
+Output one line per finding:
+
+`⚠ Anchor stale: "<decision name>" cites <path>, which this branch changed. Re-measure and refresh the anchor.`
+
+If no anchored entry cites a changed path, skip silently. A record carrying no anchored entry produces no output on any branch, which is every project until a decision is written or amended under the rule.

package/claude/skills/claude-docs/references/wireframe-sweep.md

@@ -0,0 +1,45 @@
+---
+title: Wireframe coverage sweep
+description: Slug derivation from a UI-affecting path, the contradicted and uncovered findings, the surface stub, and the report lines
+---
+
+# Wireframe coverage sweep
+
+Mechanics for Step 4 of `claude-docs`. The body owns the skip conditions and the UI-path filter, and this file owns what the sweep does once a UI-affecting path survives that filter.
+
+## Deriving a candidate slug
+
+For each UI-affecting path, derive a candidate surface slug from the file's basename and parent folder (e.g. `web/src/features/mock/MockDemoStrip.tsx` → `mock-demo-strip` or `mock`). Cross-reference against the surface files in `.claude/wireframes/`.
+
+## Findings
+
+**Contradicted sections.** When a surface file exists for a path in the diff and the diff renames or removes a literal string that appears in the wireframe prose (e.g. provider name, button label, copy string), output a one-line report entry and stop. Do not auto-rewrite prose. Operator resolves.
+
+**Uncovered surfaces.** When a UI-affecting path has no matching surface file by slug, write `.claude/wireframes/<slug>.md` with this stub:
+
+```markdown
+---
+title: <Slug as title case>
+description: TODO: describe the surface.
+---
+
+# <Slug as title case>
+
+TODO: describe when and where this surface appears.
+
+## Behavior
+
+- TODO
+```
+
+Skip the write when the slug would collide with an existing file (different surface, same slug). Surface the collision in the report instead.
+
+## Output
+
+Output one line per finding:
+
+- `⚠ Wireframe drift in .claude/wireframes/<surface>.md: <contradicted string>`
+- `📝 Stubbed: .claude/wireframes/<surface>.md`
+- `⚠ Slug collision: <slug> matches existing <existing-surface>.md, review and rename`
+
+If the sweep finds nothing, skip silently.

package/claude/skills/claude-feature/REQUIREMENT.md

@@ -0,0 +1,36 @@
+---
+name: claude-feature
+description: What feature planning is for, the gaps it closes, and why it stops before implementing
+---
+
+# Claude feature requirement
+
+## Gap
+
+Without this skill, implementation starts before anyone knows what it touches. A session reads no project context and rediscovers a settled constraint halfway through, the file list emerges as the work goes rather than before it, and the ambiguities that needed a decision get resolved silently in whichever direction the first edit happened to go. A constraint naming a surface to leave alone forbids two different acts at once, so the executing session picks one and the branch either grows an excluded concern or ships a reference to a file the change deleted.
+
+## Must
+
+- Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
+- Name every file the work touches with the reason it is touched
+- Surface each unresolved ambiguity as a numbered question carrying a suggested answer and an empty answer slot, so the plan is decision-ready in one pass
+- State which act a constraint forbids when it names a surface to leave alone, since conforming that surface and retargeting a pointer into it are different acts and only one is out of scope
+- Scale the output to the work. A two-file change with nothing to decide should not produce a plan file.
+- Stop at the plan and wait to be told to continue
+
+## Must not
+
+- Implement, or edit any file the plan describes
+- Read directories speculatively. Context spent on files the feature does not touch is context the plan does not get.
+- Bundle independent concerns into one plan, since a plan covering two things gets executed as neither
+- Restate the plan in chat during follow-up rounds. The file is the source of truth and a chat copy of it goes stale immediately.
+
+## Guards
+
+- No feature description: stop and ask for one
+
+## Out of scope
+
+- Executing the plan, which is the ship pipeline
+- Task-board state, which `claude-tasks` owns. A plan links to its task and does not create one.
+- Reconciling the planning docs after the work lands, which `claude-docs` owns

package/claude/skills/claude-feature/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: claude-feature
+description: Plans a feature by reading the project's Claude setup and scanning relevant source files. Outputs which files to touch, risks, and ambiguities, then stops. Use before implementing anything, or when asked to "implement X", "add X", "build X", or "I want to add X". Do NOT implement. Plan only.
+---
+
+# Claude feature
+
+## Guards
+
+- If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
+- Do not implement anything. Output the plan and stop.
+- When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
+
+## Step 1: read the Claude setup
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: current scope and status, then any task file the feature relates to
+
+Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
+
+- `.claude/DESIGN.md`: tokens, typography, spacing, and component rules
+- `.claude/wireframes/index.md` + the surface files relevant to the feature: intended UI layout and behavior. Read `index.md` first, then load only the per-surface files (`.claude/wireframes/<surface>.md`) the feature actually touches. Do not read the whole folder speculatively.
+
+When the plan adds or revises a surface, the wireframe file follows `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`.
+
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically. Path-scoped rules apply to the files they match.
+
+## Step 2: scan relevant source files
+
+Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively.
+
+Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
+
+Open each file before describing what is in it. A count or a claim carried from an earlier session, a summary, or another document is the most common way a plan ships the wrong scope.
+
+## Step 3: build the plan
+
+The section list, what each section holds, the suggested-and-answer contract, and the lifecycle are fixed by `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. Read it before writing the file and follow it rather than working the shape from memory.
+
+What this skill adds on top of the standard:
+
+- Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
+- Suggest a real default when best practice, the codebase, or prior context points to one.
+- Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
+- When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
+
+## Step 4: output
+
+Decide the mode based on what Step 3 produced:
+
+- **Small** when the plan touches 2 files or fewer, has no architectural or cross-cutting choices, and both Risks and Questions come out `None identified.`
+- **Full** otherwise
+
+A consumer list is a `Risks` entry, which already forces Full. Establishing a resource with more than one consumer, where at least one writes, is a cross-cutting choice wherever that list ends up living, so such a plan stays Full even at two files.
+
+### Small mode
+
+Output the plan to chat. Do not write a plan file. The markers match the standard's, so a plan that later grows into a file keeps the shape it was drafted in.
+
+```markdown
+**Files to touch:**
+
+- `path/to/file`: reason
+```
+
+If real questions exist, include a numbered `**Questions:**` section below, each with a `- Suggested:` line and an `- Answer:` slot:
+
+```markdown
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+Omit empty sections. Do not print `None identified.` in chat.
+
+### Full mode
+
+Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.claude/plans/feature-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist.
+
+From a linked worktree the file-editing tools refuse that path, so the plan goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+The file follows the template in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every plan.
+
+Run `canon records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
+
+Then output in chat:
+
+```markdown
+📝 Wrote .claude/plans/feature-<slug>.md
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+
+Next: /claude-worktree
+```
+
+Show only the path line and the `Next:` line when there are no questions. The `.claude/plans/` directory is gitignored. Do not stage or commit the file.
+
+Do not proceed to implementation until the user explicitly says to continue.
+
+## Discussion rounds
+
+After the plan is written, the user may re-ping with follow-up questions or pushback. Keep chat output to a decision-help shape.
+
+- State each pick as one-line pick plus one-line reason. Do not use section headers, context blocks, or multi-section breakdowns in chat. Those belong in the plan file.
+- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings.
+- When a finding needs more than two lines to explain, update `.claude/plans/feature-<slug>.md` in place with the detail and point the user at the file instead.

package/claude/skills/claude-groundwork/REQUIREMENT.md

@@ -0,0 +1,48 @@
+---
+name: claude-groundwork
+description: Why a question that has not been measured gets a disposable folder instead of a plan, and the write scope that lets the track run without pausing
+---
+
+# Claude groundwork requirement
+
+## Gap
+
+Without this skill, a question nobody has measured is answered with a plan. The session commits to an approach before the current state is known, and the reasoning that produced it lives in a conversation that compacts away. A research pass that does run spreads its findings across chat, so the next session re-measures what this one already counted, or worse carries a figure from recall and states it as current.
+
+Two failure modes cost more than the rest. A track that fans out to subagents returns findings without the reasoning that makes the folder worth keeping, which turns a conversation into a search result. And an experiment fixture written under the project root loads that project's own instruction files through the ancestor chain, so the arm measures the repository instead of the question, and the result reads as evidence either way.
+
+A track that closes with several separable findings writes only one task, and the rest have no stated route out of the folder. Without one, a finding sits until the operator asks whether filing it elsewhere is the next step, which is how a track that measured everything correctly still lost work between sessions.
+
+## Must
+
+- Detect open, resume, and close from the folder itself, matching the topic against tracks already there before deriving a slug
+- Name a newly opened folder with a two-digit ordinal ahead of the slug, taken from the highest one already present across groundwork and intake
+- Apply the qualifying test in open mode alone, so a track already measured is not refused by the test that admitted it
+- Measure the current state now rather than carrying a figure from a previous session
+- Carry a lean and the finding that would overturn it on every open question, or admit that a measurement is missing
+- Confine writes to the track folder, with the close-time task file, the experiment fixture, and the intake routing below as the only exceptions
+- Route a closing-track finding the required task does not cover through `claude-intake`, rather than leaving it to be asked about. The route runs in the same session, so it is a write outside the folder rather than a handoff to a later one.
+- Link every claim about a source outside the project, and list an unread source as a lead rather than citing it
+- Put a fixture a headless run is pointed at outside the repository
+- Write the next-session file self-contained, since the folder is unbacked and dies with the machine
+
+## Must not
+
+- Write a feature plan, a source change, a standard, a rule, or a reference doc
+- Dispatch subagents. A search too large to run inline is a finding that the question is too broad.
+- Close while an open question quietly fails an outcome, rather than resolving it or recording it as knowingly accepted
+- Spawn more than three billed headless runs without asking
+- Match a topic against the shared scratch directory, which holds folders that were never tracks
+- Pause for approval between steps, which the write scope is what makes safe
+
+## Guards
+
+- No topic given: stop rather than inferring one
+- Fewer than two of the three qualifying conditions hold in open mode: stop and route to the planning skill, because the decision is already made
+- Resume and close are exempt from that test by definition
+
+## Out of scope
+
+- Writing the plan the track concludes toward, which `claude-feature` owns
+- Implementing anything the track recommends
+- Persisting the folder. It is gitignored and disposable, which is what makes it the right container for an unanswered question.