@erclx/aitk 3.55.0 → 3.57.0

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

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

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

@@ -114,7 +114,7 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
 4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the row's file set against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the sets overlap, or a stated reason serializes the row behind something already out.
 5. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
-6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
+6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the worker's own message says the address pass finished, per the channel `claude-worker` states, rather than polling for an answer nothing else marks as landed. Then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
    - Read the threshold off `claude-pr-review`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
    - Resolve the target at the moment of sending with `aitk 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

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -81,6 +81,48 @@ The last bullet is the one under pressure, since the dispatch that first proved
 
 Report the dispatch as loudly as the human-launch line it replaces: name the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
+## Dispatch to address a review
+
+`claude-address-review` is a single pass, not a chain, so a launch naming it
+alone reaches no `claude-worker` and takes no role, which owes no message
+either. `#1251`'s replacement session was launched that way, onto the branch a
+review had already posted findings against, and it answered by posting a
+thread reply and telling its controller nothing. Reach the role directly on
+this launch instead of wrapping a second chain around one skill that has none
+of its own.
+
+The branch already exists here, opened by whatever built it, so this shape
+skips the plan-derived name the build shape resolves above. Take `<branch>`
+off the pull request's own head ref. Enter the worktree the original build
+left on disk, `.claude/worktrees/<slug>/`, with `EnterWorktree`'s `path` form
+when it is still there, or `git worktree add .claude/worktrees/<slug>/
+<branch>` when it was cleaned up, so `<slug>` is that directory name either
+way.
+
+`EnterWorktree` refuses that path in the ordinary case, because the original
+build session stays registered against its own worktree after going idle and
+holds a harness-level lock the roster does not report. Work in the folder
+directly with `Bash`, `Read`, and `Edit` instead of retrying the tool, which
+is the route two workers already took today on two different branches.
+
+```bash
+claude --bg --model <model> -n "worker-<slug>" "Enter the worktree for <branch> at .claude/worktrees/<slug>/, creating it from that branch if the folder is gone. Run /aitk:claude-worker, then /aitk:claude-address-review. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id at the moment you send, and never resolve an addressee by name prefix. Message it when the address pass finishes, carrying what was addressed and the PR's CI state, and message it again if you stop on a question."
+```
+
+`<dispatcher-id>` and `<model>` resolve the same way the build shape resolves
+them above.
+
+Take this shape wherever a review needs answering and no live session already
+holds the branch. Where one does, message it to run `claude-address-review`
+instead, per the loop's own step 6, since a session already there needs no
+second one dispatched onto the same branch.
+
+That check is blind to a session working through the direct-path fallback
+above, since a session that never runs `EnterWorktree` never moves its
+registered branch off `main`, so `aitk sessions list --branch` reports nothing
+holding it. A dispatch landing on a branch worked that way collides with
+nothing the check can see.
+
 ## Fall back to the human
 
 Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.

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

@@ -34,10 +34,11 @@ running and re-invoking it would restart the build.
 
 ## The channel
 
-The controlling session cannot watch this one build, so two messages are owed and
-nothing else.
+The controlling session cannot watch this one build, so three messages are owed
+and nothing else.
 
 - Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
+- Announce when an address-review pass finishes, as `claude-address-review` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and it is what tells the controller to re-review rather than leaving it to poll for an answer nothing marks as landed.
 - Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round that drains an inbound message, so a relayed answer arrives under the open question and changes nothing.
 - Send nothing on progress. A worker reporting progress rebuilds, on this side of the channel, the poll the announcement retired on the other.
 

package/docs/agents/commands.md

@@ -41,6 +41,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
 | `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
+| `aitk migrate rename`      | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
 | `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `aitk worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
 | `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |

package/docs/operating-model.md

@@ -94,13 +94,19 @@ reply that changes an outcome, such as a worker naming the plan question that
 already declined a finding, still belongs back on the PR, since the session
 holding it ends and the thread is what a later reader opens.
 
