@erclx/aitk 3.20.0 → 3.22.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.20.0",
+  "version": "3.22.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/setup-init/SKILL.md

@@ -107,13 +107,13 @@ AITK_NON_INTERACTIVE=1 aitk tooling sync vite-react ./frontend --skip base --wri
 AITK_NON_INTERACTIVE=1 aitk tooling sync python ./backend --skip base --write
 ```
 
-Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs and its own `.claude/tooling/<stack>.md` audit docs.
+Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs, and its own stack reference reads through `aitk tooling reference <stack>`.
 
 Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
 
 - **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
 - **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
-- **Docs.** Open `<target>/.claude/tooling/<tooling-stack>.md` and `<target>/.claude/tooling/web.md` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
+- **Docs.** Run `aitk tooling reference <tooling-stack>` and `aitk tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
 
 Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
 

package/claude/skills/toolkit-cli/SKILL.md

@@ -9,17 +9,17 @@ What each `aitk` sync or install command does to existing files in a target proj
 
 ## Overwrite contract
 
-| Surface                                                  | Command             | Effect on existing files                                          |
-| -------------------------------------------------------- | ------------------- | ----------------------------------------------------------------- |
-| Golden configs, listed in full below                     | `aitk tooling sync` | Overwritten once `--write` is passed. Local edits are lost.       |
-| Dictionary seeds (`.cspell/*.txt`)                       | `aitk tooling sync` | Merged and sorted. Existing terms preserved.                      |
-| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `aitk tooling sync` | Copy-once. Dropped on first install, untouched after.             |
-| Standards                                                | none                | Nothing installs. `aitk standards <name>` reads and never writes. |
-| Seed docs and `CLAUDE.md`                                | `aitk claude init`  | Skipped when present. Never overwritten.                          |
-| Seed docs                                                | `aitk claude sync`  | Never touched. Only `.gitignore` is written.                      |
-| References (`.claude/tooling/<stack>.md`)                | `aitk tooling ref`  | Overwritten.                                                      |
-| `.gitignore`, deps, scripts                              | any sync            | Additive. Existing entries preserved. Deps re-pin on major skew.  |
-| Generated `index.md`                                     | any sync or regen   | Rewritten from target state. Hand edits are lost.                 |
+| Surface                                                  | Command             | Effect on existing files                                                   |
+| -------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------- |
+| Golden configs, listed in full below                     | `aitk tooling sync` | Overwritten once `--write` is passed. Local edits are lost.                |
+| Dictionary seeds (`.cspell/*.txt`)                       | `aitk tooling sync` | Merged and sorted. Existing terms preserved.                               |
+| Other seeds (`cspell.json`, `.lintstagedrc`, state docs) | `aitk tooling sync` | Copy-once. Dropped on first install, untouched after.                      |
+| Standards                                                | none                | Nothing installs. `aitk standards <name>` reads and never writes.          |
+| Seed docs and `CLAUDE.md`                                | `aitk claude init`  | Skipped when present. Never overwritten.                                   |
+| Seed docs                                                | `aitk claude sync`  | Never touched. Only `.gitignore` is written.                               |
+| Stack references                                         | none                | Nothing installs. `aitk tooling reference <stack>` reads and never writes. |
+| `.gitignore`, deps, scripts                              | any sync            | Additive. Existing entries preserved. Deps re-pin on major skew.           |
+| Generated `index.md`                                     | any sync or regen   | Rewritten from target state. Hand edits are lost.                          |
 
 ## What a tooling sync can overwrite
 

package/docs/target-projects.md

@@ -45,8 +45,8 @@ Two steps, in order:
 The chain is:
 
 - `aitk init` installs base tooling, Claude seeds, and governance rules into `.claude/rules/` in the same pass
