@erclx/canon 4.66.0 → 4.67.0

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

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

package/docs/agents/commands.md

@@ -51,6 +51,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon records push`             | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                                                                                                                                                                             |
 | `canon records pull`             | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                                                                                                                                                                                |
 | `canon migrate rename`           | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                                                                                                                                                                   |
+| `canon migrate skill-names`      | Move the prefixed skill folders onto their two-word names and rewrite every citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                        |
 | `canon migrate records`          | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                                                         |
 | `canon migrate record-tree`      | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)                                                                                                                                                               |
 | `canon migrate rule-layout`      | Move a target's installed rules from the flat `.claude/rules/<subdir>/` layout to `.claude/rules/canon/<subdir>/`, reporting the plan without `--write` (`--root`, `--json`)                                                                                                                                           |
@@ -138,7 +139,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `secrets`   | `scan`                                                                                                                                |
 | `deps`      | `audit`                                                                                                                               |
 | `labels`    | `audit`                                                                                                                               |
-| `migrate`   | `rename`, `records`                                                                                                                   |
+| `migrate`   | `rename`, `skill-names`, `records`                                                                                                    |
 | `autoship`  | `classify`                                                                                                                            |
 | `pr`        | `key-changes`, `head`, `checks`                                                                                                       |
 | `audits`    | `run`, `list`                                                                                                                         |
@@ -153,6 +154,8 @@ 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 skill-names` moves the plugin skills that carried a `claude-` prefix onto their two-word names and rewrites every citation of one. It shares its engine with `migrate rename` and differs in what it is scanning for: a skill name is a whole name rather than a word stem, so it matches only where the word ends, which is what keeps a longer word that merely opens with a skill name, such as `claude-worktrees`, out of it. It takes no `--scope`, since the skill folders it moves are authored in the toolkit and no target holds a copy of that catalog, which leaves a target's own citations of a renamed skill as the whole of what it rewrites there. The changelog and the eval transcripts are passed over on the argument the other sweep already carries, that each records what shipped or what a session ran under whatever name was current then.
+
 `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 nearest non-blank 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.

package/docs/target-projects.md

@@ -173,6 +173,25 @@ canon migrate rule-layout --write --json
 
 The first line reports the plan and the second applies it, relocating each rule and carrying an edited one's recorded hash forward so it still reports as edited on the next sync rather than reading clean. Run it once, ahead of `canon gov sync` or `canon gov install`, on any project scaffolded before this move landed.
 
+### Rename the skill citations, once
+
+Twenty-five plugin skills dropped their `claude-` prefix for two-word names, so `canon:claude-docs` answers as `canon:docs-fold` and `canon:claude-tasks` as `canon:task-board`. A project that installed governance or tooling before that release holds files naming the old ones, and the plugin answers to none of them.
+
+Two of those files run rather than sit there. `.husky/post-merge` prints a command for a person to type, and `.claude/hooks/pr-create-log.sh` hands a session a message naming a skill, so a stale copy tells someone to invoke something that no longer exists. A rule under `.claude/rules/canon/core/` names skills too, though a rule is read rather than run.
+
+Resync what the toolkit owns, then sweep what the project wrote:
+
+```bash
+canon gov sync
+canon tooling sync <stack> . --write
+canon migrate skill-names --json
+canon migrate skill-names --write --json
+```
+
+Run the second line once per stack the project holds, since the two hooks above arrive from different ones. The third reports the plan and the fourth applies it.
+
+The order carries the reason. A sync replaces each toolkit-owned copy with one already carrying the new names, and the sweep afterwards reaches the prose the project wrote itself. Sweeping first rewrites those installed files in place, which moves them off the hash the install recorded, so the next sync reads them as edited by the project and leaves them alone.
+
 ### Check first
 
 `canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.

package/package.json

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

package/src/commands/migrate.ts

@@ -5,6 +5,7 @@ import { listRepositoryFiles } from '@/git-files'
 import { indexSourceRules } from '@/gov/adapter'
 import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
