@erclx/canon 4.87.0 → 4.88.1

package/docs/workflow/ai-workflow.md

@@ -63,7 +63,7 @@ Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full fi
 
 The routing test is whether the repository can answer an item today. A session grepping handles the yes, and a groundwork track handles the no.
 
-A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
+A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/runs/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
 What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
 
@@ -81,7 +81,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `canon:plan-feature` in each session. Plans land at the main worktree root as `.canon/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `review-branch` writes a per-branch report at the main worktree root (`review/branch-<slug>.md`), and `ui-test` writes a per-branch checklist handoff there too (`tmp/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
+- Implement, verify, and review each feature independently. `review-branch` writes a per-branch report at the main worktree root (`review/branch-<slug>.md`), and `ui-test` writes a per-branch checklist handoff there too (`tmp/handoff/ui-checklist/<slug>.md`) that `git-pr` posts to the pull request and removes, so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `canon:git-ship`
 - For full autonomy per worktree, invoke `canon:auto-ship` instead of the manual chain. Approve the plan, walk away, come back to a pull request the chain marked as a draft and then read the flag back on. The mark says the work has had no review yet, and it holds no window, since readying a pull request to merge lifts it directly, an act reserved to the operator or to the controlling session that closed the review.
 
@@ -111,6 +111,8 @@ A person points it at a private repository once and both verbs refuse until they
 
 `canon records size` reports what each of these folders holds, heaviest first, along with `.canon/tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
 
+`canon records prune-tmp` reports scratch under `.canon/tmp` nobody has touched inside an age window, and deletes it only with `--write`. A `tmp/handoff/` folder and the live `tmp/pr/poll/` baseline are never offered, since a reader deletes a handoff once it is read and a poll baseline is state a session still needs. See [records](../agents/records.md) for the candidate shapes and the exit codes.
+
 A plan that ships is archived, never deleted. `canon tasks archive` moves it to `.canon/plans/archive/` alongside the task it belonged to and retargets that task's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
 A branch review report takes the other route and is swept rather than archived. `review-branch` writes it flat into `.canon/review/` as `branch-<slug>.md`, the session addressing it reads it once, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so `docs-fold` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.

package/governance/rules/core/055-scratch.md

@@ -9,3 +9,4 @@ description: Write temporary files to the scratch folder structure
 - Write temporary files to `.canon/tmp/<slug>/<file>.md` in the project root, a nested `<slug>/` folder with a kebab-slug tied to the topic, not a flat `<slug>-<file>.md`. The scratch-guard hook enforces the location.
 - Write to `.claude/.tmp/<slug>/` instead in a project that carries no `.canon/` root, which is one the record move has not reached. The hook accepts either, but the ignore file is the source: `.gitignore` and its manifest counterpart are what keep the fallback spelling out of `git status`, and the hook and this rule both defer to it. `canon migrate records` is what moves a project from this second spelling to the first. <!-- canon-keep-record-root -->
 - "The project root" above means the current worktree by default. `085-worktrees.md` states the same mixed default for `.canon/tmp/` and defers to each skill's own body for which write resolves at the main root instead.
+- `runs/`, `hooks/`, `handoff/`, `pr/`, and `render/` are reserved under `tmp/` for build and command output that can be regenerated, hook state, skill-to-skill handoff, pull request scratch, and render output. A session slug must not take one of these five names.

package/package.json

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

package/scripts/tooling/verify.sh

@@ -16,7 +16,7 @@ show_help() {
   echo -e "${GREY}│${NC}    --keep       ${GREY}# Keep tmp dir after run for inspection${NC}"
   echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
   echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Scaffolds <stack> into .canon/tmp/verify-<stack>/, syncs the full"
+  echo -e "${GREY}│${NC}  Scaffolds <stack> into .canon/tmp/runs/verify-<stack>/, syncs the full"
   echo -e "${GREY}│${NC}  layer chain, and runs check + test:e2e + screenshot."
   echo -e "${GREY}└${NC}"
   exit 0
@@ -102,7 +102,7 @@ main() {
   open_timeline "canon tooling verify $stack"
   trap close_timeline EXIT
 
-  local tmp_root="$PROJECT_ROOT/.canon/tmp"
+  local tmp_root="$PROJECT_ROOT/.canon/tmp/runs"
   local tmp_dir="$tmp_root/verify-$stack"
 
   mkdir -p "$tmp_root"

package/src/claude/skills-headings.ts

@@ -21,7 +21,7 @@
  * `markdown.md` has a body backtick a named thing, so the natural spelling of
  * the citation is `` See the `Parallel sessions` heading in `CLAUDE.md` `` and
  * a class stopping at the first backtick never reaches the file. That heading
- * is real in this repository's own root file. Both classes returned the same
+ * was real in this repository's own root file when the check was written. Both classes returned the same
  * twenty lines over `claude/skills/` at the stamp, so the backtick exclusion
  * was carrying nothing and hiding the spelling an author would reach for.
  *

package/src/commands/migrate.ts

@@ -1164,7 +1164,7 @@ export function register(program: Command): void {
         '  review/{design,board,slides,diagrams}/ -> tmp/render/<kind>/',
         '  review/references/              -> picks/references/',
         '  review/branch/review-<slug>.md  -> review/branch-<slug>.md',
-        '  review/ui-checklist-<slug>.md   -> tmp/ui-checklist/<slug>.md',
+        '  review/ui-checklist-<slug>.md   -> tmp/handoff/ui-checklist/<slug>.md',
         '  review/evidence/<slug>/         -> picks/<slug>/ or evidence/<nn>-<slug>/',
         '',
         'An evidence folder is a pick when it directly holds an arm-<id>',

package/src/commands/records.ts

@@ -10,6 +10,12 @@ import {
   isOrdinalKind,
   ORDINAL_KINDS,
 } from '@/records/ordinal'
+import {
+  DEFAULT_OLDER_THAN_DAYS,
+  type PruneReport,
+  type PruneUnit,
+  pruneScratch,
+} from '@/records/prune'
 import {
   type FolderSize,
   formatBytes,
@@ -50,6 +56,9 @@ const EXIT_MIGRATABLE = 2
 /** Returned when `--claim` loses every retry to a collision. */
 const EXIT_CONTENDED = 2
 
+/** Returned when candidates exist and `--write` was not passed. */
+const EXIT_PRUNABLE = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -61,6 +70,11 @@ interface MigrateCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
 }
 
+interface PruneCommandOptions extends ValidateCommandOptions {
+  readonly write?: boolean
+  readonly olderThan?: string
+}
+
 interface OrdinalCommandOptions extends ValidateCommandOptions {
   readonly claim?: boolean
 }
@@ -233,6 +247,55 @@ export function register(program: Command): void {
       process.exitCode = await runSize(opts)
     })
 
+  records
+    .command('prune-tmp')
+    .description('Report scratch nobody has touched in a while, and delete it')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Delete every candidate the report lists')
+    .option(
+      '--older-than <days>',
+      `Age in days a unit's newest file must clear to be offered (default ${DEFAULT_OLDER_THAN_DAYS})`,
+    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A candidate is a unit whose newest file is older than --older-than:',
+        '  a tmp/<slug>/ folder, a folder one level inside runs/, render/, or',
+        '  pr/, or a single marker file inside hooks/<hook>/. A unit with no',
+        '  files is offered whatever its age.',
+        '',
+        'tmp/handoff/ and tmp/pr/poll/ are never offered, since a reader deletes',
+        'a handoff itself and a poll baseline is live state. The pre-split names',
+        'the same two folders replaced (memory-routing/, teach-promotion/,',
+        'ui-checklist/, pr-poll/) are skipped the same way rather than offered',
+        'as ordinary slugs.',
+        '',
+        'Exit codes:',
+        '  0  nothing to prune, or --write deleted every candidate',
+        '  1  refused, with the reason on stderr or in the JSON record, or a',
+        '     delete failed',
+        '  2  candidates exist and --write was not passed',
+        '',
+        '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 like canon records size, so a machine restored by canon',
+        'records pull reads everything as new, which fails safe by offering',
+        'nothing.',
+        '',
+        'Examples:',
+        '  canon records prune-tmp',
+        '  canon records prune-tmp --write',
+        '  canon records prune-tmp --older-than 30 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PruneCommandOptions) => {
+      process.exitCode = await runPruneTmp(opts)
+    })
+
   records
     .command('push')
     .description(
@@ -390,6 +453,102 @@ function reportSize(outcome: Extract<SizeOutcome, { ok: true }>): void {
   outro()
 }
 
+async function runPruneTmp(opts: PruneCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const olderThan = Number(opts.olderThan ?? DEFAULT_OLDER_THAN_DAYS)
+
+  if (!Number.isFinite(olderThan) || olderThan <= 0) {
+    return reportRefusal(
+      'canon records prune-tmp',
+      {
+        reason: 'bad-older-than',
+        message: `--older-than must be a positive number of days, got ${opts.olderThan}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const write = opts.write ?? false
+  const outcome = await pruneScratch(root, olderThan, write)
+
+  if (!outcome.ok)
+    return reportRefusal('canon records prune-tmp', outcome, emitJson)
+
+  return reportPrune(outcome, emitJson)
+}
+
+function pruneRow(entry: PruneUnit): string[] {
+  return [
+    entry.path,
+    String(entry.files),
+    formatBytes(entry.bytes),
+    entry.newest ?? '',
+  ]
+}
+
+function pruneExitCode(outcome: PruneReport): number {
+  if (outcome.failed.length > 0) return 1
+  if (outcome.candidates.length > 0 && outcome.deleted.length === 0)
+    return EXIT_PRUNABLE
+  return 0
+}
+
+function reportPrune(outcome: PruneReport, emitJson: boolean): number {
+  const exit = pruneExitCode(outcome)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return exit
+  }
+
+  intro('canon records prune-tmp')
+
+  if (outcome.candidates.length === 0) {
+    logStep('Prunable')
+    logInfo(`none, older than ${plural(outcome.olderThan, 'day')}`)
+  } else {
+    logStep(outcome.deleted.length > 0 ? 'Deleted' : 'Prunable')
+
+    const headers = ['path', 'files', 'size', 'newest']
+    const rows = outcome.candidates.map(pruneRow)
+    const widths = headers.map((header, column) =>
+      columnWidth(
+        header,
+        rows.map((row) => row[column]),
+      ),
+    )
+    const render = (cells: readonly string[]): string =>
+      cells
+        .map((cell, column) =>
+          column === 0
+            ? cell.padEnd(widths[column])
+            : cell.padStart(widths[column]),
+        )
+        .join('  ')
+        .trimEnd()
+
+    pipeOutput([render(headers), ...rows.map(render)].join('\n'))
+
+    if (outcome.deleted.length === 0) logInfo('Re-run with --write to delete.')
+  }
+
+  if (outcome.skipped.length > 0) {
+    logStep('Skipped')
+    for (const entry of outcome.skipped)
+      logInfo(`${entry.path}: ${entry.reason}`)
+  }
+
+  if (outcome.failed.length > 0) {
+    logStep('Failed')
+    for (const entry of outcome.failed)
+      logWarn(`${entry.path}: ${entry.message}`)
+  }
+
+  outro()
+  return exit
+}
+
 async function runPush(opts: BackupCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await pushRecords(root)

package/src/migrate/record-layout.ts

@@ -6,7 +6,7 @@
  * feedback moves to `.canon/feedback/`, option captures to `.canon/picks/`,
  * claim-backing folders to a numbered `.canon/evidence/`, renders rebuilt from
  * committed sources to `.canon/tmp/render/`, a branch report flattens to
- * `review/branch-<slug>.md`, and a flat checklist joins the `tmp/ui-checklist/`
+ * `review/branch-<slug>.md`, and a flat checklist joins the `tmp/handoff/ui-checklist/`
  * handoff folder. `canon records push` carries every top-level `.canon/`
  * entry except `EXCLUDED_ENTRIES`, so the new root folders are backed with no
  * list edit, and `tmp/render/` is deliberately not.
@@ -120,7 +120,7 @@ export const RECORD_LAYOUT_MOVES: readonly RecordLayoutMove[] = [
     kind: 'files',
     from: ['review'],
     prefix: 'ui-checklist-',
-    to: [SCRATCH, 'ui-checklist'],
+    to: [SCRATCH, 'handoff', 'ui-checklist'],
     renamed: '',
     prune: false,
   },

package/src/migrate/scratch-evidence.ts

@@ -48,11 +48,9 @@ import { recordDir, SCRATCH } from '@/record-root'
  * `verify-astro` and `verify-vite-react` pass the same test and are excluded
  * by name: both are scaffolds a command generates rather than records a
  * session wrote, and each is 100+ MB, which the review remote is not sized
- * for. `ablation`, `eval-runs`, `sandbox-runs`, `memory-archive`,
- * `groundwork-fixtures`, `precompact-handoff`, `pr-poll`, `pr`,
- * `address-review`, and `memory-routing` fail the second clause: a script or
- * a skill body names each of those paths, so moving one needs a code change
- * first rather than a promotion.
+ * for. `ablation`, `runs`, `memory-archive`, `hooks`, `pr`, and `handoff`
+ * fail the second clause: a script or a skill body names each of those
+ * paths, so moving one needs a code change first rather than a promotion.
  */
 export const PROMOTED_FOLDERS: readonly string[] = [
   'hero-probe',