@erclx/canon 4.87.0 → 4.88.1

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

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

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

@@ -121,7 +121,7 @@ The verb ships with the CLI and this body ships with the plugin, matching Step 6
 
 If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `canon:ui-test`.
 
-If `ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .canon/tmp/ui-checklist/<slug>.md, which reaches the pull request once /git-ship runs. Verify manually, then run /git-ship.`
+If `ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .canon/tmp/handoff/ui-checklist/<slug>.md, which reaches the pull request once /git-ship runs. Verify manually, then run /git-ship.`
 
 If all UI changes are covered by e2e tests, continue.
 

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

@@ -149,7 +149,7 @@ Read `canon/context/index.md` at `pwd` to see which domain entries exist. Skip t
 
 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 `.canon/tmp/memory-routing/<slug>.md` at the main worktree root. `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, which for a nested `canon/context/<domain>/index.md` heading is the sibling file the fact belongs under rather than the generated index itself. Then delete the handoff file so a later run does not fold it twice.
+**Routed facts.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/handoff/memory-routing/<slug>.md` at the main worktree root. `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, which for a nested `canon/context/<domain>/index.md` heading is the sibling file the fact belongs under rather than the generated index itself. 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.
 
@@ -183,13 +183,13 @@ Write each updated entry immediately. Output one line per file, naming the path
 
 Add a line naming the handoff when one was consumed:
 
-`🧹 Folded: .canon/tmp/memory-routing/<slug>.md`
+`🧹 Folded: .canon/tmp/handoff/memory-routing/<slug>.md`
 
 The base lint-staged config runs `canon indexes regen` on every committed `*.md`, so `canon/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 `.canon/tmp/teach-promotion/<slug>.md` at the main worktree root. `teach-workspace` 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.
+Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`, falling back to `latest` on an empty result, and read `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root. `teach-workspace` 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:
 
@@ -204,7 +204,7 @@ Output one line per page landed:
 
 Add a line naming the handoff when one was consumed:
 
-`🧹 Folded: .canon/tmp/teach-promotion/<slug>.md`
+`🧹 Folded: .canon/tmp/handoff/teach-promotion/<slug>.md`
 
 Report a block left unfolded rather than dropping it:
 

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

@@ -20,12 +20,21 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Reads a color without compositing its alpha, samples a round control at the corner of its bounding box, or confirms a panel's dimensions while it sits above the viewport. Each reads as a passing measurement about something no reader sees.
 - Meets a machine with no browser binary and reports on the arms anyway, since nothing in the default flow separates a render that failed from one that was never attempted.
 - Hand-writes a mockup of a surface a running app already serves, which drifts from what ships by a few pixels and a few words the moment the app's own markup or stylesheet moves on.
+- Varies a property the decision is not about, which satisfies the one-property rule and produces a set differing in the layer a reader notices least. Five palettes over one identical page read as five skins of one design, and the operator rejected the whole set on sight.
+- Renders each arm in whatever theme it happens to carry, so a set spanning both themes cannot be compared without the operator toggling every arm and holding the earlier ones in memory.
+- Looks at a render to confirm it came out rather than to judge whether it is worth showing, which satisfies the rule against reporting an unseen result and still hands over weak work.
+- Writes the run's renders to a scratch path outside the record that cites them, leaving the folder holding source markup and none of the images, so the judgment is unreachable to everyone except the session that made it.
+- Narrows the page onto the picked arm in place on each iteration, so every earlier round is overwritten and a later pass cannot see what was already rejected.
 
 ## Must
 
 - Produce three to five arms with the shipping state among them, each carrying an id, a label, and what the arm costs.
 - Author the whole candidate set as one self-contained page and render it once, so the comparison arrives as one image, except where the surface under decision is a running app: there the page links a copy of the built stylesheet rather than inlining it, per `references/live-arms.md`.
-- Vary one property across the arms, so the answer names a difference.
+- Name the layer the decision lives at before drafting, and vary the arms at that layer alone, so the answer names the difference that decided it rather than the cheapest one to change.
+- Render every arm in one theme at a time, with a control that sets the whole set, so the comparison holds still while the operator reads it.
+- Judge each render against a stated bar before handing it over, name the weakest thing on the page, and fix it where that sentence would embarrass the work.
+- Write each iteration to its own folder rather than narrowing the previous one in place, so every earlier round stays openable.
+- Write the run's renders inside the record that cites them wherever one exists, and reserve the scratch path for inputs that are re-runnable and cited by nothing.
 - Render before reporting on any arm, and report a missing browser binary as a refusal naming the repair rather than describing an arm nobody has seen.
 - Take the pick through the structured question surface, with the recommendation ranked first and marked, and every option carrying its cost.
 - Keep every write inside the run's scratch folder until the pick is final.

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

@@ -15,7 +15,7 @@ Some decisions are settled by looking rather than by reasoning, and no draft is
 
 ## Step 1: name the decision and the arms
 
