@erclx/canon 4.0.0

package/src/audits/catalog.ts

@@ -0,0 +1,876 @@
+import type { SkillsAuditRefusal } from '@/claude/skills-audit'
+import type { RankRefusal } from '@/claude/skills-rank'
+import type { ReachRefusal } from '@/claude/skills-reach'
+import type { ContextAuditRefusal } from '@/context/audit'
+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'
+import type { ValidateRefusal as BoardRefusal } from '@/tasks/validate'
+
+/**
+ * The audits this repository already owns, and how to read each one's record.
+ *
+ * Every verb here ships its own `--json` shape with its own keys, and this
+ * module reads each shape rather than forcing a common envelope on them. Each
+ * record already has consumers, so an envelope would be a breaking change to
+ * every one of them bought for tidiness.
+ */
+
+/** How far a finding from this audit reaches. */
+export type Corpus =
+  /** Committed, so every clone measures the same files and a delta is shared. */
+  | 'tracked'
+  /** Gitignored session scratch, so the numbers are one machine's alone. */
+  | 'per-machine'
+  /**
+   * Read from an index off this machine, so the count moves when someone
+   * publishes rather than when someone edits here.
+   *
+   * Its own member rather than either of the two above. A baseline would
+   * record growth nobody caused, which is what keeps it out of the retained
+   * set alongside per-machine scratch, and an index this run could not reach
+   * is an ordinary absence rather than the broken checkout a missing tracked
+   * tree would be.
+   */
+  | 'upstream'
+
+export type AuditStatus =
+  /** The audit reported and every count it produced is zero. */
+  | 'clean'
+  /** The audit reported findings it does not gate on. */
+  | 'reported'
+  /** The audit reported a finding that is a fact, which fails the aggregate. */
+  | 'finding'
+  /**
+   * The per-machine corpus this audit reads is not on this disk, which is the
+   * ordinary state of a gitignored folder on a fresh clone and in CI.
+   */
+  | 'absent'
+  /** The audit did not report, so the aggregate measured less than the set. */
+  | 'unmeasured'
+
+export interface AuditSpec {
+  readonly id: string
+  readonly label: string
+  /** Arguments after `canon`, always ending in `--json`. */
+  readonly argv: readonly string[]
+  /**
+   * Exit codes this verb sets on a finding that is a fact.
+   *
+   * Empty for every verb whose findings are judgments. The catalog decides
+   * this rather than the exit code, because a reporting verb sets 2 on
+   * findings it deliberately does not gate on, so the code alone cannot say
+   * whether a finding is a fact.
+   */
+  readonly gatingExits: readonly number[]
+  readonly corpus: Corpus
+  /**
+   * Refusal reasons that mean this audit has no corpus here rather than that
+   * it broke, overriding what the corpus alone would allow.
+   *
+   * Present only where the corpus answers wrongly. A tracked corpus normally
+   * allows nothing, since a tree that ships to targets and cannot be found is
+   * a broken checkout, and the secret scan is the exception: a project that
+   * publishes nothing has no shipped tree to read, which is an ordinary state
+   * rather than a defect.
+   */
+  readonly absentReasons?: readonly string[]
+  /**
+   * Pulls the counts worth retaining out of this verb's record.
+   *
+   * Returns `undefined` when the record does not carry the keys it reads,
+   * which is a measure that did not run rather than a corpus with nothing in
+   * it. Zero there would read as clean, which is the two-states-look-alike
+   * defect this repository has already fixed elsewhere.
+   */
+  readonly counts: (record: unknown) => Record<string, number> | undefined
+}
+
+export interface AuditResult {
+  readonly id: string
+  readonly label: string
+  readonly status: AuditStatus
+  /** Retained by the baseline, which is `tracked` alone. */
+  readonly tracked: boolean
+  /** Why it is or is not retained, which `tracked` alone cannot say. */
+  readonly corpus: Corpus
+  readonly exitCode: number
+  readonly counts?: Record<string, number>
+  /** Why the audit did not report, present only on `unmeasured`. */
+  readonly reason?: string
+}
+
+/** The exit code every command here sets when it refuses. */
+const EXIT_REFUSED = 1
+
+/** The exit code every command here sets when it carries findings. */
+const EXIT_FINDINGS = 2
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined
+  }
+  return value as Record<string, unknown>
+}
+
+function lengthOf(value: unknown): number | undefined {
+  return Array.isArray(value) ? value.length : undefined
+}
+
+/**
+ * Folds a set of per-key readings into one record, or `undefined` when any of
+ * them could not be read. One unreadable key means the record is not the shape
+ * the extractor was written against, and reporting the rest would publish a
+ * partial count under a name that claims to be whole.
+ */
+function allOf(
+  readings: Record<string, number | undefined>,
+): Record<string, number> | undefined {
+  const counts: Record<string, number> = {}
+  for (const [key, value] of Object.entries(readings)) {
+    if (value === undefined) return undefined
+    counts[key] = value
+  }
+  return counts
+}
+
+/**
+ * Reads the architecture record's three measures, or nothing when the project
+ * carries no record.
+ *
+ * Three states rather than two, matching what the verb publishes. The key
+ * absent is a run that never opened the record, which the aggregate never asks
+ * for and so reads as a shape that moved. Null is a project entitled to carry
+ * no record, whose other context counts still stand, so it contributes no key
+ * rather than a zero that would read as a conforming record.
+ */
+function architectureCounts(
+  root: Record<string, unknown>,
+): Record<string, number> | undefined | 'absent' {
+  if (!('architecture' in root)) return undefined
+  if (root.architecture === null) return 'absent'
+
+  const record = asObject(root.architecture)
+  const decisions = record?.decisions
+  if (
+    record === undefined ||
+    !Array.isArray(decisions) ||
+    typeof record.lines !== 'number'
+  ) {
+    return undefined
+  }
+
+  // A record stating no length rule has no ceiling to be past, and reporting
+  // zero there would read as one measured and found conforming.
+  const ceiling =
+    typeof record.ceiling === 'number' ? record.ceiling : undefined
+
+  let unverifiable = 0
+  let unchecked = 0
+  for (const raw of decisions) {
+    const entry = asObject(raw)
+    const claim = entry?.claim
+    const checks = lengthOf(entry?.checks)
+    if (typeof claim !== 'string' || checks === undefined) return undefined
+
+    if (claim === 'neither') unverifiable += 1
+    else if (checks === 0) unchecked += 1
+  }
+
+  return {
+    // A boolean, counted so the aggregate reads it the way it reads every
+    // other measure. The verb gates on it separately, and the key is absent
+    // rather than zero on a record that declared no ceiling.
+    ...(ceiling !== undefined && {
+      recordOverLength: record.lines > ceiling ? 1 : 0,
+    }),
+    recordUnverifiable: unverifiable,
+    recordUnchecked: unchecked,
+  }
+}
+
+function contextCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  const entries = root.entries
+  if (!Array.isArray(entries)) return undefined
+
+  let bareReferences = 0
+  for (const entry of entries) {
+    const bare = lengthOf(asObject(entry)?.bareReferences)
+    if (bare === undefined) return undefined
+    bareReferences += bare
+  }
+
+  const architecture = architectureCounts(root)
+  if (architecture === undefined) return undefined
+
+  const counts = allOf({
+    unresolvedCitations: lengthOf(asObject(root.citations)?.unresolved),
+    longEntries: lengthOf(root.length),
+    missingSections: lengthOf(root.missingSections),
+    indexDrift: lengthOf(root.indexDrift),
+    bareReferences,
+  })
+
+  if (counts === undefined) return undefined
+  return architecture === 'absent' ? counts : { ...counts, ...architecture }
+}
+
+function markdownCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  const entries = root.entries
+  if (!Array.isArray(entries)) return undefined
+
+  const depth = asObject(root.checkpoints)?.run
+  // A depth reading needs the checkpoint it is measured against. Counting zero
+  // without it reports a corpus nobody measured for depth as one with no file
+  // past the line.
+  if (entries.length > 0 && typeof depth !== 'number') return undefined
+
+  let bans = 0
+  let heavyBullets = 0
+  let heavyParagraphs = 0
+  let filesPastDepth = 0
+  let flatParagraphs = 0
+
+  for (const raw of entries) {
+    const entry = asObject(raw)
+    if (entry === undefined) return undefined
+
+    const entryBans = lengthOf(entry.bans)
+    const bullets = lengthOf(entry.heavyBullets)
+    const paragraphs = lengthOf(entry.heavyParagraphs)
+    const run = entry.longestRun
+    if (
+      entryBans === undefined ||
+      bullets === undefined ||
+      paragraphs === undefined ||
+      typeof run !== 'number'
+    ) {
+      return undefined
+    }
+
+    bans += entryBans
+    heavyBullets += bullets
+    heavyParagraphs += paragraphs
+    if (typeof depth === 'number' && run > depth) filesPastDepth += 1
+
+    // A file below the measuring floor carries no cadence key at all, which is
+    // a file that was not measured rather than one with no flat paragraph.
+    const flat = asObject(entry.cadence)?.flat
+    if (typeof flat === 'number') flatParagraphs += flat
+  }
+
+  return { bans, heavyBullets, heavyParagraphs, filesPastDepth, flatParagraphs }
+}
+
+/** The finding arrays `canon claude skills audit` publishes, in its own order. */
+const SKILL_FINDINGS = [
+  'missingRequirement',
+  'nameMismatch',
+  'missingDescription',
+  'longDescription',
+  'readme',
+  'folderName',
+  'requirementSections',
+] as const
+
+function skillCounts(record: unknown): Record<string, number> | undefined {
+  const findings = asObject(asObject(record)?.findings)
+  if (findings === undefined) return undefined
+
+  return allOf(
+    Object.fromEntries(
+      SKILL_FINDINGS.map((key) => [key, lengthOf(findings[key])]),
+    ),
+  )
+}
+
+/**
+ * Reads the unqualified citations alone, leaving the qualified ones out.
+ *
+ * A qualified citation is a repair that already landed, so folding the two
+ * together would report a corpus getting worse every time one is fixed. The
+ * key is still read rather than assumed present, since a record carrying
+ * neither array is a shape that moved rather than a catalog with nothing in it.
+ */
+function reachCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined || !Array.isArray(root.qualified)) return undefined
+
+  return allOf({ unqualifiedCitations: lengthOf(root.unqualified) })
+}
+
+/**
+ * Reads the routing measure's miss and unmeasurable counts, leaving `rank1`
+ * and `top3` out. Both move in lockstep with `misses` over a fixed-size
+ * corpus, so carrying them would report one movement three times, the same
+ * reasoning `restatedCounts` already takes over its own pair of derived
+ * totals. `unmeasurable` is retained separately, since it counts a defect in
+ * the instrument rather than a collision the catalog itself carries.
+ */
+function rankCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  return allOf({
+    misses: lengthOf(root.misses),
+    unmeasurable: lengthOf(root.unmeasurable),
+  })
+}
+
+function boardCounts(record: unknown): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  // The board keeps its untested rows apart from its findings on purpose, so
+  // they move no exit code. Folding them together here would undo that.
+  return allOf({
+    findings: lengthOf(root.findings),
+    untested: lengthOf(root.untested),
+  })
+}
+
+/**
+ * Reads the advisory verb's per-severity object rather than a total.
+ *
+ * A single count folds a critical advisory into a low one, and the response to
+ * the two differs. The keys are read off the record rather than listed here,
+ * so a severity the index adds is carried instead of silently dropped.
+ */
+function advisoryCounts(record: unknown): Record<string, number> | undefined {
+  const severities = asObject(asObject(record)?.severities)
+  if (severities === undefined) return undefined
+
+  const counts: Record<string, number> = {}
+  for (const [severity, value] of Object.entries(severities)) {
+    if (typeof value !== 'number') return undefined
+    counts[`advisories-${severity}`] = value
+  }
+
+  return counts
+}
+
+/**
+ * Reads the uncovered paths alone, which is the half that is a finding.
+ *
+ * The declined paths are deliberately not counted. They are whichever declined
+ * rows this branch happened to touch rather than a measure of the map, so a
+ * clean trunk reads zero while the map declares eight, and the number would
+ * describe the branch rather than the decision.
+ *
+ * Retaining it also broke the verdict. `classify` reads a clean run as quiet
+ * only when every count is zero, so a branch touching one declined path exited
+ * 0 and still reported as carrying findings.
+ */
+function labelCoverageCounts(
+  record: unknown,
+): Record<string, number> | undefined {
+  const root = asObject(record)
+  if (root === undefined) return undefined
+
+  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
+
+  return allOf({ findings: lengthOf(root.findings) })
+}
+
+function commentCounts(record: unknown): Record<string, number> | undefined {
+  const snapshot = asObject(record)?.snapshot
+  if (!Array.isArray(snapshot)) return undefined
+
+  let degradationHits = 0
+  for (const language of snapshot) {
+    const hits = lengthOf(asObject(language)?.degradationHits)
+    if (hits === undefined) return undefined
+    degradationHits += hits
+  }
+
+  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
+
+  // The unclassified count travels with the findings because it is the honest
+  // shape of this measure: a refactor and a new behavior cannot be told apart
+  // from history, and a findings count alone claims coverage it does not have.
+  return allOf({
+    findings: lengthOf(root.findings),
+    unclassified: lengthOf(root.unclassified),
+  })
+}
+
+/** The record kinds `canon records validate` takes, and the corpus each reads. */
+const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
+  ['plans', 'per-machine'],
+  ['groundwork', 'per-machine'],
+  ['intake', 'per-machine'],
+  ['memory', 'per-machine'],
+  ['standards', 'tracked'],
+  ['teach', 'per-machine'],
+]
+
+/**
+ * Every audit the aggregate runs.
+ *
+ * `context`, `markdown`, and `skills` gate because the merge gate in
+ * `src/gate/stages.ts` already fails a push on each. `secrets` is the one entry that gates without
+ * a stage behind it, added deliberately rather than as a side effect, since a
+ * credential in the published tree is a fact and the split this repository
+ * records gates a fact and reports a judgment. Weigh any further addition
+ * against that test rather than against the count.
+ *
+ * Each verb runs once in its fullest form. Running the gating half separately
+ * would walk the same tree twice for a number the full record already carries.
+ */
+export const AUDITS: readonly AuditSpec[] = [
+  {
+    id: 'context',
+    label: 'Context folders',
+    argv: ['context', 'audit', '--json'],
+    gatingExits: [EXIT_FINDINGS],
+    corpus: 'tracked',
+    // The one reason this verb refuses for that is an absence rather than a
+    // break, on the same test the reach check and the skill audit take: no
+    // target adopts `.claude/context/`, `.claude/diagrams/`, and
+    // `.claude/wireframes/` all at once, so without the allowance every such
+    // project reports the verb unmeasured on every run and never changes.
+    absentReasons: ['no-folders'] satisfies ContextAuditRefusal[],
+    counts: contextCounts,
+  },
+  {
+    id: 'markdown',
+    label: 'Markdown corpus',
+    argv: ['markdown', 'audit', '--json'],
+    // 3 is the empty ban set, which is the corpus walked with nothing looked
+    // for. That is a broken check rather than a clean tree, so it fails here
+    // the way it already fails the push.
+    gatingExits: [EXIT_FINDINGS, 3],
+    corpus: 'tracked',
+    counts: markdownCounts,
+  },
+  {
+    id: 'skills',
+    label: 'Skill corpora',
+    argv: ['claude', 'skills', 'audit', '--json'],
+    gatingExits: [EXIT_FINDINGS],
+    corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying neither `claude/skills/`
+    // nor `.claude/skills/` has adopted no skill convention this audit reads.
+    absentReasons: ['no-corpus'] satisfies SkillsAuditRefusal[],
+    counts: skillCounts,
+  },
+  {
+    id: 'skills-reach',
+    label: 'Shipped citation reach',
+    argv: ['claude', 'skills', 'reach', '--json'],
+    // Reports rather than gates, on the split this file already draws. A body
+    // naming a toolkit path is sometimes correct, since the instruction may be
+    // meant for a session in this repository, so the verdict is a judgment and
+    // a push failing on one teaches a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    // The one reason this verb refuses for, and it is an absence rather than a
+    // break. A tracked corpus normally allows nothing, since a tree that ships
+    // to targets and cannot be found is a broken checkout, and this is the
+    // second exception on the same test the secret scan takes: a project
+    // carrying neither `claude/skills/` nor `.claude/skills/` has adopted no
+    // skill convention, so without the allowance it reports the verb
+    // unmeasured on every run and never changes, which is the permanent signal
+    // the per-machine allowance exists against.
+    absentReasons: ['no-skills'] satisfies ReachRefusal[],
+    counts: reachCounts,
+  },
+  {
+    id: 'skills-rank',
+    label: 'Skill routing measure',
+    argv: ['claude', 'skills', 'rank', '--json'],
+    // Reports rather than gates. The corpus is a first run with no baseline to
+    // fail a push against, and a lexical ranker bounds a necessary condition
+    // rather than reporting real routing behavior, so a push failing on a
+    // moved rank would teach a contributor to route around the stage.
+    gatingExits: [],
+    corpus: 'tracked',
+    // The one reason this run refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying neither `claude/skills/`
+    // nor `.claude/skills/` has adopted no skill convention this audit reads.
+    // The two case-corpus refusals never reach here, since they need `--cases`
+    // and this argv passes none.
+    absentReasons: ['no-skills'] satisfies RankRefusal[],
+    counts: rankCounts,
+  },
+  {
+    id: 'tasks',
+    label: 'Task board',
+    argv: ['tasks', 'validate', '--json'],
+    gatingExits: [],
+    corpus: 'per-machine',
+    counts: boardCounts,
+  },
+  ...RECORD_KINDS.map(([kind, corpus]) => ({
+    id: `records-${kind}`,
+    label: `Records: ${kind}`,
+    argv: ['records', 'validate', kind, '--json'],
+    gatingExits: [],
+    corpus,
+    // `standards` is the one tracked kind here, so it takes none of the
+    // per-machine default the other five inherit from their corpus. A target
+    // reads standards through `canon standards` rather than a copy in its own
+    // tree, so carrying no standards folder at all is the
+    // ordinary state of every project but this repository.
+    ...(kind === 'standards' && {
+      absentReasons: ['no-folder'] satisfies RecordRefusal[],
+    }),
+    counts: findingsOnly,
+  })),
+  {
+    id: 'comments',
+    label: 'Comment census',
+    argv: ['comments', 'scan', '--json'],
+    gatingExits: [],
+    corpus: 'tracked',
+    counts: commentCounts,
+  },
+  {
+    id: 'test-order',
+    label: 'Test order',
+    argv: ['gov', 'test-order', '--json'],
+    gatingExits: [],
+    corpus: 'tracked',
+    counts: testOrderCounts,
+  },
+  {
+    id: 'secrets',
+    label: 'Shipped tree secrets',
+    argv: ['secrets', 'scan', '--json'],
+    // The fourth gate, and the first added since the note above was written.
+    // A credential-shaped value sitting in the tree this repository publishes
+    // is a fact rather than a judgment, which is the test that note asks any
+    // addition to pass. It is decided here and stated in the context entry
+    // rather than arriving as a side effect of registering a measure.
+    gatingExits: [EXIT_FINDINGS],
+    corpus: 'tracked',
+    // The three reasons that mean this tree publishes nothing, which is where
+    // most targets installing this CLI sit. Without the allowance the
+    // aggregate reports `incomplete` on every run in every such project and
+    // never changes, which is the permanent signal the per-machine allowance
+    // exists against.
+    //
+    // Two reasons are deliberately left out, and both are a corpus that exists
+    // and went unread. `no-git` is a broken checkout, and `no-files-field` is a
+    // publish that would pack the whole tree, so calling either an absence
+    // would report a pass over a shipped tree nobody measured.
+    absentReasons: [
+      'no-manifest',
+      'no-publish',
+      'no-shipped-files',
+    ] satisfies ScanRefusal[],
+    counts: findingsOnly,
+  },
+  {
+    id: 'labels',
+    label: 'Pull request label coverage',
+    argv: ['labels', 'audit', '--json'],
+    // Reports rather than gates, on the split this file already draws. Whether
+    // an uncovered surface deserves a label is a judgment, and a push failing
+    // on one would ask a contributor to answer a question only the person who
+    // owns the surface can.
+    gatingExits: [],
+    // The map is committed, so every clone reads the same rows and a delta is
+    // shared. The changed set the rows are read against is the branch's, which
+    // is what makes a clean trunk report zero rather than nothing.
+    corpus: 'tracked',
+    // Only `uncovered` is retained, for the reason its extractor states.
+    //
+    // The one reason that means this project declares no surfaces to cover,
+    // which is the recorded decision that a project without a map is labelled
+    // silently. A tracked corpus normally allows nothing absent, and this is
+    // the second exception beside the secret scan rather than a default.
+    //
+    // The other three are deliberately left out. A map that will not parse, a
+    // map with no usable row, and a range git could not answer are each a
+    // corpus that exists and went unread, so calling any of them an absence
+    // would report a pass over a branch nobody measured.
+    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: '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',
+    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',
+    argv: ['deps', 'audit', '--json'],
+    // Reports rather than gates, on the same split. A published advisory is a
+    // fact about the index and a judgment about this tree, since the upgrade
+    // may not exist yet, and a push failing on one teaches a contributor to
+    // route around the stage while nothing about the dependency has changed.
+    gatingExits: [],
+    corpus: 'upstream',
+    counts: advisoryCounts,
+  },
+]
+
+export function auditFor(id: string): AuditSpec | undefined {
+  return AUDITS.find((audit) => audit.id === id)
+}
+
+export function isTracked(spec: AuditSpec): boolean {
+  return spec.corpus === 'tracked'
+}
+
+export function countsFor(
+  spec: AuditSpec,
+  record: unknown,
+): Record<string, number> | undefined {
+  return spec.counts(record)
+}
+
+/**
+ * Reads the reason a refusing verb published, so the aggregate names the cause
+ * rather than only the exit. Every command here puts it in `reason`, and the
+ * ones that also carry a sentence put that in `message`.
+ */
+function refusalReason(record: unknown, exitCode: number): string {
+  const root = asObject(record)
+  const reason = typeof root?.reason === 'string' ? root.reason : undefined
+  const message = typeof root?.message === 'string' ? root.message : undefined
+
+  if (reason !== undefined && message !== undefined) {
+    return `${reason}: ${message}`
+  }
+  return reason ?? message ?? `exited ${exitCode} with no reason on stdout`
+}
+
+/**
+ * The reasons a verb publishes when the folder it reads is simply not there.
+ *
+ * Typed against the unions those two verbs export rather than spelled as bare
+ * strings, so renaming a reason at its source fails this build. A literal here
+ * would go on matching nothing and quietly turn every expected absence back
+ * into an unmeasured audit.
+ */
+const ABSENT_REASONS: readonly (RecordRefusal | BoardRefusal)[] = [
+  'no-folder',
+  'no-board',
+]
+
+/**
+ * Every reason the advisory verb refuses for, all of which are an absence.
+ *
+ * An index it could not reach, a project that is not JavaScript, and one whose
+ * dependencies were never resolved are three states in which there is nothing
+ * to measure rather than something broken. The verb has no fourth reason, so
+ * this is its whole union rather than a chosen subset, and typing it that way
+ * fails the build if a later reason arrives without this decision being made.
+ *
+ * Typed against that module's own union for the reason the record reasons are:
+ * a literal here would go on matching nothing after a rename and turn every
+ * offline run back into an unmeasured audit.
+ */
+const ADVISORY_ABSENT_REASONS: readonly AuditRefusal[] = [
+  'no-record',
+  'no-lockfile',
+  'no-manifest',
+]
+
+/**
+ * Whether a refusal is a folder this machine never created rather than a break.
+ *
+ * Every gitignored record folder is absent on a fresh clone and in CI, so six
+ * of the twelve refuse there on every run. Counting those as unmeasured pins
+ * the verdict at `incomplete` forever, and a signal that never changes is one
+ * nobody reads after the second time they see it.
+ *
+ * A tracked corpus gets no such allowance. That tree ships to targets, so a
+ * checkout that cannot find it is broken, and reading the absence as ordinary
+ * would report a pass over a corpus nobody measured.
+ *
+ * An upstream corpus takes the allowance for a different reason. Its index is
+ * off this machine, so an offline run reaches nothing through no fault of the
+ * tree, and pinning the verdict at incomplete every time the network is down
+ * is the same signal-nobody-reads failure the per-machine case already names.
+ */
+function absentReasonsFor(spec: AuditSpec): readonly string[] {
+  if (spec.absentReasons !== undefined) return spec.absentReasons
+  if (spec.corpus === 'per-machine') return ABSENT_REASONS
+  if (spec.corpus === 'upstream') return ADVISORY_ABSENT_REASONS
+  return []
+}
+
+function isExpectedAbsence(spec: AuditSpec, record: unknown): boolean {
+  const allowed = absentReasonsFor(spec)
+  if (allowed.length === 0) return false
+
+  const reason = asObject(record)?.reason
+  return typeof reason === 'string' && allowed.includes(reason)
+}
+
+/**
+ * Turns one verb's exit code and stdout into a result the aggregate can report.
+ *
+ * Unparseable output is `unmeasured` rather than clean, for the reason the
+ * verify pipeline already states about its own skipped stages: a run that does
+ * not report is a broken command, and skipping would report the pass the check
+ * exists to withhold.
+ */
+export function classify(
+  spec: AuditSpec,
+  exitCode: number,
+  stdout: string,
+): AuditResult {
+  const base = {
+    id: spec.id,
+    label: spec.label,
+    tracked: isTracked(spec),
+    corpus: spec.corpus,
+    exitCode,
+  }
+
+  let record: unknown
+  let parsed = true
+  try {
+    record = JSON.parse(stdout)
+  } catch {
+    parsed = false
+  }
+
+  if (exitCode === EXIT_REFUSED) {
+    return {
+      ...base,
+      status: isExpectedAbsence(spec, record) ? 'absent' : 'unmeasured',
+      reason: parsed
+        ? refusalReason(record, exitCode)
+        : `refused with no record on stdout`,
+    }
+  }
+
+  const counts = parsed ? spec.counts(record) : undefined
+
+  if (spec.gatingExits.includes(exitCode)) {
+    return { ...base, status: 'finding', ...(counts && { counts }) }
+  }
+
+  if (exitCode !== 0 && exitCode !== EXIT_FINDINGS) {
+    return {
+      ...base,
+      status: 'unmeasured',
+      reason: `exited ${exitCode}, which this verb does not document`,
+    }
+  }
+
+  if (counts === undefined) {
+    return {
+      ...base,
+      status: 'unmeasured',
+      reason: parsed
+        ? 'the record did not carry the keys this audit reads'
+        : 'stdout carried no JSON record',
+    }
+  }
+
+  if (exitCode === EXIT_FINDINGS) {
+    return { ...base, status: 'reported', counts }
+  }
+
+  const quiet = Object.values(counts).every((value) => value === 0)
+  return { ...base, status: quiet ? 'clean' : 'reported', counts }
+}