@erclx/aitk 3.18.0 → 3.19.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.19.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.18.0",
+  "version": "3.19.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,
+  }
+}