@erclx/aitk 3.8.0 → 3.10.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.8.0",
+  "version": "3.10.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -11,9 +11,12 @@ Without this skill, a new skill lands in the wrong shape and the wrong place. A
 
 A skill born without its requirement is the second failure, and it surfaces much later. Coverage of the corpus is what the operator reads to decide whether a skill should exist, so every skill created without the sibling decays that reading, and the sweep that closes the gap has to reconstruct what the skill was for from the body it already shipped.
 
+A third failure is a folder created for a moment a rule, a verb, or an existing skill already reaches, or for a procedure no session would get wrong from first principles. Nothing caught that before the folder existed, so the corpus grew by a skill an inward audit later had to argue for removing, with only a commit body recording the argument.
+
 ## Must
 
 - Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
+- Answer, in writing, whether a rule, a verb, or an existing skill already reaches this moment, and whether the body carries a procedure a session would get wrong from first principles. A folder that fails either belongs to the surface that already covers it, not to a new skill.
 - Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
 - Confirm the name and both files with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
 - Write to the conventional skills path, so discovery finds it without configuration
@@ -23,6 +26,7 @@ A skill born without its requirement is the second failure, and it surfaces much
 - Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
 - Write either file before the user has seen it
 - Derive the requirement from the drafted body, which records the draft's overfitting as the requirement
+- Gate creation on whether anything will invoke the new skill beyond the author typing its name. That question has no answer yet.
 
 ## Guards
 
@@ -31,4 +35,4 @@ A skill born without its requirement is the second failure, and it surfaces much
 ## Out of scope
 
 - Editing an existing skill, which the authoring standard and the skill's own requirement govern
-- Judging whether the skill is warranted. A skill nobody needed is an audit finding, not a creation-time refusal.
+- Whether anything ends up invoking the new skill: the usage census in `.claude/context/claude-plugin/skill-strategy.md`, read once the skill has run

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

@@ -18,9 +18,15 @@ Read these files in parallel:
 
 ## Steps
 
-1. Draft the full `SKILL.md` from the user's description
-2. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
-3. Confirm the skill name and both files with the user before writing
-4. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
+1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles:
+   - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
+   - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
+   - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
+2. Draft the full `SKILL.md` from the user's description
+3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
+4. Confirm the skill name and both files with the user before writing
+5. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
 
 Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
+
+The two-question check has a shipped precedent. Pull request `#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.

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

@@ -52,8 +52,6 @@ Run `aitk tooling sync <stack> <target> --check` for the list resolved against a
 - `.vscode/extensions.json`
 - `.vscode/settings.json`
 - `commitlint.config.js`
-- `scripts/clean.sh`
-- `scripts/update.sh`
 - `scripts/verify.sh`
 
 ### python

package/docs/agents/audits.md

@@ -22,11 +22,11 @@ aitk audits list --json
 
 ## What it runs
 
-Sixteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Eighteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
 The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
 
-Thirteen of the sixteen read a tree on this disk. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
+Fifteen of the eighteen read a tree on this disk, the one added by `restated.md` and the one added by `census.md` among them, since the first reads three such trees against each other and the second counts every file in one. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction, and the one added by `label-coverage.md` reads a branch range against a map the project declares.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 

package/docs/agents/census.md

@@ -0,0 +1,23 @@
+---
+title: Census
+description: Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
+---
+
+# Census
+
+`aitk census [path]` reports how large a tree is: the tracked-plus-untracked file count, a breakdown by extension, and a line total. It reads `listRepositoryFiles`, the same corpus the citation check, the markdown corpus, and the secret scan already read, so this is not a fourth definition of what counts.
+
+```bash
+aitk census
+aitk census src --json
+```
+
+| Option   | Behavior                                                   |
+| -------- | ---------------------------------------------------------- |
+| `--json` | Add a machine-readable record on stdout, keeping the frame |
+
+Grouping is by extension rather than by a named language category. A config file and a source file land in separate buckets and two source files sharing an extension land in one, and a file with no extension, such as `Dockerfile`, lands under `no-extension`.
+
+Line counts are text-only. A file that reads as binary, and a file git lists that will not open, such as a symlink leaving the tree, are counted toward the file total and their extension's file count, and left out of every line count. The record's `skipped` field states that gap rather than leaving a reader to infer it from the difference between the file count and the summed extension line counts. It carries both causes as one number: on a healthy tree the two are indistinguishable, so a `skipped` count above what the tree's own binary files explain is itself the signal that something in the corpus will not open.
+
+The command reports a snapshot rather than a delta. It registers in the audit catalog with an empty gating set, so `aitk audits run --record` is what turns two snapshots into the growth series a hand count used to approximate: 481 files on one date and 965 five weeks later, with nothing between them because nobody had counted again.

package/docs/agents/commands.md

@@ -50,9 +50,11 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                 |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                             |
+| `aitk gov restated`        | Report every instruction the always-loaded file shares with the seed or a shipped skill body, classed and with its anchors named (`--json`)    |
 | `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
 | `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
 | `aitk labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                  |
