@erclx/aitk 3.18.0 → 3.20.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.18.0",
+  "version": "3.20.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/docs/agents/counts.md

@@ -0,0 +1,68 @@
+---
+title: Self-stated counts
+description: Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
+---
+
+# Self-stated counts
+
+`aitk gov counts` reports a sentence stating how many members a closed catalog holds where the stated figure disagrees with what the tree actually counts. A document that reports its own catalog size carries a number nothing else compares against the tree, so it goes stale on the edit that moves the catalog and reads as current until a reviewer happens to recompute it.
+
+```bash
+aitk gov counts
+aitk gov counts --json
+aitk gov counts --root ../my-app
+```
+
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--root <path>` | Tree to read, defaulting to the current directory          |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
+
+## The catalogs it reads
+
+A closed set of six, each with a filesystem reader behind it rather than every list command this CLI ships:
+
+- `skills`: shipped plugin skills, a folder per `claude/skills/*/SKILL.md`
+- `rules`: authored governance rules, a file per `governance/rules/**/*.md`
+- `standards`: the authoring corpus at `standards/`
+- `snippets`: distinct entries across every `snippets/` category, matching what `regen-hero.sh` counts
+- `commands`: top-level `aitk` commands, read off `src/cli.ts`'s registration imports
+- `audits`: the registered set in `src/audits/catalog.ts`, this entry included
+
+The set is closed rather than derived, so widening it is a deliberate change to this file rather than a side effect of a new list command shipping elsewhere. `commands` is the one catalog with no meaning outside this repository: a project installing this CLI carries no `src/cli.ts` of its own, and that catalog reads as not applicable there rather than as zero, since zero would report a finding against any such project stating its command count as anything but zero, forever.
+
+## How a match is decided
+
+A sentence has to carry an assertion verb (`loads`, `ships`, `carries`, `holds`, `counts`, `totals`, `documents`, `declares`, `installs`, `lists`, `contains`, `comprises`) or an article (`the`, `a`, `an`) immediately ahead of the number, which is immediately ahead of the catalog noun, with one optional qualifying word between the number and the noun (`sixty-one shipped skills`). The number reads either as digits or as a spelled-out cardinal through ninety-nine, since this corpus states a catalog size in words as often as in digits.
+
+The verb gate is not the first design tried. A bare number next to a catalog noun anywhere in the tracked corpus returned 290 findings against a repository whose actionable instance count was one. Reading that run showed why: `18 rules citing a standard`, `21 skill bodies`, and `eight internal skills` all pair a number with a catalog noun while naming a subset, an example, or a different catalog than the one matched, and that shape dominates ordinary prose. Every instance this sweep was written against reads the number as the direct object of a verb asserting the catalog's own total, and gating on that verb is what took the false-positive count from 290 to five on the same tree.
+
+The article half was added after a first review of the shipped design found a live miss: `.claude/context/development/gates.md` stated a stale audit total while the tree held 20, and the verb gate never reached it, since that sentence puts its verb after the noun rather than ahead of the number. Widening the trigger set to admit an article ahead of the number closed that gap.
+
+## The plausibility filter
+
+The verb gate alone still left four false positives standing: `carries two rules about a standard's own lifecycle`, `holds one rule or one fact` (twice, once per mirrored copy), and `documents two similar commands`. Each pairs an assertion verb with a catalog noun used for something the `rules` or `commands` catalog does not mean, and what tells those apart from the one live finding is magnitude: a catalog this sweep tracks drifts by a few members between the day a sentence was written and the day it is read, so a genuine staleness claim sits near the true count. `2` beside a true count of `59` is not a catalog that shrank, it is a different `rules` entirely.
+
+A stated figure is read only when it sits within a factor of two of the true count, in either direction. That bound is tuned against the run this sweep was written against rather than reasoned to from first principles, the way `restated.ts` tunes its own document-frequency ceiling, and it is a property of the scale every catalog here sits at (the tens) rather than a universal rule.
+
+The article gate is looser than the verb list and carries a real cost. Re-running against the tree once it widened caught the live miss above and also misread a passage in `.claude/context/standards/destinations.md` naming a real subset, a standard outside the retired `standards/bundled/` fan-out, as a claim about the whole standards catalog. The qualifying adjective there fills the same optional-word slot `sixty-one shipped skills` needs to match at all, and no syntactic rule tells a qualifier that narrows a catalog from one that only restates it. The finding could not be closed by correcting a figure, since the sentence was true when the corpus held it, only unmarked as a past state, which is the class the date exclusion already reads past. Naming the moment, the same way `.claude/ARCHITECTURE.md` dates its own figures, closed it with no change to the matcher.
+
+## What it does not measure
+
+A delta phrased as a transition (`from fourteen to fifteen`), a fraction (`thirteen of sixteen`), and a total reached through an indirect noun (`denominator of sixty-one shipped skills`) are all catalog-size claims this corpus carries, and none matches the assertion-verb shape this reads. Each is a known gap rather than an oversight, left for a wider pass once this design's own false-positive rate is measured over more than one run.
+
+A calendar date (`2026-08-21`) or a backticked commit reference in the same sentence reads the whole sentence past, since that is how this corpus already marks a figure as a historical record rather than a live claim. `.claude/ARCHITECTURE.md` and the context entries carry a figure this way deliberately, and every one of them stays correct forever.
+
+The wider check over prose restatements is deliberately out of reach here. `aitk gov restated` already records a parser over prose as rejected, and this sweep reaches a number with a command behind it rather than two sentences a reader has to judge as agreeing.
+
+## Exit codes
+
+Exit codes are `0` when no stated figure disagrees with the tree, `1` for a refusal, and `2` for at least one disagreement.
+
+Nothing wires this into `bun run check` or into a hook. The false-positive rate is read off the first real run rather than assumed ahead of it, and gating a measure with an unmeasured rate is what teaches a contributor to route around the stage. `aitk gov restated` and `aitk gov test-order` are the siblings this reasoning already governs.
+
+Both refusals are breaks rather than absences. A tree with no git history or no markdown file at all is a broken checkout, matching what `aitk markdown audit` already reads `no-git` and `no-markdown` as, since this sweep shares that corpus.
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `findings` rather than the exit when a skill consumes this.