-1. State the decision in one sentence, naming what changes between arms and what stays fixed.
+1. State the decision in one sentence, naming what changes between arms and what stays fixed. Name the layer that sentence puts the decision at, and check that the arms will differ there rather than somewhere cheaper to change.
 2. Derive a kebab slug from that sentence. Call the folder every file this run writes to `<dest>` below. `<dest>` is `.canon/tmp/<slug>/`, a nested `<slug>/` folder rather than a flat `<slug>-<file>.md`, which is the shape every temporary write in this project takes. Running inside a live `plan-groundwork` track is the one exception: `<dest>` is the track's own `evidence/<slug>/` instead, since a candidate render is evidence the track's decision file cites rather than spike input.
 3. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
 4. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
@@ -28,10 +28,12 @@ Write every arm side by side on one self-contained HTML page at `<dest>/candidat
 - One page for the pick, never a set of separate images handed to the operator to compare from memory. The comparison they judge is `candidates.html`, which Step 3 renders and Step 4 asks about. The per-arm files exist only for Step 6's archival capture, once the pick is made, and only the last pass through this step is what Step 6 finds there.
 - Wrap each arm's markup in the same class on both files, chosen once per run and reused everywhere, so one selector addresses an arm on the combined page and on its own standalone file alike.
 - Label each arm on the page with its id and its cost, so the render carries what the question will ask about.
+- Give the combined page one control that sets every arm's theme at once, beside whatever per-arm control the arms carry. A set spanning both themes cannot be compared, since the operator has to toggle each arm and hold the earlier ones in memory, which is the failure the single-page rule exists to prevent.
 - Take the live-app branch instead when the surface under decision is a running app: lift the rendered markup and link a copy of the built stylesheet rather than inlining, per `${CLAUDE_SKILL_DIR}/references/live-arms.md`.
 - On the default path, inline every style, script, and asset the page needs. The render reads the file off disk, so a page reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
 - On the default path, declare a font stack the machine resolves, such as `system-ui` behind a generic fallback. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
 - Vary one property across the arms. A page whose arms differ in three ways answers no question, since the pick cannot say which difference decided it.
+- Vary the property the decision is about, which the rule above is satisfiable without. Holding composition fixed and varying color obeys it exactly and produces five skins of one design, because a set differing in the layer a reader notices least answers nothing. A palette is chosen to serve a composition, so it cannot be picked ahead of one.
 
 ## Step 3: render and hand off
 
@@ -44,8 +46,10 @@ canon capture <dest>/candidates.html --selector <element>
 - `--selector` has no default and the command refuses without it. Name the element wrapping the arms rather than `body`, which crops to whatever the page's own margins leave.
 - `canon capture` and `canon drive` both need a browser binary the toolkit does not install. When either refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, then stop rather than describing an arm nobody has seen.
 - Serve the page instead of capturing it when the operator has to drive the decision, such as a hover response, a scroll-linked position, or a pace. Start `canon serve <dest> --entry candidates.html` in the background and read the link off its record, since the printed link opens `index.html` without that flag and `<dest>` holds no such file. A still answers how a thing looks and answers none of those.
+- Write the render inside the record that cites it wherever one exists, by pointing `--out` at `<dest>/renders/` rather than at a session scratch path. A pick taken from an image the record does not hold is a judgment nobody but this session can check, and the archival capture in Step 6 covers the final round alone.
 - Hand over the address rather than a description. Emit the PNG path on its own line, and the link beside it where the page is served.
 - Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
+- Look to judge rather than to confirm. Reading the image back to check it rendered satisfies the rule above and still hands over weak work, so name the weakest thing on the page in a sentence. Where that sentence would embarrass the work, fix it and hand over the second version. Say the remaining weakness out loud either way, so the operator is not hunting for what you already know.
 
 ## Step 4: take the pick
 
@@ -58,11 +62,11 @@ Put the choice to the operator through the structured question surface, since a
 
 ## Step 5: loop on the pick
 
-1. Narrow the page to the picked arm, plus whatever the operator asked to change about it.
+1. Write each iteration to its own `<dest>` rather than narrowing the previous one in place, suffixing the slug so the folders sort. An iteration overwritten is one a later pass cannot open, and the losing round is what stops a correction re-proposing something already rejected.
 2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm where it does not.
 3. Re-render, hand off again, and take the next answer.
 4. Repeat until the operator says it is right. The loop stops on their word and on nothing else, so a run stopping because the arms stopped differing has stopped early.
-5. Hold the real surface untouched across every iteration. Nothing outside `<dest>` changes until the pick is final.
+5. Hold the real surface untouched across every iteration. Nothing outside the run's own folders changes until the pick is final.
 
 ## Step 6: close
 

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

@@ -31,7 +31,7 @@ A missing tracking ref is no longer a guard. An open pull request proves the bra
 
 5. Post the evidence comparison, on every invocation including `reply-owned`, since this comment is not the reply step 8 owns. Run `canon pr evidence <number> --json`, resolving `<number>` from `gh pr view --json number`, and read `reason` on the record rather than the exit code.
    - `no-evidence`: nothing changed under an `evidence/` segment this push. Say nothing and move on.
-   - `ok`: write `body` to `.canon/tmp/pr-evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr-evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr-evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
+   - `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post the comment with `gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md` when the record carries no `commentId`, or edit the existing one in place with `gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md` when it does. Clean up the tmp file only after the call reports success.
    - Any other reason is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and continue without stopping the chain.
 6. Check for existing review comments: `gh api 'repos/{owner}/{repo}/pulls/<number>/comments' --jq 'length'`, resolving `<number>` from `gh pr view --json number`.
 7. Sync the body and title on every invocation, before the routing below decides on the reply.

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

@@ -148,18 +148,18 @@ if [ -n "$pr_labels" ]; then
   gh pr edit "$pr_number" --add-label "$pr_labels" >/dev/null ||
     printf 'Label apply failed. Create a missing label with: gh label create <name>\n' >&2
 fi
-rm -rf .canon/tmp/pr
+rm -rf .canon/tmp/pr/body
 printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
 ```
 
 ### Post the UI checklist
 