+import { AITK_RULES, type RenameRules } from '@/migrate/rename'
 import {
   applyRecordTree,
   planRecordTree,
@@ -24,6 +25,7 @@ import {
   type RuleLayoutPlan,
   walkFlatRules,
 } from '@/migrate/rule-layout'
+import { SKILL_NAME_MAP, SKILL_NAME_RULES } from '@/migrate/skill-names'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -33,12 +35,15 @@ import {
 } from '@/migrate/scratch-evidence'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { readStamp, stampedHashes } from '@/sync/stamp'
-import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
+import { logError, logInfo, logStep, logWarn, plural } from '@/ui'
 
-interface RenameOptions {
+interface SweepOptions {
   readonly json?: boolean
   readonly write?: boolean
   readonly root?: string
+}
+
+interface RenameOptions extends SweepOptions {
   readonly scope?: string
 }
 
@@ -51,12 +56,11 @@ function isScope(value: string): value is Scope {
 }
 
 /**
- * Reports rather than writes without `--write`, matching `canon 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.
+ * The `aitk` sweep, which is the one rename with a second population to name.
+ * A target holds toolkit-owned folders whose content came from here beside
+ * prose that project wrote, and the scope is what separates them.
  */
 async function runRename(opts: RenameOptions): Promise<number> {
-  const root = opts.root ?? process.cwd()
   const scope = opts.scope ?? 'self'
 
   if (!isScope(scope)) {
@@ -64,6 +68,33 @@ async function runRename(opts: RenameOptions): Promise<number> {
     return 1
   }
 
+  return runSweep(opts, AITK_RULES, scope)
+}
+
+/**
+ * The skill rename owns no scope. Every folder it moves is authored here, and
+ * no target holds a copy of this repository's skill catalog, so there is no
+ * second population for a caller to name.
+ */
+async function runSkillNames(opts: SweepOptions): Promise<number> {
+  return runSweep(opts, SKILL_NAME_RULES, undefined)
+}
+
+/**
+ * One sweep over a repository's tracked files under whichever rules it was
+ * handed.
+ *
+ * Reports rather than writes without `--write`, matching `canon 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 runSweep(
+  opts: SweepOptions,
+  rules: RenameRules,
+  scope: Scope | undefined,
+): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
   const files = await listRepositoryFiles(root)
   if (files === undefined) {
     logError(`Could not list files under ${root}. Is it a git repository?`)
@@ -72,7 +103,7 @@ async function runRename(opts: RenameOptions): Promise<number> {
 
   const scoped = scope === 'target' ? files.filter(isToolkitOwned) : files
   const sources = await readSources(root, scoped)
-  const plan = planRename(sources)
+  const plan = planRename(sources, rules)
 
   // 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
@@ -84,12 +115,15 @@ async function runRename(opts: RenameOptions): Promise<number> {
             root,
             files.filter((f) => !isToolkitOwned(f)),
           ),
+          rules,
         ).entries.length
       : 0
 
+  // 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) {
-    pipeOutput(
-      JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2),
+    process.stdout.write(
+      `${JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2)}\n`,
     )
   }
 
@@ -115,8 +149,12 @@ async function runRename(opts: RenameOptions): Promise<number> {
   return 0
 }
 
-function report(plan: RenamePlan, scope: Scope, citations: number): void {
-  logInfo(`Scope ${scope}.`)
+function report(
+  plan: RenamePlan,
+  scope: Scope | undefined,
+  citations: number,
+): void {
+  if (scope !== undefined) logInfo(`Scope ${scope}.`)
   logInfo(
     `${plural(plan.entries.length, 'file')} to change, ${plural(plan.renamed, 'occurrence')} to rewrite.`,
   )
@@ -138,12 +176,12 @@ function report(plan: RenamePlan, scope: Scope, citations: number): void {
 
 function toRecord(
   plan: RenamePlan,
-  scope: Scope,
+  scope: Scope | undefined,
   citations: number,
   wrote: boolean | undefined,
 ): unknown {
   return {
-    scope,
+    ...(scope === undefined ? {} : { scope }),
     wrote: wrote === true,
     files: plan.entries.length,
     renamed: plan.renamed,
@@ -851,6 +889,45 @@ export function register(program: Command): void {
       process.exitCode = await runRename(opts)
     })
 
+  migrate
+    .command('skill-names')
+    .description('Move the prefixed skill folders onto their two-word names')
+    .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',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Rewrites ${Object.keys(SKILL_NAME_MAP).length} skill names and moves the folders that carry them.`,
+        'It takes no scope. The skill folders it moves are authored in the',
+        'toolkit and no target holds a copy of that catalog, so in a target it',
+        'rewrites citations of a renamed skill and moves nothing.',
+        '',
+        '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, and neither is an eval transcript.',
+        'Each records what shipped or what a session ran under the name that',
+        'was current then.',
+        '',
+        'Examples:',
+        '  canon migrate skill-names',
+        '  canon migrate skill-names --write',
+        '  canon migrate skill-names --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SweepOptions) => {
+      process.exitCode = await runSkillNames(opts)
+    })
+
   migrate
     .command('rule-layout')
     .description('Move installed rules from the flat layout onto canon/')