@erclx/canon 4.9.0 → 4.9.2

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

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

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

@@ -158,13 +158,18 @@ This chain owns the receipt's lifetime, which is what makes the Output block's c
 
 Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, the CI watch, and the scoped memory review, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
 
-One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch:
+One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, then read the flag back:
 
 ```bash
-gh pr ready --undo
+gh pr ready --undo <number>
+gh pr view <number> --json isDraft
 ```
 
-Placement is the whole point of naming it. Marking after the watch leaves the pull request ready to merge for as long as CI runs, which is the window an unattended worker's branch is least supervised.
+Name the number `git-ship`'s pull request step returned on both calls rather than leaving either to resolve by branch, since each matches a head ref and ignores state, so a reused branch name reaches a merged namesake. The read is where that costs the most, answering with the wrong record's flag, and the write above it errors rather than mutating one.
+
+Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the undo on a disagreeing read, which fights whoever readied it instead of guarding anything.
+
+Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and it is the operator's act to take.
 
 `git-ship` verifies again at its own gate, which repeats this chain's Step 3 on the run where nothing stopped. That cost is deliberate: four of the stop points in the table below hand the run straight back to that body, and a gate the chain skips for being redundant is a gate no resumed run ever meets.
 
@@ -173,16 +178,18 @@ Placement is the whole point of naming it. Marking after the watch leaves the pu
 Respond with up to five lines:
 
 ```plaintext
-✅ Autoshipped (draft): <PR url>
+✅ Autoshipped (<state>): <PR url>
 <N minor findings kept in .canon/review/branch/review-<slug>.md>
 <N facts routed to context entries>
 <N memories captured in .canon/memory/>
 <Memory proposal at .canon/review/memory/memory-review-<slug>.md>
 ```
 
+`<state>` is whatever the Step 7 read returned, being `draft` or `ready, unsupervised`, rather than the state the undo asked for. Writing the word `draft` there unconditionally is what this line used to do, and it named a state no step had read.
+
 Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
 
-This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the draft state and the second reports the minor findings Step 6 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the draft under a `✅ Shipped` that does not name it.
+This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the state the read returned and the second reports the minor findings Step 6 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
 
 ## Failure recovery
 

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

@@ -119,7 +119,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
    - Resolve the target at the moment of sending with `canon sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step 5 routes on the count and the confidence it answers with
    - Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
    - Name the skill for the reader to run rather than writing an invocation, which arrives as text
-   - Read the pull request's own draft flag rather than the state a worker reports, since two reported a draft that read ready inside ninety seconds
+   - Read the pull request's own draft flag rather than the state a worker reports, since two reported a draft that read ready inside ninety seconds, and report what the read returned and when rather than the state alone. The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment, so a read taken between the pull request opening and that call sees a genuinely ready pull request about to become a draft. That is how a poll on `#1307` told an operator the opposite of what the worker had said.
 
 A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, report the invocation for the human, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it. Every dispatch in the trial behind this step found a live session, so this branch stands on reasoning rather than on observation.
 

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

@@ -25,6 +25,7 @@ running and re-invoking it would restart the build.
 - Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/memory/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.
 - Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is true where this session stands and wrong about the world, and a reader with no second tree to check cannot separate the two.
 - Build the plan the launch named. Do not write a second one when the path fails to resolve, since a row that cites a plan already has one and drafting another produces two plans for one row.
+- Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft and no step anywhere un-marks, so a flag reading ready afterwards was lifted by a person readying it to merge, which GitHub requires and is theirs to take. Re-drafting fights them, which four sessions did on 2026-08-31 on a belief no surface in the tree states.
 
 ## The board is read-only
 

package/docs/agents/commands.md

@@ -142,7 +142,9 @@ Common patterns:
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
-`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first. A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. Running it twice rewrites nothing, which is the check that the exclusions and the markers fired.
+`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
+
+A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
 ## Version skew
 

package/docs/ai-workflow.md

@@ -80,7 +80,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 - Invoke `canon:claude-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. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review/branch/review-<slug>.md`, `review/ui-checklist-<slug>.md`), 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:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
+- For full autonomy per worktree, invoke `canon:claude-autoship` 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 and is the operator's act.
 
 To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `canon:claude-orchestrate`. It holds the cross-feature call, plans each feature itself or dispatches a cold planner under `canon:claude-planner` to write the plan, refills the ready queue so a free worker never waits, and reviews each worker's PR with `canon:claude-pr-review`, then tells the session holding that branch to run `canon:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `canon:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
 