+| `aitk census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                           |
 | `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)         |
 | `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                      |
 | `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                          |

package/docs/agents/index.md

@@ -10,6 +10,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
 - [Capture](capture.md): Rendering committed HTML sources to PNG, what the command asserts about fonts, and why it is toolkit-only
+- [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
 - [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
@@ -24,6 +25,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Records](records.md): Validating the session records under .claude/ and the standards corpus, the per-kind checks, the refusal reasons, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
+- [Restated instructions](restated.md): Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Routing report](routing.md): Reading per CLAUDE.md section how many bullets name a path, what counts as naming one, when a rule counts as covering it, the two refusals, and why the verb reports rather than gates
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain

package/docs/agents/restated.md

@@ -0,0 +1,78 @@
+---
+title: Restated instructions
+description: Counting the instructions the always-loaded file shares with the seed and the shipped skill bodies, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
+---
+
+# Restated instructions
+
+`aitk gov restated` reports every instruction the always-loaded file states that a second surface states too. It answers a question nothing else here could: one rule was found written in three places, and it was found by accident when a shipped skill deleted a file the rule said to keep.
+
+```bash
+aitk gov restated
+aitk gov restated --json
+aitk gov restated --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 corpus it reads
+
+Three surfaces, and they are not read symmetrically. Every top-level bullet in `CLAUDE.md` is a subject, and the other two are searched:
+
+- `tooling/claude/seeds/CLAUDE.md`, read as bullets, since the seed carries the same shape as the file it is authored from
+- `claude/skills/*/SKILL.md`, read as every prose line and bullet, since the motivating case was stated in a body as a paragraph rather than a list item
+
+Frontmatter, headings, tables, and fenced blocks are read past. A heading names a section instead of stating a rule, a fenced block is an example whose words belong to the prose around it, and a body's `description` restates that skill's own purpose, so sweeping it would match every subject naming its domain.
+
+A rule stated in two skill bodies and never in `CLAUDE.md` is outside this reading. The bullets there are the subjects, and a subject is what the search runs from.
+
+## How a match is decided
+
+Matching is recall-first and keyed on shared distinctive tokens rather than on a phrase two surfaces spell the same way. The case this exists for was one rule written three different ways, so a near-exact matcher would ship a cheap report blind to the defect it was built for.
+
+A token is distinctive when it appears in at most 20 of the corpus's statements, which is under one percent of them. `.claude/plans/` sits at 14 and is the anchor the motivating case turns on, while `file` sits at 371 and would match most of the tree.
+
+A backticked token counts double. An author marking a span as code named an identifier rather than describing one, so `.claude/plans/archive/` says more about what a statement governs than any two prose words do. Two statements are one rule when their shared anchors reach a weight of 3.
+
+Every record names the anchors its match rested on, so a reader can weigh a finding instead of taking it.
+
+## The three classes
+
+- **Mirror.** Both files sit on a declared path pair whose duplication is deliberate. `CLAUDE.md` and the seed are the one pair, since the seed is authored from it and `claude-seed-sync` exists to reconcile the two. Excluding by pair rather than by content is the point: the duplication is a location fact this repository already records, and a content test would rediscover it on every run.
+- **Repetition.** Two surfaces state one rule and neither is declared a copy of the other.
+- **Contradiction.** The prohibition falls on one surface alone, on a match strong enough to read that as a disagreement. This is a polarity reading rather than a judgment about meaning, so weigh each against the surfaces it names.
+
+The contradiction floor sits above the match floor deliberately. A thin match says two statements touch the same subject, which is not enough to claim one forbids what the other prescribes, so a weak pair reports as a repetition and the loudest class is reserved for a pair sharing real identity.
+
+Two further rules decide where a prohibition counts, and both came out of false positives rather than from reasoning ahead of the corpus.
+
+Polarity is read off the clause the anchors landed in, and off the densest such clause rather than every one carrying an anchor. A statement states one rule across several clauses, so a union answers true whenever any clause anywhere carries a marker, which is the whole statement again under another name.
+
+The marker also has to open its clause, because an instruction leads with its verb. `Never delete a task file` prohibits where `a fallback never fires` reports, and no test reading the marker anywhere in the clause tells those apart. What that costs is a prohibition written mid-clause, which now reads as description and lands the pair in the repetition class, so both surfaces still reach the report and only the label is weaker.
+
+A mirror that disagrees stays a finding. The exclusion reaches a repetition alone, because the two files on a declared pair are meant to agree.
+
+## Which surface is authoritative
+
+Each restatement names where a later edit starts.
+
+- `claude-md` for a seed match, since the always-loaded file is authored first and the seed carries it to a target
+- `skill-body` where the subject names that skill, which is the content-ownership rule that behavior triggered only when editing one domain belongs to that domain's skill
+- `unknown` everywhere else, which is a first-class answer rather than a gap
+
+The ownership table assigns a cross-domain rule and a domain-triggered one, and reaches nothing stated in a skill body the always-loaded file never names. Guessing there would put a reader on a surface nobody decided.
+
+## Exit codes
+
+Exit codes are `0` when no instruction is restated outside a declared mirror, `1` for a refusal, and `2` for at least one restatement outside one. Mirrors move no exit code.
+
+Nothing wires this into `bun run check` or into a hook. A restatement is legitimate more often than not, and gating a measure whose ordinary result is a finding is what teaches contributors to route around the stage. `aitk gov test-order` and `aitk labels audit` are the siblings.
+
+Both refusals are absences rather than breaks. A target holds neither the seed nor a shipped skills tree, so `aitk audits run` reads `no-instructions` and `no-surfaces` as a corpus that is not there rather than a verb that failed.
+
+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 `counts` rather than the exit when a skill consumes this.

package/governance/rules/claude/570-skill.md

@@ -12,6 +12,8 @@ paths:
 ## Before editing
 
 - Read the skill's sibling `REQUIREMENT.md` when one exists. If the change closes no gap it states, change the requirement first or drop the change.
+- Confirm `create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
+- Report it rather than proceeding silently when `create-skill` does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
 
 ## After editing
 

package/package.json

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

package/src/audits/catalog.ts

@@ -1,5 +1,6 @@
 import type { ReachRefusal } from '@/claude/skills-reach'
 import type { AuditRefusal } from '@/deps/audit'
+import type { RestatedRefusal } from '@/gov/restated'
 import type { LabelAuditRefusal } from '@/labels/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
 import type { ScanRefusal } from '@/secrets/scan'
@@ -356,6 +357,33 @@ function labelCoverageCounts(
   return allOf({ uncovered: lengthOf(root.uncovered) })
 }
 
+/**
+ * Reads the two classes that are findings, leaving the declared mirrors out.
+ *
+ * A mirror is an authoring root and its consumed copy, which duplicate on
+ * purpose, so folding them in would report a corpus getting worse every time a
+ * seed is kept in step with the file it is authored from. Same reasoning the
+ * label audit drops its declined rows on.
+ *
+ * The reach count is left out for a different reason. It counts how many
+ * surfaces an instruction reached rather than whether anything is wrong, and it
+ * moves in lockstep with the two retained here, so a baseline carrying it would
+ * report one movement twice.
+ */
+function restatedCounts(record: unknown): Record<string, number> | undefined {
+  const counts = asObject(asObject(record)?.counts)
+  if (counts === undefined) return undefined
+
+  return allOf({
+    contradictions:
+      typeof counts.contradictions === 'number'
+        ? counts.contradictions
+        : undefined,
+    repetitions:
+      typeof counts.repetitions === 'number' ? counts.repetitions : undefined,
+  })
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -377,6 +405,23 @@ function commentCounts(record: unknown): Record<string, number> | undefined {
   return { degradationHits }
 }
 
+/**
+ * Reads the census's three headline totals, leaving the extension breakdown
+ * out. The breakdown is what a caller reads for its own sake, and folding
+ * every extension into the retained baseline would grow the recorded key set
+ * with every language the tree ever picks up.
+ */
+function censusCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined || !Array.isArray(root.byExtension)) return undefined
+
+  return allOf({
+    files: typeof root.files === 'number' ? root.files : undefined,
+    skipped: typeof root.skipped === 'number' ? root.skipped : undefined,
+    lines: typeof root.lines === 'number' ? root.lines : undefined,
+  })
+}
+
 function testOrderCounts(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -548,6 +593,38 @@ export const AUDITS: readonly AuditSpec[] = [
     absentReasons: ['no-map'] satisfies LabelAuditRefusal[],
     counts: labelCoverageCounts,
   },
+  {
+    id: 'restated',
+    label: 'Restated instructions',
+    argv: ['gov', 'restated', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // a rule stated on two surfaces should be stated on one is a judgment the
+    // person owning the surface takes, and most restatements here are correct,
+    // so a push failing on one would fail on the ordinary case.
+    gatingExits: [],
+    corpus: 'tracked',
+    // Both reasons the sweep refuses for, and each is an absence rather than a
+    // break. A target holds neither the seed nor a shipped skills tree, so
+    // without the allowance every project installing this CLI reports the verb
+    // unmeasured on every run and never changes, which is the permanent signal
+    // the per-machine allowance exists against. Same shape as the reach verb.
+    absentReasons: [
+      'no-instructions',
+      'no-surfaces',
+    ] satisfies RestatedRefusal[],
+    counts: restatedCounts,
+  },
+  {
+    id: 'census',
+    label: 'Codebase census',
+    argv: ['census', '--json'],
+    // Reports rather than gates. A file count is a measure, not a judgment, so
+    // registering it here exists to retain growth against the baseline rather
+    // than to fail a push on a number moving.
+    gatingExits: [],
+    corpus: 'tracked',
+    counts: censusCounts,
+  },
   {
     id: 'deps',
     label: 'Dependency advisories',

package/src/census/count.ts

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises'
+import { extname, join } from 'node:path'
+import { isBinary } from '@/binary'
+import { listRepositoryFiles } from '@/git-files'
+
+export type CensusRefusal = 'no-git'
+
+export interface ExtensionCount {
+  readonly extension: string
+  readonly files: number
+  readonly lines: number
+}
+
+export interface CensusResult {
+  readonly kind: 'measured'
+  readonly files: number
+  /** Binary or unreadable, counted toward `files` and excluded from `lines`. */
+  readonly skipped: number
+  readonly lines: number
+  readonly byExtension: readonly ExtensionCount[]
+}
+
+export interface CensusFailure {
+  readonly kind: 'refused'
+  readonly reason: CensusRefusal
+}
+
+/**
+ * Open descriptors allowed at once while reading the tree, matching
+ * `src/comments/scan.ts`. A single `Promise.all` over every path opens one
+ * descriptor per file, which exhausts a default 1024 limit on a large
+ * repository and fails the whole census with EMFILE.
+ */
+const CONCURRENT_READS = 64
+
+interface ReadOutcome {
+  readonly path: string
+  /** Absent when the read failed: a symlink leaving the tree, or a file git
+   * listed and the working tree no longer holds. */
+  readonly text?: string
+}
+
+async function readOne(root: string, path: string): Promise<ReadOutcome> {
+  try {
+    return { path, text: await readFile(join(root, path), 'utf8') }
+  } catch {
+    return { path }
+  }
+}
+
+function extensionFor(path: string): string {
+  const ext = extname(path)
+  return ext === '' ? 'no-extension' : ext.slice(1).toLowerCase()
+}
+
+/**
+ * A trailing newline is the file's terminator rather than an empty final line,
+ * which is what keeps a file ending `a\nb\n` at two lines rather than three.
+ */
+function countLines(text: string): number {
+  if (text === '') return 0
+  const lines = text.split('\n')
+  return text.endsWith('\n') ? lines.length - 1 : lines.length
+}
+
+/**
+ * Censuses the tracked-plus-untracked tree under `root`: a file count, a
+ * breakdown by extension, and a line total that skips whatever reads as
+ * binary.
+ *
+ * Reads `listRepositoryFiles`, the same corpus the citation check, the
+ * markdown corpus, and the secret scan already share, so this is not a
+ * fourth definition of what counts.
+ */
+export async function census(
+  root: string,
+): Promise<CensusResult | CensusFailure> {
+  const listed = await listRepositoryFiles(root)
+  if (listed === undefined) return { kind: 'refused', reason: 'no-git' }
+
+  const totals = new Map<string, { files: number; lines: number }>()
+  let skipped = 0
+  let lines = 0
+
+  for (let start = 0; start < listed.length; start += CONCURRENT_READS) {
+    const batch = listed.slice(start, start + CONCURRENT_READS)
+    const outcomes = await Promise.all(batch.map((path) => readOne(root, path)))
+
+    for (const outcome of outcomes) {
+      const extension = extensionFor(outcome.path)
+      const entry = totals.get(extension) ?? { files: 0, lines: 0 }
+      entry.files += 1
+
+      // A read that failed and a file that read as binary are counted the
+      // same way: toward `files`, excluded from every line count.
+      if (outcome.text === undefined || isBinary(outcome.text)) {
+        skipped += 1
+      } else {
+        const counted = countLines(outcome.text)
+        entry.lines += counted
+        lines += counted
+      }
+
+      totals.set(extension, entry)
+    }
+  }
+
+  const byExtension = [...totals.entries()]
+    .map(([extension, counts]) => ({ extension, ...counts }))
+    .sort((a, b) => b.files - a.files || a.extension.localeCompare(b.extension))
+
+  return { kind: 'measured', files: listed.length, skipped, lines, byExtension }
+}

package/src/cli.ts

@@ -30,6 +30,7 @@ import { register as audits } from '@/commands/audits'
 import { register as secrets } from '@/commands/secrets'
 import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
+import { register as census } from '@/commands/census'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -71,6 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
+    `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -85,6 +87,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk sandbox git:commit`,
     `${GREY}│${NC}    aitk gov install react`,
     `${GREY}│${NC}    aitk gov sync ../my-app`,
+    `${GREY}│${NC}    aitk gov restated --json`,
     `${GREY}│${NC}    aitk standards markdown`,
     `${GREY}│${NC}    aitk snippets install base ../my-app`,
     `${GREY}│${NC}    aitk snippets sync ../my-app`,
@@ -115,6 +118,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk secrets scan --json`,
     `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk labels audit --json`,
+    `${GREY}│${NC}    aitk census --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -163,6 +167,7 @@ sessions(program)
 secrets(program)
 deps(program)
 labels(program)
+census(program)
 audits(program)
 upgrade(program)
 

package/src/commands/census.ts

@@ -0,0 +1,105 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { census, type CensusRefusal } from '@/census/count'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface CensusCommandOptions {
+  readonly json?: boolean
+}
+
+const REFUSALS: Record<CensusRefusal, string> = {
+  'no-git': 'git could not list this tree, so the corpus is unknown.',
+}
+
+export function register(program: Command): void {
+  program
+    .command('census')
+    .description(
+      'Report tracked file count, a breakdown by extension, and line totals',
+    )
+    .argument('[path]', 'Tree to census, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        '  Tracked files plus untracked files git does not ignore, the same',
+        '  corpus the citation check, the markdown corpus, and the secret',
+        '  scan already read. A line total skips whatever reads as binary.',
+        '',
+        'Exit codes:',
+        '  0  the census completed',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk census',
+        '  aitk census src --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: CensusCommandOptions) => {
+      process.exitCode = await runCensus(path, opts)
+    })
+}
+
+async function runCensus(
+  path: string | undefined,
+  opts: CensusCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk census')
+
+  const result = await census(root)
+
+  if (result.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[result.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: result.reason,
+          message: REFUSALS[result.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  logStep('Files')
+  logInfo(
+    `${plural(result.files, 'file')}, ${result.skipped} skipped as binary or unreadable`,
+  )
+
+  logStep('By extension')
+  for (const entry of result.byExtension) {
+    logInfo(
+      `${entry.extension}: ${plural(entry.files, 'file')}, ${entry.lines} lines`,
+    )
+  }
+
+  logStep('Lines')
+  logInfo(`${result.lines} counted, skipping binary or unreadable files`)
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        files: result.files,
+        skipped: result.skipped,
+        lines: result.lines,
+        byExtension: result.byExtension,
+      })}\n`,
+    )
+  }
+
+  return 0
+}