-Two messages travel the other way and the worker owes both. It announces its own
-pull request as the ship chain opens one, naming the number, the branch, and the
-task it closes. That is the one transition only that session can observe, since
-a worker that finishes goes idle rather than exiting, and one sat unnoticed for
-eighteen minutes before the announcement existed.
-
-The second reports a block before that block becomes an interactive prompt. A
+Three messages travel the other way and the worker owes all three. It announces
+its own pull request as the ship chain opens one, naming the number, the
+branch, and the task it closes. That is the one transition only that session
+can observe, since a worker that finishes goes idle rather than exiting, and
+one sat unnoticed for eighteen minutes before the announcement existed.
+
+It announces again when an address-review pass finishes, naming what it
+addressed and the pull request's new CI state. That transition is the other
+one only the worker can observe, and it replaces the same idle-poll gap on the
+review's return leg, after a worker once addressed a posted review by
+answering on the thread alone and telling its controller nothing.
+
+The third reports a block before that block becomes an interactive prompt. A
 queued message drains at the next tool round and a session already waiting on
 input never reaches one, so an answer relayed to an open prompt renders beneath
 the question and changes nothing. Nothing is sent on progress, which would

package/package.json

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

package/src/cli.ts

@@ -26,6 +26,7 @@ import { register as teach } from '@/commands/teach'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
+import { register as migrate } from '@/commands/migrate'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as worktrees } from '@/commands/worktrees'
@@ -182,6 +183,7 @@ comments(program)
 context(program)
 markdown(program)
 records(program)
+migrate(program)
 sessions(program)
 targets(program)
 worktrees(program)

package/src/commands/migrate.ts

