@erclx/aitk 0.109.0 → 0.111.0

package/README.md

@@ -38,11 +38,15 @@ Nothing refreshes on its own. Claude Code ships auto-update off for third-party
 ```bash
 claude plugin marketplace update aitk
 claude plugin update aitk@aitk
-bun install --global @erclx/aitk
+aitk upgrade
 ```
 
 The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
 
+`aitk upgrade` reads the package manager off its own install path and reinstalls with that one, so you don't have to remember which put it there. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
+
+You don't have to wait until something breaks to find out you're behind. `aitk sync --check` and `aitk claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
+
 To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `aitk --version` and `claude plugin list`.
 
 ## Why

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.109.0",
+  "version": "0.111.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/audits.md

@@ -0,0 +1,88 @@
+---
+title: Audits
+description: 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
+---
+
+# Audits
+
+`aitk audits run` runs every audit this repository owns, reports each one under a single verdict, and compares each count to the floor the last recorded run left behind. Nothing here is a new measure. Every number it prints comes from a verb that already published it, which is what makes the command cheap and what separates it from writing another check.
+
+```bash
+aitk audits run
+aitk audits run --json
+aitk audits run --record
+aitk audits list --json
+```
+
+| Option          | Behavior                                                          |
+| --------------- | ----------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+| `--root <path>` | Measure this tree instead of the current worktree                 |
+| `--record`      | Write this run's tracked counts to `.claude/audits/baseline.json` |
+
+## What it runs
+
+Twelve 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, twelve runs finish in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`.
+
+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.
+
+## What gates and what reports
+
+Three findings fail the run: an unresolved context citation, a banned character, word, or spelling, and a skill folder carrying no `REQUIREMENT.md`. Those are the same three `scripts/core/verify.sh` already fails a push on, and the aggregate adds nothing to the set. Each is a fact with no false-positive class behind it.
+
+Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
+
+Growth against the baseline reports too. The standards behind the largest measures set no hard cap, so a count that rose is a fact about the corpus and a judgment about whether it matters.
+
+## Exit codes
+
+| Code | Meaning                                                              |
+| ---- | -------------------------------------------------------------------- |
+| `0`  | Every audit reported and none carried a finding that is a fact       |
+| `1`  | Refused, with the reason on stderr                                   |
+| `2`  | An audit carries a finding that is a fact                            |
+| `3`  | An audit did not report, so the run measured less than the whole set |
+
+`3` is a defect in the run rather than in the tree, which is why it takes a code of its own. An aggregate reporting a pass over a set it never finished measuring is the failure the command exists against, so an unparseable record, a verb that could not be started, and an exit no verb documents all land there instead of quietly counting as clean. The `markdown audit` empty-ban-set exit is the precedent: a corpus walked with nothing looked for is a broken check, not a clean tree.
+
+The verdict is published as a field as well as an exit code. A reader branching on `summary.verdict` gets `clean`, `reported`, `findings`, or `incomplete` without inferring the difference between a quiet corpus and one nobody finished measuring.
+
+### An absent corpus is not an unmeasured one
+
+A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
+
+The allowance is narrow. It covers a per-machine corpus refusing because its folder is missing, and nothing else. A tracked tree that cannot be found is a broken checkout, and a per-machine verb refusing for any other reason is a broken verb. Both stay `unmeasured`.
+
+Every run states how many corpora it measured against how many it skipped, including a run with no findings at all. A count of what passed reads as a verdict on the whole set unless the run also says what it never reached.
+
+### What a shallow checkout changes
+
+`aitk gov test-order` scopes its range against the trunk and falls back to the root commit when no trunk ref resolves. A depth-1 checkout has neither, so the range is empty and the verb reports zero of everything rather than refusing. The numbers are real for the history present, which means a shallow run under-reports against a baseline taken from a full clone and shows as shrinkage. That is the safe direction, and it is the reason a `test-order` delta is worth reading only from a clone carrying the history.
+
+## The retained baseline
+
+`.claude/audits/baseline.json` holds the counts from the last run recorded with `--record`, alongside the day it was taken and the commit it was read at. Each later run reports which counts moved and by how much.
+
+The file is committed. A per-machine record cannot answer the question this half exists for, which is whether a number grew since anyone last looked, and a fresh checkout has to inherit that answer rather than start over. The cost is that a branch moving a count either fixes it or re-records it and says why, which is the shape the consumed-copy assertion already carries.
+
+It sits under the project root rather than beside the aggregator in `src/`. The numbers describe one repository's corpus, and `src/` ships to every project that installs the CLI, so a baseline in the package would hand a target these counts to measure its own tree against.
+
+### What is kept out of it
+
+A gitignored record folder holds one machine's session scratch. Its counts describe somebody else's disk, so committing them writes a floor no other clone can reproduce and every contributor reads a regression against a number that was never about their tree. The board and five of the six record kinds are therefore reported on every run and recorded in none. `records-standards` is the exception, because that corpus is tracked.
+
+An audit that did not report is left out rather than written as zero. Zero there records a clean corpus nobody measured, and the next run reads its real numbers as a regression against a floor that was never taken.
+
+### The first run
+
+A run with no baseline behind it says so rather than showing a delta of zero. Those two states say the same thing to a reader and mean opposite things, which is a defect this repository has already had to fix twice elsewhere. The same reasoning covers a check the baseline never recorded, a key the run produced that the record does not carry, and a key the record carries that this run did not produce. Each is named for what it is.
+
+A hand-edited baseline that does not parse refuses the whole run. Reading a broken record as an absent one would reset the floor the file exists to hold, silently.
+
+## In the verify pipeline
+
+`bun run check` runs the set as a reporting stage after the three gating stages, and never fails on it. Those three stages keep their own specific remedies, so the aggregate reports the rest and the growth, and a fact still fails the push at the stage that names what to do about it.
+
+The stage reads `summary`, a flat object of scalars published beside the nested arrays. Every key in it is unique across the whole record, so a shell stage greps one out without a JSON parser. The three verbs the gating stages already ran walk their trees a second time here, which is the 0.8 seconds measured above and the reason the whole set runs rather than only the part those stages skip: one verdict over every audit is the value, and a stage measuring a subset would report a health nobody took.

