@erclx/canon 4.83.0 → 4.85.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.83.0",
+  "version": "4.85.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/draft-and-pick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draft-and-pick
-description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write tests for a change already made, which is `ui-test`, or to script a recording, which is `draft-screencast`.
+description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write tests for a change already made, which is `ui-test`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
 ---
 
 # Draft and pick

package/claude/skills/git-ship/SKILL.md

@@ -48,7 +48,7 @@ An installed binary carrying no `plan-reach` subcommand reports the reach unread
 
 Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
 
-Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
+Stop at the Propose phase. Do not run Apply. Promoting an entry to an always-loaded rule or a skill body ships as its own change, separate from this feature.
 
 ## After completion
 

package/claude/skills/memory-review/REQUIREMENT.md

@@ -29,7 +29,7 @@ A pen the caller cannot face is the same gap wearing a different shape. Routing
 ## Must not
 
 - Apply anything the user has not approved by item
-- Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
+- Author a toolkit rule inline. A toolkit rule under `internal/rules/` or `governance/rules/` has an owner and a scaffolding path, `internal-governance`, and a rule written here bypasses it. A project rule under `.claude/rules/project/` is project-owned and takes an `Edit` appending to an existing file, or a handoff to `create-rule` when none fits.
 - Mutate tracked files from the main worktree
 - Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
 - Delete a memory entry at all. Every exit from the pen is a move into the archive.