@@ -0,0 +1,175 @@
+import type { Command } from 'commander'
+import { listRepositoryFiles } from '@/git-files'
+import { applyRename, readSources } from '@/migrate/apply'
+import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
+import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
+
+interface RenameOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+  readonly scope?: string
+}
+
+const SCOPES = ['self', 'target'] as const
+
+type Scope = (typeof SCOPES)[number]
+
+function isScope(value: string): value is Scope {
+  return (SCOPES as readonly string[]).includes(value)
+}
+
+/**
+ * Reports rather than writes without `--write`, matching `aitk records
+ * migrate`. A rename touching this many files has no undo short of the branch
+ * it ran on, so the safe outcome sits on the default path.
+ */
+async function runRename(opts: RenameOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+  const scope = opts.scope ?? 'self'
+
+  if (!isScope(scope)) {
+    logError(`Unknown scope ${scope}. Use one of ${SCOPES.join(', ')}.`)
+    return 1
+  }
+
+  const files = await listRepositoryFiles(root)
+  if (files === undefined) {
+    logError(`Could not list files under ${root}. Is it a git repository?`)
+    return 1
+  }
+
+  const scoped = scope === 'target' ? files.filter(isToolkitOwned) : files
+  const sources = await readSources(root, scoped)
+  const plan = planRename(sources)
+
+  // A target scope reports the citations it did not rewrite, since prose the
+  // project wrote is theirs to change and a sweep editing it underneath them
+  // is the failure this scope exists to avoid.
+  const citations =
+    scope === 'target'
+      ? planRename(
+          await readSources(
+            root,
+            files.filter((f) => !isToolkitOwned(f)),
+          ),
+        ).entries.length
+      : 0
+
+  if (opts.json) {
+    pipeOutput(
+      JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2),
+    )
+  }
+
+  report(plan, scope, citations)
+
+  if (plan.entries.length === 0) return 0
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRename(root, plan)
+  logStep(
+    `Rewrote ${plural(applied.written, 'file')} and moved ${plural(applied.moved, 'path')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not move ${plural(applied.failed.length, 'path')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return 0
+}
+
+function report(plan: RenamePlan, scope: Scope, citations: number): void {
+  logInfo(`Scope ${scope}.`)
+  logInfo(
+    `${plural(plan.entries.length, 'file')} to change, ${plural(plan.renamed, 'occurrence')} to rewrite.`,
+  )
+  logInfo(`${plural(plan.moves, 'path')} to move.`)
+  logInfo(
+    `${plural(plan.protectedCount, 'occurrence')} protected and left alone.`,
+  )
+
+  if (plan.excluded.length > 0) {
+    logInfo(`Excluded: ${plan.excluded.join(', ')}.`)
+  }
+
+  if (citations > 0) {
+    logWarn(
+      `${plural(citations, 'file')} outside toolkit-owned folders still cite the old name. They are yours to change.`,
+    )
+  }
+}
+
+function toRecord(
+  plan: RenamePlan,
+  scope: Scope,
+  citations: number,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    scope,
+    wrote: wrote === true,
+    files: plan.entries.length,
+    renamed: plan.renamed,
+    moves: plan.moves,
+    protected: plan.protectedCount,
+    excluded: plan.excluded,
+    citations,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      renamed: entry.renamed,
+    })),
+  }
+}
+
+export function register(program: Command): void {
+  const migrate = program
+    .command('migrate')
+    .description('Move a project off the retired aitk name')
+    .helpOption('-h, --help', 'Show this help message')
+
+  migrate
+    .command('rename')
+    .description('Rewrite every unprotected aitk token to canon')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .option('--scope <scope>', `What to rewrite: ${SCOPES.join(', ')}`, 'self')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scopes:',
+        '  self    every tracked file, for the toolkit repository itself',
+        '  target  toolkit-owned folders only, reporting the rest as citations',
+        '',
+        'Exit codes:',
+        '  0  nothing to rewrite, or --write applied the whole plan',
+        '  1  refused, or a move failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'The changelog is never rewritten. Its entries record what shipped',
+        'under the old name, and GitHub redirects the links they carry.',
+        'aitk-sandbox is a separate repository and is left alone.',
+        '',
+        'Examples:',
+        '  aitk migrate rename',
+        '  aitk migrate rename --write',
+        '  aitk migrate rename --scope target --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RenameOptions) => {
+      process.exitCode = await runRename(opts)
+    })
+}

package/src/migrate/apply.ts

@@ -0,0 +1,115 @@
+import { $ } from 'bun'
+import { readFile, mkdir, rmdir, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { gitEnv } from '@/git-env'
+import type { RenamePlan, RenameSource } from '@/migrate/plan'
+
+/**
+ * A file whose bytes carry a NUL is read as binary and its content is left
+ * alone, which lets the path still move. Reporting the empty string rather
+ * than a flag keeps the planner pure: an unchanged content rewrite is already
+ * how it expresses "path only", so binary needs no branch of its own there.
+ */
+export async function readSources(
+  root: string,
+  paths: readonly string[],
+): Promise<RenameSource[]> {
+  const sources: RenameSource[] = []
+
+  for (const path of paths) {
+    const bytes = await readFile(join(root, path)).catch(() => undefined)
+    if (bytes === undefined) continue
+
+    const binary = bytes.includes(0)
+    sources.push({ path, text: binary ? '' : bytes.toString('utf8') })
+  }
+
+  return sources
+}
+
+export interface ApplyResult {
+  readonly written: number
+  readonly moved: number
+  readonly failed: readonly string[]
+}
+
+/**
+ * Writes the plan. Content lands first and the move follows, so a failed move
+ * leaves the rewrite on a path that still exists rather than stranding content
+ * at a destination nothing points at yet.
+ *
+ * `git mv` rather than a filesystem rename, so the history follows the file and
+ * a reviewer reading the pull request sees a rename instead of a delete beside
+ * an add.
+ */
+export async function applyRename(
+  root: string,
+  plan: RenamePlan,
+): Promise<ApplyResult> {
+  let written = 0
+  let moved = 0
+  const failed: string[] = []
+
+  for (const entry of plan.entries) {
+    if (entry.text !== undefined) {
+      await writeFile(join(root, entry.path), entry.text)
+      written += 1
+    }
+
+    if (entry.movesTo === undefined) continue
+
+    await mkdir(dirname(join(root, entry.movesTo)), { recursive: true })
+    const result = await $`git -C ${root} mv ${entry.path} ${entry.movesTo}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+    if (result.exitCode === 0) moved += 1
+    else failed.push(entry.path)
+  }
+
+  await pruneEmptyParents(
+    root,
+    plan.entries
+      .filter((entry) => entry.movesTo !== undefined)
+      .map((entry) => dirname(entry.path)),
+  )
+
+  return { written, moved, failed }
+}
+
+/**
+ * Removes the directories a move emptied.
+ *
+ * Git tracks files rather than directories, so moving the last file out of one
+ * leaves the directory on disk with nothing in it and nothing in the diff to
+ * say so. A renamed skill folder that keeps its old shell beside the new one
+ * reads to a person, and to a plugin loader walking the tree, as though the
+ * rename only half happened.
+ *
+ * `rmdir` refuses a directory that still holds anything, which is the guard:
+ * a folder with an untracked file in it stays, and the refusal is ignored
+ * rather than reported because it means the folder was not empty to begin
+ * with.
+ */
+async function pruneEmptyParents(
+  root: string,
+  directories: readonly string[],
+): Promise<void> {
+  const deepestFirst = [...new Set(directories)].sort(
+    (left, right) => right.length - left.length,
+  )
+
+  for (const directory of deepestFirst) {
+    let current = directory
+
+    while (current !== '.' && !current.startsWith('..')) {
+      const removed = await rmdir(join(root, current))
+        .then(() => true)
+        .catch(() => false)
+      if (!removed) break
+
+      current = relative(root, join(root, current, '..'))
+    }
+  }
+}

