@erclx/canon 4.65.0 → 4.67.0

package/src/design/css.ts

@@ -1,4 +1,6 @@
+import type { Component } from '@/design/components'
 import { COMPONENTS } from '@/design/components'
+import type { FontFace } from '@/design/fonts'
 import { FONT_FACES } from '@/design/fonts'
 import type { DesignTokens } from '@/design/tokens'
 import { TOKENS } from '@/design/tokens'
@@ -113,39 +115,52 @@ ${pairs}
 }`
 }
 
-function componentBlock(): string {
-  return COMPONENTS.map(
-    (component) => `/* ${component.name}
+function componentBlock(components: readonly Component[]): string {
+  return components
+    .map(
+      (component) => `/* ${component.name}
    ${component.note} */
 
 ${component.rules}`,
-  ).join('\n\n')
+    )
+    .join('\n\n')
 }
 
 /**
- * `@font-face` rules carrying the mono stack's primary family as base64, so a
- * stylesheet renders in the same typeface everywhere regardless of what the
- * reader's machine has installed. Only the teach stylesheet opts in today.
+ * `@font-face` rules carrying a font list as base64, so a stylesheet renders
+ * in the same typeface everywhere regardless of what the reader's machine has
+ * installed. Defaults to the mono stack's primary family; teach passes its own
+ * three faces instead of widening this default for every consumer.
  */
-function fontFaceBlock(): string {
-  return FONT_FACES.map(
-    (face) => `@font-face {
+function fontFaceBlock(faces: readonly FontFace[]): string {
+  return faces
+    .map(
+      (face) => `@font-face {
   font-family: '${face.family}';
   font-weight: ${face.weight};
   font-style: normal;
   font-display: swap;
   src: url(data:font/woff2;base64,${face.base64}) format('woff2');
 }`,
-  ).join('\n\n')
+    )
+    .join('\n\n')
 }
 
 export interface CssOptions {
   /** Prepended as a comment, naming what wrote the file and from where. */
   readonly banner?: string
-  /** Component rules ride along by default; a token-only consumer opts out. */
-  readonly components?: boolean
-  /** Off by default. Embeds the mono stack's faces as base64 `@font-face` rules. */
-  readonly embedFonts?: boolean
+  /**
+   * Component rules ride along by default; a token-only consumer opts out
+   * with `false`. Pass an explicit list, such as teach's own chrome set, to
+   * emit those instead of the generic default.
+   */
+  readonly components?: boolean | readonly Component[]
+  /**
+   * Off by default. `true` embeds the mono stack's faces as base64
+   * `@font-face` rules. Pass an explicit list, such as teach's three faces,
+   * to embed those instead.
+   */
+  readonly embedFonts?: boolean | readonly FontFace[]
 }
 
 export function buildDesignCss(
@@ -155,10 +170,22 @@ export function buildDesignCss(
   const banner =
     options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
   const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
-  const parts = options.embedFonts ? [fontFaceBlock(), root] : [root]
+  const faces =
+    options.embedFonts === true
+      ? FONT_FACES
+      : Array.isArray(options.embedFonts)
+        ? options.embedFonts
+        : undefined
+  const parts = faces ? [fontFaceBlock(faces), root] : [root]
   parts.push(lightBlock(tokens))
 
-  if (options.components !== false) parts.push(componentBlock())
+  const components =
+    options.components === false
+      ? undefined
+      : Array.isArray(options.components)
+        ? options.components
+        : COMPONENTS
+  if (components) parts.push(componentBlock(components))
 
   return `${banner}${parts.join('\n\n')}\n`
 }

package/src/exec.ts

@@ -1,11 +1,15 @@
 import { join } from 'node:path'
 import { execa } from 'execa'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
+import { logWarn } from '@/ui'
 
 export async function execScript(
   script: string,
   args: string[],
 ): Promise<void> {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const scriptPath = join(PROJECT_ROOT, 'scripts', script)
   const result = await execa(scriptPath, args, {
     stdio: 'inherit',

package/src/migrate/plan.ts

@@ -1,6 +1,7 @@
 import {
   isExcludedPath,
   renamePath,
+  type RenameRules,
   renameText,
   scanText,
 } from '@/migrate/rename'
@@ -59,20 +60,27 @@ export function isToolkitOwned(path: string): boolean {
  * 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.
+ *
+ * The rules arrive as an argument rather than being read from a module, since
+ * this planner serves every rename the engine compiles and the four calls
+ * below have no other way to say which one they mean.
  */
-export function planRename(sources: readonly RenameSource[]): RenamePlan {
+export function planRename(
+  sources: readonly RenameSource[],
+  rules: RenameRules,
+): RenamePlan {
   const entries: RenameEntry[] = []
   const excluded: string[] = []
 
   for (const source of sources) {
-    if (isExcludedPath(source.path)) {
+    if (isExcludedPath(source.path, rules)) {
       excluded.push(source.path)
       continue
     }
 
-    const movesTo = renamePath(source.path)
-    const rewritten = renameText(source.text)
-    const counts = scanText(source.text)
+    const movesTo = renamePath(source.path, rules)
+    const rewritten = renameText(source.text, rules)
+    const counts = scanText(source.text, rules)
     const moved = movesTo !== source.path
     const changed = rewritten !== source.text
 

package/src/migrate/rename.ts

@@ -1,98 +1,153 @@
 /**
- * The token rewrite behind the `aitk` to `canon` rename.
+ * The token rewrite behind a mechanical 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.
+ *
+ * The token map, the protected forms, and the exclusion set are a parameter
+ * rather than module state, so one engine serves more than one rename. Two
+ * sweeps sharing a module constant would have to agree on a single map, and
+ * the second rename this repository needed shares nothing with the first
+ * except the scanning discipline above.
  */
 
 /**
- * Forms carrying the token that name something other than this tool, matched
- * ahead of the token itself so they pass through untouched.
+ * An article whose agreement the rename breaks.
  *
- * `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.
+ * Stated as a pattern and a replacement rather than a function so a preset is
+ * data a test can read back. It runs against the already-rewritten line, which
+ * is what keeps it clear of the protected forms: a form the scanner passed
+ * through still spells the old token afterward, so it never matches here.
  */
-const PROTECTED = ['aitk-sandbox'] as const
+export interface ArticleFixup {
+  readonly pattern: RegExp
+  readonly replacement: string
+}
+
+/** One rename's rules, as an author states them. */
+export interface RenameRuleSpec {
+  /** Every spelling of the token, and what each becomes. */
+  readonly replacements: Readonly<Record<string, string>>
+  /** Marks a line that names a retired spelling on purpose. */
+  readonly keepMarker: string
+  /** Forms carrying a token that name something the rename leaves alone. */
+  readonly protectedForms?: readonly string[]
+  /** Files whose content is left alone entirely. */
+  readonly excludedPaths?: readonly string[]
+  /** Path prefixes whose files are left alone entirely. */
+  readonly excludedPrefixes?: readonly string[]
+  readonly articleFixups?: readonly ArticleFixup[]
+  /**
+   * Whether a token has to end where the word ends.
+   *
+   * A rename whose tokens are whole names wants this, and one whose tokens are
+   * word stems cannot have it. `aitk` is a stem that legitimately carries a
+   * suffix, as in `aitk-allow-superseded`, so requiring a boundary there would
+   * leave every hyphenated form behind. A skill name is not a stem, and
+   * `claude-worktree` inside `claude-worktrees` is a different subject: the
+   * wiki page about the harness feature, which the rename must not move.
+   */
+  readonly wholeToken?: boolean
+}
 
 /**
- * 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.
+ * A spec with its scanner compiled and its alternatives ordered.
+ *
+ * `tokenOrder` is reported rather than kept private because the ordering is a
+ * correctness property a caller has to be able to assert. A token containing a
+ * shorter token has to be tried first, and reading that off the rewritten
+ * string only works when the two happen to share a destination, which is
+ * correctness by accident rather than by rule.
  */
-const REPLACEMENT: Readonly<Record<string, string>> = {
-  aitk: 'canon',
-  AITK: 'CANON',
-  Aitk: 'Canon',
+export interface RenameRules {
+  readonly replacements: Readonly<Record<string, string>>
+  readonly keepMarker: string
+  readonly protectedForms: readonly string[]
+  readonly tokenOrder: readonly string[]
+  readonly excludedPaths: readonly string[]
+  readonly excludedPrefixes: readonly string[]
+  readonly articleFixups: readonly ArticleFixup[]
+  readonly scan: RegExp
 }
 
 /**
- * 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.
+ * A branch that can never take, standing in for an empty protected list.
+ *
+ * The scanner reads a protected match off capture group 1, so a preset that
+ * protects nothing still has to emit that group or every later group shifts by
+ * one. An empty alternation would match the empty string at every position
+ * instead, which reports a protected hit on every character.
  */
-const SCAN = new RegExp(
-  `(${PROTECTED.join('|')})|(${Object.keys(REPLACEMENT).join('|')})`,
-  'g',
-)
+const NEVER_MATCHES = '(?!)'
 
 /**
- * Files whose content is left alone entirely.
+ * What may not follow a token when a preset asks for whole tokens.
  *
- * 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.
+ * A plain word boundary rejects a following letter and accepts a following
+ * hyphen, since `\b` reads a hyphen as the end of a word. That leaves
+ * `claude-intake` matching inside `claude-intake-answer`, with the ordering of
+ * the alternation the only thing standing between them. Naming the characters
+ * that continue an identifier holds on both, so the ordering and the boundary
+ * each cover what the other could miss, and a slash, a dot, or a backtick
+ * still ends a token.
  */
+const TOKEN_TAIL = '(?![A-Za-z0-9_-])'
+
+function escapeForPattern(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 /**
- * 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.
+ * Longest first, so a token is never consumed by a shorter token it contains.
+ *
+ * The sort is stable, so alternatives of equal length keep the order the
+ * author wrote them in and a preset whose tokens are all one length compiles
+ * to the alternation it already had.
  */
-const EXCLUDED_PREFIXES: readonly string[] = [
-  'src/migrate/',
-  'scripts/eval/result-',
-]
+function longestFirst(values: readonly string[]): readonly string[] {
+  return [...values].sort((left, right) => right.length - left.length)
+}
 
 /**
- * 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.
+ * 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 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',
-]
+function compileScan(
+  protectedForms: readonly string[],
+  tokenOrder: readonly string[],
+  wholeToken: boolean,
+): RegExp {
+  const guarded =
+    protectedForms.length > 0
+      ? protectedForms.map(escapeForPattern).join('|')
+      : NEVER_MATCHES
 
-export interface ScanCount {
-  readonly renamed: number
-  readonly protectedCount: number
+  const tail = wholeToken ? TOKEN_TAIL : ''
+
+  return new RegExp(
+    `(${guarded})|(${tokenOrder.map(escapeForPattern).join('|')})${tail}`,
+    'g',
+  )
 }
 
-export function isExcludedPath(path: string): boolean {
-  if (EXCLUDED_PATHS.includes(path)) return true
-  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix))
+export function defineRenameRules(spec: RenameRuleSpec): RenameRules {
+  const protectedForms = longestFirst(spec.protectedForms ?? [])
+  const tokenOrder = longestFirst(Object.keys(spec.replacements))
+
+  return {
+    replacements: spec.replacements,
+    keepMarker: spec.keepMarker,
+    protectedForms,
+    tokenOrder,
+    excludedPaths: spec.excludedPaths ?? [],
+    excludedPrefixes: spec.excludedPrefixes ?? [],
+    articleFixups: spec.articleFixups ?? [],
+    scan: compileScan(protectedForms, tokenOrder, spec.wholeToken === true),
+  }
 }
 
 /**
@@ -100,54 +155,114 @@ export function isExcludedPath(path: string): boolean {
  * 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.
+ * `an aitk` in the corpus reads wrong the moment the token moves.
  *
  * 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
+const AITK_ARTICLE = /\b([Aa])n(\s+`?)(canon|CANON|Canon)(?![A-Za-z])/g
 
 /**
- * Marks a line that names the retired spelling on purpose.
+ * The `aitk` to `canon` rename.
  *
- * 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.
+ * `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.
+ *
+ * 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.
+ *
+ * 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. An eval result is a transcript on the same argument, recording the
+ * commands a session actually ran under whatever name was current then.
+ *
+ * The sweep's own source is the other excluded member, and it is not a
+ * preference. This module states the `aitk` 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.
+ *
+ * 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 KEEP_MARKER = 'canon-keep-retired'
+export const AITK_RULES: RenameRules = defineRenameRules({
+  replacements: {
+    aitk: 'canon',
+    AITK: 'CANON',
+    Aitk: 'Canon',
+  },
+  keepMarker: 'canon-keep-retired',
+  protectedForms: ['aitk-sandbox'],
+  excludedPrefixes: ['src/migrate/', 'scripts/eval/result-'],
+  excludedPaths: [
+    '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',
+  ],
+  articleFixups: [{ pattern: AITK_ARTICLE, replacement: '$1$2$3' }],
+})
+
+export interface ScanCount {
+  readonly renamed: number
+  readonly protectedCount: number
+}
+
+export function isExcludedPath(path: string, rules: RenameRules): boolean {
+  if (rules.excludedPaths.includes(path)) return true
+  return rules.excludedPrefixes.some((prefix) => path.startsWith(prefix))
+}
 
 /** Rewrites every unprotected spelling of the token. */
-export function renameText(text: string): string {
+export function renameText(text: string, rules: RenameRules): string {
   const lines = text.split('\n')
   const rewritten = lines.map((line, index) =>
-    isKept(lines, index) ? line : renameLine(line),
+    isKept(lines, index, rules) ? line : renameLine(line, rules),
   )
 
   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)
+/**
+ * Whether a line names a 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 a 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.
+ */
+function isKept(
+  lines: readonly string[],
+  index: number,
+  rules: RenameRules,
+): boolean {
+  if (lines[index]?.includes(rules.keepMarker)) return true
+  return index > 0 && (lines[index - 1]?.includes(rules.keepMarker) ?? false)
 }
 
-function renameLine(line: string): string {
-  const replaced = line.replace(SCAN, (match, guarded: string | undefined) =>
-    guarded === undefined ? REPLACEMENT[match] : guarded,
+function renameLine(line: string, rules: RenameRules): string {
+  const replaced = line.replace(
+    rules.scan,
+    (match, guarded: string | undefined) =>
+      guarded === undefined ? rules.replacements[match] : guarded,
   )
 
-  return replaced.replace(
-    ARTICLE,
-    (_match, article: string, gap: string, token: string) =>
-      `${article}${gap}${token}`,
+  return rules.articleFixups.reduce(
+    (text, fixup) => text.replace(fixup.pattern, fixup.replacement),
+    replaced,
   )
 }
 
@@ -156,15 +271,15 @@ function renameLine(line: string): string {
  * 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 {
+export function scanText(text: string, rules: RenameRules): ScanCount {
   let renamed = 0
   let protectedCount = 0
   const lines = text.split('\n')
 
   for (const [index, line] of lines.entries()) {
-    if (isKept(lines, index)) continue
+    if (isKept(lines, index, rules)) continue
 
-    for (const [, guarded] of line.matchAll(SCAN)) {
+    for (const [, guarded] of line.matchAll(rules.scan)) {
       if (guarded === undefined) renamed += 1
       else protectedCount += 1
     }
@@ -178,6 +293,6 @@ export function scanText(text: string): ScanCount {
  * 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)
+export function renamePath(path: string, rules: RenameRules): string {
+  return renameText(path, rules)
 }

package/src/migrate/skill-names.ts

@@ -0,0 +1,89 @@
+import { defineRenameRules, type RenameRules } from '@/migrate/rename'
+
+/**
+ * The twenty-five shipped skills that carried a `claude-` prefix, and the
+ * two-word name each takes instead.
+ *
+ * The plugin namespace already resolves every one of them as `canon:<name>`,
+ * so the prefix bought grouping rather than uniqueness, and the grouping it
+ * bought was the wrong axis: it marked which surface a skill reads rather than
+ * what the skill does. The prefixes that replace it name a phase or a role, so
+ * a listing groups the review triple, the three planning skills, and the three
+ * session roles together.
+ *
+ * Every name takes two words. Ten of these would have landed as a bare single
+ * word under a plain strip, and a bare word such as `review` or `docs` is a
+ * substring of ordinary prose with no token left for a later sweep to find.
+ */
+export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
+  'claude-address-review': 'review-address',
+  'claude-autoship': 'auto-ship',
+  'claude-design-extract': 'design-extract',
+  'claude-diagram': 'draft-diagram',
+  'claude-docs': 'docs-fold',
+  'claude-feature': 'plan-feature',
+  'claude-groundwork': 'plan-groundwork',
+  'claude-intake': 'plan-intake',
+  'claude-intake-answer': 'plan-intake-answer',
+  'claude-markdown-propose': 'markdown-propose',
+  'claude-memory-capture': 'memory-capture',
+  'claude-memory-review': 'memory-review',
+  'claude-orchestrate': 'role-orchestrator',
+  'claude-planner': 'role-planner',
+  'claude-pr-review': 'review-pr',
+  'claude-review': 'review-branch',
+  'claude-seed-sync': 'seed-sync',
+  'claude-standards-audit': 'standards-audit',
+  'claude-tasks': 'task-board',
+  'claude-teach': 'teach-workspace',
+  'claude-ui-test': 'ui-test',
+  'claude-ux-audit': 'ux-audit',
+  'claude-ux-measure': 'ux-measure',
+  'claude-worker': 'role-worker',
+  'claude-worktree': 'session-worktree',
+}
+
+/**
+ * The skill rename.
+ *
+ * It protects nothing. The `aitk` sweep had to guard a sibling repository
+ * whose name contained the token, and no string here contains a skill name
+ * while meaning something else: the one overlap in the map is
+ * `claude-intake` inside `claude-intake-answer`, which the longest-first
+ * ordering settles rather than a protected form. Reading that off the output
+ * would report a pass either way, since both rows land on a name opening with
+ * `plan-intake`, so the ordering is asserted directly.
+ *
+ * It matches whole tokens. A skill name is a complete name rather than a word
+ * stem, and the corpus holds one word that opens with a name and means
+ * something else: `wiki/claude/claude-worktrees.md` documents the harness
+ * feature, not the skill, and every sibling in that folder is named
+ * `claude-<topic>.md` for a Claude Code concept. Sixteen occurrences of it
+ * would have moved to a name the folder's own convention contradicts.
+ *
+ * No article fixup travels with it. `auto-ship` is the one destination opening
+ * on a vowel sound, and the corpus spells an article before it once, which is
+ * cheaper to repair by hand than to state as a rule the rest of the map never
+ * fires.
+ *
+ * The map's own module and its test state the rename rather than using the old
+ * names, so a sweep over them turns each key into its own replacement and
+ * leaves a rewriter that matches nothing. The changelog and an eval transcript
+ * are excluded on the argument the `aitk` preset already carries: each records
+ * what shipped or what a session ran under whatever name was current then, so
+ * rewriting one makes it testify to a release or a run that never happened.
+ *
+ * The record archives need no entry here. They are gitignored, so the tracked
+ * listing every sweep reads never reaches them.
+ */
+export const SKILL_NAME_RULES: RenameRules = defineRenameRules({
+  replacements: SKILL_NAME_MAP,
+  keepMarker: 'canon-keep-retired',
+  wholeToken: true,
+  excludedPrefixes: ['scripts/eval/result-'],
+  excludedPaths: [
+    'CHANGELOG.md',
+    'src/migrate/skill-names.ts',
+    'src/migrate/skill-names.test.ts',
+  ],
+})

package/src/project-root.ts

@@ -51,3 +51,20 @@ export function findCheckoutMismatch(startDir: string): string | undefined {
     dir = parent
   }
 }
+
+/**
+ * The warning line every verb that answers from `PROJECT_ROOT` emits when the
+ * caller's cwd sits inside a second checkout, or `undefined` when it does not.
+ *
+ * It returns the string rather than logging it so this module keeps no `@/ui`
+ * dependency and the wording is unit-testable on its own. The wording names
+ * both roots and no subcommand: the four chokepoints that carry it stand under
+ * eight-plus verbs each, so a per-verb suffix would cost a parameter at every
+ * call site to buy back one verb's exact string.
+ */
+export function checkoutMismatchWarning(cwd: string): string | undefined {
+  const mismatch = findCheckoutMismatch(cwd)
+  if (mismatch === undefined) return undefined
+
+  return `Resolved via ${PROJECT_ROOT}, not the checkout at ${mismatch}. Run \`bun ${mismatch}/src/cli.ts ...\` to answer from that checkout instead.`
+}