package/claude/skills/memory-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-review
-description: Reviews `.canon/memory/` and proposes per-entry actions (promote to `CLAUDE.md`, move into a skill body, route to a context entry, hand off to governance, or retire as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
+description: Reviews `.canon/memory/` and proposes per-entry actions (promote to an always-loaded rule, move into a skill body, route to a context entry, hand off to governance, or retire as stale). Also runs the discuss, challenge, apply, and cleanup phases on an existing review file. Use when asked to "review memory", "discuss memory questions", "challenge the promotes", "apply memory decisions", "cleanup memory review", "promote memory", or "consolidate memories". Do NOT auto-apply. Output a grouped proposal and wait for block-by-block approval.
 ---
 
 # Memory review
@@ -48,11 +48,12 @@ Read in parallel from the project root:
 
 Read in parallel from the project root. Skip any file or folder that does not exist.
 
-- `CLAUDE.md`: project behavior rules and Content ownership section
+- `CLAUDE.md`: project behavior rules and Content ownership section, still a read target for the absorbed-already check even though it takes no new promotion
 - every `SKILL.md` under `.claude/skills/`: domain-scoped internal skill bodies
 - every `SKILL.md` under `claude/skills/`: plugin skill bodies
 - every `*.md` under `${CLAUDE_SKILL_DIR}/../../standards/`: authoring references
 - every `*.md` under `governance/rules/` in the toolkit repo, or `.claude/rules/` in a target project: coding-standards rules
+- every `*.md` under `internal/rules/` in the toolkit repo, or `.claude/rules/project/` in a target project: always-loaded rules a promote lands in
 
 ### Step 3: classify each entry
 
@@ -62,11 +63,13 @@ Read in parallel from the project root. Skip any file or folder that does not ex
 
 For each in-scope entry (see Scope), pick one action:
 
-- **Promote to `CLAUDE.md`**: the rule is cross-domain behavior or a design principle applied across the whole project.
+- **Promote to an always-loaded rule**: the rule is cross-domain behavior or a design principle applied across the whole project, passing `592-claude-md.md`'s test (applies every session regardless of what is being edited). Do not author a toolkit rule file inline.
+  - In the toolkit repo, hand off to `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, which own `internal/rules/core/` (this repo only, never ships) and `governance/rules/core/` (ships to every target).
+  - In a target project, append the rule to an existing file under `.claude/rules/project/` with `Edit`, since a project rule is project-owned and sync never overwrites it, or hand off to the `create-rule` skill when no existing file fits.
 - **Promote to a skill body**: the rule fires only when editing a specific path-scoped domain. Name the target skill.
 - **Promote to a standards file**: the rule is an authoring reference that belongs in the project's own standards folder as `<domain>.md`.
-- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `canon/context/index.md`. Append it to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root, in the format `memory-capture` writes, and tell the user to run `/docs-fold` from a branch. Do not edit the context entry here.
-- **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning). Do not author the rule file inline. Never edit the synced `.claude/rules/` copies of toolkit rules, because `canon gov sync` overwrites them. Stop at handoff.
+- **Promote to a context entry**: the entry states a fact about a domain carrying an entry in `canon/context/index.md`. Append it to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root, in the format `memory-capture` writes, and tell the user to run `/docs-fold` from a branch. Do not edit the context entry here. A project-identity or command fact takes this action when a context entry owns the subject, such as a development entry for commands, and **Retire** otherwise, naming a hand edit to `CLAUDE.md` as the reason. Memory review does not write the root file itself.
+- **Hand off to governance**: the rule is coding-standards class (typescript, testing, naming, error-handling, performance, logging, concurrency, planning), never a cross-domain behavior rule. Do not author the rule file inline. Never edit the synced `.claude/rules/` copies of toolkit rules, because `canon gov sync` overwrites them. Stop at handoff. This and **Promote to an always-loaded rule** never both claim one entry: class names the topic (coding-standards routes here), firing axis names the rest (applies-every-session routes to the rule promote).
   - In the toolkit repo, point the user at `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, which own the source-of-truth rules under `governance/rules/`.
   - In a target project, point the user at the `create-rule` skill, which scaffolds a project-local rule under `.claude/rules/`.
 - **Retire**: the rule is stale, already absorbed into a durable surface, too vague to phrase as a rule, or a one-time incident narrative. Apply moves the file to `.canon/tmp/memory-archive/` rather than deleting it.
@@ -83,7 +86,7 @@ The check covers implication, not only keyword match. If an adjacent bullet in t
 
 #### Crispness check
 
-Rules that resist crisp one-line phrasing default to **Retire** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use terser phrasing for `CLAUDE.md` and imperative phrasing for skill bodies.
+Rules that resist crisp one-line phrasing default to **Retire** over promote. Never promote a memory unchanged. Rewrite to match the destination surface's tone. Use single-directive rule-bullet phrasing for an always-loaded rule and imperative phrasing for skill bodies.
 
 ### Step 4: write the proposal to the review file
 
@@ -134,9 +137,9 @@ Before applying any item, check the worktree state:
 
 If the result is `MAIN`, stop and tell the user: `❌ Apply phase mutates tracked files. Run /session-worktree first.` Discuss and Challenge phases only touch `.canon/review/` scratch and run from anywhere.
 
-Before applying a promote to root `CLAUDE.md`, load `internal-claude` so its seed-mirror rule fires on the edit.
+Before applying a promote to an always-loaded rule in the toolkit repo, load `internal-governance`, which owns `internal/rules/core/` and `governance/rules/core/` and is the only route that may author into either. In a target project, hand off to `create-rule` with no load, since `internal-governance` is a toolkit-internal skill under `.claude/skills/` that a target project never has. An `Edit` appending to an existing file under `.claude/rules/project/` needs no load either.
 
-Promotions are a separate concern from any feature in flight. Keep the promoted edits on their own commit. Do not fold a `CLAUDE.md` or skill-body change into a feature's commits, because a feature reviewer should not have to vet a change to how the agent operates.
+Promotions are a separate concern from any feature in flight. Keep the promoted edits on their own commit. Do not fold an always-loaded-rule or skill-body change into a feature's commits, because a feature reviewer should not have to vet a change to how the agent operates.
 
 For each item, parse the `Decision:` line:
 
@@ -149,7 +152,7 @@ Free-form text after the verb is a reason. Capture it in the receipt but do not
 
 Action by action type:
 
-- **Promote**: use `Edit` to insert the rewritten rule into the target surface, then archive the memory file.
+- **Promote**: use `Edit` to insert the rewritten rule into the target surface, then archive the memory file. A promote to an always-loaded rule in the toolkit repo never reaches this line: it stops as a handoff to `internal-governance`, the same as **Hand off** below, and archives only on the user's explicit confirmation.
 - **Promote to a context entry**: append the fact to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root, then archive the memory file. `docs-fold` folds it in on its next run from a branch, which is what keeps one skill writing context entries.
 - **Hand off**: do not edit governance. Archive the memory file only if the user confirmed the handoff explicitly. Otherwise leave it in place.
 - **Retire**: archive the memory file.

package/claude/skills/memory-review/references/receipt-format.md

@@ -45,4 +45,4 @@ Decision:
 
 ## Variation by action
 
-For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.
+For Hand off items, the body is a pointer to the governance target instead of a rewritten rule: `internal-governance` and `${CLAUDE_SKILL_DIR}/../../standards/rule.md` in the toolkit repo, or the `create-rule` skill in a target project. For a Promote to an always-loaded rule item, the H2 target names the rule file path the rule lands in, `<target>` in the template above, being an existing path under `internal/rules/core/` or `governance/rules/core/` in the toolkit repo, or under `.claude/rules/project/` in a target project, or the `create-rule` pointer when no existing file fits. For Retire items, skip the rewrite block. Every item gets a `Decision:` slot regardless of action. `Take:` is added only when a question response is needed.

package/claude/skills/ux-walkthrough/REQUIREMENT.md

@@ -0,0 +1,53 @@
+---
+name: ux-walkthrough
+description: Why a multi-finding inspection walkthrough with the operator needs its own surface beside draft-and-pick, and where the boundary against building and auditing falls
+---
+
+# UX walkthrough requirement
+
+## Gap
+
+Without this skill, a session running an inspection walkthrough with the operator:
+
+- Files every round's evidence into one flat shared folder, so nothing shows which walkthrough a folder came from or in what order the rounds ran.
+- Hands over screenshots or file paths the operator cannot open, where a served localhost page is the one form that reaches them.
+- Asks the pick question before the operator has the page, so the answer is taken from a description.
+- Sends the link inside the same message as the question, where the structured question surface draws over it and the operator never sees the link.
+- Draws arms as hand-written mock-ups of the app, which drift a few pixels and a few words from what ships, rather than lifting the built page's own markup and stylesheet.
+- Measures the mark and not the text inside it, or the gap and not what shows above it, so a pick ships with half its condition unchecked.
+- Quotes figures in a pick question from memory, and records them without reading the computed values back.
+- Relays each pick as it is taken when the operator wants picks batched on their own call.
+- Serves a rebuilt export from a server whose working directory was deleted by the rebuild, and measures a page that is not there.
+- Applies a pick to the tracked tree, or deletes the candidate pages, because the single-decision loop it borrowed does both.
+- Leaves findings, numbers and build criteria in chat, so whoever files the work does it from a summary rather than from a record.
+
+## Must
+
+- Record conditions, findings with their measurements, picks with the arms they beat, evidence paths and build criteria in one walkthrough file under `.canon/walkthroughs/`.
+- Measure each finding off the built page before drafting any arm.
+- Build candidate pages from the app's rendered markup and built stylesheet, with a theme toggle, served on localhost.
+- Capture every arm in every theme the app ships to its walkthrough's own evidence folder, and look at the captures before handing the link over.
+- Number the walkthrough folder and each round's folders so they sort in the order they ran, and let a round's number match its finding's.
+- Send the localhost link in its own message, ending the turn, before every pick question is asked.
+- Hold picks and relay them only when the operator calls a batch, as one message, to the controller where one exists and to the operator otherwise.
+- Route a finding with no visible choice into the batch as a proposed row rather than drafting arms for it.
+
+## Must not
+
+- Change a tracked file, create a branch or commit, or file a task row.
+- Apply a winning arm or delete the evidence.
+- Draft arms for a finding the operator has not raised.
+- Restate `draft-and-pick`'s arm rules or the `canon capture` and `canon serve` mechanics.
+- Fire on a request naming one decision alone, which `draft-and-pick` covers.
+- Review criterion, not a gate: whether anything other than the operator or a controller's launch brief invokes this skill, and which lines a second project found in its way. Read both back after it has run outside the project it was written in.
+
+## Guards
+
+The refusal strings sit in the body. Two conditions stop a run: no build to measure against, and a request to change a tracked file.
+
+## Out of scope
+
+- `draft-and-pick` runs one decision end to end and applies it. This runs many decisions and applies none.
+- `ux-audit` reads source for roughness. This takes its findings from what the operator saw.
+- `plan-feature` and a worker build a pick. This stops at the record and the batch.
+- The controller, or the operator where none exists, decides rows, order and pull request boundaries. This proposes and does not file.

package/claude/skills/ux-walkthrough/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ux-walkthrough
+description: Runs an inspection walkthrough over a running app with the operator. Measures each finding off the built page, drafts arms as served HTML pages lifted from the app's own markup and stylesheet, hands over the localhost link before every pick question, records findings and picks with the arms they beat in one walkthrough file, and relays picks only in batches the operator calls. Use when asked to "run a first-use walkthrough", "do an operator walkthrough", "go through my findings one by one", "inspection walkthrough over the app", or "walk through everything I listed with me". Do NOT use for one decision on its own, which is `draft-and-pick`, to read source for roughness, which is `ux-audit`, or to build a pick, which is `plan-feature` and a worker.
+---
+
+# UX walkthrough
+
+A walkthrough turns what the operator sees in a running app into findings and picks a builder can act on without the conversation. The render is the decision and the record carries the measurements, so every pick here is taken by looking and written down with the numbers behind it.
+
+## Guards
+
+- If no running build or build command exists to measure against, stop: `❌ Nothing to inspect. A walkthrough measures a running build.`
+- If the session is asked to change a tracked file, stop and route it: `❌ A walkthrough records and does not build. Hand the pick to whoever dispatches the build.`
+- Draft no arm for a finding the operator has not raised or agreed to take up.
+
+## Posture
+
+- Write only under `.canon/`, never a tracked file, and create no branch, commit or task row.
+- Stay in the checkout the session started in. Enter no worktree for a walkthrough, since nothing it writes is tracked.
+- Read the `walkthrough.md` of every earlier walkthrough under `.canon/walkthroughs/` first, and raise nothing they already decided.
+- Name every folder a walkthrough writes with a two-digit prefix, per `${CLAUDE_SKILL_DIR}/references/record.md`, so the walkthrough and its rounds sort in the order they ran.
+- Put builds, generator scripts and logs in a scratch folder outside the tracked tree, and anything the operator opens under `.canon/tmp/`.
+
+## Steps
+
+1. **Bring up both builds and record the conditions.** Follow `${CLAUDE_SKILL_DIR}/references/builds.md`. Start the walkthrough file with the commit, the ports and the build commands before the first finding.
+2. **Take the operator's list in their order.** Name each item as a finding with the walkthrough letter and a number, such as T1, and confirm the order once rather than per item.
+3. **Measure before drafting.** Read the component behind the finding and pull the numbers off the built page, per `${CLAUDE_SKILL_DIR}/references/measuring.md`. Write the finding into the walkthrough file with those numbers before any arm exists.
+4. **Route a finding with no visible choice.** A parse defect, a stale figure or a broken invariant gets recorded as a finding with no draft and goes into the batch as a proposed row, not as a pick.
+5. **Draft three or four arms.** Follow `draft-and-pick` Steps 1 and 2 for the arms, with arm 0 the shipped state, one property varied and a cost on each. Build the page from the app's own rendered markup, per `${CLAUDE_SKILL_DIR}/references/candidate-pages.md`.
+6. **Look before handing anything over.** Capture every arm in every theme the app ships into `.canon/walkthroughs/<nn>-<slug>/evidence/<nn>-<slug>/`, with the finding's number as the prefix, open the captures, and fix what rendered wrong before the operator sees the page.
+7. **Hand the link, then ask.** Emit `http://localhost:<port>/<nn>-<slug>/candidates.html` in a message that ends the turn, confirmed with a `200`, carrying no question. Take any reply after that message as the operator having looked, an explicit "go" included, rather than holding for a stated confirmation, and only then put the choice through the structured question surface with the recommendation first.
+8. **Record the pick.** Write what won, what it beat and by which numbers, where the evidence is, and the build criteria, per `${CLAUDE_SKILL_DIR}/references/record.md`. Read every figure you quote back from the page or the data file first, and correct the record where the question quoted one wrong.
+9. **Hold picks for the batch.** Relay nothing per pick. When the operator calls the batch, send it once per `${CLAUDE_SKILL_DIR}/references/relay.md`.
+10. **Close on the operator's word.** Add the walkthrough summary table and the handoff, leave the evidence in place, and report every file written by its path.
+
+## Rules
+
+- Answer a question the operator asks mid-walkthrough in prose first, with a recommendation, and offer a draft rather than drafting unasked.
+- Say when a pick revises an earlier walkthrough's pick, and record it as a revision naming the pick it revises.
+- Check a claim against the code or the data before an arm makes it, since an arm drawn on a wrong fact is a pick on nothing.
+- Measure both halves of a pick whose condition has two, such as a gap and what shows above it.
+- Keep a finding's measured numbers and the pick's build criteria in the record, never only in chat.
+
+## What this delegates
+
+- `draft-and-pick` owns the arm discipline and the structured question. This walkthrough departs from its Step 2 inlining and its Step 6 apply and delete, for the reasons `${CLAUDE_SKILL_DIR}/references/candidate-pages.md` states.
+- `write-human` carries the voice of every recorded passage and any copy an arm puts in front of a reader.
+- `plan-feature` and whoever dispatches builds turn a batch into plans and code.
+- `canon capture`, `canon serve` and `canon sessions list` own the render, the address and the roster.

package/claude/skills/ux-walkthrough/references/builds.md

@@ -0,0 +1,15 @@
+# Builds and servers
+
+Read when bringing the app up at the start of a walkthrough, and whenever a measurement returns nothing it should.
+
+## Bring up
+
+- Run the live build and whatever service it calls from the checkout the session started in, and record the commit, ports and any state that changes a reading as the walkthrough file's conditions.
+- Build the artifact the deploy ships in a scratch folder outside the tracked tree, so a build never touches the project.
+- Serve that artifact the way the host resolves it. A plain file server can answer a clean route the host rewrites with a 404, such as `/about` for `about.html`.
+- Rebuild from the current main whenever main moves mid-walkthrough, and say so in the record. Measuring a stale build reports on code that no longer ships.
+
+## Traps
+
+- Restart a server after rebuilding what it serves. A server started inside an output folder the rebuild replaced keeps serving a deleted directory, and every selector comes back empty.
+- Note what a build cannot show, such as live timing a recorded build does not carry or recompile pauses a dev server adds. Neither is a finding.

package/claude/skills/ux-walkthrough/references/candidate-pages.md

@@ -0,0 +1,26 @@
+# Candidate pages
+
+Read when drafting arms for a finding. Skip it for a finding with no visible choice.
+
+## Build from the app
+
+- Dump the rendered markup of the surface under test from the built page, after it has loaded, into a JSON file in scratch. Strip scripts from the dump.
+- Copy the built stylesheet and font files under `.canon/tmp/`, at the path the dumped markup links them from, so a candidate page renders with the stylesheet the app ships. Every arm then differs from the shipped page only by what the arm names.
+- Trim a large dump to the part the finding needs, and keep the wrapper classes intact so layout rules keyed to them still resolve.
+- Size each frame to the content width the finding names rather than the window width, since a container query reads the frame.
+- Write copy an arm introduces with `write-human`, and take every other word from the dump.
+
+## The page
+
+- Generate the page with a short script, one per round, so a shared change is one edit and a rerun.
+- Put a theme button on the page that flips the app's own theme switch on the root, rather than drawing each frame once per theme. Read `?arm=<id>&theme=<name>` to strip every other arm and the button for capture. Skip the button for an app that ships one theme.
+- Print each frame's measurement under it from a script in the page, so the numbers the operator reads are the browser's.
+- Write an index page linking one page per arm when an arm is a whole page or a route rather than a frame, with thumbnails copied beside it.
+- Name anything the preview cannot reproduce, such as an asset whose colors follow the browser rather than the page's theme button, rather than fixing the page around it.
+
+## Where this departs from draft-and-pick
+
+- Capture into the walkthrough's own numbered evidence folder instead of the folder `draft-and-pick` Step 6 archives arms into, per `${CLAUDE_SKILL_DIR}/references/record.md`.
+- Link the app's built stylesheet instead of inlining every asset. Lifted markup needs the real stylesheet, and an inlined copy is the drift this avoids.
+- Keep `candidates.html` and never apply the winning arm. The walkthrough records and a build applies.
+- Leave `.canon/tmp/<nn>-<slug>/` in place until the picks are built, and never delete the round's evidence folder.

package/claude/skills/ux-walkthrough/references/measuring.md

@@ -0,0 +1,22 @@
+# Measuring
+
+Read before writing a finding and before recording a pick.
+
+## Off the page
+
+- Measure on the built page in a real browser at the widths the finding names, in every theme the app ships, and record the viewport.
+- Read computed styles rather than class lists. A class list names intent, and the computed value is what paints.
+- Measure text contrast against the ground it sits on, and a mark's contrast against its own ground, as two numbers. A mark that sets a background and no text color inherits the browser default, and only the text reading catches it.
+- Measure empty space by text extent, the union of each text node's client rects, rather than by leaf element boxes. A block element spans its row whatever its text covers.
+- Measure a landing by the landed element's top against the bar's bottom edge and by whether the element before it is visible. A pick with a two-part condition needs both readings.
+- Reproduce the shipped value inside the candidate page before trusting an arm's numbers. Arm 0 reading the same as the live page is what shows the page matches.
+
+## Off the data
+
+- Re-derive a figure from the data file that produced it rather than from any document quoting it. Two documents can disagree, and neither is the source.
+- Count a defect across the whole corpus or tree before recording its size, and say whether it sits only at the end, only in one version, or throughout.
+- Test a proposed fix without editing code where the question is its effect, by patching the function in a throwaway script and comparing before and after on counts the fix could move.
+
+## Before quoting
+
+- Read every figure a pick question or a record quotes back from the page or the script that computed it. Correct the record in place when the question quoted one wrong, and say so.

package/claude/skills/ux-walkthrough/references/record.md

@@ -0,0 +1,36 @@
+# The walkthrough record
+
+Read when starting the walkthrough file, recording a finding, and recording a pick.
+
+## File
+
+- Write to `.canon/walkthroughs/<nn>-<slug>/walkthrough.md`, with `<nn>-<slug>` the walkthrough's own folder.
+- Open with one paragraph naming the walkthrough, the date, the commit and what landed since the last walkthrough, then `## Conditions`, `## Findings`, `## Picks`, `## Walkthrough summary` and `## Handoff`.
+- Number findings with one letter per walkthrough and a counter, and never reuse a number.
+
+## Folder names
+
+- With no earlier walkthrough on this topic, a fresh folder takes the next ordinal in `.canon/walkthroughs/`'s own sequence: list the folders present, take the highest `<nn>`, and increment it, starting at `01` when none exist.
+- Put a round's captures at `.canon/walkthroughs/<nn>-<slug>/evidence/<nn>-<slug>/` and its candidate pages at `.canon/tmp/<nn>-<slug>/`, where the inner `<nn>` is the finding's own number, so T1's folders start `01-`.
+- Leave a gap where a finding has no draft. The missing number is what maps each folder to its entry in the record.
+- Take `<slug>` from the decision sentence the way `draft-and-pick` Step 1 derives it, and add only the prefix.
+- Rename no folder from a walkthrough that predates this rule. Tracked documents cite those paths, and a rename breaks every citation.
+
+## A finding
+
+- Head it `### T<n>: <what is wrong, as a claim>`.
+- State what the operator saw, the code behind it by path and line, and the measurement in a table when it has more than two readings.
+- Name an earlier pick the finding revises, and a collision with work in flight.
+
+## A pick
+
+- Head it `### Pick <n>, T<n>: arm <id>, <what won>`.
+- One paragraph on what the arm does and its measured result, then `It beat:` with one bullet per losing arm and the number that lost it.
+- One `Evidence:` line naming the evidence folder and its file set.
+- `Build criteria:` as bullets a builder checks against the built page, each measurable, including what the render shows that the prose does not.
+- An answer to a question the operator asked with the pick goes under the criteria, stated as a decision with its reason.
+
+## Close
+
+- `## Walkthrough summary` is one table row per finding: the finding, the pick, and the arms it beat.
+- `## Handoff` proposes how the picks split into pull requests by the files each writes, and names shared files and the order they force.

package/claude/skills/ux-walkthrough/references/relay.md

@@ -0,0 +1,25 @@
+# Relaying picks
+
+Read when the operator calls a batch, and at the start of the walkthrough when a launch brief asks for collisions.
+
+## Where the batch goes
+
+- Send it to the controller where the session was dispatched by one, resolved per the Channel rule, matched by name through `canon gov list --rules --json` rather than a path a target may not have installed.
+- Give it to the operator as one list in the conversation where no controller exists. The walkthrough file is the handoff either way.
+
+## When
+
+- Relay nothing per pick. Relay once when the operator calls the batch, covering every pick held since the last one.
+- Put a finding with no visible choice in the same batch, as a proposed row.
+
+## The message
+
+- Open with one line saying what the batch holds and where the record is.
+- Give each pick its finding, the arm, the numbers that decided it, the arms beaten, and the files it writes.
+- Close with overlaps and order: files two picks share, picks that must follow another, and collisions with open pull requests or unmerged branches.
+- Name anything the operator holds that is not a row, such as a repository setting.
+
+## Collisions
+
+- List open pull requests with their files, and unmerged remote branches with `git diff --stat origin/main...origin/<branch>`, and compare file sets rather than descriptions.
+- Stamp an overlap with the commit it was measured against.

package/claude/skills/youtube-transcripts/SKILL.md

@@ -25,7 +25,7 @@ canon transcripts <url>
 ```
 
 - Pass `--keep-timestamps` when the user wants `[mm:ss]` markers per line instead of prose.
-- Pass `--out <dir>` to override the output directory. The default is `transcripts/` in the current directory.
+- Pass `--out <dir>` to override the output directory, resolved against the current directory. The default is the backed `.canon/transcripts/` folder at the main worktree root, under a filename shaped `<fetch-date>--<title-slug>--<video-id>.md`.
 - The written file path prints to stdout. Surface it back to the user as a full relative path, in the form the project's instruction file sets under `## Output`.
 
 ## After the fetch

package/docs/agents/commands.md

@@ -53,7 +53,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon records migrate`          | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                                                                                                                                                                         |
 | `canon records ordinal`          | Report or claim the next ordinal `intake` and `groundwork` share, creating the folder atomically (`--claim`, `--json`)                                                                                                                                                                                                 |
 | `canon records size`             | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                                                                                                                                                                           |
-| `canon records push`             | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                                                                                                                                                                             |
+| `canon records push`             | Commit every record folder less the exclusion set and push it to a private records remote (`--json`)                                                                                                                                                                                                                   |
 | `canon records pull`             | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                                                                                                                                                                                |
 | `canon migrate rename`           | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                                                                                                                                                                   |
 | `canon migrate skill-names`      | Move the prefixed skill folders onto their two-word names and rewrite every citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                        |

package/docs/agents/records.md

@@ -126,7 +126,7 @@ Exit codes: `0` reported the next ordinal, or `--claim` created the folder. `1`
 
 ## Size
 
-`canon records size` reports what each record folder holds and how much of it is recent. It reads the ten backed folders named under Push and pull, plus the scratch folder, and it gates nothing.
+`canon records size` reports what each record folder holds and how much of it is recent. It reads the same backed folders push carries, resolved the same way, plus the scratch folder, and it gates nothing.
 
 ```bash
 canon records size
@@ -138,7 +138,7 @@ canon records size --json
 | `--json`        | Add a machine-readable record on stdout       |
 | `--root <path>` | Project root, defaulting to the main worktree |
 
-The table carries one row per folder that exists, heaviest first, with the file count, the bytes, a count for each growth window, and the dates of the least and most recently written file. Those dates render in the machine's local time, which is the calendar day whoever wrote the file was living in, and the reading is per-machine already. Folders that do not exist are named on one line below it rather than printed as rows of zeros. The record a `--json` call emits carries every folder either way, each with a `present` flag, so a caller reading the record gets a stable set of keys and can tell an absent folder from one the reading skipped.
+The table carries one row per folder that exists, heaviest first, with the file count, the bytes, a count for each growth window, and the dates of the least and most recently written file. Those dates render in the machine's local time, which is the calendar day whoever wrote the file was living in, and the reading is per-machine already. Folders that do not exist are named on one line below it rather than printed as rows of zeros. At the legacy `.claude` root, the record a `--json` call emits carries every folder in the fixed list either way, each with a `present` flag, so a caller reading the record gets a stable set of keys and can tell an absent folder from one the reading skipped. At a `.canon` root, the folder set is read off the directory itself rather than off a fixed list, so an absent folder is not listed at all: nothing enumerates a name nobody has created yet.
 
 Ordering by weight is what makes the reading worth taking. A folder listed alphabetically hides behind its neighbors, and the row a reader came for is the one that grew.
 
@@ -150,7 +150,7 @@ The scratch folder is read here and skipped by a backup, because deletable witho
 
 The window counts read `mtime`, so what they report is a file written inside the window rather than one created there. An entry edited long after it landed reads as recent, which overstates growth and never understates it, and these folders are append-mostly so the two readings agree on nearly every file. The one reading that is wrong rather than early is a machine restored by `canon records pull`, which resets the work tree hard and re-dates every file it writes, so a window taken there counts the restore. Nothing on the filesystem separates the two, since a restored file is new by every stamp it carries.
 
-Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the project holds neither record root. A project holding a root and no records is empty rather than absent, and each folder's own `present` flag already says which of the ten it carries.
+Exit codes: `0` the reading completed, `1` refused. The one refusal is `no-folder`, raised when the project holds neither record root. A project holding a root and no records is empty rather than absent: at the legacy `.claude` root each folder's own `present` flag says which ones it carries, and at a `.canon` root the folder list itself is already the answer, since nothing absent is named.
 
 ## Push and pull
 
@@ -162,9 +162,9 @@ canon records push --json
 canon records pull
 ```
 
-The backed folders are `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, all under whichever record root the project carries. They are the record root's own entries less three: `tmp`, which is deletable without loss, `.claude/worktrees/`, whose contents belong to the project repository already, and `.records.git/`, which is the history the rest are pushed into. Nothing bounds the list from outside any more, since the claude manifest ships one `.canon/` root entry and names no folder, so spelling the nine out is what keeps a record folder added later from silently entering the payload. Each name is a top-level record folder and every archive sits inside the one it archives, so the list stays at one entry per surface however many archives appear. It is a constant rather than configuration, and it deliberately does not match the six record kinds `validate` hardcodes.
+At the `.canon` root, the backed folders are every top-level directory less three: `tmp`, which is deletable without loss, `ordinal-locks`, whose entries are transient per claim and would race the claim they guard, and `.records.git`, which is the history the rest are pushed into. Nothing bounds the set from outside, since the claude manifest ships one `.canon/` root entry and names no folder, so a record folder added later enters the payload on its own rather than waiting on a name written here. A push names each folder in scope that the records index has never tracked before, so a folder that picked up a name by mistake, such as a misrouted scratch write, is visible in the report rather than entering the payload silently. The legacy `.claude` root keeps a fixed allowlist instead, since that root also holds tracked `skills/`, `rules/`, and `hooks/` a push must never carry, and an exclusion set there would stage all three. Each name is a top-level record folder and every archive sits inside the one it archives, so the set stays at one entry per surface however many archives appear, and it deliberately does not match the six record kinds `validate` hardcodes.
 
-Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the nine folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
+Records are gitignored by design, so the history lives in a second git directory at `.records.git` inside the record root, with that root as its work tree. Both resolve off the root together rather than folder by folder, since a history opened at one root beside a work tree at the other would stage the deletion of every folder a move relocated. Every path stays where it is, which is what a separate checkout could not do. The verbs stage the backed folders by explicit pathspec with `--force`, so nothing outside them can enter the index however the ignore rules read, and the project working tree and its index are never touched. Each pathspec is a bare folder name and git reads it against the current directory rather than against the work tree the same call names, so the invocation carries `-C` at the work tree beside the other two flags. That is what lets either verb run from a linked worktree under `.claude/worktrees/`, which sits inside the records work tree and would otherwise prefix every name with its own path.
 
 ### Setup
 
@@ -196,7 +196,7 @@ Point it at a private repository, and at one that is not a remote of the project
 
 `split-roots` runs ahead of every gate below it and fires on a half-migrated tree, which is what a `canon migrate records` run that failed partway leaves. `recordRoot` answers for the whole tree on the first root that exists, so a folder left at the old root is absent from the work tree while the records index still names it, and an unguarded `add -A` would stage its deletion and drop it from the remote on the next push. Finish the move, or put the stranded folders back beside the others.
 
-The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding none of the ten has nothing to lose, so a restore onto a fresh checkout runs straight through.
+The two `pull` refusals exist because the directions are not symmetric. A push only adds, while a pull onto a machine holding work that never left it would discard that work. Resolve either by running `push` first, or by moving the local folders aside. A machine holding no backed folders has nothing to lose, so a restore onto a fresh checkout runs straight through.
 
 ### When it runs
 

package/docs/workflow/ai-workflow.md

@@ -105,7 +105,7 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `canon records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`canon records push` carries these folders off the disk they live on, and `canon records pull` brings them back. Nine of them are backed: `diagrams`, `groundwork`, `intake`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each carrying whatever it has archived inside it. The history lives in a second git directory at `.canon/.records.git` with `.canon/` as its work tree, so every path a task file cites stays where it is.
+`canon records push` carries these folders off the disk they live on, and `canon records pull` brings them back. Every top-level entry under `.canon/` is backed except `tmp`, `ordinal-locks`, and `.records.git`, so a folder added later enters the payload on its own rather than waiting on a name written into a list. Push names each folder it carries the first time it sees it, which is what keeps a stray folder visible instead of silently entering the payload. The history lives in a second git directory at `.canon/.records.git` with `.canon/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](../agents/records.md) for the refusal table.
 