package/docs/agents/commands.md

@@ -13,7 +13,7 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                                                                         |
 | `aitk sync [path]`         | Sync all installed domains in a target project                                                                                            |
-| `aitk sync --check`        | Report toolkit drift without writing (`--json`, `--exit-code`)                                                                            |
+| `aitk sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                     |
 | `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                        |
 | `aitk sandbox reset`       | Reset sandbox to baseline                                                                                                                 |
 | `aitk sandbox clean`       | Wipe the sandbox                                                                                                                          |
@@ -44,9 +44,12 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
 | `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                    |
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                            |
-| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD` (`--json`)                                                         |
+| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`) |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--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                                                     |
+| `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                     |
 
 ## Domain commands
 
@@ -68,6 +71,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `comments`  | `scan`                                                                                      |
 | `context`   | `audit`                                                                                     |
 | `markdown`  | `audit`                                                                                     |
+| `audits`    | `run`, `list`                                                                               |
 
 Common patterns:
 
@@ -75,3 +79,17 @@ Common patterns:
 - `install <name> <path>` → install a specific entry into a target project.
 - `sync <path>` → reapply all installed entries in a target project.
 - `create [name]` → scaffold a new authoring entry in this repo.
+
+## Version skew
+
+`aitk sync --check` and `aitk claude skills drift` are the two moments a target
+already stops to reconcile with the toolkit, so each reports the installed
+version against the newest published one. No other command performs the lookup,
+which keeps a registry round trip out of the catalog reads an agent runs in a
+loop.
+
+The report carries three states and never changes an exit code. `behind` names
+`aitk upgrade` as the remedy, `current` says so, and `unknown` carries the
+reason the registry could not be reached. Branch on the `skew.state` field in
+the JSON record rather than on the exit, since an offline machine has to read as
+unmeasured rather than as a failing check.

package/docs/agents/index.md