package/docs/target-projects.md

@@ -128,15 +128,17 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 Session records moved out of `.claude/` and into a root of their own. What is committed stays where it is, and everything gitignored, being the task board, the plans, the memory pen, the review reports, and the scratch folder, now lives under `.canon/`, which a single ignore entry covers.
 
-**`canon migrate records` is not in a published release yet.** It ships with the change that split the roots, so an installed binary answers `unknown command` until the next release carries it. Until then, run it out of a canon checkout against the project by path:
+`4.7.0` carries `canon migrate records`, so run these three lines from inside the project. Run `canon upgrade` first regardless of what you hold, since the sweep learned to pass over the records themselves after that release and a `4.7.0` binary rewrites them.
 
 ```bash
 canon tooling sync claude . --write
-bun src/cli.ts migrate records --root /path/to/project --json
-bun src/cli.ts migrate records --root /path/to/project --write --json
+canon migrate records --json
+canon migrate records --write --json
 ```
 
-Once the release lands, the same three lines read `canon migrate records` from inside the project. Either way the first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+The first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+
+Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
 
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 

package/package.json

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

package/src/commands/migrate.ts

@@ -6,6 +6,7 @@ import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
 import {
   ignoresDestination,
+  isRecordArtifact,
   planRecordsMove,
   type RecordsPlan,
 } from '@/migrate/records'
@@ -176,17 +177,24 @@ async function runRecords(opts: RecordsOptions): Promise<number> {
     return 1
   }
 
-  const plan = planRecordsMove(root, await readSources(root, files))
+  // Filtered before the read rather than inside the planner, because the
+  // records are the largest thing in the tree and `readSources` awaits one file
+  // at a time. This repository's own record tree is 9,744 files at 83M, and the
+  // backup history under it is object files read whole and discarded as binary.
+  const toSweep = files.filter((path) => !isRecordArtifact(path))
+  const records = files.length - toSweep.length
+
+  const plan = planRecordsMove(root, await readSources(root, toSweep))
 
   // stdout, so the record pipes clean. `pipeOutput` frames to stderr, which is
   // where this command's report belongs and where a JSON record does not.
   if (opts.json) {
     process.stdout.write(
-      `${JSON.stringify(toRecordsRecord(plan, opts.write))}\n`,
+      `${JSON.stringify(toRecordsRecord(plan, records, opts.write))}\n`,
     )
   }
 