@@ -242,6 +242,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
 | `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
 | `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |
+| `canon:ux-walkthrough`   | To run a multi-finding inspection pass over a running app with the operator             |
 
 ### Ship it
 

package/docs/workflow/visual-design-workflow.md

@@ -41,6 +41,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
 - Anthropic's `frontend-design` plugin optional for light visual steering
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.83.0",
+  "version": "4.85.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -138,6 +138,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Tell me the paint and layout cost of this page right now.',
     expect: 'ux-measure',
   },
+  {
+    prompt:
+      'Sit with me while I go through my whole list of app findings one at a time, and write down each pick with what it beat.',
+    expect: 'ux-walkthrough',
+  },
   {
     prompt:
       'I am building this branch for another session. What am I on the hook for, and what is off limits?',

package/src/commands/records.ts

@@ -1,7 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { BACKED_FOLDERS, pullRecords, pushRecords } from '@/records/backup'
+import { pullRecords, pushRecords } from '@/records/backup'
 import { migrateRecord } from '@/records/migrate'
 import {
   type ClaimOutcome,
@@ -14,7 +14,7 @@ import {
   type FolderSize,
   formatBytes,
   GROWTH_WINDOWS,
-  SIZED_FOLDERS,
+  sizedFolders,
   type SizeOutcome,
   sizeRecords,
 } from '@/records/size'
@@ -207,8 +207,9 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Folders read under .claude/:',
-        `  ${SIZED_FOLDERS.join(', ')}`,
+        'Folders read, at whichever record root the project carries:',
+        '  every folder canon records push carries, plus the scratch folder',
+        '  (deletable without loss, so a backup skips it, but a reading does not)',
         '',
         'Exit codes:',
         '  0  the reading completed',
@@ -274,8 +275,10 @@ function backupHelp(verb: 'push' | 'pull'): string {
 
   return [
     '',
-    'Backed folders under .claude/:',
-    `  ${BACKED_FOLDERS.join(', ')}`,
+    'Backed folders, at whichever record root the project carries:',
+    '  every top-level entry, less tmp, ordinal-locks, and .records.git',
+    '  (a legacy .claude root instead uses a fixed list; run this with --json',
+    '  to see what actually resolved, including any folder seen for the first time)',
     '',
     'Exit codes:',
     '  0  the records remote and this machine agree',
@@ -404,6 +407,9 @@ async function runPush(opts: BackupCommandOptions): Promise<number> {
   logInfo(
     `${outcome.folders.length} folder(s), ${outcome.changed} path(s) changed`,
   )
+  if (outcome.firstSeen.length > 0) {
+    logWarn(`first seen: ${outcome.firstSeen.join(', ')}`)
+  }
   logStep(outcome.pushed ? 'Pushed' : 'Nothing to push')
   logInfo(
     outcome.commit

package/src/design/tokens.ts

@@ -104,7 +104,7 @@ export const TOKENS: DesignTokens = {
   ].join('\n'),
 
   colorNote: [
-    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`. Two corrections landed with this record becoming the source. The light `muted` step moved from `#7A736A`, which read 4.38 and 4.09 against the two light grounds, and the dark `accent` moved off the `#C8602E` the slide theme carried, which read 4.36 and 3.99 against the two dark ones. Both now sit on the values below.',
+    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`.',
     '',
     'Warning and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes and no rendered surface implements an equivalent. Giving either a hex value would invent a mapping no file has, so they carry no contrast reading either.',
     '',
@@ -232,7 +232,7 @@ export const TOKENS: DesignTokens = {
   typographyNote: [
     'One family covers every role but `page-display`, which is the landing page hero and takes the proportional sibling of the same superfamily. The size scale runs from 11.5 to 52 pixels, and six values map onto a role. Five further values are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
     '',
-    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches. A hero headline set at the display cap reads as a section heading rather than an opening, which four rendered arms measured on 2026-09-04 before the step was added.',
+    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches, since a hero headline set at the display cap reads as an opening rather than as a section heading.',
     '',
     'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
     '',
@@ -353,8 +353,11 @@ export const TOKENS: DesignTokens = {
   motion:
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 
-  iconography:
-    "No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing. The same mark also ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift: `regen-hero.sh` derives one from the live SVG colored with whatever `--color-accent` (`#e0724b`) the fetched token CSS carries, `src/design/render.ts` carries the path data as a hardcoded literal colored via `colorValue('light-accent')` (`#a4471c`), since a data URI has no CSS context and that page renders on light chrome, and `teach-workspace`'s `SKILL.md` names one in prose colored `rgb(224,114,75)`, the same value as the dark accent written as decimal rather than hex to clear the shipped-references gate's commit-sha check. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for.",
+  iconography: [
+    'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
+    '',
+    'The same mark ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift, colored to fit the chrome each renders on: the dark accent (`#e0724b`) for a dark-chrome surface and the light accent (`#a4471c`) for a light-chrome one. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+  ].join('\n'),
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */

package/src/migrate/scratch-evidence.ts

@@ -26,7 +26,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import { BACKED_FOLDERS } from '@/records/backup'
+import { presentFolders } from '@/records/backup'
 import { recordDir, SCRATCH } from '@/record-root'
 
 /**
@@ -168,13 +168,13 @@ function applyRewrites(
   return { text: rewritten.join('\n'), count }
 }
 
-/** The files under every `BACKED_FOLDERS` entry, archives included. */
+/** The files under every present backed folder at `root`, archives included. */
 export async function walkScratchEvidenceCorpus(
   root: string,
 ): Promise<string[]> {
   const files: string[] = []
 
-  for (const folder of BACKED_FOLDERS) {
+  for (const folder of presentFolders(root)) {
     const dir = recordDir(root, folder)
     if (!existsSync(dir)) continue
 

package/src/record-root.ts

@@ -46,8 +46,9 @@ const CANON_SCRATCH = 'tmp'
 /**
  * Every entry that lives under the record root, at the name `.claude/` gave it.
  *
- * These are the twelve ignore patterns the move to `.canon/` collapsed into one,
- * so the list counts entries rather than record folders: `.records.git` is the
+ * These are the twelve ignore patterns the move to `.canon/` collapsed into
+ * one, plus every record folder added since, so the list counts entries
+ * rather than record folders: `.records.git` is the
  * backup history rather than a record, and `README.md` is a file a records pull
  * writes back. `worktrees` is absent because the harness creates a worktree
  * under `.claude/` and requires its target to sit there.
@@ -72,6 +73,8 @@ export const RECORD_ENTRIES: readonly string[] = [
   'review',
   'tasks',
   'teach',
+  'transcripts',
+  'walkthroughs',
 ]
 
 /** Whether a name under `.claude/` is one the record root owns. */

package/src/records/backup.ts

@@ -1,27 +1,25 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 import { RECORD_ROOTS, recordRoot } from '@/record-root'
 
 /**
- * The folders a backup carries, relative to the record root `workTree` resolves
- * rather than to either root specifically, since the same ten names sit under
- * whichever one a tree holds.
+ * The legacy `.claude`-root allowlist, read only when a project has not moved
+ * to `.canon/` yet.
  *
- * Nothing bounds this list any more, and the move is what took the bound away.
- * The claude manifest used to ship a folder apiece, so the `# Claude` group
- * named a superset this could be read against; it ships one `.canon/` root
- * entry now and names no folder at all. Spelling the list out is therefore the
- * whole of the protection rather than half of it, since a record folder added
- * under `.canon/` is ignored the moment it exists and enters no payload until
- * a name is written here.
+ * That root still tracks `skills/`, `rules/`, and `hooks/` a backup must never
+ * carry, so it cannot take the exclusion-based reading `foldersAt` applies at
+ * `.canon/`: every top-level entry there is fair game and an allowlist is the
+ * only thing separating a record folder from the vendor's own. A `.canon/` root
+ * carries no such mix, since nothing else lives there, which is what let the
+ * bound move from this list to `EXCLUDED_ENTRIES`.
  *
- * Three counts describe this surface and each is right about a different
- * question, so they are stated apart rather than reconciled. Ten is what a
- * disk loss would take, which is this list. Twelve is what sat under `.claude/`
- * as an ignored folder before the move, which adds the scratch folder that is
- * deletable without loss and `worktrees/`, whose contents belong to the
+ * Three counts describe what this list once bounded and each is right about a
+ * different question, so they are stated apart rather than reconciled. Eleven
+ * is what a disk loss would take, which is this list. Twelve is what sat under
+ * `.claude/` as an ignored folder before the move, which adds the scratch folder
+ * that is deletable without loss and `worktrees/`, whose contents belong to the
  * enclosing repository already. Thirteen is what the move relocated, which counts
  * ignore entries rather than folders: the twelve less `worktrees/`, which stayed,
  * plus `.records.git/` and the `README.md` a records pull writes back.
@@ -47,6 +45,7 @@ export const BACKED_FOLDERS = [
   'tasks',
   'teach',
   'transcripts',
+  'walkthroughs',
 ] as const
 
 /**
@@ -72,6 +71,53 @@ const RETIRED_FOLDERS = [
 /** The history directory's own name, which keeps its dot at either record root. */
 const RECORDS_GIT_NAME = '.records.git'
 
+/**
+ * Top-level `.canon/` entries a backup never carries, named rather than
+ * matched by pattern so a reader can see the whole exemption in one place.
+ *
+ * `tmp` is deletable without loss, per the scratch standard. `ordinal-locks`
+ * is transient per claim, and pushing one races the claim it guards.
+ * `.records.git` is the history itself, and reading directories rather than
+ * every entry already keeps a pull's `README.md` out, so this is the one name
+ * that still has to be said: without it a listing would stage the history
+ * into itself.
+ */
+export const EXCLUDED_ENTRIES = [
+  'tmp',
+  'ordinal-locks',
+  RECORDS_GIT_NAME,
+] as const
+
+/**
+ * The record folders sitting at `dir` right now, at either root spelling.
+ *
+ * A `.claude`-spelled directory reads the fixed allowlist, filtered to what
+ * exists, since that root also holds `skills/`, `rules/`, and `hooks/` no
+ * exclusion set names. A `.canon`-spelled directory reads its own top-level
+ * directories less `EXCLUDED_ENTRIES` instead, since nothing else shares that
+ * root and a folder added there is a record folder by construction.
+ *
+ * Takes a directory rather than a project root so `strandedFolders` can ask it
+ * about a candidate root other than the one `workTree` resolved.
+ */
+function foldersAt(dir: string): string[] {
+  if (basename(dir) === '.claude') {
+    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder)))
+  }
+
+  const entries = existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true })
+    : []
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter(
+      (name) =>
+        !EXCLUDED_ENTRIES.includes(name as (typeof EXCLUDED_ENTRIES)[number]),
+    )
+}
+
 /**
  * The tree a backup stages, which is the record root itself.
  *
@@ -166,6 +212,8 @@ export interface PushReport {
   readonly ok: true
   readonly root: string
   readonly folders: readonly string[]
+  /** A folder in scope this push found on disk but the records index had never tracked. */
+  readonly firstSeen: readonly string[]
   readonly changed: number
   readonly commit?: string
   readonly pushed: boolean
@@ -371,9 +419,10 @@ async function resolveRemote(
  * work tree hard and leaves the stranded copy beside it, which is not a loss but
  * is a tree where two roots disagree and neither is wrong.
  *
- * Only `BACKED_FOLDERS` is read. The scratch folder is deletable by definition
- * and `worktrees/` belongs to the enclosing repository, so neither stranded
- * anywhere costs a record.
+ * Reads `foldersAt` on each candidate, so a `.canon` candidate is checked
+ * against its own exclusion set rather than the `.claude` allowlist. The
+ * scratch folder is deletable by definition and `worktrees/` belongs to the
+ * enclosing repository, so neither stranded anywhere costs a record.
  */
 function strandedFolders(root: string): string[] {
   const resolved = resolve(workTree(root))
@@ -382,9 +431,7 @@ function strandedFolders(root: string): string[] {
     const dir = join(root, candidate)
     if (resolve(dir) === resolved) return []
 
-    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder))).map(
-      (folder) => join(candidate, folder),
-    )
+    return foldersAt(dir).map((folder) => join(candidate, folder))
   })
 }
 
@@ -403,9 +450,15 @@ function refuseSplitRoots(root: string): BackupRefused | undefined {
   )
 }
 
+/** A pathspec-safe subset, plus which of it never entered the records index before. */
+interface FolderScope {
+  readonly scope: readonly string[]
+  readonly firstSeen: readonly string[]
+}
+
 /**
- * The subset of the backed and retired names a pathspec can name: on disk, or
- * already in the records index.
+ * The subset of the present, retired, and previously-tracked names a pathspec
+ * can name.
  *
  * A pathspec matching neither fails the whole `add`, which is why the subset
  * exists. The index half is what covers a folder deleted in full. Reading disk
@@ -414,29 +467,64 @@ function refuseSplitRoots(root: string): BackupRefused | undefined {
  * every other unpushed deletion.
  *
  * The retired names are the same case one level up, where the folder left the
- * backed list rather than the disk, and the index is the only side that still
- * knows it existed.
+ * disk before the index caught up, and the index is the only side that still
+ * knows it existed. At a `.canon` root a folder can leave the same way under a
+ * name `RETIRED_FOLDERS` never anticipated, which is what folding the index
+ * into the candidate set (rather than only using it as a filter) covers.
+ *
+ * `firstSeen` is a folder in scope that disk carries but the index has never
+ * tracked, which is the read a caller reports rather than acts on: a folder
+ * `.canon` picked up that should have been excluded is visible in the push
+ * report instead of entering the payload silently.
  */
-async function scopedFolders(root: string): Promise<string[]> {
+async function scopedFolders(root: string): Promise<FolderScope> {
   const tracked = await records(root, ['ls-files'])
   const indexed = new Set(
     tracked.ok ? tracked.text.split('\n').filter(Boolean).map(topSegment) : [],
   )
 
-  return [...BACKED_FOLDERS, ...RETIRED_FOLDERS].filter(
+  const present = new Set(foldersAt(workTree(root)))
+  const retired = RETIRED_FOLDERS.filter(
     (folder) => existsSync(join(workTree(root), folder)) || indexed.has(folder),
   )
+  const scope = [...new Set([...present, ...retired, ...indexed])].sort()
+  const firstSeen = scope.filter(
+    (folder) => present.has(folder) && !indexed.has(folder),
+  )
+
+  return { scope, firstSeen }
 }
 
 function topSegment(path: string): string {
   return path.split('/')[0]
 }
 
-/** What a report names, which is the folders a reader can go and open. */
-function presentFolders(root: string): string[] {
-  return BACKED_FOLDERS.filter((folder) =>
-    existsSync(join(workTree(root), folder)),
-  )
+/**
+ * What a report names, which is the folders a reader can go and open.
+ *
+ * Exported so the scratch-evidence walk and the push and pull help text read
+ * the same resolved set rather than each re-deriving it against
+ * `BACKED_FOLDERS`, which is silently wrong at a `.canon` root.
+ */
+export function presentFolders(root: string): string[] {
+  return foldersAt(workTree(root))
+}
+
+/**
+ * The record folder names a project could ever carry, without regard to
+ * whether each currently exists: `BACKED_FOLDERS` at the legacy `.claude`
+ * root, since nothing else names a folder there, and the live directory
+ * listing at `.canon`, since nothing bounds that root's names from outside
+ * any more and a name nobody has created yet cannot be listed.
+ *
+ * Exported for `canon records size`, whose own contract reports every folder
+ * whether or not it exists so a caller reading the record gets a stable set
+ * of keys. `presentFolders` filters by existence instead, which is right for
+ * a push report naming what a reader can go and open and wrong here.
+ */
+export function candidateFolders(root: string): string[] {
+  const tree = workTree(root)
+  return basename(tree) === '.claude' ? [...BACKED_FOLDERS] : foldersAt(tree)
 }
 
 function countLines(text: string): number {
@@ -458,7 +546,7 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const remote = await resolveRemote(root, enclosing)
   if (typeof remote !== 'string') return remote
 
-  const scope = await scopedFolders(root)
+  const { scope, firstSeen } = await scopedFolders(root)
 
   if (scope.length > 0) {
     // `-f` is what carries the payload: every backed folder is ignored by the
@@ -494,7 +582,7 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   const folders = presentFolders(root)
   const head = await records(root, ['rev-parse', '--short', 'HEAD'])
   if (!head.ok) {
-    return { ok: true, root, folders, changed, pushed: false }
+    return { ok: true, root, folders, firstSeen, changed, pushed: false }
   }
 
   const branch = await projectBranch(root, enclosing)
@@ -505,7 +593,15 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
   ])
   if (!pushed.ok) return failed('push', pushed)
 
-  return { ok: true, root, folders, changed, commit: head.text, pushed: true }
+  return {
+    ok: true,
+    root,
+    folders,
+    firstSeen,
+    changed,
+    commit: head.text,
+    pushed: true,
+  }
 }
 
 /**
@@ -556,7 +652,7 @@ export async function pullRecords(root: string): Promise<PullOutcome> {
   const target = await records(root, ['rev-parse', 'FETCH_HEAD'])
   if (!target.ok) return failed('rev-parse', target)
 
-  const scope = await scopedFolders(root)
+  const { scope } = await scopedFolders(root)
 
   if (scope.length > 0) {
     const dirty = await records(root, ['status', '--porcelain', '--', ...scope])

package/src/records/size.ts

@@ -2,20 +2,24 @@ import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
-import { BACKED_FOLDERS } from '@/records/backup'
+import { candidateFolders } from '@/records/backup'
 
 /**
- * The folders a size reading covers, named at the record root they sit under.
+ * The folders a size reading covers at `root`, resolved the same way a push
+ * resolves its scope rather than pinned to `BACKED_FOLDERS`, which is silently
+ * wrong at a `.canon` root.
  *
- * It is the backed set plus the scratch folder, which a backup skips because it is
- * deletable without loss and a reading covers because deletable is not the same
- * as empty: the routing handoffs and the memory archive both sit there and both
- * accumulate. `.records.git` stays out because it is the backup history rather
- * than a record, and `worktrees/` stays out because each entry there is a
- * checkout of the enclosing repository with its own removal verb, and one of
- * them outweighs every record folder combined.
+ * It is the present backed set plus the scratch folder, which a backup skips
+ * because it is deletable without loss and a reading covers because deletable
+ * is not the same as empty: the routing handoffs and the memory archive both
+ * sit there and both accumulate. `.records.git` stays out because it is the
+ * backup history rather than a record, and `worktrees/` stays out because each
+ * entry there is a checkout of the enclosing repository with its own removal
+ * verb, and one of them outweighs every record folder combined.
  */
-export const SIZED_FOLDERS = [...BACKED_FOLDERS, SCRATCH] as const
+export function sizedFolders(root: string): string[] {
+  return [...candidateFolders(root), SCRATCH]
+}
 
 /**
  * The windows a reading reports, in days.
@@ -227,9 +231,9 @@ export async function sizeRecords(
 
   // Each folder is walked independently, and the report is ordered by the
   // caller rather than by arrival, so `Promise.all` keeps the input order while
-  // the ten walks overlap.
+  // the walks overlap.
   const folders = await Promise.all(
-    SIZED_FOLDERS.map((folder) => measure(root, folder, now)),
+    sizedFolders(root).map((folder) => measure(root, folder, now)),
   )
 
   return {

package/standards/skill.md

@@ -210,7 +210,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, or `teach/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.