@erclx/canon 5.31.0 → 5.33.0

package/src/sandbox/provision.ts

@@ -8,7 +8,6 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
-import { probeScenario, stageScenario } from '@/sandbox/hooks'
 import {
   FIXTURE_SUFFIX,
   FIXTURES_DIR,
@@ -34,9 +33,8 @@ import {
 
 /**
  * Provisions one scenario into the sandbox tree, and resets or cleans that tree.
- * A bash scenario's hooks run through `sandbox-hook.sh` and a TypeScript one's
- * arm runs in process through `scenario.ts`, and everything between them runs
- * here, in the order the retired bash dispatcher held.
+ * A scenario's arm runs in process through `scenario.ts`, and everything
+ * around it runs here, in the order the retired bash dispatcher held.
  *
  * Narration is part of the contract. `canon sandbox equivalence` compares the
  * log line for line against the bash harness, so every message, its frame
@@ -403,36 +401,22 @@ interface Scenario {
 
 /**
  * Reads what a scenario declares ahead of provisioning: its config exports and
- * whether it stages from the anchor. A bash scenario answers through the probe,
- * and a TypeScript one from its module, which is also what its stage runs.
+ * whether it stages from the anchor, from its module, which is also what its
+ * stage runs.
  */
 function declareScenario(
   root: string,
   scenario: Scenario,
   env: NodeJS.ProcessEnv,
-):
-  | { kind: 'sh'; file: string; isAnchor: boolean }
-  | { kind: 'ts'; definition: ScenarioDefinition; isAnchor: boolean } {
+): { definition: ScenarioDefinition; isAnchor: boolean } {
   const name = `${scenario.category}/${scenario.command}`
   const resolved = resolveScenarioFile(
     join(root, 'sandbox'),
     scenario.category,
     scenario.command,
   )
-  if (!resolved.ok && resolved.reason === 'ambiguous')
-    fail(
-      `Sandbox script ${name} exists as both .sh and .ts. Delete the one the port replaced.`,
-    )
   if (!resolved.ok) fail(`Sandbox script not found: ${name}`)
 
-  if (resolved.kind === 'sh') {
-    const probe = probeScenario(resolved.file, env)
-    if (!probe.ok) throw new Halt(probe.status)
-    Object.assign(env, probe.exports)
-
-    return { kind: 'sh', file: resolved.file, isAnchor: probe.isAnchor }
-  }
-
   let definition: ScenarioDefinition
   try {
     definition = loadScenario(resolved.file)
@@ -443,7 +427,7 @@ function declareScenario(
   }
   Object.assign(env, scenarioExports(definition, root, env))
 
-  return { kind: 'ts', definition, isAnchor: definition.anchor === true }
+  return { definition, isAnchor: definition.anchor === true }
 }
 
 async function provisionScenario(
@@ -481,21 +465,14 @@ async function provisionScenario(
   // A scenario that execs a verb as its last step hands the run to that verb,
   // whose own frame is the last one written, so nothing follows it here. An
   // in-process arm writes its exports straight into `env`.
-  const staged =
-    declared.kind === 'sh'
-      ? stageScenario(declared.file, env)
-      : {
-          ...(await stageScenarioInProcess(declared.definition, {
-            root,
-            dir: sandbox,
-            env,
-            arm: scenario.arm,
-          })),
-          exports: {},
-        }
+  const staged = await stageScenarioInProcess(declared.definition, {
+    root,
+    dir: sandbox,
+    env,
+    arm: scenario.arm,
+  })
   if (staged.ending === 'replaced') throw new Halt(staged.status, false)
   if (staged.ending === 'exited') throw new Halt(staged.status)
-  Object.assign(env, staged.exports)
 
   const isSkipAutoCommit = (env.SANDBOX_SKIP_AUTO_COMMIT ?? '') !== ''
   const isSkipInject = (env.SANDBOX_SKIP_SKILL_INJECT ?? '') !== ''
@@ -602,7 +579,7 @@ function parseTarget(target: string): { category: string; command: string } {
 }
 
 export interface SandboxRequest {
-  /** False where a caller already opened the frame, as `run.sh` and the picker do. */
+  /** False where a caller already opened the frame, as `canon sandbox run` and the picker do. */
   readonly isHeader: boolean
   /** `<category>:<command>`, `reset`, or `clean`. */
   readonly target: string

package/src/sandbox/scenario.ts

@@ -8,10 +8,19 @@ import {
   readFileSync,
   statSync,
   writeFileSync,
+  writeSync,
 } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join, relative } from 'node:path'
-import { logError, logInfo, logStep, logWarn, palette, select } from '@/cli/ui'
+import {
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  palette,
+  pipeOutput,
+  select,
+} from '@/cli/ui'
 
 /**
  * The TypeScript form of a sandbox scenario: `sandbox/<category>/<command>.ts`,
@@ -33,15 +42,13 @@ export const FIXTURE_SUFFIX = '.fixture'
 /** A scenario whose only arm carries this name routes none, as a bash file with no picker did. */
 export const DEFAULT_ARM_NAME = 'default'
 
-/** Every bash scenario passed this prompt to `select_or_route_scenario`. */
+/** The picker's message unless a scenario names another. */
 const ROUTE_PROMPT = 'Which scenario?'
 
 /** Every scenario that sets the anchor pushes to this one throwaway repository. */
 export const SANDBOX_ANCHOR_REPO = 'canon-sandbox'
 
-const EXTENSIONS = ['.ts', '.sh'] as const
-
-export type ScenarioKind = 'ts' | 'sh'
+const EXTENSION = '.ts'
 
 export type ArmSetup = (ctx: StageContext) => void | Promise<void>
 
@@ -50,6 +57,14 @@ export interface ScenarioDefinition {
   readonly config?: Readonly<Record<string, string>>
   /** Stages the tree from the anchor fixture and names the throwaway remote. */
   readonly anchor?: boolean
+  /**
+   * Stages and narrates ahead of the picker, so the picker's echo lands after
+   * it on the frame. Runs before the arm is
+   * routed, which leaves `ctx.arm` undefined.
+   */
+  readonly prepare?: ArmSetup
+  /** The picker's message, for a scenario that asks something other than the default. */
+  readonly prompt?: string
   /** In routing order, so the first arm is the one a headless caller gets. */
   readonly arms: Readonly<Record<string, ArmSetup>>
 }
@@ -61,43 +76,27 @@ export function scenario(definition: ScenarioDefinition): ScenarioDefinition {
 export interface ScenarioFile {
   readonly command: string
   readonly file: string
-  readonly kind: ScenarioKind
 }
 
 /**
- * Lists the scenarios in one category folder, one per stem. A stem present in
- * both forms is reported apart rather than listed twice, since picking one
- * without saying so is the failure the refusal exists to prevent.
+ * Lists the scenarios in one category folder, one per `.ts` stem. A file in any
+ * other form is ignored rather than refused, so a hand-written leftover does not
+ * break the listing.
  */
 export function listScenarioFiles(categoryDir: string): {
   scenarios: ScenarioFile[]
-  ambiguous: string[]
 } {
-  const byStem = new Map<string, ScenarioFile[]>()
+  const scenarios: ScenarioFile[] = []
   for (const entry of readdirSync(categoryDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue
-    const kind = EXTENSIONS.find((ext) => entry.name.endsWith(ext))
-    if (kind === undefined) continue
-    const command = entry.name.slice(0, -kind.length)
-    const found = byStem.get(command) ?? []
-    found.push({
-      command,
+    if (!entry.isFile() || !entry.name.endsWith(EXTENSION)) continue
+    scenarios.push({
+      command: entry.name.slice(0, -EXTENSION.length),
       file: join(categoryDir, entry.name),
-      kind: kind === '.ts' ? 'ts' : 'sh',
     })
-    byStem.set(command, found)
   }
+  scenarios.sort((a, b) => a.command.localeCompare(b.command))
 
-  const scenarios: ScenarioFile[] = []
-  const ambiguous: string[] = []
-  for (const [command, found] of [...byStem].sort(([a], [b]) =>
-    a.localeCompare(b),
-  )) {
-    if (found.length > 1) ambiguous.push(command)
-    else if (found[0] !== undefined) scenarios.push(found[0])
-  }
-
-  return { scenarios, ambiguous }
+  return { scenarios }
 }
 
 /** Every category folder under `sandbox/`, fixtures excluded. */
@@ -112,21 +111,18 @@ export function listCategories(sandboxDir: string): string[] {
 
 export type ResolvedScenario =
   | ({ readonly ok: true } & ScenarioFile)
-  | { readonly ok: false; readonly reason: 'missing' | 'ambiguous' }
+  | { readonly ok: false; readonly reason: 'missing' }
 
 export function resolveScenarioFile(
   sandboxDir: string,
   category: string,
   command: string,
 ): ResolvedScenario {
-  const found = EXTENSIONS.map((ext) =>
-    join(sandboxDir, category, `${command}${ext}`),
-  ).filter((path) => existsSync(path) && statSync(path).isFile())
-  if (found.length > 1) return { ok: false, reason: 'ambiguous' }
-  const file = found[0]
-  if (file === undefined) return { ok: false, reason: 'missing' }
-
-  return { ok: true, command, file, kind: file.endsWith('.ts') ? 'ts' : 'sh' }
+  const file = join(sandboxDir, category, `${command}${EXTENSION}`)
+  if (!existsSync(file) || !statSync(file).isFile())
+    return { ok: false, reason: 'missing' }
+
+  return { ok: true, command, file }
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -144,7 +140,7 @@ export function loadScenario(file: string): ScenarioDefinition {
   if (!isRecord(definition))
     throw new Error(`${file} has no default export from scenario()`)
 
-  const { arms, config, anchor } = definition
+  const { arms, config, anchor, prepare, prompt } = definition
   if (!isRecord(arms) || Object.keys(arms).length === 0)
     throw new Error(`${file} declares no arms`)
   for (const [name, setup] of Object.entries(arms))
@@ -158,6 +154,10 @@ export function loadScenario(file: string): ScenarioDefinition {
     throw new Error(`${file} config holds a value that is not a string`)
   if (anchor !== undefined && typeof anchor !== 'boolean')
     throw new Error(`${file} anchor is not a boolean`)
+  if (prepare !== undefined && typeof prepare !== 'function')
+    throw new Error(`${file} prepare is not a function`)
+  if (prompt !== undefined && typeof prompt !== 'string')
+    throw new Error(`${file} prompt is not a string`)
 
   return definition as unknown as ScenarioDefinition
 }
@@ -169,7 +169,7 @@ export function armNames(definition: ScenarioDefinition): string[] {
   return names.length === 1 && names[0] === DEFAULT_ARM_NAME ? [] : names
 }
 
-/** Twin of `scripts/config.sh`, which derives the organization from the toolkit's own remote. */
+/** Derives the organization from the toolkit's own remote unless `GITHUB_ORG` names one. */
 function deriveGithubOrg(root: string, env: NodeJS.ProcessEnv): string {
   if ((env.GITHUB_ORG ?? '') !== '') return env.GITHUB_ORG ?? ''
 
@@ -188,8 +188,8 @@ function deriveGithubOrg(root: string, env: NodeJS.ProcessEnv): string {
 }
 
 /**
- * What the bash probe reported for a scenario: its config, the organization
- * `config.sh` derives, and the anchor's repository name. These land in the one
+ * What provisioning reads off a scenario: its config, the derived organization,
+ * and the anchor's repository name. These land in the one
  * environment provisioning passes to every child, the seed and gov installs
  * included.
  */
@@ -225,6 +225,24 @@ export interface RunOptions {
   readonly stderr?: 'inherit' | 'ignore'
   /** Returns a failing status rather than stopping the arm, the `|| true` of the bash form. */
   readonly allowFailure?: boolean
+  /** Set for this command alone, the `NAME=value command` prefix of the bash form. */
+  readonly env?: Readonly<Record<string, string>>
+}
+
+export interface CaptureOptions {
+  /** Relative to the tree, the `cd` of a bash subshell. */
+  readonly cwd?: string
+  /** Fed to the command's stdin, the `<file` or `<<<` of the bash form. */
+  readonly input?: string
+  readonly env?: Readonly<Record<string, string>>
+  /** `inherit` leaves the stream on the terminal, where `pipe` hands it back for a file. */
+  readonly stderr?: 'pipe' | 'inherit' | 'ignore'
+}
+
+export interface Captured {
+  readonly status: number
+  readonly stdout: string
+  readonly stderr: string
 }
 
 export interface StageContext {
@@ -240,6 +258,8 @@ export interface StageContext {
     warn(message: string): void
     /** A bare frame line, the `echo -e "${GREY}│${NC}"` of the bash form. */
     bar(): void
+    /** Indents borrowed output inside the frame, the `pipe_output` of the bash form. */
+    pipe(text: string): void
   }
   fixtures(category: string, command: string, arm: string, stage: string): void
   git(...args: string[]): void
@@ -248,6 +268,18 @@ export interface StageContext {
   run(command: string, args: readonly string[], options?: RunOptions): number
   /** Runs a command and returns its stdout, stopping the arm on a failure. */
   read(command: string, args: readonly string[], options?: RunOptions): string
+  /**
+   * Runs a command and returns both streams with its status, never stopping the
+   * arm. For the `>file 2>file || status=$?` shape, where the outcome is the
+   * record the arm exists to hold.
+   */
+  capture(
+    command: string,
+    args: readonly string[],
+    options?: CaptureOptions,
+  ): Captured
+  /** Writes to a stream the way a bare `cat` or `echo` did, in order with the commands around it. */
+  print(text: string, stream?: 'stdout' | 'stderr'): void
   write(path: string, content: string): void
   append(path: string, content: string): void
   mkdir(path: string): void
@@ -291,14 +323,24 @@ export function createStageContext(options: ContextOptions): StageContext {
     args: readonly string[],
     stdout: 'inherit' | 'ignore' | 'pipe',
     stderr: 'inherit' | 'ignore' | 'pipe',
+    extra: {
+      cwd?: string
+      input?: string
+      env?: Readonly<Record<string, string>>
+    } = {},
   ) => {
-    const stdio: StdioOptions = ['ignore', stdout, stderr]
+    const stdio: StdioOptions = [
+      extra.input === undefined ? 'ignore' : 'pipe',
+      stdout,
+      stderr,
+    ]
 
     return spawnSync(command, [...args], {
-      cwd: dir,
-      env,
+      cwd: extra.cwd === undefined ? dir : join(dir, extra.cwd),
+      env: extra.env === undefined ? env : { ...env, ...extra.env },
       encoding: 'utf8',
       stdio,
+      input: extra.input,
     })
   }
 
@@ -312,6 +354,7 @@ export function createStageContext(options: ContextOptions): StageContext {
       args,
       runOptions.stdout ?? 'inherit',
       runOptions.stderr ?? 'inherit',
+      { env: runOptions.env },
     )
     const status = result.status ?? 1
     if (status !== 0 && runOptions.allowFailure !== true)
@@ -325,7 +368,13 @@ export function createStageContext(options: ContextOptions): StageContext {
     args: readonly string[],
     runOptions: RunOptions = {},
   ): string => {
-    const result = spawn(command, args, 'pipe', runOptions.stderr ?? 'inherit')
+    const result = spawn(
+      command,
+      args,
+      'pipe',
+      runOptions.stderr ?? 'inherit',
+      { env: runOptions.env },
+    )
     const status = result.status ?? 1
     if (status !== 0 && runOptions.allowFailure !== true)
       throw new ScenarioStop(status, 'exited')
@@ -333,6 +382,26 @@ export function createStageContext(options: ContextOptions): StageContext {
     return status === 0 ? result.stdout : ''
   }
 
+  const capture = (
+    command: string,
+    args: readonly string[],
+    captureOptions: CaptureOptions = {},
+  ): Captured => {
+    const result = spawn(
+      command,
+      args,
+      'pipe',
+      captureOptions.stderr ?? 'pipe',
+      captureOptions,
+    )
+
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout ?? '',
+      stderr: result.stderr ?? '',
+    }
+  }
+
   const git = (...args: string[]): void => {
     run('git', args)
   }
@@ -357,8 +426,7 @@ export function createStageContext(options: ContextOptions): StageContext {
 
   /**
    * `gh` answers an absent repository and an unreachable host with one status,
-   * so the 404 alone separates them. Creating is the opt-in, for the reason
-   * `ensure_sandbox_anchor_repo` in `scripts/lib/sandbox-git.sh` records.
+   * so the 404 alone separates them. Creating is the opt-in.
    */
   const ensureAnchorRepo = (org: string, repo: string): void => {
     const probe = spawn(
@@ -413,7 +481,7 @@ export function createStageContext(options: ContextOptions): StageContext {
     git('remote', 'add', 'origin', `https://github.com/${org}/${repo}.git`)
   }
 
-  /** Twin of `stage_fixtures` in `scripts/lib/sandbox-fixtures.sh`. */
+  /** Copies a fixture folder into the tree. */
   const fixtures = (
     category: string,
     command: string,
@@ -476,12 +544,20 @@ export function createStageContext(options: ContextOptions): StageContext {
         const { GREY, NC } = palette(process.stderr)
         process.stderr.write(`${GREY}│${NC}\n`)
       },
+      // `pipe_output` read lines, so an empty body printed nothing at all.
+      pipe: (text) => {
+        if (text !== '') pipeOutput(text)
+      },
     },
     fixtures,
     git,
     commit: (subject) => git('commit', '-m', subject, '--no-verify', '-q'),
     run,
     read,
+    capture,
+    print: (text, stream = 'stdout') => {
+      writeSync(stream === 'stdout' ? 1 : 2, text)
+    },
     write: (path, content) => {
       mkdirSync(dirname(inTree(path)), { recursive: true })
       writeFileSync(inTree(path), content)
@@ -504,17 +580,18 @@ export function createStageContext(options: ContextOptions): StageContext {
 }
 
 /**
- * Picks the arm the way `select_or_route_scenario` did: a routed name first,
+ * Picks the arm: a routed name first,
  * echoed on the frame, then the first arm for a headless caller, then a prompt.
  */
 async function routeArm(
   names: readonly string[],
   env: NodeJS.ProcessEnv,
+  prompt: string,
 ): Promise<string> {
   const echo = (name: string): string => {
     const { GREY, NC, WHITE } = palette(process.stderr)
     process.stderr.write(
-      `${GREY}│${NC}\n${GREY}◇${NC} ${ROUTE_PROMPT} ${WHITE}${name}${NC}\n`,
+      `${GREY}│${NC}\n${GREY}◇${NC} ${prompt} ${WHITE}${name}${NC}\n`,
     )
 
     return name
@@ -533,13 +610,13 @@ async function routeArm(
 
   if (!process.stdin.isTTY) {
     logError(
-      `${ROUTE_PROMPT} requires a TTY. Pass an argument or set CANON_NON_INTERACTIVE=1.`,
+      `${prompt} requires a TTY. Pass an argument or set CANON_NON_INTERACTIVE=1.`,
     )
     throw new ScenarioStop(1, 'exited')
   }
 
   return select({
-    message: ROUTE_PROMPT,
+    message: prompt,
     options: names.map((name) => ({ value: name, label: name })),
   })
 }
@@ -560,8 +637,13 @@ export async function stageScenarioInProcess(
 ): Promise<StageOutcome> {
   try {
     const names = armNames(definition)
+    await definition.prepare?.(
+      createStageContext({ ...options, arm: undefined }),
+    )
     const name =
-      names.length === 0 ? DEFAULT_ARM_NAME : await routeArm(names, options.env)
+      names.length === 0
+        ? DEFAULT_ARM_NAME
+        : await routeArm(names, options.env, definition.prompt ?? ROUTE_PROMPT)
     const setup = Object.hasOwn(definition.arms, name)
       ? definition.arms[name]
       : undefined

package/src/sandbox/tree.ts

@@ -8,11 +8,9 @@ import { join } from 'node:path'
  * in `CANON_SANDBOX_RUN_ID` for the rest of this process, so a script that
  * spawns a child inheriting `process.env` — `canon sandbox run` calling
  * `canon sandbox` to provision and then `canon sandbox check` — resolves the same tree in every one
- * of them, as do the hook and installer children provisioning spawns. A process
+ * of them, as do the installer children provisioning spawns. A process
  * that already carries the variable, inherited from such a parent, reuses it
  * rather than minting a new one.
- *
- * Twin of `mint_sandbox_run_id` in `scripts/lib/sandbox-path.sh`.
  */
 export function mintSandboxRunId(): string {
   const existing = process.env.CANON_SANDBOX_RUN_ID
@@ -28,9 +26,7 @@ export function mintSandboxRunId(): string {
  * per-run default is unit-testable on its own rather than only through the
  * command's registration.
  *
- * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
- * boundary rules out a shared constant, so a change to the default lands on
- * both sides. The fall-through used to be one path per machine, so two
+ * The fall-through used to be one path per machine, so two
  * sessions each resolving the default at once provisioned over each other
  * with neither told; `mintSandboxRunId` gives the path a per-run component
  * instead, which is what makes two such sessions land on two different trees.

package/src/shipped/references.ts

@@ -168,8 +168,8 @@ const DOCS_PATH = /(?<![\w./-])docs\/[^\s`)\]]*\.md\b/g
  * Reported unless `isStandardsPathReportable` reads the match as a
  * deliberate placeholder rather than a real citation. A body illustrating
  * the shape a project's own `standards/<name>.md` takes writes a bracketed
- * token this pattern also matches, such as `standards/<slug>.md` in
- * `create-standard/SKILL.md`, which names no real file. A bare,
+ * token this pattern also matches, such as `standards/<slug>.md`
+ * in a skill that drafts one, which names no real file. A bare,
  * non-bracketed match now reports whether or not the file exists, unlike
  * `DOCS_PATH`, which still gates on existence: a same-repository citation
  * under this corpus names no target project's own tree the way a `docs/`
@@ -206,7 +206,7 @@ const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
  *
  * Anchored on the trailing `\d{3}-[\w-]+\.md` rather than on the bare
  * `.claude/rules/` prefix, which is what keeps a folder mention carrying no
- * number, such as `create-rule`, `memory-review`, and `target-setup` already
+ * number, such as `create-rule`, `target-check`, and `target-setup` already
  * write correctly, from matching. The segment group between `rules/` and the
  * numbered file admits both a governance-namespace path
  * (`canon/canon/604-scratch.md`) and a project-namespace one

package/src/standards/read.ts

@@ -59,7 +59,51 @@ export function standardRoots(root: string): StandardRoot[] {
  * map goes with the verb in the last slice of the retirement.
  */
 const MOVED_STANDARDS: Readonly<Record<string, string>> = {
+  board: 'claude/skills/task-board/references/board.md',
+  context: 'claude/skills/context-fold/references/context.md',
+  design: 'claude/skills/canvas-board/references/design.md',
+  docs: 'claude/skills/docs-sync/references/docs.md',
+  figures: 'claude/skills/draft-figure/references/figures.md',
+  readme: 'claude/skills/docs-sync/references/readme.md',
+  rule: 'claude/skills/create-rule/references/rule.md',
+  skill: 'claude/skills/create-skill/references/skill.md',
+  branch: 'claude/skills/git-branch/references/branch.md',
+  commit: 'claude/skills/git-commit/references/commit.md',
+  pr: 'claude/skills/git-pr/references/pr.md',
+  publish: 'claude/skills/git-pr/references/publish.md',
+  slug: 'claude/skills/git-branch/references/slug.md',
+  versioning: 'claude/skills/git-commit/references/versioning.md',
   markdown: 'claude/skills/markdown-craft/references/markdown.md',
+  canvas: 'claude/skills/canvas-board/references/canvas.md',
+  glossary: 'claude/skills/teach-workspace/references/glossary.md',
+  groundwork: 'claude/skills/plan-groundwork/references/groundwork.md',
+  'groundwork-spikes':
+    'claude/skills/plan-groundwork/references/groundwork-spikes.md',
+  intake: 'claude/skills/plan-intake/references/intake.md',
+  mermaid: 'claude/skills/draft-figure/references/mermaid.md',
+  plan: 'claude/skills/plan-feature/references/plan.md',
+  'plan-lifecycle': 'claude/skills/plan-feature/references/plan-lifecycle.md',
+  ready: 'claude/skills/draft-ready/references/ready.md',
+  requirements: 'claude/skills/draft-doc/references/requirements.md',
+  'skill-paths': 'claude/skills/create-skill/references/skill-paths.md',
+  'skill-practice': 'claude/skills/create-skill/references/skill-practice.md',
+  session: 'claude/skills/session-map/references/session.md',
+  'skill-requirement':
+    'claude/skills/create-skill/references/skill-requirement.md',
+  tasks: 'claude/skills/task-board/references/tasks.md',
+  'tasks-decline': 'claude/skills/task-board/references/tasks-decline.md',
+  teach: 'claude/skills/teach-workspace/references/teach.md',
+  wiki: 'claude/skills/draft-doc/references/wiki.md',
+}
+
+/**
+ * The package-relative path a retired standard now lives at, so a caller that
+ * resolves against a root of its own tests the same map the verb reads.
+ */
+export function movedStandardPath(name: string): string | undefined {
+  if (!Object.hasOwn(MOVED_STANDARDS, name)) return undefined
+
+  return MOVED_STANDARDS[name]
 }
 
 function filename(name: string): string {

package/src/sync/git.ts

@@ -96,7 +96,7 @@ export function pullRequestBody(changes: readonly DomainChange[]): string {
     '',
     `Sync ${domains} from toolkit.`,
     '',
-    '## Key Changes',
+    '## Key changes',
     '',
   ]
 

package/src/sync/seeds-report.ts

@@ -34,7 +34,7 @@ export interface SeedsReport {
  * Classifies every seed the toolkit ships against the target's copy, and never
  * returns a change. Seeds are copy-once files a project is expected to edit, so
  * the engine's copy path would overwrite `CLAUDE.md` wholesale. Reporting alone
- * is what lets `seed-sync` merge one section at a time instead.
+ * is what lets an operator merge one section at a time by hand instead.
  *
  * Attribution reuses the history reader rather than the engine's own recovery
  * pass, which is private and takes a `SyncAdapter` seeds have no way to supply.

package/src/tasks/archive.ts

@@ -578,7 +578,7 @@ function isBulletFor(line: string, target: string): boolean {
 
 /**
  * Resolves the `Plan:` target against the board and against the project root
- * both, which is how `context-fold` reads the same line. It accepts `../plans/x.md`
+ * both, which is how `task-complete` reads the same line. It accepts `../plans/x.md`
  * and `.canon/plans/x.md` as one file, so a gate reading only the first form
  * would pass the second and strand the plan this exists to protect.
  *
@@ -633,7 +633,7 @@ function atOneRoot(path: string, plans: string[], root: string): string {
 /**
  * Names the other live tasks whose `Plan:` line lands on the same file through
  * any of its links. This is
- * the rule `context-fold` applies before it archives a plan, held here so one
+ * the rule the `post-merge` hook applies before it archives a plan, held here so one
  * question has one implementation: a plan another live task still cites is a
  * plan the sweep is correct to leave, and a guard that read the folder instead
  * refused every task sharing one plan and deadlocked the board against the
@@ -697,7 +697,7 @@ export type CitationOutcome = PlanCitations | ArchiveRefused
 
 /**
  * Answers where one task's plan sits and who else holds it, which is the whole
- * of the last-live-citation rule. `context-fold` reads this rather than scanning
+ * of the last-live-citation rule. The archive reads this rather than scanning
  * the board itself, so the sweep that moves a plan and the gate that refuses a
  * task archive cannot drift into disagreeing about which plan is free.
  *
@@ -897,7 +897,7 @@ async function resolveStem(
 
 /**
  * Archives one task as a single unit: the move, the ordering-row removal, and
- * the index regen. The hook and `task-board` both call this, so every gate
+ * the index regen. The hook and `task-complete` both call this, so every gate
  * refuses rather than reports. A caller with nobody watching cannot act on a
  * warning, and two callers gating differently is the drift this exists to stop.
  */
@@ -918,7 +918,7 @@ export async function archiveTask(
   const from = join(dir, `${stem}.md`)
   const text = await readFile(from, 'utf8')
 
-  // `context-fold` ticks outcomes at ship time, before the merge, so an earlier
+  // `task-complete` ticks outcomes at ship time, before the merge, so an earlier
   // slice merging after the last slice shipped would find every box ticked
   // while the last slice is still open. Only the last number closes the task.
   const last = readPullRequest(text).at(-1)