-`ui-test` writes a manual checklist to `.canon/tmp/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This step is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and there is nothing to post.
+`ui-test` writes a manual checklist to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root when a change needs visual verification, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This step is the file's sole consumer. Resolve the main root the way `session-worktree` does (`git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`) and check for the file there. A missing file means no checklist was produced, and there is nothing to post.
 
 When it exists, scan it against `${CLAUDE_SKILL_DIR}/../../standards/publish.md` before posting, the same as the pull request body above. Post it as its own comment on `<number>`, the number the final command above resolved, rather than folding it into the body, since a later push editing the body would overwrite checkboxes a reviewer already ticked:
 
 ```bash
-gh pr comment <number> --body-file <main-root>/.canon/tmp/ui-checklist/<slug>.md
+gh pr comment <number> --body-file <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
 ```
 
 Run the cleanup below only once that call reports success. On a failure, stop and leave the file in place: a retry needs the checklist to still be there, and deleting it on a failed post loses the only copy with nothing landed on the pull request.
@@ -167,11 +167,11 @@ Run the cleanup below only once that call reports success. On a failure, stop an
 From a linked worktree the file-editing tools refuse a main-root path, so the cleanup goes out through `Bash` as two plain commands, the file and then the folder, rather than joined by `&&`, which is refused as compound:
 
 ```bash
-rm <main-root>/.canon/tmp/ui-checklist/<slug>.md
+rm <main-root>/.canon/tmp/handoff/ui-checklist/<slug>.md
 ```
 
 ```bash
-rmdir <main-root>/.canon/tmp/ui-checklist 2>/dev/null || true
+rmdir <main-root>/.canon/tmp/handoff/ui-checklist 2>/dev/null || true
 ```
 
 The `rmdir` is a no-op when another branch's pending checklist still sits in the folder, which keeps this step from deleting a handoff that is not its own.
@@ -181,16 +181,16 @@ The `rmdir` is a no-op when another branch's pending checklist still sits in the
 Run `canon pr evidence <number> --json` against the number the pull request step above resolved. Read `reason` on the record rather than the exit code.
 
 - `no-evidence`: nothing changed under an `evidence/` segment. Say nothing and move on.
-- `ok`: write `body` to `.canon/tmp/pr-evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post or update the comment:
+- `ok`: write `body` to `.canon/tmp/pr/evidence/body-<number>.md` at the main worktree root (resolved the way `session-worktree` does), then post or update the comment:
 
 ```bash
-gh pr comment <number> --body-file <main-root>/.canon/tmp/pr-evidence/body-<number>.md
+gh pr comment <number> --body-file <main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
 When the record carries a `commentId`, edit that comment in place instead of posting a second one, reading the body field from the tmp file with `@`:
 
 ```bash
-gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr-evidence/body-<number>.md
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/<commentId> -f body=@<main-root>/.canon/tmp/pr/evidence/body-<number>.md
 ```
 
 Clean up the tmp file the way the UI-checklist step does, only after the call reports success.

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

@@ -80,25 +80,25 @@ For independent mode, base every branch on `main`:
 git branch -m <current_branch> <new_name>
 
 # Create, cherry-pick, push, and open PR for each secondary branch
-mkdir -p .canon/tmp/pr-split
+mkdir -p .canon/tmp/pr/split
 git switch -c <branch> main && git cherry-pick <sha> <sha> \
   && git push -u origin <branch> \
-  && (cat <<'BODY' > .canon/tmp/pr-split/<branch>.md
+  && (cat <<'BODY' > .canon/tmp/pr/split/<branch>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch>.md \
-  && rm .canon/tmp/pr-split/<branch>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr/split/<branch>.md \
+  && rm .canon/tmp/pr/split/<branch>.md
 
 # Return to primary branch, push, and open its PR
 git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .canon/tmp/pr-split/<new_name>.md
+  && (cat <<'BODY' > .canon/tmp/pr/split/<new_name>.md
 <body following pr.md template, written from the primary's commits>
 BODY
-) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<new_name>.md \
-  && rm .canon/tmp/pr-split/<new_name>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr/split/<new_name>.md \
+  && rm .canon/tmp/pr/split/<new_name>.md
 
 # Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .canon/tmp/pr-split 2>/dev/null || true
+rmdir .canon/tmp/pr/split 2>/dev/null || true
 ```
 
 For stacked mode, base each branch on the previous and cherry-pick only that group's commits:
@@ -107,36 +107,36 @@ For stacked mode, base each branch on the previous and cherry-pick only that gro
 # Rename current branch to reflect primary concern
 git branch -m <current_branch> <new_name>
 
-mkdir -p .canon/tmp/pr-split
+mkdir -p .canon/tmp/pr/split
 
 # Group 1: based on main
 git switch -c <branch-1> main && git cherry-pick <g1-sha> <g1-sha> \
   && git push -u origin <branch-1> \