@@ -8,6 +8,7 @@ category: Agent surface
 
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
+- [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
 - [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

package/docs/agents/scripting.md

@@ -11,15 +11,16 @@ What a skill or script reads to discover names at runtime, and how each domain i
 
 Use these to discover what's available instead of hardcoding names.
 
-| Command                          | Returns                                              |
-| -------------------------------- | ---------------------------------------------------- |
-| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts         |
-| `aitk snippets list --json`      | Presets and categories with their slugs              |
-| `aitk standards list --json`     | Standards docs and the paths each governs            |
-| `aitk gov list --json`           | Governance stacks, rule sets, and unreferenced rules |
-| `aitk claude seeds list --json`  | Seed doc sources with content                        |
-| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag        |
-| `aitk docs list --json`          | Consumer docs plus per-domain context                |
+| Command                          | Returns                                                          |
+| -------------------------------- | ---------------------------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts                     |
+| `aitk snippets list --json`      | Presets and categories with their slugs                          |
+| `aitk standards list --json`     | Standards docs and the paths each governs                        |
+| `aitk gov list --json`           | Governance stacks, rule sets, and unreferenced rules             |
+| `aitk claude seeds list --json`  | Seed doc sources with content                                    |
+| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag                    |
+| `aitk docs list --json`          | Consumer docs plus per-domain context                            |
+| `aitk audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
 
 ### Catalog fields
 
@@ -129,4 +130,7 @@ AITK_NON_INTERACTIVE=1 aitk wiki init /path/to/project
 
 # Run a sandbox scenario non-interactively
 SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
+
+# Read every audit as one record. Exit 2 is a fact, 3 an audit that did not report
+aitk audits run --json
 ```

package/docs/target-projects.md

@@ -114,6 +114,12 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 `aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
 
+#### The binary first
+
+The report opens by naming the binary running it. The installed version reads against the newest published one, and a version behind that points you at `aitk upgrade`, since every section under it is a reading taken by whichever toolkit you happen to have. An unreachable registry reports unknown with its reason rather than failing, so `--exit-code` still gates on the drift the check measured locally and an offline machine stays green.
+
+#### Then the causes
+
 A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
 That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes. Standards, snippets, and governance record a hash per installed file. Tooling records the stack chain it resolved instead, since its install runs no per-file walk to attribute.

package/package.json

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

package/scripts/core/verify.sh

@@ -25,6 +25,11 @@ SANDBOX_UNDECLARED_CEILING=47
 # a new arrival against, and a config file would absorb the arrival silently.
 GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query"
 
+# The retained counts the audit stage compares each run against. Spelled here
+# rather than derived, because this script only ever names the file in a remedy
+# a reader has to be able to open, and `aitk audits run` owns writing it.
+AUDITS_BASELINE=".claude/audits/baseline.json"
+
 check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
@@ -209,10 +214,11 @@ seed_entry_count() {
     awk '{ total += $1 } END { print total + 0 }'
 }
 
-# One numeric summary key out of a coverage report. The per-scenario objects carry
-# neither key this is called with, so the match reaches the top level alone and
-# the caller does not depend on the order the keys are emitted in.
-sandbox_summary_field() {
+# One numeric summary key out of a command's JSON record. Every caller passes a
+# name the nested objects in that record do not carry, so the match reaches the
+# top level alone and the caller does not depend on the order the keys are
+# emitted in.
+json_summary_field() {
   printf '%s' "$2" | grep -o "\"$1\":[0-9]\+" | grep -o '[0-9]\+'
 }
 
@@ -466,8 +472,8 @@ main() {
     # `|| x=""` on both, because a grep that matches nothing exits non-zero and
     # errexit would take the script down at the assignment, before the guard
     # below could name what went missing.
-    total=$(sandbox_summary_field totalScenarios "$coverage_output") || total=""
-    armed=$(sandbox_summary_field armedScenarios "$coverage_output") || armed=""
+    total=$(json_summary_field totalScenarios "$coverage_output") || total=""
+    armed=$(json_summary_field armedScenarios "$coverage_output") || armed=""
     if [ -z "$total" ] || [ -z "$armed" ]; then
       log_error "The coverage report carried no scenario totals, so the stage measured nothing. Run bun src/cli.ts sandbox coverage --json."
     fi
@@ -478,6 +484,68 @@ main() {
     log_info "$armed of $total scenarios declare expectations, $undeclared undeclared against a ceiling of $SANDBOX_UNDECLARED_CEILING"
   fi
 
+  # The three stages above gate on the three findings here that are facts, and
+  # this stage reports the rest. It runs the whole set anyway rather than only
+  # what those stages skip, because the aggregate's own value is one verdict
+  # over every audit, and a stage measuring a subset would report a health this
+  # repository never took.
+  #
+  # The duplicate walk costs 0.8s wall against roughly 4.4s of processor,
+  # measured on the authoring machine at 12 verbs run together. That is under
+  # every other stage in this script, which is what settles the open question
+  # about whether the pipeline can afford it.
+  #
+  # This reports and never fails. Growth in a judgment count is the thing the
+  # baseline exists to make visible, and failing a push on one would teach a
+  # contributor to route around the stage, which is the split every audit stage
+  # here already keeps. A fact still fails the push, at the specific stage above
+  # that names its own remedy.
+  log_step "Audit set"
+  local audits_output audits_status=0 audits_grown audits_shrunk audits_facts audits_unmeasured audits_absent audits_unrecorded
+  audits_output=$(cd "$PROJECT_ROOT" && bun src/cli.ts audits run --json 2>/dev/null) || audits_status=$?
+  if [ -z "$audits_output" ]; then
+    log_warn "Skipped, the audit set did not report (exit $audits_status)"
+  else
+    audits_grown=$(json_summary_field grown "$audits_output") || audits_grown=""
+    audits_shrunk=$(json_summary_field shrunk "$audits_output") || audits_shrunk=""
+    audits_facts=$(json_summary_field facts "$audits_output") || audits_facts=""
+    audits_unmeasured=$(json_summary_field unmeasured "$audits_output") || audits_unmeasured=""
+    audits_absent=$(json_summary_field absent "$audits_output") || audits_absent=""
+    audits_unrecorded=$(json_summary_field unrecorded "$audits_output") || audits_unrecorded=""
+
+    # An absent field is a record this stage cannot read, which is not the same
+    # as a run with nothing to report. Reading it as zero would print a clean
+    # line over a summary nobody parsed.
+    if [ -z "$audits_grown" ] || [ -z "$audits_facts" ] || [ -z "$audits_unmeasured" ]; then
+      log_warn "The audit record carried no summary, so this stage measured nothing. Run bun src/cli.ts audits run."
+    else
+      # An absent per-machine folder is the ordinary state here rather than a
+      # finding, since every one of them is gitignored and CI carries none. It
+      # is still stated, because a stage naming only what it measured claims a
+      # coverage it does not have.
+      if [ -n "$audits_absent" ] && [ "$audits_absent" -gt 0 ]; then
+        log_info "$audits_absent per-machine corpus/corpora absent, so unmeasured here by design"
+      fi
+      if [ "$audits_unmeasured" -gt 0 ]; then
+        log_warn "$audits_unmeasured audit(s) did not report, so the set is incomplete. Run bun src/cli.ts audits run."
+      fi
+      if [ "$audits_facts" -gt 0 ]; then
+        log_warn "$audits_facts audit(s) carry a finding that is a fact. The stage above names the remedy."
+      fi
+      if [ -n "$audits_unrecorded" ] && [ "$audits_unrecorded" -gt 0 ]; then
+        log_warn "$audits_unrecorded tracked audit(s) have no recorded floor. Take one with bun src/cli.ts audits run --record."
+      fi
+      if [ "$audits_grown" -gt 0 ]; then
+        log_warn "$audits_grown measure(s) grew against $AUDITS_BASELINE. Run bun src/cli.ts audits run to see which, then fix them or re-record and say why."
+      else
+        log_info "No measure grew against $AUDITS_BASELINE"
+      fi
+      if [ -n "$audits_shrunk" ] && [ "$audits_shrunk" -gt 0 ]; then
+        log_info "$audits_shrunk measure(s) fell against $AUDITS_BASELINE"
+      fi
+    fi
+  fi
+
   # The plugin is the second delivery path and this is the only stage gating it,
   # so the skip below is for a contributor's machine rather than for the merge
   # gate. A runner installs the CLI as a workflow step, which makes an absent

package/src/audits/baseline.ts

@@ -0,0 +1,194 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { AuditResult } from '@/audits/catalog'
+
+/**
+ * Where the retained counts live, relative to the project root.
+ *
+ * Committed rather than per-machine, because the question this half answers is
+ * whether a number grew since anyone last looked, and a fresh checkout has to
+ * inherit that answer. A per-machine record makes every contributor's first run
+ * a first run.
+ *
+ * Under the project root rather than beside the aggregator in `src/`, because
+ * the numbers describe one repository's corpus and `src/` ships to every target
+ * that installs the CLI. A baseline in the package would hand a target this
+ * repository's counts to measure its own tree against.
+ */
+export const BASELINE_REL = join('.claude', 'audits', 'baseline.json')
+
+export interface Baseline {
+  /** The day the record was taken, as `YYYY-MM-DD`. */
+  readonly recordedAt: string
+  /** The commit the counts were read at, so a reader can reproduce them. */
+  readonly commit: string
+  readonly checks: Readonly<Record<string, Readonly<Record<string, number>>>>
+}
+
+export interface Stamp {
+  readonly recordedAt: string
+  readonly commit: string
+}
+
+export interface MovedCount {
+  readonly key: string
+  readonly from: number
+  readonly to: number
+  readonly delta: number
+}
+
+export type Delta =
+  | {
+      readonly id: string
+      readonly kind: 'compared'
+      readonly moved: readonly MovedCount[]
+      /** Keys the run reproduced exactly. */
+      readonly steady: readonly string[]
+      /** Keys the run produced that the baseline never recorded. */
+      readonly added: readonly { key: string; to: number }[]
+      /** Keys the baseline holds that this run did not produce. */
+      readonly dropped: readonly { key: string; from: number }[]
+    }
+  /** No recorded floor, so a zero delta would be indistinguishable from quiet. */
+  | { readonly id: string; readonly kind: 'unrecorded' }
+  /** Gitignored scratch, whose counts are one machine's and answer nobody else. */
+  | { readonly id: string; readonly kind: 'per-machine' }
+  /** The audit did not report, so there is nothing to compare. */
+  | { readonly id: string; readonly kind: 'unmeasured' }
+
+/**
+ * Builds the record a run leaves behind.
+ *
+ * Only a tracked corpus is retained. A gitignored record folder holds one
+ * machine's session scratch, so committing its counts writes a floor no other
+ * clone can reproduce, and every contributor would read a regression against a
+ * number that describes somebody else's disk.
+ *
+ * An audit that did not report is left out rather than written as zero. Zeros
+ * there record a clean corpus nobody measured, and the next run reads its real
+ * numbers as a regression against a floor that was never taken.
+ */
+export function baselineFrom(
+  results: readonly AuditResult[],
+  stamp: Stamp,
+): Baseline {
+  const checks: Record<string, Record<string, number>> = {}
+
+  for (const result of results) {
+    if (!result.tracked || result.counts === undefined) continue
+    checks[result.id] = { ...result.counts }
+  }
+
+  return { recordedAt: stamp.recordedAt, commit: stamp.commit, checks }
+}
+
+/**
+ * Compares this run against the recorded floor, one audit at a time.
+ *
+ * A first run reports `unrecorded` rather than a delta of zero. A zero delta
+ * against an absent baseline says the same thing as a corpus that did not move,
+ * and those are the two states this repository has already had to separate
+ * twice elsewhere.
+ */
+export function compareBaseline(
+  baseline: Baseline | undefined,
+  results: readonly AuditResult[],
+): Delta[] {
+  return results.map((result) => {
+    if (!result.tracked) return { id: result.id, kind: 'per-machine' as const }
+    if (result.counts === undefined) {
+      return { id: result.id, kind: 'unmeasured' as const }
+    }
+
+    const recorded = baseline?.checks[result.id]
+    if (recorded === undefined) {
+      return { id: result.id, kind: 'unrecorded' as const }
+    }
+
+    const moved: MovedCount[] = []
+    const steady: string[] = []
+    const added: { key: string; to: number }[] = []
+    const dropped: { key: string; from: number }[] = []
+
+    for (const [key, to] of Object.entries(result.counts)) {
+      const from = recorded[key]
+      if (from === undefined) {
+        added.push({ key, to })
+      } else if (from === to) {
+        steady.push(key)
+      } else {
+        moved.push({ key, from, to, delta: to - from })
+      }
+    }
+
+    for (const [key, from] of Object.entries(recorded)) {
+      if (!(key in result.counts)) dropped.push({ key, from })
+    }
+
+    return {
+      id: result.id,
+      kind: 'compared' as const,
+      moved,
+      steady,
+      added,
+      dropped,
+    }
+  })
+}
+
+function isBaseline(value: unknown): value is Baseline {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  return (
+    typeof record.recordedAt === 'string' &&
+    typeof record.commit === 'string' &&
+    typeof record.checks === 'object' &&
+    record.checks !== null &&
+    !Array.isArray(record.checks)
+  )
+}
+
+/**
+ * Reads the recorded floor, or `undefined` when none has been taken.
+ *
+ * An absent file and a broken one are different answers. Absent is a first run.
+ * Broken is a record someone hand-edited into a shape nothing can read, and
+ * reading that as absent would silently reset the floor the file exists to hold.
+ */
+export async function readBaseline(
+  root: string,
+): Promise<Baseline | undefined> {
+  const path = join(root, BASELINE_REL)
+
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error(`${BASELINE_REL} does not parse as JSON. Fix or delete it.`)
+  }
+
+  if (!isBaseline(parsed)) {
+    throw new Error(
+      `${BASELINE_REL} carries no recordedAt, commit, and checks. Fix or delete it.`,
+    )
+  }
+
+  return parsed
+}
+
+export async function writeBaseline(
+  root: string,
+  baseline: Baseline,
+): Promise<string> {
+  const path = join(root, BASELINE_REL)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8')
+  return path
+}