@erclx/aitk 3.19.0 → 3.21.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.19.0",
+  "version": "3.21.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/create-rule/REQUIREMENT.md

@@ -1,39 +1,41 @@
 ---
 name: create-rule
-description: Why a project-local rule needs a band, a number checked against two catalogs, and a scope key that decides when it fires
+description: Why a project-local rule needs a subdir, a number from the band reserved for one, and a scope key that decides when it fires
 ---
 
 # Create rule requirement
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names, but the band still needs a free number to stay readable against the toolkit's own numbering.
+Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names.
 
-The band gets picked by feel, so a UI copy rule lands in the always-on range and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
+Numbering in `900-999` closes the other half. A number scanned against today's toolkit catalog goes stale on the next release, and a reserved band does not.
+
+The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
 
 ## Must
 
 - Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
-- Pick the band from the topic and take its number range and folder from that choice
+- Pick the subdir from the topic and take the folder from that choice
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
-- Check both the target's used prefixes and the toolkit catalog before taking a number
+- Take the lowest free number at or above `900`, scanning every project subdir the target holds rather than one
 - Read the rule standard before writing the body
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
-- Preview the resolved path, band, number, and frontmatter, then write without pausing
+- Preview the resolved path, subdir, number, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently
 
 ## Must not
 
 - Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
 - Work the body shape or the frontmatter from memory
-- Take a number without checking the toolkit catalog, which is the collision that surfaces later
+- Take a number below `900`, which a later toolkit release can ship into
 - Write more than one topic into a single rule
 
 ## Guards
 
 - No project Claude directory: stop, since there is nowhere for the rule to live
 - The request names no behavior to enforce: stop rather than inventing one
-- The toolkit CLI is not on PATH: scan the target alone and warn that a later install could collide
+- The reserved band holds no free number: stop rather than reaching below `900`
 
 ## Out of scope
 

package/claude/skills/create-rule/SKILL.md

@@ -5,7 +5,7 @@ description: Scaffolds a project-specific governance rule into `.claude/rules/pr
 
 # Create rule
 
-Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `aitk gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog.
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `aitk gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog. A rule written anywhere else under `.claude/rules/` survives the sync too, and the report offers it the path under the project subfolder it would take.
 
 ## Guards
 
@@ -19,30 +19,30 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 - What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
 - Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
 
-## Step 2: resolve band and subdir
+## Step 2: resolve the subdir
 
-Pick the band from the topic. Each band owns a number range and a subdir under `.claude/rules/project/`:
+Pick the subdir from the topic. It sits under `.claude/rules/project/` and names the rule's domain:
 
-- `core/` 000-099: global persona, testing, error handling, planning. Always-on, no `paths:`.
-- `lang/` 100-199: one programming language.
-- `framework/` 200-299: one framework.
-- `lib/` 300-399: one library or tool.
-- `ui/` 400-499: UI copy, accessibility, forms.
-- `claude/` 500-599: `.claude/` authoring surfaces.
+- `core/`: global persona, testing, error handling, planning. Always-on, no `paths:`.
+- `lang/`: one programming language.
+- `framework/`: one framework.
+- `lib/`: one library or tool.
+- `ui/`: UI copy, accessibility, forms.
+- `claude/`: `.claude/` authoring surfaces.
 
 ## Step 3: pick a free number
 
-Pick the lowest unused number in the band that collides with neither the project nor the toolkit catalog:
+A project-authored rule numbers in `900-999`, the band reserved for one. `000-899` belongs to the toolkit, so a number free in the target today is one a later release can ship into.
 
-- Scan the target's `.claude/rules/project/<subdir>/` for used prefixes.
-- Run `aitk gov list --json 2>/dev/null` and read the shipped rule numbers in the same range, so the band stays readable against the toolkit's own numbering even though location already keeps a later `aitk gov install` from touching this file.
-- If `aitk` is not on PATH, scan the target only and warn that the band could read confusingly against a later toolkit install.
+- Scan every `.claude/rules/project/<subdir>/` in the target for used prefixes, not only the subdir this rule lands in. The band runs as one sequence across all of them.
+- Take the lowest unused number at or above `900`.
+- Stop and say so if the band is full, rather than reaching below `900`.
 
 ## Step 4: write the rule
 
 Read `${CLAUDE_SKILL_DIR}/../../standards/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
 
-Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, band, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
 
 Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
 

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/agents/install-and-sync.md

@@ -16,6 +16,21 @@ is left alone regardless of its name, since that subfolder is project-authored
 by location. It also removes a stale `.claude/GOV.md`
 from the retired build. Use `aitk gov install` to add rules.
 
+A rule the toolkit finds no source for, sitting in a shared subdirectory rather
+than under `.claude/rules/project/`, is reported with the path under that
+subfolder it would take. The offer is conditional on the project having written
+the rule, since a rule the toolkit shipped and later renamed reaches the same
+line, and moving one there would mark it the project's for good. Nothing is
+moved either way, because a rule's installed path is one the project's own
+rules, skills, and docs may cite. `aitk standards rule` carries the reserved
+number bands behind that placement, where `900-999` is the range a
+project-authored rule takes and everything below it belongs to the toolkit.
+
+`aitk snippets sync` reports the same way for a snippet outside
+`.claude/snippets/project/`, since both adapters declare the subfolder.
+`aitk sync --check` does not. It skips every orphaned entry, so the destination
+reaches the two domain sync verbs alone.
+
 When the target's install recorded a stack, `aitk gov sync` also reports a
 rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry
 carrying no change. This is what makes a target whose recorded sync point

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/governance/rules/claude/590-rule-authoring.md

@@ -8,8 +8,10 @@ paths:
 
 ## Numbering
 
-- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`, taking a number that collides with neither the project's rules nor any installed shared set.
-- Give every rule a numeric prefix and keep the slug to one to three kebab words.
+- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`. Give every rule a numeric prefix and keep the slug to one to three kebab words.
+- Treat `000-899` as reserved for a rule set that ships to targets, `000-599` across the shared subdirectories and `600-899` held for ones it has not added.
+- Number a rule the project authored itself in `900-999` and write it at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`.
+- Do not take a reserved number for a project-authored rule because nothing installed holds it today. A later release can ship into it.
 
 ## Body
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.19.0",
+  "version": "3.21.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/sync/engine.ts

@@ -81,9 +81,10 @@ export interface ScanEntry {
   /** Toolkit revision this file's content came from, when history proved it. */
   readonly since?: string
   /**
-   * Overrides `report`'s generic text for this entry's state. `collectMissing`
-   * is the one producer: a stack name is only known to the adapter that
-   * resolved it, and the generic `missing` line cannot carry one.
+   * Overrides `report`'s generic text for this entry's state. Two producers
+   * write one: `collectMissing`, since a stack name is only known to the
+   * adapter that resolved it, and an orphan sitting outside the declared
+   * project subfolder, since the generic line names no destination.
    */
   readonly notice?: string
 }
@@ -143,6 +144,9 @@ export interface SyncAdapter {
    * location rather than by the name inference `locateSource` runs.
    * Checked before `locateSource`, so a file here is orphaned even when its
    * name also matches a toolkit source, and never enters the stamp.
+   *
+   * Declaring it also gives the report a destination to name when the name
+   * inference orphans a file sitting anywhere else.
    */
   readonly projectSubdir?: string
   /** Defaults to applying. */
@@ -200,7 +204,7 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     const source = adapter.locateSource(file)
 
     if (source === undefined || !existsSync(source)) {
-      entries.push({ state: 'orphaned', rel: file.rel })
+      entries.push(misplacedOrphan(adapter, target, file))
       continue
     }
 
@@ -419,7 +423,8 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
       logWarn(
         entry.notice ?? `${entry.rel} (listed by the stack, not installed)`,
       )
-    else logWarn(`${entry.rel} (not in toolkit source, skipping)`)
+    else
+      logWarn(entry.notice ?? `${entry.rel} (not in toolkit source, skipping)`)
   }
 
   for (const surface of plan.retired) {
@@ -486,6 +491,43 @@ function isProjectAuthored(adapter: SyncAdapter, file: InstalledFile): boolean {
   return file.relToRoot.split('/')[0] === adapter.projectSubdir
 }
 
+/**
+ * An orphan the name inference caught rather than the location test. No source
+ * name matched, which is what a project-authored file looks like and also what
+ * a file the toolkit shipped and later renamed looks like, so the line offers
+ * the destination on a condition rather than asserting who wrote the file.
+ * Moving a toolkit leftover into the project subfolder would mark it the
+ * project's permanently, and only the operator can tell the two apart.
+ *
+ * The stamp cannot tell them apart either. `recordStamp` skips a file whose
+ * source is gone and `writeStamp` replaces the domain's whole `files` map, so
+ * a renamed rule's entry survives exactly one sync past the rename, and a
+ * target installed before stamping shipped has no entry to read at all.
+ *
+ * Naming the destination is all this does. Moving the file rewrites a path the
+ * project's own rules, skills, and docs may cite, so the sync leaves it where
+ * it is.
+ */
+function misplacedOrphan(
+  adapter: SyncAdapter,
+  target: string,
+  file: InstalledFile,
+): ScanEntry {
+  const subdir = adapter.projectSubdir
+  if (subdir === undefined) return { state: 'orphaned', rel: file.rel }
+
+  const belongs = relative(
+    target,
+    resolve(adapter.installedRoot(target), subdir, file.relToRoot),
+  )
+
+  return {
+    state: 'orphaned',
+    rel: file.rel,
+    notice: `${file.rel} (not in toolkit source, skipping. Move it to ${belongs} if the project authored it.)`,
+  }
+}
+
 function isInside(target: string, path: string): boolean {
   const rel = relative(target, path)
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)

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/rule.md

@@ -33,17 +33,27 @@ Write both when both apply. A rule stating the directive and a skill stating how
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
 - Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`