package/src/migrate/plan.ts

@@ -0,0 +1,103 @@
+import {
+  isExcludedPath,
+  renamePath,
+  renameText,
+  scanText,
+} from '@/migrate/rename'
+
+/** One tracked file, as the planner reads it. */
+export interface RenameSource {
+  readonly path: string
+  readonly text: string
+}
+
+/**
+ * One file the sweep touches. `text` is absent when only the path moves, so a
+ * caller writing the plan can tell a content rewrite from a pure move and
+ * leave a binary file's bytes alone.
+ */
+export interface RenameEntry {
+  readonly path: string
+  readonly movesTo?: string
+  readonly text?: string
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export interface RenamePlan {
+  readonly entries: readonly RenameEntry[]
+  readonly excluded: readonly string[]
+  readonly renamed: number
+  readonly protectedCount: number
+  readonly moves: number
+}
+
+/**
+ * Folders a target receives from the toolkit and does not author.
+ *
+ * The rename may rewrite these in a consuming project, because their content
+ * came from here and a stale spelling in them is the toolkit's own defect.
+ * Everything else in a target is prose that project wrote, where a citation is
+ * reported for a person to decide rather than rewritten underneath them.
+ */
+const TOOLKIT_OWNED: readonly string[] = [
+  '.claude/aitk/',
+  '.claude/canon/',
+  '.claude/rules/',
+  '.claude/tooling/',
+]
+
+export function isToolkitOwned(path: string): boolean {
+  return TOOLKIT_OWNED.some((owned) => path.startsWith(owned))
+}
+
+/**
+ * What the sweep would do to a set of files.
+ *
+ * Pure, so the decision and the write are separable and the same plan can be
+ * reported or applied. A file whose content and path both stay put is dropped
+ * rather than carried as a no-op entry, which keeps the reported count equal
+ * to the number of files the sweep actually changes.
+ */
+export function planRename(sources: readonly RenameSource[]): RenamePlan {
+  const entries: RenameEntry[] = []
+  const excluded: string[] = []
+
+  for (const source of sources) {
+    if (isExcludedPath(source.path)) {
+      excluded.push(source.path)
+      continue
+    }
+
+    const movesTo = renamePath(source.path)
+    const rewritten = renameText(source.text)
+    const counts = scanText(source.text)
+    const moved = movesTo !== source.path
+    const changed = rewritten !== source.text
+
+    if (!moved && !changed) continue
+
+    entries.push({
+      path: source.path,
+      ...(moved ? { movesTo } : {}),
+      ...(changed ? { text: rewritten } : {}),
+      renamed: counts.renamed,
+      protectedCount: counts.protectedCount,
+    })
+  }
+
+  return {
+    entries,
+    excluded,
+    renamed: total(entries, (entry) => entry.renamed),
+    protectedCount: total(entries, (entry) => entry.protectedCount),
+    moves: entries.filter((entry) => entry.movesTo !== undefined).length,
+  }
+}
+
+function total(
+  entries: readonly RenameEntry[],
+  read: (entry: RenameEntry) => number,
+): number {
+  return entries.reduce((sum, entry) => sum + read(entry), 0)
+}

package/src/migrate/rename.ts

@@ -0,0 +1,183 @@
+/**
+ * The token rewrite behind the `aitk` to `canon` rename.
+ *
+ * The sweep is mechanical and its danger is entirely in what it must not
+ * touch, so the scanner is one pass with the protected forms tried first
+ * rather than a chain of replacements. A chain reprocesses its own output,
+ * which is how a protected form that contains the token gets rewritten by a
+ * later rule that cannot see it was already decided.
+ */
+
+/**
+ * Forms carrying the token that name something other than this tool, matched
+ * ahead of the token itself so they pass through untouched.
+ *
+ * `aitk-sandbox` is a separate repository that is not being renamed. It has to
+ * win against the bare token, and it also has to win against the owner-scoped
+ * spelling, since `erclx/aitk-sandbox` would otherwise rewrite to
+ * `erclx/canon-sandbox` and name a repository that does not exist.
+ */
+const PROTECTED = ['aitk-sandbox'] as const
+
+/**
+ * Every spelling of the token, and what each becomes. Case is carried in the
+ * map rather than derived, because the uppercase form is an environment
+ * variable prefix and the title-case form is a heading word, and a derived
+ * transform would have to guess which convention it was looking at.
+ */
+const REPLACEMENT: Readonly<Record<string, string>> = {
+  aitk: 'canon',
+  AITK: 'CANON',
+  Aitk: 'Canon',
+}
+
+/**
+ * One alternation so the engine decides each position once. Group 1 is a
+ * protected form and group 2 is a token to rewrite, and the protected branch
+ * sits first because a regex alternation is ordered.
+ */
+const SCAN = new RegExp(
+  `(${PROTECTED.join('|')})|(${Object.keys(REPLACEMENT).join('|')})`,
+  'g',
+)
+
+/**
+ * Files whose content is left alone entirely.
+ *
+ * The changelog is release history. Its entries record what shipped under the
+ * old name, so rewriting them falsifies the record, and the pull request links
+ * it carries keep resolving because GitHub redirects a renamed repository's
+ * old URLs.
+ *
+ * The sweep's own source is the other member, and it is not a preference. This
+ * module states the token map as literal keys, so rewriting it turns every key
+ * into its own replacement and leaves a rewriter that maps `canon` to `canon`
+ * and matches nothing. Its tests name both spellings on purpose for the same
+ * reason, and the command's help text documents the old name a caller is
+ * migrating off. Whatever these four files should say after the rename is
+ * written by hand, because the sweep cannot be the thing that decides it.
+ */
+/**
+ * An eval result is a transcript. It records the commands a session actually
+ * ran and the paths it actually opened, under whatever name was current when
+ * the run happened, so rewriting one makes it testify to a session that never
+ * took place. The changelog is excluded for the same reason and differs only
+ * in living at a fixed path.
+ */
+const EXCLUDED_PREFIXES: readonly string[] = [
+  'src/migrate/',
+  'scripts/eval/result-',
+]
+
+/**
+ * The four test files below exist to prove the retired spellings still
+ * resolve, so both names appear in each on purpose. Rewriting one is worse
+ * than a broken test: the retired-variable case would collapse into a copy of
+ * the current-variable case beside it and keep passing, reporting coverage for
+ * a fallback nothing exercises any more.
+ */
+const EXCLUDED_PATHS: readonly string[] = [
+  'CHANGELOG.md',
+  'src/commands/migrate.ts',
+  'src/sync/stamp.test.ts',
+  'src/targets/registry.test.ts',
+  'src/targets/sweep.test.ts',
+  'src/ui.test.ts',
+]
+
+export interface ScanCount {
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export function isExcludedPath(path: string): boolean {
+  if (EXCLUDED_PATHS.includes(path)) return true
+  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+}
+
+/**
+ * An indefinite article that agreed with the retired name and no longer
+ * agrees with the replacement.
+ *
+ * The old name opens on a vowel sound and the new one does not, so every
+ * `an aitk` in the corpus reads wrong the moment the token moves. This matches
+ * against the already-rewritten text rather than the source, which is what
+ * keeps it clear of the protected forms: `an aitk-sandbox` still says
+ * `aitk-sandbox` afterward, so it never matches here.
+ *
+ * The tail rejects a following letter rather than asking for a word boundary,
+ * which is what separates `an canonical` from `an CANON_STATE_DIR`. A boundary
+ * treats the underscore as part of the word and declines the environment
+ * variable, where the whole identifier is the token continuing.
+ */
+const ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
+
+/**
+ * Marks a line that names the retired spelling on purpose.
+ *
+ * A fallback path, a retired environment variable, and a dictionary entry
+ * covering the record corpora all have to keep saying the old name, and a
+ * second run over an already-renamed tree would otherwise strip exactly the
+ * compatibility this rename shipped. The marker sits on the line itself or on
+ * the one above it, which is the same placement `canon-allow-superseded`
+ * already uses in this repository.
+ */
+const KEEP_MARKER = 'canon-keep-retired'
+
+/** Rewrites every unprotected spelling of the token. */
+export function renameText(text: string): string {
+  const lines = text.split('\n')
+  const rewritten = lines.map((line, index) =>
+    isKept(lines, index) ? line : renameLine(line),
+  )
+
+  return rewritten.join('\n')
+}
+
+function isKept(lines: readonly string[], index: number): boolean {
+  if (lines[index]?.includes(KEEP_MARKER)) return true
+  return index > 0 && (lines[index - 1]?.includes(KEEP_MARKER) ?? false)
+}
+
+function renameLine(line: string): string {
+  const replaced = line.replace(SCAN, (match, guarded: string | undefined) =>
+    guarded === undefined ? REPLACEMENT[match] : guarded,
+  )
+
+  return replaced.replace(
+    ARTICLE,
+    (_match, article: string, gap: string, token: string) =>
+      `${article}${gap}${token}`,
+  )
+}
+
+/**
+ * What `renameText` would do, without doing it. Reported rather than inferred
+ * from a diff so a run can say how much it protected, which is the number a
+ * reader needs to trust that the exclusions fired at all.
+ */
+export function scanText(text: string): ScanCount {
+  let renamed = 0
+  let protectedCount = 0
+  const lines = text.split('\n')
+
+  for (const [index, line] of lines.entries()) {
+    if (isKept(lines, index)) continue
+
+    for (const [, guarded] of line.matchAll(SCAN)) {
+      if (guarded === undefined) renamed += 1
+      else protectedCount += 1
+    }
+  }
+
+  return { renamed, protectedCount }
+}
+
+/**
+ * The path a file moves to. Runs the same scanner as the content rewrite, so
+ * a protected form appearing in a path is protected there too and the two
+ * halves of the sweep cannot disagree about what the token means.
+ */
+export function renamePath(path: string): string {
+  return renameText(path)
+}