-  reportRecords(plan)
+  reportRecords(plan, records)
 
   if (plan.collisions.length > 0) {
     logError(
@@ -229,7 +237,7 @@ function readGitignore(root: string): string | undefined {
   }
 }
 
-function reportRecords(plan: RecordsPlan): void {
+function reportRecords(plan: RecordsPlan, records: number): void {
   logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
   for (const move of plan.moves) logInfo(`  ${move.from} -> ${move.to}`)
   logInfo(
@@ -237,6 +245,14 @@ function reportRecords(plan: RecordsPlan): void {
   )
   logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
 
+  // A count rather than a list, and its own line rather than a place in
+  // `excluded`. That field exists so a reader can go and check a handful by
+  // hand, and a record tree would bury them. The count is what answers the
+  // question a target actually has, which is where the rest of the files went.
+  if (records > 0) {
+    logInfo(`${plural(records, 'file')} under a record root, left alone.`)
+  }
+
   if (plan.excluded.length > 0) {
     logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep.`)
   }
@@ -244,6 +260,7 @@ function reportRecords(plan: RecordsPlan): void {
 
 function toRecordsRecord(
   plan: RecordsPlan,
+  records: number,
   wrote: boolean | undefined,
 ): unknown {
   return {
@@ -255,6 +272,7 @@ function toRecordsRecord(
     rewritten: plan.rewritten,
     kept: plan.kept,
     excluded: plan.excluded.length,
+    records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,
       rewritten: entry.rewritten,
@@ -294,6 +312,11 @@ export function register(program: Command): void {
         'A line carrying canon-keep-record-root, or the line below it, keeps the',
         'old root. Prose that dates a decision needs it; a live path does not.',
         '',
+        'The records themselves are never swept. Everything under .canon/ and',
+        'every .claude/ record folder is left alone and reported as a count, so',
+        'a run after the ignore entries collapse touches the same files as one',
+        'before it.',
+        '',
         'Examples:',
         '  canon migrate records',
         '  canon migrate records --write',

package/src/migrate/records.ts

@@ -10,7 +10,12 @@
 
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { type RecordRoot, RECORD_ENTRIES, spell } from '@/record-root'
+import {
+  type RecordRoot,
+  RECORD_ENTRIES,
+  RECORD_ROOTS,
+  spell,
+} from '@/record-root'
 
 /** The root the entries below leave, exported so the writer can prune it. */
 export const FROM_ROOT: RecordRoot = '.claude'
@@ -104,6 +109,66 @@ export function isExcludedPath(path: string): boolean {
   return EXCLUDED_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
 
+/**
+ * The roots holding nothing but records, so a path under one is a record
+ * whatever it is named.
+ *
+ * `.canon/` qualifies by construction. `.claude/ARCHITECTURE.md` fixes the rule
+ * that every gitignored session record moves there and nothing tracked ever
+ * lands there, which covers a record folder `RECORD_ENTRIES` has yet to learn
+ * about. The old root is the one that cannot take a whole-root reading, and it
+ * is derived by exclusion rather than named, so a third root added later reads
+ * as records-only unless someone says otherwise.
+ */
+const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
+  (root) => root !== FROM_ROOT,
+)
+
+/**
+ * Every prefix under which a path is a record rather than a file to sweep.
+ *
+ * The asymmetry is the point. A whole-root prefix is correct for the new root
+ * and wrong for the old one, which is mixed: this repository tracks 163 files
+ * under `.claude/`, and a target's installed `.claude/rules/core/035-tasks.md`
+ * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
+ * it silently. The old root is therefore entry-scoped, through `spell` so the
+ * one naming variant stays decided in `record-root.ts`.
+ *
+ * Joined with a literal separator rather than through `join`, the way
+ * `EXCLUDED_PREFIXES` already is. These are matched against what `git ls-files`
+ * returns, which is forward-slashed on every platform, where `join` would spell
+ * a backslash on Windows and match nothing.
+ */
+const RECORD_PREFIXES: readonly string[] = [
+  ...RECORD_ONLY_ROOTS,
+  ...RECORD_ENTRIES.map((entry) => `${FROM_ROOT}/${spell(FROM_ROOT, entry)}`),
+]
+
+/**
+ * Whether a path is a record artifact, which the sweep passes over entirely.
+ *
+ * Separate from `isExcludedPath`, which reports what it skips because a reader
+ * has to check those by hand. A record artifact is never something to check,
+ * and a target's record tree is large enough that reporting each one would bury
+ * the handful of exclusions that matter.
+ *
+ * A record folder becomes visible to the sweep at the moment `canon tooling
+ * sync claude` prunes the twelve old ignore entries down to one `.canon/` line,
+ * which is the step the documented first-run order puts immediately before this
+ * verb. Without this predicate the run that follows reads the memory pen and
+ * the groundwork trails as source and rewrites them.
+ *
+ * The three retired flat archives stay outside this, the way `CITATION` already
+ * leaves them alone: `.claude/plans-archive/x.md` does not start with
+ * `.claude/plans/`, and widening the entry list to catch it would change what
+ * `MOVED_ENTRIES` means for the folder half of the verb.
+ */
+export function isRecordArtifact(path: string): boolean {
+  return RECORD_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  )
+}
+
 /**
  * Marks a line naming the old root on purpose.
  *
@@ -244,6 +309,11 @@ export function planRecordsMove(
   let kept = 0
 
   for (const source of sources) {
+    // Silently, and ahead of the exclusion test. The command boundary filters
+    // these out before it reads them, so this is what keeps the pure function
+    // correct under a direct call rather than what the verb relies on.
+    if (isRecordArtifact(source.path)) continue
+
     if (isExcludedPath(source.path)) {
       // Only an excluded file that actually carries a citation is reported. The
       // predicate covers every test file in the tree, so counting them all would