package/docs/agents/index.md

@@ -15,6 +15,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
 - [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
+- [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, the pointer the recording paints, and what each refusal reports
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote

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/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.18.0",
+  "version": "3.20.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -21,7 +21,6 @@ PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 TEMPLATE="$PROJECT_ROOT/assets/hero.html.tmpl"
 OUTPUT="$PROJECT_ROOT/assets/hero.html"
-CLI_ENTRY="$PROJECT_ROOT/src/cli.ts"
 LISTED=10
 
 # `bun src/cli.ts` rather than `aitk`, since a globally linked binary resolves to
@@ -35,27 +34,23 @@ if [ ! -f "$TEMPLATE" ]; then
   exit 1
 fi
 
-# The commands have no `--json` catalog to read, so the count comes from the
-# registration block in the CLI entry point, which is the one place a command is
-# added. `--help` is hand-authored ASCII and would drift from what is registered.
-if [ ! -f "$CLI_ENTRY" ]; then
-  echo "regen-hero: missing CLI entry point at $CLI_ENTRY" >&2
-  exit 1
-fi
-
-COMMAND_COUNT="$(grep -c '^import { register as ' "$CLI_ENTRY" || true)"
-if [ "${COMMAND_COUNT:-0}" -eq 0 ]; then
-  echo "regen-hero: no command registrations found in $CLI_ENTRY, refusing to write a zeroed hero" >&2
-  exit 1
-fi
-
+# The commands have no `--json` catalog of their own, so the count comes from
+# `aitk gov counts`, which already reads the registration block in the CLI
+# entry point to judge a document stating its own command count. Reading that
+# figure here rather than re-deriving it with a second regex is what keeps the
+# two readings of `src/cli.ts` from drifting apart unwatched, which is the
+# defect `aitk gov counts` itself exists to catch.
+# `gov counts` exits non-zero on an ordinary finding, unlike every `list` verb
+# below, so its output is read past that under `set -e` rather than aborting
+# a hero rebuild for a stale count somewhere unrelated in the tree.
+COUNTS_JSON="$(catalog gov counts || true)"
 SKILLS_JSON="$(catalog claude skills list)"
 GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
 
-for payload in "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -69,6 +64,7 @@ done
 PAYLOAD_DIR="$(mktemp -d)"
 trap 'rm -rf "$PAYLOAD_DIR"' EXIT
 
+printf '%s' "$COUNTS_JSON" >"$PAYLOAD_DIR/counts.json"
 printf '%s' "$SKILLS_JSON" >"$PAYLOAD_DIR/skills.json"
 printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
@@ -76,15 +72,16 @@ printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
 
 export PAYLOAD_DIR
-export TEMPLATE OUTPUT LISTED PROJECT_ROOT COMMAND_COUNT
+export TEMPLATE OUTPUT LISTED PROJECT_ROOT
 
 bun --eval '
 const { readFileSync } = require("node:fs")
 
-const { PAYLOAD_DIR, TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT, COMMAND_COUNT } = process.env
+const { PAYLOAD_DIR, TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT } = process.env
 
 const payload = (name) => readFileSync(PAYLOAD_DIR + "/" + name + ".json", "utf8")
 
+const COUNTS_JSON = payload("counts")
 const SKILLS_JSON = payload("skills")
 const GOV_JSON = payload("gov")
 const STANDARDS_JSON = payload("standards")
@@ -108,6 +105,11 @@ const snippets = new Set(
   JSON.parse(SNIPPETS_JSON).categories.flatMap((category) => category.entries),
 )
 const toolingStacks = JSON.parse(TOOLING_JSON).stacks
+const commandCount = JSON.parse(COUNTS_JSON).catalogs.commands
+if (!commandCount) {
+  console.error("regen-hero: gov counts read no commands catalog, refusing to write a zeroed hero")
+  process.exit(1)
+}
 
 const escape = (value) =>
   value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
@@ -191,7 +193,7 @@ const values = {
   SNIPPET_COUNT: String(snippets.size),
   GOV_STACK_COUNT: String(gov.stacks.length),
   TOOLING_STACK_COUNT: String(toolingStacks.length),
-  COMMAND_COUNT: String(Number(COMMAND_COUNT)),
+  COMMAND_COUNT: String(commandCount),
   SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
   RULE_ENTRIES: entries(deliveredRules),
   STANDARD_ENTRIES: entries(standards),

package/src/audits/catalog.ts

@@ -669,6 +669,18 @@ export const AUDITS: readonly AuditSpec[] = [
     ] satisfies RestatedRefusal[],
     counts: restatedCounts,
   },
+  {
+    id: 'counts',
+    label: 'Self-stated catalog counts',
+    argv: ['gov', 'counts', '--json'],
+    // Reports rather than gates, on the split this file already draws. The
+    // false-positive rate is read off the first real run rather than assumed
+    // ahead of it, and gating a measure with an unmeasured rate is what teaches
+    // a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    counts: findingsOnly,
+  },
   {
     id: 'census',
     label: 'Codebase census',

package/src/commands/gov.ts

@@ -2,6 +2,12 @@ import { existsSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import {
+  type CountFinding,
+  type CountsRefusal,
+  type CountsReport,
+  scanCounts,
+} from '@/counts/scan'
 import { PROJECT_ROOT } from '@/project-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
@@ -83,12 +89,23 @@ interface RestatedOptions {
   readonly json?: boolean
 }
 
+interface CountsOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 /** What a reader does about each way the sweep produced no reading. */
 const RESTATED_REFUSALS: Record<RestatedRefusal, string> = {
   'no-instructions': `No ${INSTRUCTIONS_REL} here, or it carries no bullet, so there is no instruction corpus to sweep.`,
   'no-surfaces': `Neither ${SEED_REL} nor ${SHIPPED_SKILLS_REL}/ is here, so no second surface exists to match against.`,
 }
 
+const COUNTS_REFUSALS: Record<CountsRefusal, string> = {
+  'no-git':
+    'This tree is not a git checkout, so there is no tracked markdown corpus to read.',
+  'no-markdown': 'No markdown file in this tree, so there is nothing to scan.',
+}
+
 export function register(program: Command): void {
   const gov = program
     .command('gov')
@@ -213,6 +230,56 @@ export function register(program: Command): void {
       process.exitCode = runTestOrder(opts)
     })
 
+  gov
+    .command('counts')
+    .description(
+      'Report a self-stated catalog count that disagrees with what the tree holds',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Tree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads every tracked markdown file for a sentence stating how many',
+        'members a closed catalog holds, then compares the stated figure',
+        'against what the tree actually counts.',
+        '',
+        'Catalogs read: skills, governance rules, standards, snippets, CLI',
+        'commands, and audit ids. Closed rather than derived, so widening the',
+        'set is a deliberate change rather than a side effect of a new list',
+        'command shipping elsewhere.',
+        '',
+        'A sentence carrying a calendar date or a backticked commit reference',
+        'is read past, since that is how this corpus already marks a figure as',
+        'a historical record rather than a live claim.',
+        '',
+        'What it does not measure:',
+        '  a delta phrased as a transition (from fourteen to fifteen) and a',
+        '  fraction (thirteen of sixteen) are both catalog-size claims this',
+        '  corpus carries, and neither matches the number-then-noun shape read here',
+        '',
+        'Exit codes:',
+        '  0  no stated figure disagrees with the tree',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  at least one stated figure disagrees with the tree',
+        '',
+        'It reports and never gates. The false-positive rate is read off the',
+        'first run rather than assumed, and a push failing on a stated figure',
+        'that reads correctly to a person would teach a contributor to route',
+        'around the stage.',
+        '',
+        'Examples:',
+        '  aitk gov counts',
+        '  aitk gov counts --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: CountsOptions) => {
+      process.exitCode = await runCounts(opts)
+    })
+
   gov
     .command('superseded')
     .description(
@@ -575,6 +642,73 @@ function reportTestOrder(
   outro()
 }
 
+/**
+ * Reports and never gates, matching the two sweeps above. The false-positive
+ * rate here is unmeasured before a first run against a real corpus, and
+ * gating a measure with an unknown false-positive rate is what teaches a
+ * contributor to route around the stage.
+ */
+async function runCounts(opts: CountsOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const report = await scanCounts(root)
+  const emitJson = opts.json ?? false
+
+  if (report.kind === 'unreadable') {
+    intro('aitk gov counts')
+    logStep('Refused')
+    logWarn(COUNTS_REFUSALS[report.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: report.reason,
+          message: COUNTS_REFUSALS[report.reason],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  reportCounts(report, root)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...report })}\n`)
+  }
+
+  return report.findings.length > 0 ? 2 : 0
+}
+
+function describeFinding(finding: CountFinding): string {
+  return `${finding.file}:${finding.line} states ${finding.stated} but the tree holds ${finding.actual} ${finding.catalog}`
+}
+
+function reportCounts(
+  report: Extract<CountsReport, { kind: 'measured' }>,
+  root: string,
+): void {
+  intro('aitk gov counts')
+
+  logStep('Corpus')
+  logInfo(`${report.filesScanned} tracked markdown file(s) in ${root}`)
+  logInfo(
+    Object.entries(report.catalogs)
+      .map(([id, count]) => `${id}: ${count ?? 'n/a'}`)
+      .join(', '),
+  )
+
+  logStep(report.findings.length === 0 ? 'Clean' : 'Findings')
+  if (report.findings.length === 0) {
+    logInfo('no self-stated catalog count disagrees with the tree')
+  } else {
+    for (const finding of report.findings) logWarn(describeFinding(finding))
+  }
+
+  outro()
+}
+
 /**
  * Both selectors absent means both sections, which is the bash default. Naming
  * both is the same as naming neither rather than an error, since the two flags

package/src/counts/catalogs.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { AUDITS } from '@/audits/catalog'
+import { listSkills } from '@/claude/skills-list'
+import { buildGovCatalog } from '@/gov/list'
+import { buildSnippetsCatalog } from '@/snippets/list'
+import { listStandards } from '@/standards/read'
+
+export interface Catalog {
+  readonly id: string
+  /** The noun form a prose sentence carries, singular first. */
+  readonly nouns: readonly [string, string]
+  /**
+   * `undefined` means this tree carries nothing this catalog reads, which is
+   * ordinary for every catalog but `commands`: a target installing this CLI
+   * has no `src/cli.ts` of its own, and reading that as zero would report a
+   * finding against every project stating its command count as anything but
+   * zero, forever.
+   */
+  readonly count: (root: string) => number | undefined
+}
+
+/** One line per registered top-level command. */
+const REGISTER_IMPORT = /^import \{ register as /gm
+
+/**
+ * Every top-level `aitk` command, read off the CLI entry point rather than a
+ * catalog verb, because a command carries no `--json` listing of its own
+ * siblings. `regen-hero.sh` reads its own `COMMAND_COUNT` through `gov counts`
+ * rather than a second regex on `src/cli.ts`, so this is the one place that
+ * pattern is written.
+ *
+ * This is the one catalog with no meaning outside this repository, the way
+ * `regen-hero.sh` documents itself as clone-only for the same reason.
+ */
+function countCommands(root: string): number | undefined {
+  const cli = join(root, 'src', 'cli.ts')
+  if (!existsSync(cli)) return undefined
+  return [...readFileSync(cli, 'utf8').matchAll(REGISTER_IMPORT)].length
+}
+
+/**
+ * The distinct entries across every category, matching what `regen-hero.sh`
+ * counts. A snippet reachable from two categories is one snippet, not two.
+ */
+function countSnippets(root: string): number {
+  const catalog = buildSnippetsCatalog(root)
+  return new Set(catalog.categories.flatMap((category) => category.entries))
+    .size
+}
+
+/**
+ * The closed set of catalogs this sweep counts a document against.
+ *
+ * Closed rather than derived from every list command this CLI ships, on the
+ * design the plan settled on: a wider set widens the false-positive class
+ * before the first run has measured how large that class already is. Each
+ * reader here walks the filesystem directly rather than shelling out to its
+ * own `aitk` verb, since this module already runs inside the process that
+ * would spawn it.
+ */
+export const CATALOGS: readonly Catalog[] = [
+  {
+    id: 'skills',
+    nouns: ['skill', 'skills'],
+    count: (root) => listSkills(root).length,
+  },
+  {
+    id: 'rules',
+    nouns: ['rule', 'rules'],
+    count: (root) => buildGovCatalog(root).rules.length,
+  },
+  {
+    id: 'standards',
+    nouns: ['standard', 'standards'],
+    count: (root) => listStandards(root).length,
+  },
+  {
+    id: 'snippets',
+    nouns: ['snippet', 'snippets'],
+    count: countSnippets,
+  },
+  {
+    id: 'commands',
+    nouns: ['command', 'commands'],
+    count: countCommands,
+  },
+  {
+    id: 'audits',
+    nouns: ['audit', 'audits'],
+    // Reads the registered set living in this same process, so the count this
+    // row reports is the tree's own audit surface rather than a stale copy of
+    // it, this entry included.
+    count: () => AUDITS.length,
+  },
+]

package/src/counts/numbers.ts

@@ -0,0 +1,79 @@
+const ONES: Record<string, number> = {
+  zero: 0,
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+}
+
+const TEENS: Record<string, number> = {
+  ten: 10,
+  eleven: 11,
+  twelve: 12,
+  thirteen: 13,
+  fourteen: 14,
+  fifteen: 15,
+  sixteen: 16,
+  seventeen: 17,
+  eighteen: 18,
+  nineteen: 19,
+}
+
+const TENS: Record<string, number> = {
+  twenty: 20,
+  thirty: 30,
+  forty: 40,
+  fifty: 50,
+  sixty: 60,
+  seventy: 70,
+  eighty: 80,
+  ninety: 90,
+}
+
+/**
+ * Every spelled-out cardinal from zero through ninety-nine, keyed lowercase.
+ *
+ * Every catalog this reads is under a hundred members, so the compound tens
+ * form (`sixty-one`) is the only multi-word shape worth building: the corpus
+ * this was written against spells a catalog size in words as often as in
+ * digits, and a matcher reading digits alone would miss half its own
+ * motivating cases.
+ */
+export const WORD_NUMBERS: ReadonlyMap<string, number> = (() => {
+  const words = new Map<string, number>()
+  for (const [word, value] of Object.entries(ONES)) words.set(word, value)
+  for (const [word, value] of Object.entries(TEENS)) words.set(word, value)
+  for (const [tensWord, tensValue] of Object.entries(TENS)) {
+    words.set(tensWord, tensValue)
+    for (const [onesWord, onesValue] of Object.entries(ONES)) {
+      if (onesValue === 0) continue
+      words.set(`${tensWord}-${onesWord}`, tensValue + onesValue)
+    }
+  }
+  return words
+})()
+
+/**
+ * Longest key first, so the alternation matches `sixty-one` whole rather than
+ * stopping at `sixty` and leaving `-one` unconsumed.
+ */
+const WORD_ALTERNATION = [...WORD_NUMBERS.keys()]
+  .sort((left, right) => right.length - left.length)
+  .join('|')
+
+/** A bare digit run, capped at three since every catalog here is under 1,000. */
+const DIGIT_PATTERN = '\\d{1,3}'
+
+/** Either spelling a catalog size takes in this corpus, for a caller building its own regex around it. */
+export const NUMBER_PATTERN = `(?:${DIGIT_PATTERN}|${WORD_ALTERNATION})`
+
+/** The value a matched token names, or `undefined` for a word this map does not carry. */
+export function parseNumber(token: string): number | undefined {
+  if (/^\d+$/.test(token)) return Number(token)
+  return WORD_NUMBERS.get(token.toLowerCase())
+}

package/src/counts/scan.ts

@@ -0,0 +1,258 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type Catalog, CATALOGS } from '@/counts/catalogs'
+import { NUMBER_PATTERN, parseNumber } from '@/counts/numbers'
+import { resolveMarkdown } from '@/markdown/files'
+
+export interface CountFinding {
+  readonly file: string
+  readonly line: number
+  readonly catalog: string
+  readonly stated: number
+  readonly actual: number
+  readonly sentence: string
+}
+
+/**
+ * Narrower than `MarkdownAuditRefusal`. This sweep takes no path arguments,
+ * so `resolveMarkdown` can never return its `no-match` reason here.
+ */
+export type CountsRefusal = 'no-git' | 'no-markdown'
+
+export type CountsReport =
+  | {
+      readonly kind: 'measured'
+      readonly filesScanned: number
+      /**
+       * The true count this run read for every catalog, keyed by id.
+       * `undefined` for a catalog this tree carries nothing to count, which
+       * `commands` is on every project but this repository.
+       */
+      readonly catalogs: Readonly<Record<string, number | undefined>>
+      readonly findings: readonly CountFinding[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: CountsRefusal }
+
+/**
+ * A calendar date, which reads a sentence as a historical record rather than
+ * a live claim about the tree. `.claude/ARCHITECTURE.md` and the context
+ * entries carry a figure this way deliberately, and every one of them stays
+ * correct forever, so a sentence carrying one is read past rather than
+ * matched.
+ */
+const DATE = /\b\d{4}-\d{2}-\d{2}\b/
+
+/** A commit-length hex token in a backtick span, the other marker of a dated record. */
+const COMMIT = /`[0-9a-f]{7,12}`/
+
+function isDated(sentence: string): boolean {
+  return DATE.test(sentence) || COMMIT.test(sentence)
+}
+
+/**
+ * Splits a rendered line into the sentences a reader sees.
+ *
+ * A markdown paragraph in this corpus is written as one long line rather than
+ * hard-wrapped, so a line is routinely several sentences deep, and a date
+ * naming one of them must not excuse a live claim two sentences away in the
+ * same line.
+ */
+function sentencesOf(line: string): string[] {
+  return line
+    .split(/(?<=[.!?])\s+/)
+    .map((sentence) => sentence.trim())
+    .filter((sentence) => sentence !== '')
+}
+
+/**
+ * A verb asserting the whole of something, immediately ahead of the number.
+ *
+ * The first design matched a bare number next to a catalog noun anywhere in
+ * the tracked corpus, and running it here returned 290 findings against a
+ * repository whose Files-to-touch names one live instance. Reading the
+ * corpus behind that run showed why: `18 rules citing a standard`, `21 skill
+ * bodies`, and `eight internal skills` all pair a number with a catalog noun
+ * while naming a subset, an example, or a different catalog than the one
+ * matched, and that shape dominates ordinary prose. Every instance this
+ * module was written against reads the number as the direct object of a verb
+ * asserting the catalog's own total, `the full entry loads 59 skills` being
+ * the live one, and gating the match on that verb is what a full re-read of
+ * the 290 showed removing all of them while keeping that one.
+ */
+const ASSERTION_VERBS = [
+  'loads',
+  'ships',
+  'carries',
+  'holds',
+  'counts',
+  'totals',
+  'documents',
+  'declares',
+  'installs',
+  'lists',
+  'contains',
+  'comprises',
+]
+
+/**
+ * An article immediately ahead of the number, admitting the shape a bare verb
+ * gate cannot reach: `the twelve audits read gitignored folders` asserts the
+ * catalog's own total with the verb sitting after the noun rather than ahead
+ * of the number.
+ *
+ * Found on this module's own first review, against a live instance the verb
+ * gate alone reported clean: `.claude/context/development/gates.md` stated
+ * `the twelve audits` while the tree held 20, sitting inside the plausibility
+ * bound this design already carries, so nothing but the missing shape kept it
+ * from reporting.
+ *
+ * The article is looser than the verb list, and re-running against the tree
+ * once it widened produced the class this trades for the miss above: `the 21
+ * flat standards` read a real subset (a standard outside the retired
+ * `standards/bundled/` fan-out) as a claim about the whole catalog, since
+ * `flat` fills the same optional-word slot `sixty-one shipped skills` needs to
+ * match at all. No syntactic rule tells a qualifier that narrows a catalog
+ * from one that only restates it, and the sentence was true when written, so
+ * the fix was not a narrower matcher: the clause was dated as a past state,
+ * the way `.claude/ARCHITECTURE.md` dates its own figures, which is the class
+ * the date exclusion below already reads past.
+ */
+const ARTICLES = ['the', 'a', 'an']
+
+/**
+ * Matches a catalog's stated size: an assertion verb or an article, the
+ * number, an optional single qualifying word, then the noun in either number.
+ *
+ * The optional word between the number and the noun is what reaches a form
+ * like `installs 11 shipped snippets` without also reaching past an
+ * intervening clause, since a wider gap would start pairing a number in one
+ * clause with a noun in the next. Requiring the noun's own plural form to
+ * double as its match narrows the corpus this reads without hand-listing
+ * every irregular plural, since none of these six is irregular.
+ *
+ * What this drops along with the false positives: `denominator of sixty-one
+ * shipped skills` and `exposed all 59` both state a real catalog total and
+ * neither puts a verb or an article directly ahead of the number, so both
+ * read past. The gap between the trigger and the number is a second axis
+ * this could widen once this design's own false-positive rate is measured
+ * over more than the two runs behind it so far.
+ */
+function buildMatcher(catalog: Catalog): RegExp {
+  const [singular, plural] = catalog.nouns
+  const triggers = [...ASSERTION_VERBS, ...ARTICLES].join('|')
+  return new RegExp(
+    `\\b(?:${triggers})\\s+(${NUMBER_PATTERN})(?:\\s+[a-z]+)?\\s+(?:${singular}|${plural})\\b`,
+    'gi',
+  )
+}
+
+const MATCHERS: readonly { catalog: Catalog; regex: RegExp }[] = CATALOGS.map(
+  (catalog) => ({ catalog, regex: buildMatcher(catalog) }),
+)
+
+/**
+ * A stated figure within a factor of two of the true count, in either
+ * direction.
+ *
+ * The verb gate alone still passed a run against this repository at four
+ * false positives to one real finding: `carries two rules about a
+ * standard's own lifecycle`, `holds one rule or one fact`, and `documents
+ * two similar commands` each pair an assertion verb with a catalog noun
+ * used for something this tree's `rules` or `commands` catalog does not
+ * mean. What tells those apart from the live finding is magnitude. A
+ * catalog this sweep tracks drifts by a few members between the day a
+ * sentence was written and the day it is read, so a genuine staleness claim
+ * sits near the true count, and `2` beside a true count of `59` is not a
+ * catalog that shrank, it is a different `rules` entirely.
+ *
+ * Tuned against the run this module was written against rather than
+ * reasoned to from first principles, the way `restated.ts` tunes its own
+ * document-frequency ceiling. Every catalog here sits in the tens, and the
+ * bound is a property of that scale rather than a universal one.
+ */
+const PLAUSIBLE_RATIO = 0.5
+
+function isPlausibleClaim(stated: number, actual: number): boolean {
+  if (actual === 0) return stated === 0
+  return (
+    stated / actual >= PLAUSIBLE_RATIO && actual / stated >= PLAUSIBLE_RATIO
+  )
+}
+
+/**
+ * Scans every tracked markdown file for a sentence stating how many members
+ * one of the closed catalogs holds, and compares the stated figure against
+ * what the tree actually counts.
+ *
+ * What it does not measure: a delta phrased as a transition (`from fourteen
+ * to fifteen`), a fraction (`thirteen of sixteen`), and a total reached
+ * through an indirect noun (`denominator of sixty-one shipped skills`) are
+ * all catalog-size claims this corpus carries, and none matches the
+ * assertion-verb shape this reads. Each is a known gap rather than an
+ * oversight, left for a wider pass once this one's false-positive rate is
+ * measured.
+ */
+export async function scanCounts(root: string): Promise<CountsReport> {
+  const scope = await resolveMarkdown(root, [])
+  if (scope.kind === 'unavailable') {
+    return { kind: 'unreadable', reason: 'no-git' }
+  }
+  if (scope.files.length === 0) {
+    return { kind: 'unreadable', reason: 'no-markdown' }
+  }
+
+  const catalogs: Record<string, number | undefined> = {}
+  for (const catalog of CATALOGS) catalogs[catalog.id] = catalog.count(root)
+
+  const findings: CountFinding[] = []
+
+  for (const file of scope.files) {
+    const text = readFileSync(join(root, file), 'utf8')
+    let fenced = false
+
+    text.split('\n').forEach((line, index) => {
+      if (line.trimStart().startsWith('```')) {
+        fenced = !fenced
+        return
+      }
+      if (fenced) return
+
+      for (const sentence of sentencesOf(line)) {
+        if (isDated(sentence)) continue
+
+        for (const { catalog, regex } of MATCHERS) {
+          regex.lastIndex = 0
+          const match = regex.exec(sentence)
+          if (match === null) continue
+
+          const stated = parseNumber(match[1])
+          if (stated === undefined) continue
+
+          const actual = catalogs[catalog.id]
+          // No true count on this tree, which is the ordinary state of the
+          // `commands` catalog outside this repository. A stated figure has
+          // nothing to be judged stale against.
+          if (actual === undefined) continue
+          if (stated === actual) continue
+          if (!isPlausibleClaim(stated, actual)) continue
+
+          findings.push({
+            file,
+            line: index + 1,
+            catalog: catalog.id,
+            stated,
+            actual,
+            sentence,
+          })
+        }
+      }
+    })
+  }
+
+  return {
+    kind: 'measured',
+    filesScanned: scope.files.length,
+    catalogs,
+    findings,
+  }
+}

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/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