-- `<n>` is a number in the subdirectory's band and `<slug>` is a one-to-three-word kebab topic
-- Scaffold a rule with a number that collides with neither the project's rules nor any installed shared rule set
+- `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
+- A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, keeping the same subdirectory names
 - Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
 
+## Reserved numbers
+
+`000-899` is reserved for a rule set that ships to targets. `000-599` is what the six subdirectories above already divide, at 100 per subdirectory, and `600-899` is held for subdirectories a shipped set has not added yet.
+
+A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.
+
+The cost is that a project-authored rule's leading digit stops naming its domain. Its subdirectory names it instead, and install preserves that either way. What a shared band costs is worse: a session that loads two rules reading as one number, with nothing in the folder to say which is which.
+
+`aitk gov sync` reports a rule it finds no toolkit source for, outside `.claude/rules/project/`, and offers the path under it. The offer is conditional on the project having authored the rule, because a rule the toolkit shipped and later renamed looks identical from the outside and moving one there would mark it the project's for good. Nothing is moved either way, since a rule's installed path is one the project's own rules, skills, and docs may cite.
+
 ## Two sources numbering into one folder
 
-A shared rule set and a project's own rules land in the same installed folder and draw from the same band, so the two need a division or they collide. Divide the band by source rather than by topic: one source takes the top of each band and the other takes the gaps between the tens. A rule set that ships to targets should take the tens, since it is the source a project cannot renumber.
+The reservation above divides one pair, being a shipped set against the rules a project wrote for itself. A third source numbering into the same folder needs its own division, which is the case for a rule set held back from targets and installed only where it was authored. Divide by source rather than by topic: one source takes the top of each subdirectory's band and the other takes the gaps between the tens.
 
-The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks the division, so it holds only while both sources follow it.
+The collision this prevents is silent. Two rules that resolve to the same `<n>-<slug>` path leave one file in the installed folder, and neither the install nor the session that reads it reports which source lost. Nothing checks a division outside the reserved bands, so it holds only while both sources follow it.
 
-State the division where the rule sources are described, not in the rules themselves. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
+State that division where the rule sources are described, not inside the rules it divides. A rule states its own topic, and a numbering convention spanning two sources belongs to whatever documents the pair.
 
 ## Frontmatter
 

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 "$@"