-- `aitk tooling sync <stack> --write` adds stack-specific deps, scripts, gitignore entries, and drops `.claude/tooling/<stack>.md` (plus parents) as the agent's audit context
-- The agent follows the reference to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
+- `aitk tooling sync <stack> --write` adds stack-specific deps, scripts, and gitignore entries
+- The agent reads `aitk tooling reference <stack>` (plus parents) as its audit context, follows it to generate eslint, vitest, playwright configs and the stack's setup script, and extends `.claude/context/ci.md` and `.claude/context/development.md` per the reference's extend sections <!-- audit-ignore-citations -->
 - `setup-verify` runs the installed `package.json` scripts (lint, typecheck, check, test, build) and reports pass or fail
 
 The chain serves a fresh scaffold and names a destination for the three states it does not. An existing project goes to `aitk:toolkit-operator`, which reads what the project already carries before naming a per-domain command. An install wanting the Claude layer without the tooling chain runs `aitk claude init` for the seed docs and then `aitk:setup-indexes` for the index system. A language the toolkit ships no stack for is the one of the three the chain still runs for, on `base`, with the fallback marked in the preview so it can be declined there.
@@ -175,7 +175,7 @@ Reconcile the configs with `aitk tooling sync <stack> <path> --check` to read wh
 
 `aitk sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence.
 
-It never touches user-owned seed files. Governance rules in `.claude/rules/`, tooling configs, and reference docs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
+It never touches user-owned seed files. Governance rules in `.claude/rules/` and tooling configs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
 
 Standards take no part in that run. Nothing installed them, so there is no copy to reconcile and no `aitk standards sync` to reach for.
 
@@ -184,7 +184,7 @@ Standards take no part in that run. Nothing installed them, so there is no copy
 - Claude seed docs such as `CLAUDE.md` and `.claude/REQUIREMENTS.md`: invoke `aitk:claude-seed-sync`. The skill splits each file into a preamble (between the H1 and the first H2) plus one part per `##` section, then diffs part by part and proposes per-part edits. User customizations are preserved.
 - Governance rules already installed: `aitk gov sync <path>` diffs and applies, and never adds new rules. A rule your recorded stack lists reports as `missing` instead.
 - Tooling configs and seeds: `aitk tooling <stack> <path>` overwrites golden configs and merges seeds
-- Reference docs for a stack: `aitk tooling ref <stack> <path>`
+- Reference docs for a stack: `aitk tooling reference <stack>` reads and never writes, so there is nothing to sync
 - Index regeneration after markdown edits: `aitk indexes regen`
 
 Use a targeted entry point when only one surface moved upstream. Use the catch-all when the toolkit lands a bundled release.
@@ -233,7 +233,7 @@ aitk tooling sync vite-react ./frontend --skip base --write
 aitk tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite) and its own `.claude/tooling/<stack>.md` audit docs.
+`--skip base` drops the `base` layer from each subtree sync, so husky, prettier, cspell, commitlint, and CI stay single at the repo root. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (eslint, vitest, tsconfig, vite), and its own stack reference reads through `aitk tooling reference <stack>`.
 
 ## Running sync from an agent session
 

package/package.json

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

package/src/commands/tooling.ts