-  && (cat <<'BODY' > .canon/tmp/pr-split/<branch-1>.md
+  && (cat <<'BODY' > .canon/tmp/pr/split/<branch-1>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch-1>.md \
-  && rm .canon/tmp/pr-split/<branch-1>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr/split/<branch-1>.md \
+  && rm .canon/tmp/pr/split/<branch-1>.md
 
 # Group 2: based on <branch-1>, this group's commits only
 git checkout -b <branch-2> && git cherry-pick <g2-sha> <g2-sha> \
   && git push -u origin <branch-2> \
-  && (cat <<'BODY' > .canon/tmp/pr-split/<branch-2>.md
+  && (cat <<'BODY' > .canon/tmp/pr/split/<branch-2>.md
 <body following pr.md template, written from the cherry-picked commits>
 BODY
-) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<branch-2>.md \
-  && rm .canon/tmp/pr-split/<branch-2>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr/split/<branch-2>.md \
+  && rm .canon/tmp/pr/split/<branch-2>.md
 
 # Return to primary branch, push, and open its PR
 git checkout <new_name> && git push -u origin <new_name> \
-  && (cat <<'BODY' > .canon/tmp/pr-split/<new_name>.md
+  && (cat <<'BODY' > .canon/tmp/pr/split/<new_name>.md
 <body following pr.md template, written from the primary's commits>
 BODY
-) && gh pr create --title "<title>" --body-file .canon/tmp/pr-split/<new_name>.md \
-  && rm .canon/tmp/pr-split/<new_name>.md
+) && gh pr create --title "<title>" --body-file .canon/tmp/pr/split/<new_name>.md \
+  && rm .canon/tmp/pr/split/<new_name>.md
 
 # Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
-rmdir .canon/tmp/pr-split 2>/dev/null || true
+rmdir .canon/tmp/pr/split 2>/dev/null || true
 ```
 
 ## After execution

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

@@ -44,7 +44,7 @@ For each project candidate, match its subject against `canon/context/index.md`.
 
 Fail closed. A project candidate matching no entry stays a memory file, and so does one matching two entries where neither is clearly the owner. The residue is what the folder is for, and a fact filed under the wrong entry is worse than one in memory because a context entry is a surface sessions trust.
 
-Do not edit a context entry here. `docs-fold` owns those edits and folds the routed facts in on its own pass, or two skills write one file at the same step. Write each routed fact to `.canon/tmp/memory-routing/<slug>.md` at the main worktree root instead, appending when the file exists. Name the heading with the entry's own path from `canon/context/index.md`, flat or the nested `index.md`, since that heading is what tells `docs-fold`'s routed-facts fold which file to open. An append is a whole-file operation the shell does directly, so send it as a plain single `Bash` command carrying a heredoc:
+Do not edit a context entry here. `docs-fold` owns those edits and folds the routed facts in on its own pass, or two skills write one file at the same step. Write each routed fact to `.canon/tmp/handoff/memory-routing/<slug>.md` at the main worktree root instead, appending when the file exists. Name the heading with the entry's own path from `canon/context/index.md`, flat or the nested `index.md`, since that heading is what tells `docs-fold`'s routed-facts fold which file to open. An append is a whole-file operation the shell does directly, so send it as a plain single `Bash` command carrying a heredoc:
 
 A flat domain takes:
 
@@ -96,7 +96,7 @@ Respond with one line per fact routed, written, or updated:
 
 When anything routed, add a line naming the handoff so the caller knows a `docs-fold` pass is owed:
 
-`→ Routed facts wait at .canon/tmp/memory-routing/<slug>.md. Run /docs-fold to fold them in.`
+`→ Routed facts wait at .canon/tmp/handoff/memory-routing/<slug>.md. Run /docs-fold to fold them in.`
 
 Omit that line when the caller runs `docs-fold` itself later in its own chain.
 

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

@@ -68,7 +68,7 @@ For each in-scope entry (see Scope), pick one action:
   - 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. 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.
+- **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/handoff/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/`.
@@ -153,7 +153,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. 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.
+- **Promote to a context entry**: append the fact to `.canon/tmp/handoff/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/plan-groundwork/SKILL.md

@@ -21,7 +21,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 
 - Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
 - One exception, at close only: write one task file recording what the track concluded.
-- A second exception, for what a spike reads: write an input under `.canon/tmp/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- A second exception, for what a spike reads: write an input under `.canon/tmp/runs/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
 - What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - A `draft-and-pick` run invoked from inside a live track follows its own branch for this, writing to `evidence/` here rather than `.canon/tmp/<slug>/`.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.

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

@@ -99,7 +99,7 @@ moved, which the earlier test could not see. Rebase again under
 continue. The second push costs one extra force-push in a
 case that needs the fix and the sibling to touch the same lines.
 
-Then write a summary reply to `.canon/tmp/address-review/reply-<number>.md`
+Then write a summary reply to `.canon/tmp/pr/reply/reply-<number>.md`
 mapping each finding to what changed, or to a one-line reason when it is a
 conscious-accept rather than a defect. Key the filename on the PR number so two
 sessions addressing different pull requests never overwrite each other between
@@ -154,7 +154,7 @@ Before posting, follow `${CLAUDE_SKILL_DIR}/../../standards/publish.md`
 and run its scan against the reply:
 
 ```bash
-canon labels scan --body-file .canon/tmp/address-review/reply-<number>.md
+canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md
 ```
 
 The hook skips `.canon/tmp/`, so this scan is the only gate on the published
@@ -163,8 +163,8 @@ capture the posted comment's id, since Step 7 edits this exact comment rather
 than trusting whichever one `gh` considers last:
 
 ```bash
-comment_url=$(gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md)
-echo "${comment_url##*issuecomment-}" > .canon/tmp/address-review/reply-<number>.id
+comment_url=$(gh pr comment <number> --body-file .canon/tmp/pr/reply/reply-<number>.md)
+echo "${comment_url##*issuecomment-}" > .canon/tmp/pr/reply/reply-<number>.id
 ```
 
 ## Step 7: confirm resolution
@@ -176,7 +176,7 @@ the closing confirmation to the reply file Step 6 already posted, so the thread
 carries one terminal state rather than a second comment under no heading:
 
 ```bash
-printf '\n✅ All review findings addressed, CI green.\n' >> .canon/tmp/address-review/reply-<number>.md
+printf '\n✅ All review findings addressed, CI green.\n' >> .canon/tmp/pr/reply/reply-<number>.md
 ```
 
 A rebase-only run addressed no finding, so it appends its own confirmation
@@ -184,14 +184,14 @@ instead of that one. Claiming findings were addressed on a pull request that
 carries none is false on a surface nothing else checks:
 
 ```bash
-printf '\n✅ Rebased onto origin/main, CI green. No review findings were open.\n' >> .canon/tmp/address-review/reply-<number>.md
+printf '\n✅ Rebased onto origin/main, CI green. No review findings were open.\n' >> .canon/tmp/pr/reply/reply-<number>.md
 ```
 
 Re-run the scan against the updated file, since the appended line is new
 content the Step 6 scan never saw:
 
 ```bash
-canon labels scan --body-file .canon/tmp/address-review/reply-<number>.md
+canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md
 ```
 
 Then edit the exact comment Step 6 posted, read back from the id it saved,
@@ -201,12 +201,12 @@ so read the id as its own plain command and write the printed value as a
 literal in the `gh api` call rather than a substitution or a variable:
 
 ```bash
-cat .canon/tmp/address-review/reply-<number>.id
+cat .canon/tmp/pr/reply/reply-<number>.id
 ```
 
 ```bash
 gh api -X PATCH "repos/{owner}/{repo}/issues/comments/<id printed above>" \
-  -F body=@.canon/tmp/address-review/reply-<number>.md
+  -F body=@.canon/tmp/pr/reply/reply-<number>.md
 ```
 
 `--edit-last` was the first shape and it targets the wrong object here.
@@ -243,10 +243,10 @@ Do not merge. Hand back to the orchestrator for re-review.
 
 ## Post-review findings
 
-Not everything worth reaching the reviewing session surfaces inside the numbered flow above. A worker that settled a risk, filed a follow-up, or found something else worth reporting after Step 7 already closed the review posts it directly rather than waiting on a review pass that has nothing left to trigger it. Write the body the way Step 6 writes a reply: load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` for the banned words, and run the `${CLAUDE_SKILL_DIR}/../../standards/publish.md` scan before posting with `canon labels scan --body-file .canon/tmp/address-review/reply-<number>.md`.
+Not everything worth reaching the reviewing session surfaces inside the numbered flow above. A worker that settled a risk, filed a follow-up, or found something else worth reporting after Step 7 already closed the review posts it directly rather than waiting on a review pass that has nothing left to trigger it. Write the body the way Step 6 writes a reply: load `write-human` for voice, follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` for the banned words, and run the `${CLAUDE_SKILL_DIR}/../../standards/publish.md` scan before posting with `canon labels scan --body-file .canon/tmp/pr/reply/reply-<number>.md`.
 
 Open with `## Post-review findings` rather than `## Review response`, since nothing on the thread is being answered. `review-pr` states the full heading set this belongs to and routes it the same as a response: `role-orchestrator`'s poll picks it up and sends the reviewing session back for a pass. Close the body with `🤖 Addressed by Claude Code` on its own line, matching the reply's footer.
 
 ```bash
-gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md
+gh pr comment <number> --body-file .canon/tmp/pr/reply/reply-<number>.md
 ```

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

@@ -165,7 +165,7 @@ Use severity: `critical` (blocks merge), `should-fix` (fix before merge), `minor
 
 ## Step 4: post to the PR
 
-Write the comment to `.canon/tmp/pr-review/body-<number>-<short-sha>.md` at the main worktree root, not the current worktree, which the rest of this step calls `<body-file>`. Resolve that root the way `session-worktree` does, and send the write as a plain single `Bash` command carrying a heredoc from a linked worktree, since `Edit` and `Write` refuse a main-root path there. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post, and the head commit stops a second pass overwriting the first one's body, leaving the folder a record of which commit each review covered.
+Write the comment to `.canon/tmp/pr/review/body-<number>-<short-sha>.md` at the main worktree root, not the current worktree, which the rest of this step calls `<body-file>`. Resolve that root the way `session-worktree` does, and send the write as a plain single `Bash` command carrying a heredoc from a linked worktree, since `Edit` and `Write` refuse a main-root path there. The PR number stops two sessions reviewing different pull requests from overwriting each other between the write and the post, and the head commit stops a second pass overwriting the first one's body.
 
 Derive both segments from Step 1. Never pick a suffix by hand, and never reuse a name the folder already holds.
 
@@ -279,7 +279,7 @@ Before posting, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md`
 Do not run the command below when `<prior-heading>` from Step 2 reads `## Review closed` and this pass carries nothing owed. That pass replaces the standing comment rather than adding one, under `### A close-out that repeats the standing one` at the end of this step. Posting first and reaching that section afterward leaves two close-outs both naming the new head, which is worse than the pair the guard exists against.
 
 ```bash
-gh pr review <number> --comment --body-file .canon/tmp/pr-review/body-<number>-<short-sha>.md
+gh pr review <number> --comment --body-file .canon/tmp/pr/review/body-<number>-<short-sha>.md
 ```
 
 A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and the board.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`

package/claude/skills/role-orchestrator/references/orchestrator-poll.md

@@ -54,7 +54,7 @@ Every classification line names a pull request and a state. A line starting `pol
 
 The script exits non-zero and classifies nothing when the open pull request list itself fails to load. That case would otherwise report every tracked pull request as merged, so the baseline is left untouched and the run says so.
 
-The baseline lives at `.canon/tmp/pr-poll/baseline.txt` under the main worktree root and is per-machine. A first run against a board already in flight reports each open pull request once before it settles.
+The baseline lives at `.canon/tmp/pr/poll/baseline.txt` under the main worktree root and is per-machine. A first run against a board already in flight reports each open pull request once before it settles.
 
 The five review headings the script matches are written by `review-pr` and `review-address`, and the whole set is stated once in the first. The reply family is matched by jq filters in the script, so a project posting its replies under different headings edits those to match. The review family is matched inside `canon pr review-state` instead, which the script and `review-pr` both read through, so a project renaming either review heading changes the verb rather than the script. Either way, a heading nothing matches reads as a pull request nobody has reviewed.
 

package/claude/skills/role-orchestrator/scripts/poll.sh

@@ -18,7 +18,7 @@ if [ -z "$MAIN_ROOT" ]; then
   echo "poll: not a git repository, so nothing is classified" >&2
   exit 1
 fi
-STATE_DIR="$MAIN_ROOT/.canon/tmp/pr-poll"
+STATE_DIR="$MAIN_ROOT/.canon/tmp/pr/poll"
 mkdir -p "$STATE_DIR"
 STATE="$STATE_DIR/baseline.txt"
 touch "$STATE"

package/claude/skills/teach-workspace/SKILL.md

@@ -217,7 +217,7 @@ Still owed:    <what the destination expects that the page does not carry yet>
 
 Then stop and let the operator strike, redirect, or confirm each block.
 
-Write nothing to a destination here. One skill owns the durable writes, and two skills editing one file at one step is the failure that rule exists against. Record each confirmed block in `.canon/tmp/teach-promotion/<slug>.md` at the main worktree root instead, appending when the file exists, with one H2 per destination naming its path, the source page beneath it, and the page body fenced:
+Write nothing to a destination here. One skill owns the durable writes, and two skills editing one file at one step is the failure that rule exists against. Record each confirmed block in `.canon/tmp/handoff/teach-promotion/<slug>.md` at the main worktree root instead, appending when the file exists, with one H2 per destination naming its path, the source page beneath it, and the page body fenced:
 
 ````markdown
 ## <destination path>
@@ -258,7 +258,7 @@ A promotion pass reports its own shape instead, one line per page the operator c
 
 ```plaintext
 ➡️ Promoting: .canon/teach/<nn>-<topic>/reference/<slug>.md → <destination path>
-→ Confirmed pages wait at .canon/tmp/teach-promotion/<slug>.md. Run /docs-fold from a branch to fold them in.
+→ Confirmed pages wait at .canon/tmp/handoff/teach-promotion/<slug>.md. Run /docs-fold from a branch to fold them in.
 ```
 
 A pass where the operator confirmed nothing writes no handoff file and reports that alone.

package/claude/skills/ui-test/REQUIREMENT.md

@@ -19,7 +19,7 @@ Writing the checklist correctly to disk does not close the gap either. The file
 - Read the project's existing test config and patterns before writing a test against them
 - Assert a user action and its outcome per test, covering the happy path and the key edge cases
 - Run the tests after writing them and fix what fails
-- Write a produced checklist to the `.canon/tmp/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting
+- Write a produced checklist to the `.canon/tmp/handoff/ui-checklist/<slug>.md` handoff at the main worktree root, overwriting
 - Report that everything is covered rather than manufacturing a checklist to show work
 
 ## Must not

package/claude/skills/ui-test/SKILL.md

@@ -59,7 +59,7 @@ If all changes are automatable, skip the manual checklist:
 
 Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Fall back to `latest` on an empty result.
 
-When a manual checklist is produced, write it directly to `.canon/tmp/ui-checklist/<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite. This is a handoff file rather than a deliverable: `git-pr` posts it as a pull request comment once one opens, then removes it, and nothing here talks to `gh` directly.
+When a manual checklist is produced, write it directly to `.canon/tmp/handoff/ui-checklist/<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist. Always overwrite. This is a handoff file rather than a deliverable: `git-pr` posts it as a pull request comment once one opens, then removes it, and nothing here talks to `gh` directly.
 
 From a linked worktree the file-editing tools refuse that path, so the checklist 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.
 
@@ -71,7 +71,7 @@ The `.canon/tmp/` directory is gitignored. Do not stage or commit the file.
 
 1. Write and run e2e tests (report pass/fail)
 2. If a manual checklist was produced, write it to file, then output only the file path in chat:
-   `📝 Wrote .canon/tmp/ui-checklist/<slug>.md`
+   `📝 Wrote .canon/tmp/handoff/ui-checklist/<slug>.md`
 3. If no checklist was needed: `✅ All changes covered by e2e tests. No manual verification needed.`
 
 Do not repeat the full checklist in chat.

package/docs/agents/commands.md

@@ -53,6 +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 prune-tmp`        | Report scratch nobody has touched inside an age window and delete it (`--write`, `--older-than`, `--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`)                                                                                                                                                                         |
@@ -190,7 +191,7 @@ A destination that already holds the same bytes marks the flat file a duplicate,
 
 `migrate record-layout` folds two record folders under the memory pen: review receipts move from `.canon/review/memory/` to `.canon/memory/review/`, and retired entries move from `.canon/tmp/memory-archive/` to `.canon/memory/archive/`, backed for the first time since `memory/` is a folder `canon records push` carries and `tmp/` is not. Each move is refused independently when its destination already exists, and the citation repoint sweeps every folder `canon records push` carries, archives included, since an archived receipt still cites the row it retired. The same `canon-keep-record-root` marker and second-run idempotence check apply. A receipt sitting at the flat `review/` root, from before `.canon/review/memory/` existed, matches neither mapped move and is reported by name rather than moved.
 
-The same verb leaves `.canon/review/` holding only reviews. Feedback moves to `.canon/feedback/`, and the design, board, slides, and diagram renders move to `.canon/tmp/render/<kind>/`, off the records remote since the commands regenerate them. Reference images move to `.canon/picks/references/`. A branch report flattens from `review/branch/review-<slug>.md` to `review/branch-<slug>.md`, and a flat `review/ui-checklist-<slug>.md` moves into `.canon/tmp/ui-checklist/`. Each folder under `review/evidence/` is decided from what it holds: one directly carrying an `arm-<id>` capture or a `design-handoff.md` is a pick and moves to `.canon/picks/<slug>/`, and any other is evidence and moves to `.canon/evidence/<nn>-<slug>/`. Evidence folders are numbered by the oldest file each holds, continuing past any ordinal `evidence/` already carries. The dry run labels each derived destination `(pick)` or `(evidence)`, so a misfiled folder shows before `--write`, and one filed wrong moves back by hand. A bare mention of an emptied folder, such as `review/evidence/` with no slug or `review/branch/` with no report name, matches no row and stays as written.
+The same verb leaves `.canon/review/` holding only reviews. Feedback moves to `.canon/feedback/`, and the design, board, slides, and diagram renders move to `.canon/tmp/render/<kind>/`, off the records remote since the commands regenerate them. Reference images move to `.canon/picks/references/`. A branch report flattens from `review/branch/review-<slug>.md` to `review/branch-<slug>.md`, and a flat `review/ui-checklist-<slug>.md` moves into `.canon/tmp/handoff/ui-checklist/`. Each folder under `review/evidence/` is decided from what it holds: one directly carrying an `arm-<id>` capture or a `design-handoff.md` is a pick and moves to `.canon/picks/<slug>/`, and any other is evidence and moves to `.canon/evidence/<nn>-<slug>/`. Evidence folders are numbered by the oldest file each holds, continuing past any ordinal `evidence/` already carries. The dry run labels each derived destination `(pick)` or `(evidence)`, so a misfiled folder shows before `--write`, and one filed wrong moves back by hand. A bare mention of an emptied folder, such as `review/evidence/` with no slug or `review/branch/` with no report name, matches no row and stays as written.
 
 ## Version skew
 

package/docs/agents/records.md

@@ -152,6 +152,33 @@ The window counts read `mtime`, so what they report is a file written inside the
 
 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.
 
+## Prune
+
+`canon records prune-tmp` reports scratch nobody has touched inside an age window, and deletes it only with `--write`. Nothing removed an abandoned scratch folder before this, so a spike folder from months ago sat beside the ones a session still needs.
+
+```bash
+canon records prune-tmp
+canon records prune-tmp --write
+canon records prune-tmp --older-than 30 --json
+```
+
+| Option                | Behavior                                                       |
+| --------------------- | -------------------------------------------------------------- |
+| `--json`              | Add a machine-readable record on stdout                        |
+| `--write`             | Delete every candidate the report lists                        |
+| `--older-than <days>` | Age a unit's newest file must clear to be offered (default 14) |
+| `--root <path>`       | Project root, defaulting to the main worktree                  |
+
+A candidate is a unit whose newest file is older than the threshold: a `tmp/<slug>/` folder, a folder one level inside `runs/`, `render/`, or `pr/`, or a single marker file inside `hooks/<hook>/`. `pr/review/` groups its body files by pull request number rather than reporting as one folder, since a review pass leaves one file per pass and a folder holding thousands of them would otherwise report as a single row nobody can prune apart. A unit holding no files, empty subfolders included, is offered whatever its age.
+
+`tmp/handoff/` and `tmp/pr/poll/` are never offered. A reader deletes a handoff themselves once it has been read, and a poll baseline is live state rather than scratch. The pre-split names the reserved split replaced, `memory-routing/`, `teach-promotion/`, `ui-checklist/`, and `pr-poll/` at the scratch root, are skipped the same way on a project the rename never reached, naming the folder they moved to, rather than being offered as ordinary slugs. An unread handoff is the one thing a wrong delete here loses for good.
+
+A scratch-root name `canon migrate record-layout` or `canon migrate scratch-evidence` moves out of scratch for good, such as `memory-archive`, is skipped the same way on a project that has not yet run that migration, naming the verb to run. The retired-entry archive `memory-archive` holds is never deleted, per the memory standard, so it stays skipped rather than aging into an offer.
+
+It writes nothing until `--write` is passed, matching `canon records migrate`: a session record has no history to undo a wrong delete from. It reads `mtime` the way `canon records size` does, so a machine restored by `canon records pull` reads its whole tree as new and fails safe by offering nothing.
+
+Exit codes: `0` nothing to prune, or `--write` deleted every candidate. `1` refused, sharing `no-folder` with `size`, or a delete failed. `2` candidates exist and `--write` was not passed.
+
 ## Push and pull
 
 `canon records push` commits the backed record folders to a private remote and pushes them. `canon records pull` fetches the other direction and writes them back. Both take `--json` and `--root` the way `validate` does, and both exit `0` on agreement and `1` on a refusal.

package/docs/agents/sandbox.md

@@ -69,7 +69,7 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
 
 Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, `concurrent` for the records present both before and after, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.