@@ -3,7 +3,6 @@ import type { Command } from 'commander'
 import { execScript } from '@/exec'
 import { PROJECT_ROOT } from '@/project-root'
 import {
-  applyReferences,
   injectConfigs,
   injectGitignore,
   injectManifest,
@@ -18,12 +17,14 @@ import {
   resolveChain,
   stackExists,
 } from '@/tooling/manifest'
+import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
 import {
   intro,
   isNonInteractive,
   logAdd,
+  logError,
   logInfo,
   logStep,
   logWarn,
@@ -32,10 +33,9 @@ import {
   select,
 } from '@/ui'
 
-const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
+const PASS_THROUGH_VERBS = ['create', 'verify'] as const
 
 interface SyncOptions {
-  readonly ref?: boolean
   readonly skip?: string
   readonly check?: boolean
   readonly write?: boolean
@@ -64,7 +64,7 @@ type Prepared =
 export function register(program: Command): void {
   const tooling = program
     .command('tooling')
-    .description('Manage tooling stacks (sync, ref, create)')
+    .description('Manage tooling stacks (sync, reference, create)')
     .helpOption('-h, --help', 'Show this help message')
 
   tooling
@@ -73,7 +73,6 @@ export function register(program: Command): void {
     .argument('[stack]', 'Tooling stack name (e.g. base, vite-react)')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
-    .option('--no-ref', 'Skip dropping reference docs')
     .option('--skip <stack>', 'Drop a layer from the extends chain')
     .option('--check', 'Report what would change and write nothing')
     .option('--write', 'Apply every change without prompting')
@@ -134,6 +133,29 @@ export function register(program: Command): void {
       process.exitCode = runList(opts)
     })
 
+  tooling
+    .command('reference')
+    .description("Print a stack's reference doc")
+    .argument('<stack>', 'Tooling stack name (e.g. base, vite-react)')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A stack resolves under tooling/ at the working root, then the corpus',
+        'inside the aitk package. No reference installs into a project, so the',
+        'package corpus is what answers there. The frame names the copy it read.',
+        '',
+        'Examples:',
+        '  aitk tooling reference base',
+        '  aitk tooling reference vite-react',
+        '',
+      ].join('\n'),
+    )
+    .action((stack: string) => {
+      process.exitCode = printReference(stack)
+    })
+
   for (const verb of PASS_THROUGH_VERBS) {
     tooling
       .command(verb)
@@ -172,6 +194,32 @@ function runList(opts: ListOptions): number {
   return 0
 }
 
+/**
+ * Writes the reference to stdout and every frame line to stderr, so a caller
+ * capturing the output with `$(...)` receives the document alone. Mirrors
+ * `print` in `src/commands/standards.ts`.
+ */
+function printReference(stack: string): number {
+  intro('aitk tooling reference')
+
+  const root = process.cwd()
+  const resolved = resolveReference(root, stack)
+
+  if (!resolved) {
+    logWarn(`Unknown stack: ${stack}`)
+    logStep('Available stacks')
+    for (const each of listStacks(PROJECT_ROOT)) logInfo(each)
+    logError("Run 'aitk tooling list' for descriptions.")
+    outro()
+    return 1
+  }
+
+  logStep(resolved.source)
+  process.stdout.write(readReference(resolved))
+  outro()
+  return 0
+}
+
 /**
  * Resolves the chain and rejects the same inputs the bash rejected, so a bad
  * stack name fails before anything touches the target.
@@ -248,10 +296,9 @@ async function runSync(
     return 1
   }
 
-  const includeReferences = opts.ref !== false
-  const result = scan(prepared.chain, prepared.target, { includeReferences })
+  const result = scan(prepared.chain, prepared.target)
 
-  report(result, includeReferences)
+  report(result)
 
   const mode = resolveWriteMode(opts)
   const { GREEN, NC } = palette(process.stderr)
@@ -290,15 +337,6 @@ async function runSync(
   await injectSeeds(prepared.chain, prepared.target)
   await injectManifest(prepared.chain, prepared.target)
 
-  const pending = result.references
-    .filter((entry) => entry.state === 'pending')
-    .map((entry) => entry.stack)
-
-  if (pending.length > 0) {
-    logStep('Applying references')
-    await applyReferences(prepared.chain, prepared.target, pending)
-  }
-
   await stampChain(prepared.chain, prepared.target)
 
   outro()
@@ -448,7 +486,7 @@ async function promptForStack(): Promise<string | undefined> {
   })
 }
 
-function report(result: ScanResult, includeReferences: boolean): void {
+function report(result: ScanResult): void {
   logStep('Scanning configs')
   for (const entry of result.configs) {
     if (entry.state === 'matching') logInfo(entry.rel)
@@ -483,16 +521,6 @@ function report(result: ScanResult, includeReferences: boolean): void {
   for (const entry of result.gitignore) {
     if (entry.state === 'missing') logAdd(entry.entry)
   }
-
-  if (!includeReferences) return
-
-  logStep('Scanning references')
-  for (const entry of result.references) {
-    if (entry.state === 'matching') logInfo(`.claude/tooling/${entry.stack}.md`)
-  }
-  for (const entry of result.references) {
-    if (entry.state === 'pending') logAdd(`.claude/tooling/${entry.stack}.md`)
-  }
 }
 
 function reportPackage(result: ScanResult): void {
@@ -540,10 +568,6 @@ function summarize(result: ScanResult): string {
     result.gitignore.filter((entry) => entry.state === 'missing').length,
     'gitignore',
   )
-  add(
-    result.references.filter((entry) => entry.state === 'pending').length,
-    'refs',
-  )
 
   return parts.join(', ')
 }

package/src/sync/check.ts

@@ -103,7 +103,6 @@ export interface ToolingCounts {
   readonly scripts: number
   readonly deps: number
   readonly gitignore: number
-  readonly references: number
 }
 
 /**
@@ -134,7 +133,6 @@ const UNMEASURED_TOOLING: ToolingReport = {
     scripts: 0,
     deps: 0,
     gitignore: 0,
-    references: 0,
   },
   changes: 0,
 }
@@ -219,7 +217,7 @@ export function buildToolingReport(
 
   if (manifests.length === 0) return { ...UNMEASURED_TOOLING, chain }
 
-  const result = scan(manifests, target, { includeReferences: true })
+  const result = scan(manifests, target)
   const record = stamp?.domains.tooling
 
   return {
@@ -236,8 +234,6 @@ export function buildToolingReport(
       deps: result.deps.filter((entry) => entry.state === 'missing').length,
       gitignore: result.gitignore.filter((entry) => entry.state === 'missing')
         .length,
-      references: result.references.filter((entry) => entry.state === 'pending')
-        .length,
     },
     changes: result.totalChanges,
   }

package/src/tooling/inject.ts

@@ -1,12 +1,5 @@
 import { existsSync } from 'node:fs'
-import {
-  copyFile,
-  mkdir,
-  readFile,
-  rm,
-  rmdir,
-  writeFile,
-} from 'node:fs/promises'
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
@@ -198,33 +191,3 @@ export async function injectManifest(
 
   await injectGitignore(chain, target)
 }
-
-/**
- * Drops reference docs into `.claude/tooling/`, clearing the legacy
- * `tooling/` location the earlier layout used.
- */
-export async function applyReferences(
-  chain: readonly Manifest[],
-  target: string,
-  stacks: readonly string[],
-): Promise<string[]> {
-  const destDir = join(target, '.claude', 'tooling')
-  await mkdir(destDir, { recursive: true })
-
-  const applied: string[] = []
-  const byName = new Map(chain.map((manifest) => [manifest.name, manifest]))
-
-  for (const stack of stacks) {
-    const manifest = byName.get(stack)
-    if (!manifest) continue
-
-    await copyFile(manifest.referenceFile, join(destDir, `${stack}.md`))
-    logAdd(`.claude/tooling/${stack}.md`)
-    applied.push(stack)
-    await rm(join(target, 'tooling', `${stack}.md`), { force: true })
-  }
-
-  await rmdir(join(target, 'tooling')).catch(() => {})
-
-  return applied
-}

package/src/tooling/manifest.ts

@@ -14,7 +14,6 @@ export interface Manifest {
   readonly dir: string
   readonly configsDir: string
   readonly seedsDir: string
-  readonly referenceFile: string
   readonly scripts: Readonly<Record<string, string>>
   readonly scriptOverrides: Readonly<Record<string, string>>
   readonly gitignore: readonly GitignoreSection[]
@@ -100,7 +99,6 @@ export function loadManifest(
     dir,
     configsDir: join(dir, 'configs'),
     seedsDir: join(dir, 'seeds'),
-    referenceFile: join(dir, 'reference.md'),
     scripts: pickStrings(scriptsTable),
     scriptOverrides: pickStrings(asTable(scriptsTable.override)),
     gitignore: readGitignoreSections(asTable(parsed.gitignore)),

package/src/tooling/read.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+
+/**
+ * Spells the package root in a report where every other root spells a
+ * project-relative path. The `source` field promises a path inside the project
+ * and a package copy is the one source that promise cannot cover, so the
+ * spelling has to be one nothing will join to a project root.
+ */
+const PACKAGE_LABEL = '<aitk>'
+
+export interface ReferenceRoot {
+  /** Absolute `tooling/` directory to search. */
+  readonly dir: string
+  /** How a report spells a copy found under this root. */
+  readonly label: string
+}
+
+export interface ResolvedReference {
+  readonly path: string
+  /** The label of the root that won, joined to the stack and filename. */
+  readonly source: string
+}
+
+function toolingSourceDir(root: string): string {
+  return join(root, 'tooling')
+}
+
+/**
+ * The roots a stack reference resolves against, mirroring `standardRoots` in
+ * `src/standards/read.ts`. No stack reference installs into a project any
+ * more, so the package corpus is the only root that answers there. The
+ * authoring root stays ahead of it for the toolkit's own repository, which
+ * authors the corpus this reads, and for a project authoring stacks of its
+ * own under the same layout.
+ */
+export function referenceRoots(root: string): ReferenceRoot[] {
+  return [
+    { dir: toolingSourceDir(root), label: 'tooling' },
+    {
+      dir: toolingSourceDir(PROJECT_ROOT),
+      label: join(PACKAGE_LABEL, 'tooling'),
+    },
+  ]
+}
+
+/** Resolves a stack's reference doc, working root first. */
+export function resolveReference(
+  root: string,
+  stack: string,
+): ResolvedReference | undefined {
+  for (const { dir, label } of referenceRoots(root)) {
+    const path = join(dir, stack, 'reference.md')
+    if (existsSync(path)) {
+      return { path, source: join(label, stack, 'reference.md') }
+    }
+  }
+
+  return undefined
+}
+
+export function readReference(reference: ResolvedReference): string {
+  return readFileSync(reference.path, 'utf8')
+}

package/src/tooling/scan.ts

@@ -26,26 +26,16 @@ export interface EntryState {
   readonly state: 'missing' | 'present'
 }
 
-export interface ReferenceState {
-  readonly stack: string
-  readonly state: 'pending' | 'matching'
-}
-
 export interface ScanResult {
   readonly configs: readonly ConfigState[]
   readonly seeds: readonly SeedState[]
   readonly scripts: readonly ScriptState[]
   readonly deps: readonly DepState[]
   readonly gitignore: readonly EntryState[]
-  readonly references: readonly ReferenceState[]
   readonly hasPackageJson: boolean
   readonly totalChanges: number
 }
 
-export interface ScanOptions {
-  readonly includeReferences: boolean
-}
-
 function isIdentical(a: string, b: string): boolean {
   if (!existsSync(b)) return false
   return readFileSync(a).equals(readFileSync(b))
@@ -55,14 +45,10 @@ function isIdentical(a: string, b: string): boolean {
  * Compares every stack in the chain against the target and reports what would
  * change. Nothing is written. Which stack wins a duplicate differs per
  * category and mirrors the bash: configs, seeds, and scripts resolve nearest
- * stack first, while dependencies, gitignore entries, and references resolve
- * from the furthest ancestor inward.
+ * stack first, while dependencies and gitignore entries resolve from the
+ * furthest ancestor inward.
  */
-export function scan(
-  chain: readonly Manifest[],
-  target: string,
-  options: ScanOptions,
-): ScanResult {
+export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const configs: ConfigState[] = []
   const seenConfigs = new Set<string>()
 
@@ -109,17 +95,12 @@ export function scan(
     : ''
   const gitignore = scanGitignore(chain, gitignoreContent)
 
-  const references = options.includeReferences
-    ? scanReferences(chain, target)
-    : []
-
   const totalChanges =
     configs.filter((entry) => entry.state !== 'matching').length +
     seeds.filter((entry) => entry.state === 'missing').length +
     scripts.filter((entry) => entry.state !== 'matching').length +
     deps.filter((entry) => entry.state === 'missing').length +
-    gitignore.filter((entry) => entry.state === 'missing').length +
-    references.filter((entry) => entry.state === 'pending').length
+    gitignore.filter((entry) => entry.state === 'missing').length
 
   return {
     configs,
@@ -127,7 +108,6 @@ export function scan(
     scripts,
     deps,
     gitignore,
-    references,
     hasPackageJson: pkg !== undefined,
     totalChanges,
   }
@@ -165,22 +145,3 @@ function scanGitignore(
 
   return states
 }
-
-function scanReferences(
-  chain: readonly Manifest[],
-  target: string,
-): ReferenceState[] {
-  const states: ReferenceState[] = []
-
-  for (const manifest of ancestorsFirst(chain)) {
-    if (!existsSync(manifest.referenceFile)) continue
-
-    const dest = join(target, '.claude', 'tooling', `${manifest.name}.md`)
-    states.push({
-      stack: manifest.name,
-      state: isIdentical(manifest.referenceFile, dest) ? 'matching' : 'pending',
-    })
-  }
-
-  return states
-}

package/standards/plan.md

@@ -123,7 +123,7 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.claude/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it.
+- Move the plan to `.claude/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.claude/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
 ## Anti-patterns

package/standards/tasks.md

@@ -217,7 +217,7 @@ Phase-label format and where labels may appear are governed by `standards/versio
 
 `Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans/archive/feature-<slug>.md`, and at `../../plans/archive/feature-<slug>.md` once the task itself is archived a folder deeper. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
 
-A project that archived plans before the folder nested under `.claude/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. Nothing migrates them, and a task retargeted without its plan moving leads nowhere.
+A project that archived plans before the folder nested under `.claude/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. A named route now moves the folder and retargets its pointers together, but no automation runs it, so an unmigrated project keeps holding the old spelling until someone does, and a task retargeted without its plan moving leads nowhere.
 
 One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
@@ -249,6 +249,8 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 
 Never delete a task file. A shipped task moves to `.claude/tasks/archive/` under its own name, and the live index regenerates without it. `aitk tasks archive` owns the move, the ordering-row removal, and the index regen as one unit.
 
+The archive nests inside `.claude/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`. Nesting is what lets a reader tell the two shapes apart on sight: the flat sibling is what a binary predating this convention still writes, so meeting one names an older checkout rather than a second archive to reconcile against this one.
+
 Two callers reach that command. The `claude-tasks` skill runs it inside a session, and the `post-merge` hook runs it unattended after a pull that merged the work. Both go through the command rather than moving the file themselves, so the two paths cannot drift into archiving differently. Every gate the command applies refuses with a non-zero exit rather than reporting, because a caller with nobody watching cannot act on a warning.
 
 One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.

package/scripts/tooling/ref.sh

@@ -1,147 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/tooling.sh"
-trap close_timeline EXIT
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  log_step "Tooling ref usage"
-  echo -e "${GREY}│${NC}  ${WHITE}Usage:${NC} aitk tooling ref [stack] [target-path]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Drops reference docs only. No config or dependency changes."
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Arguments:${NC}"
-  echo -e "${GREY}│${NC}    stack         Name of the tooling stack (e.g., base, vite-react)"
-  echo -e "${GREY}│${NC}    target-path   Target directory (default: current directory)"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-select_stack() {
-  local stacks=()
-  mapfile -t stacks < <(list_tooling_stacks)
-
-  if [ ${#stacks[@]} -eq 0 ]; then
-    log_error "No tooling stacks found in $PROJECT_ROOT/tooling"
-  fi
-
-  select_option "Select tooling stack:" "${stacks[@]}"
-  echo "$SELECTED_OPTION"
-}
-
-collect_references() {
-  local stack="$1"
-  local target="$2"
-  local -n _pending=$3
-
-  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
-  [ ! -f "$manifest" ] && return
-
-  local extends
-  extends=$(grep '^extends' "$manifest" 2>/dev/null | cut -d'"' -f2)
-
-  if [ -n "$extends" ]; then
-    collect_references "$extends" "$target" "$3"
-  fi
-
-  local reference_file="$PROJECT_ROOT/tooling/$stack/reference.md"
-  [ ! -f "$reference_file" ] && return
-
-  local dest="$target/.claude/tooling/$stack.md"
-
-  if [ -f "$dest" ] && diff -q "$reference_file" "$dest" >/dev/null 2>&1; then
-    log_info ".claude/tooling/$stack.md"
-    return
-  fi
-
-  log_add ".claude/tooling/$stack.md"
-  _pending+=("$stack")
-}
-
-apply_references() {
-  local target="$1"
-  shift
-  local stacks=("$@")
-
-  mkdir -p "$target/.claude/tooling"
-
-  for stack in "${stacks[@]}"; do
-    local src="$PROJECT_ROOT/tooling/$stack/reference.md"
-    cp "$src" "$target/.claude/tooling/$stack.md"
-    log_add ".claude/tooling/$stack.md"
-    rm -f "$target/tooling/$stack.md"
-  done
-  rmdir "$target/tooling" 2>/dev/null || true
-}
-
-main() {
-  if [[ "$1" == "-h" || "$1" == "--help" ]]; then
-    show_help
-  fi
-
-  local stack="$1"
-  local target="${2:-.}"
-
-  # Every frame below goes to stderr, so it asks about that stream rather than
-  # reading the source-time answer, which is for stdout and is what `show_help`
-  # above wants. Declared after the help branch so that call keeps it.
-  local GREEN RED YELLOW WHITE GREY NC
-  set_palette 2
-
-  echo -e "${GREY}┌${NC}" >&2
-  echo -e "${GREY}│${NC} ${WHITE}aitk tooling ref${NC}" >&2
-
-  if [ -z "$stack" ]; then
-    stack=$(select_stack)
-  fi
-
-  if is_tooling_stack_excluded "$stack"; then
-    log_error "Claude is managed by \`aitk claude\`, not \`aitk tooling\`."
-  fi
-
-  if [ ! -d "$PROJECT_ROOT/tooling/$stack" ]; then
-    log_error "Stack not found: $stack"
-  fi
-
-  guard_root "$target"
-
-  local pending=()
-
-  echo -e "${GREY}├${NC} ${WHITE}Scanning references: $stack${NC}" >&2
-  collect_references "$stack" "$target" pending
-
-  if [ "${#pending[@]}" -eq 0 ]; then
-    trap - EXIT
-    echo -e "${GREY}└${NC}\n" >&2
-    echo -e "${GREEN}✓ References up to date${NC}" >&2
-    exit 0
-  fi
-
-  local dest_display="$target/.claude/tooling/"
-  dest_display="${dest_display#./}"
-
-  select_option "Sync ${#pending[@]} reference(s) to $dest_display?" "Yes" "No"
-
-  if [ "$SELECTED_OPTION" = "No" ]; then
-    log_warn "Cancelled"
-    exit 0
-  fi
-
-  log_step "Applying changes"
-  apply_references "$target" "${pending[@]}"
-
-  trap - EXIT
-  echo -e "${GREY}└${NC}\n" >&2
-  echo -e "${GREEN}✓ References synced${NC}" >&2
-}
-
-main "$@"