@erclx/aitk 1.4.0 → 1.5.0

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

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

package/docs/agents/context-audit-checks.md

@@ -1,11 +1,11 @@
 ---
 title: Context audit checks
-description: What each non-gating check reports, the unit each checkpoint is measured in, which folders each check reaches, and what moved to the attribute tier
+description: What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
 ---
 
 # Context audit checks
 
-What each finding from `aitk context audit` means. The command surface, its flags, and the one gating check are in `context-audit.md`.
+What each finding from `aitk context audit` means. The command surface, its flags, and the two gating checks are in `context-audit.md`.
 
 ## Required sections
 
@@ -87,6 +87,22 @@ A rejected alternative is a back-reference in the past tense by construction, an
 
 The JSON record carries the findings per entry as `entries[].narration` and the sets as `checkpoints.narration`, which is absent under `--citations-only` where the run never loads them and null where no rule publishes both.
 
+## The architecture record
+
+Two findings read `.claude/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
+
+The length check compares the record against the ceiling it derives for itself, and only a record that states its own allowances has one. No standard sets a length rule for this document, so the numbers belong to whichever record declares them. The check reads a frame allowance and an allowance per decision out of the record's own prose and puts the ceiling at the frame plus the allowance times the decision count. The JSON record carries what it read as `architecture.allowances` and the reading as `architecture.lines` against `architecture.ceiling`.
+
+A record stating no such rule is measured and reported and never gated, which is the ordinary shape of a project that wrote an architecture record and no convention about its length. Holding a pair of numbers in the toolkit and gating every project against them would fail a record on a ceiling that project never agreed to, and the framed line would credit the rule to a file that does not state it.
+
+What the derivation costs where it does apply is that the ceiling rises when a decision is added and falls for nothing, so the check passes exactly when the file grew. It gates anyway, because a record that states a limit for itself and makes it computable from a count has turned it into a fact, which is what separates it from every judgment below. A rewrite of the declaring sentence past the clauses the check reads falls back to reporting rather than to a stale ceiling, so the failure shows up in the run's own output.
+
+The coverage report classifies each decision as carrying a countable claim, a structural invariant, or neither, then reports each testable entry against whether it names a check that exists. A countable claim carries a figure a run could recompute, and an invariant quantifies over a named tree closely enough that a walk could falsify it. A check is a `scripts/**.sh` path the entry spells that is on disk, or an `aitk` invocation matching a registered audit, so coverage reads the entry rather than the tree and a claim some check happens to cover without the entry saying so reads as unchecked.
+
+Three limits are stated on every run rather than hidden. The countable signal reads digits alone, so a measured claim written in words reads as uncounted. Entries are counted by heading, and one heading holding several decisions counts once. Nothing is stored, so an entry rewritten tomorrow is classified afresh the next time the verb runs and no verdict goes stale.
+
+The report gates nothing. Deciding whether a sentence states a claim is a judgment no parser settles, so the output names candidates for a reader. This answers a different question from the verification anchors `.claude/standards/architecture.md` describes, which record that one cited number was re-read. That mechanism says whether a marked figure held, and this one says how much of the record could be checked at all.
+
 ## Which folders each check reaches
 
 The provenance, required-section, and narration checks cover `.claude/context/` alone, the reference-form check covers the split folders inside it, and length and the table finding reach every audited folder.

package/docs/agents/context-audit.md

@@ -5,7 +5,7 @@ description: Running the audit, its flags and folder scope, the exit codes, the
 
 # Context audit
 
-`aitk context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter. It reads and reports. Fixing what it finds is separate work. What each finding means is in `context-audit-checks.md`.
+`aitk context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter, and it measures `.claude/ARCHITECTURE.md` beside them. It reads and reports. Fixing what it finds is separate work. What each finding means is in `context-audit-checks.md`.
 
 Findings stated over every markdown file rather than over a context entry are measured by `aitk markdown audit`, described in `markdown-audit.md`. That command resolves no folder, so it reaches trees this one refuses.
 
@@ -37,7 +37,7 @@ A run where no requested name resolves refuses, whichever list it read. Naming t
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. Length, reference form, table, provenance, and narration findings print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around. Narration is the weakest of the five, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. An architecture record that states its own line allowances gates when it is past the ceiling those derive, on any run that measures it, which is every mode except `--citations-only`, and a record stating none is reported and never gated. Entry length, reference form, table, provenance, narration, and the record's claim classification print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around. Narration is the weakest of the five, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
 
 Required-section and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 
@@ -47,7 +47,7 @@ Required-section and index findings sit between the two. Both are answerable fro
 
 The widened gate is correct here and wrong at the project root. A seed is authored once and read by every target, while a context entry in a live project is edited under time pressure by the people who own it. A missing section in the first is a defect shipping outward, and in the second it is a threshold worth reporting and not worth blocking a push over.
 
-Coverage follows the index-plus-entry contract, so it reaches seeded entries and the indexes beside them. Seed files sitting directly under `.claude/`, currently `ARCHITECTURE.md`, `DESIGN.md`, and `REQUIREMENTS.md`, belong to no audited folder and stay outside it.
+Coverage follows the index-plus-entry contract, so it reaches seeded entries and the indexes beside them. `DESIGN.md` and `REQUIREMENTS.md` sitting directly under `.claude/` belong to no audited folder and stay outside it, while `ARCHITECTURE.md` is measured on its own path. The seed record states no line allowance, so it is reported rather than gated, which is what a seed template showing the shape of a record should be.
 
 The stage prints the entries it measured per root and warns on a root that measured none. A root can resolve an audited folder and hold no entry in it, which `tooling/claude/seeds` does today, so a single pass line over the set would report coverage of a tree nothing opened.
 

package/docs/agents/index.md

@@ -12,7 +12,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [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
-- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, which folders each check reaches, and what moved to the attribute tier
+- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
 - [Context audit](context-audit.md): Running the audit, its flags and folder scope, the exit codes, the citation gate, and the widened gate the seed stage runs
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote

package/package.json

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

package/src/audits/catalog.ts

@@ -103,6 +103,61 @@ function allOf(
   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
@@ -117,13 +172,19 @@ function contextCounts(record: unknown): Record<string, number> | undefined {
     bareReferences += bare
   }
 
-  return allOf({
+  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 {

package/src/commands/context.ts

@@ -15,6 +15,14 @@ import {
   REQUIRED_SECTIONS,
   type SectionFinding,
 } from '@/context/audit'
+import {
+  type ArchitectureReport,
+  coveredCount,
+  isOverLength,
+  measureArchitecture,
+  RECORD_REL,
+  testableCount,
+} from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
 import {
   type AuditedFolder,
@@ -65,7 +73,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, and index drift',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, index drift, and the architecture record against its own ceiling',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -88,11 +96,14 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  a gating finding is present',
         '',
-        'An unresolved citation always gates. --gate widens the gate to the',
-        'other two findings that are facts rather than judgments: a missing',
-        'required section and index drift. Length, reference form, table,',
-        'provenance, and narration findings are judgments and stay advisory',
-        'under both.',
+        'An unresolved citation always gates. An architecture record that',
+        'states its own line allowances gates when it is past the ceiling',
+        'those derive, on any run except --citations-only, which never',
+        'measures it. A record stating no allowance is reported and never',
+        'gated. --gate widens the gate to the other two findings that are',
+        'facts rather than judgments: a missing required section and index',
+        'drift. Entry length, reference form, table, provenance, narration,',
+        'and the record claim classification are judgments under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `aitk markdown audit` measures them.',
@@ -205,6 +216,12 @@ async function runAudit(
   const drift = gateOnly ? [] : await auditIndexes(folders)
   const sections = gateOnly ? [] : missingSections(root, folders, entries)
   const length = gateOnly ? undefined : lengthFindings(entries)
+  // Absent under `--citations-only` and null when the project carries no
+  // record, for the reason `checkpoints.narration` states about its own two
+  // absences. A run that never looked and a project with nothing to look at
+  // are different answers, and one value for both reports the second as the
+  // first.
+  const record = gateOnly ? undefined : await measureArchitecture(root)
 
   if (gateOnly) {
     reportGate(citations)
@@ -219,6 +236,7 @@ async function runAudit(
     reportProvenance(entries, folders)
     reportNarration(entries, folders, narration)
     reportDrift(drift)
+    reportRecord(record)
     outro()
   }
 
@@ -251,6 +269,10 @@ async function runAudit(
         length,
         missingSections: sections,
         indexDrift: drift,
+        // Null says the run opened the project and found no record, which a
+        // target that never wrote one is entitled to. Absent says the run
+        // never looked, which is `--citations-only`.
+        architecture: gateOnly ? undefined : (record ?? null),
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
           renderWidth: RENDER_WIDTH,
@@ -277,6 +299,7 @@ async function runAudit(
 
   const gating = isGating({
     unresolvedCitations: citations.unresolved.length,
+    recordOverLength: record !== undefined && isOverLength(record),
     sections,
     drift,
     widened,
@@ -696,6 +719,101 @@ function reportNarration(
   )
 }
 
+/** How each classification reads in the report. */
+const CLAIM_LABEL: Record<string, string> = {
+  countable: 'countable claim',
+  invariant: 'structural invariant',
+  neither: 'reasoning only',
+}
+
+/**
+ * Reports the architecture record against the ceiling it states for itself and
+ * against what a machine could test in it.
+ *
+ * The length reading is a fact and gates. Everything below it names candidates
+ * a reader adjudicates, because deciding whether a sentence states a claim is a
+ * judgment no parser settles, and a stored verdict would age the way the
+ * anchors it sits beside already do. Nothing is stored: every run reclassifies,
+ * so an entry rewritten tomorrow is read as it stands then.
+ */
+function reportRecord(report: ArchitectureReport | undefined): void {
+  logStep('Architecture record')
+
+  if (report === undefined) {
+    logInfo(
+      `Out of scope. The project carries no ${RECORD_REL}, so there was no record to measure.`,
+    )
+    return
+  }
+
+  const decisions = report.decisions.length
+  const { allowances } = report
+
+  if (allowances === undefined) {
+    logInfo(
+      `Covers ${report.rel} alone. No standard sets a length rule for it and this record states none, so its ${plural(report.lines, 'line')} across ${plural(decisions, 'decision')} are reported and nothing is gated.`,
+    )
+    logInfo(
+      'A record declaring an allowance for its frame and one a decision is measured against the ceiling those two derive. That rule belongs to whichever record writes it, never to the toolkit.',
+    )
+  } else {
+    logInfo(
+      `Covers ${report.rel} alone, which states its own allowance of ${plural(allowances.frame, 'line')} for the frame and ${allowances.perDecision} a decision.`,
+    )
+    if (isOverLength(report)) {
+      logError(
+        `${report.lines} lines against a ceiling of ${report.ceiling} from ${plural(decisions, 'decision')}`,
+      )
+    } else {
+      logInfo(
+        `${report.lines} lines against a ceiling of ${report.ceiling} from ${plural(decisions, 'decision')}.`,
+      )
+    }
+    logInfo(
+      `The ceiling rises with the decision count, so adding a decision buys ${allowances.perDecision} lines and the check passes exactly when the file grew.`,
+    )
+  }
+
+  if (decisions === 0) {
+    logWarn('The record declares no decision, so nothing was classified.')
+    return
+  }
+
+  const testable = testableCount(report)
+  const covered = coveredCount(report)
+
+  logInfo(
+    'A countable claim carries a figure a run could recompute and an invariant quantifies over a named tree a walk could falsify. Both are candidates a reader settles, and neither gates.',
+  )
+  logInfo(
+    'A figure spelled in words reads as uncounted, since a cardinal in prose is pronominal more often than measured. Entries are counted by heading, so a heading carrying several decisions counts once and the total reads low by however many it holds.',
+  )
+  const line = `${testable} of ${decisions} carry a claim a machine could test, ${covered} of which name a check that exists`
+  // A record whose every testable claim names a check has nothing to act on,
+  // and so does one carrying no testable claim at all. Warning on both is how
+  // a section becomes one nobody reads after the second run.
+  if (testable > covered) logWarn(line)
+  else logInfo(`${line}.`)
+  logInfo(
+    'Coverage reads the entry rather than the tree, so a claim some check happens to cover without the entry naming it reads as unchecked.',
+  )
+
+  pipeOutput(
+    report.decisions
+      .map((entry) => {
+        const kind = CLAIM_LABEL[entry.claim] ?? entry.claim
+        const evidence =
+          entry.figures.length > 0 ? `  ${entry.figures.join(' ')}` : ''
+        const checks =
+          entry.checks.length > 0
+            ? `\n  checked by ${entry.checks.join(', ')}`
+            : ''
+        return `${report.rel}:${entry.line}  ${kind}${evidence}\n  ${entry.heading}${checks}`
+      })
+      .join('\n'),
+  )
+}
+
 function reportDrift(drift: readonly FolderDrift[]): void {
   logStep('Index drift')
 

package/src/context/architecture.ts

@@ -0,0 +1,364 @@
+import { access, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { AUDITS } from '@/audits/catalog'
+import { bodyLines } from '@/markdown/scan'
+
+/**
+ * The record this measures, relative to the project root.
+ *
+ * One fixed path rather than a folder walk, because the standard governing it
+ * names one document, and the length rule this measures is stated by whichever
+ * record sits there rather than by the standard or by this file.
+ */
+export const RECORD_REL = '.claude/ARCHITECTURE.md'
+
+/**
+ * The line allowances a record states for itself, absent when it states none.
+ *
+ * No standard sets a length rule for this document, so the numbers belong to
+ * whichever record declares them rather than to the toolkit. Holding a pair in
+ * code and gating every project against it audits a target against a rule it
+ * never adopted, which is the failure `canResolveAtRoot` already answers on the
+ * folder side. A record stating no rule is measured and never gated.
+ */
+export interface Allowances {
+  readonly frame: number
+  readonly perDecision: number
+}
+
+/**
+ * What a machine could do with the entry's reasoning, which is a candidate
+ * rather than a verdict.
+ *
+ * - `countable`: carries a figure over a tree, so a run could recompute it.
+ * - `invariant`: quantifies over a named tree, so a walk could falsify it.
+ * - `neither`: says why a choice was made, which nothing tests.
+ */
+export type ClaimKind = 'countable' | 'invariant' | 'neither'
+
+export interface DecisionReport {
+  readonly heading: string
+  /** Line of the `###` heading, so a report line opens at the entry. */
+  readonly line: number
+  readonly claim: ClaimKind
+  /** The digit-spelled figures behind a `countable` reading, in order. */
+  readonly figures: readonly string[]
+  /** The first sentence behind an `invariant` reading, absent otherwise. */
+  readonly quantified?: string
+  /**
+   * Executable checks the entry names, which is the only coverage signal the
+   * record carries. Empty on an entry that names none, including one whose
+   * claim some check happens to cover without the entry saying so.
+   */
+  readonly checks: readonly string[]
+}
+
+export interface ArchitectureReport {
+  readonly rel: string
+  readonly lines: number
+  /** What the record declared, absent when it states no length rule. */
+  readonly allowances?: Allowances
+  /** The frame plus the per-decision allowance, absent alongside it. */
+  readonly ceiling?: number
+  readonly decisions: readonly DecisionReport[]
+}
+
+const DECISION_HEADING = /^###\s+(.+?)\s*$/
+const SECTION_HEADING = /^##\s+\S/
+const CODE_SPAN = /`[^`]*`/g
+/** Dropped ahead of the figure scan, since an anchor date is not a claim. */
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
+const FIGURE = /\b\d+(?:,\d{3})*\b/g
+const SENTENCE_SPLIT = /(?<=[.])\s+/
+
+/** A code span naming a path, which is what a quantifier has to govern. */
+const PATH_SPAN = String.raw`\`[^\`]*(?:/|\.md|\.ts|\.sh|\.json)[^\`]*\``
+const QUANTIFIER = String.raw`\b(?:every|each|no|nothing|any|all|never|only)\b`
+/** Six words is the widest gap the corpus puts between the two. */
+const WINDOW = String.raw`(?:\s+\S+){0,6}?\s+`
+
+const QUANTIFIES_PATH = new RegExp(
+  `${QUANTIFIER}${WINDOW}${PATH_SPAN}|${PATH_SPAN}${WINDOW}${QUANTIFIER}`,
+  'i',
+)
+
+/** A code span naming a shell check this repository could run. */
+const SCRIPT_SPAN = /^scripts\/[\w./-]+\.sh$/
+/** A code span invoking the CLI, which may or may not name a registered audit. */
+const AITK_SPAN = /^aitk\s+(.+)$/
+
+/**
+ * The audit invocations a decision could name, spelled as a reader writes them.
+ *
+ * Read off the catalog rather than listed, so a verb renamed at its source
+ * stops matching here instead of going on matching a string nobody maintains.
+ */
+const AUDIT_INVOCATIONS: readonly string[] = AUDITS.map((audit) =>
+  audit.argv.filter((arg) => arg !== '--json').join(' '),
+)
+
+function codeSpans(text: string): string[] {
+  return (text.match(CODE_SPAN) ?? []).map((span) => span.slice(1, -1))
+}
+
+/**
+ * Names the executable checks an entry spells.
+ *
+ * A script has to exist on disk and an `aitk` invocation has to match a
+ * registered audit, because an entry naming a check that was removed is an
+ * uncovered claim wearing a covered one's words.
+ */
+async function namedChecks(root: string, body: string): Promise<string[]> {
+  const spans = [...new Set(codeSpans(body))]
+
+  const verbs = spans.filter((span) => {
+    const invocation = span.match(AITK_SPAN)?.[1]
+    return invocation !== undefined && AUDIT_INVOCATIONS.includes(invocation)
+  })
+
+  const scripts = spans.filter((span) => SCRIPT_SPAN.test(span))
+  const present = await Promise.all(
+    scripts.map((span) =>
+      access(join(root, span)).then(
+        () => true,
+        () => false,
+      ),
+    ),
+  )
+
+  return [...verbs, ...scripts.filter((_, index) => present[index])]
+}
+
+/**
+ * Reads the figures a decision carries, which is the countable-claim signal.
+ *
+ * Digits alone. A cardinal spelled in words reads as pronominal far more often
+ * than as measured in this corpus, where "the alternative and it is one nobody
+ * passes" outnumbers "eleven copies", and admitting the spelled form classified
+ * 22 of 24 entries as countable, which distinguishes nothing. The cost is that
+ * a measured claim written in words reads as uncounted, which the report says.
+ */
+function figuresIn(body: string): string[] {
+  return body.replace(ISO_DATE, ' ').replace(CODE_SPAN, ' ').match(FIGURE) ?? []
+}
+
+/**
+ * The first sentence quantifying over a named tree, or undefined.
+ *
+ * The quantifier has to sit within a short window of the path so a sentence
+ * mentioning both without relating them does not read as a claim about the
+ * tree. Both orders are matched, since the corpus writes the property before
+ * the path as readily as after it.
+ */
+function quantifiedSentence(body: string): string | undefined {
+  return body
+    .replace(ISO_DATE, ' ')
+    .split(SENTENCE_SPLIT)
+    .map((sentence) => sentence.replace(/\n/g, ' ').trim())
+    .find((sentence) => QUANTIFIES_PATH.test(sentence))
+}
+
+/**
+ * Classifies one entry, with the countable reading taking precedence.
+ *
+ * An entry carrying both a figure and a quantified tree is recomputable, which
+ * is the stronger test, and the two readings are reported as one kind because
+ * the coverage split a reader wants is testable against unverifiable rather
+ * than a per-entry inventory of every claim in it.
+ */
+export function classifyDecision(body: string): {
+  claim: ClaimKind
+  figures: string[]
+  quantified?: string
+} {
+  const figures = figuresIn(body)
+  if (figures.length > 0) return { claim: 'countable', figures }
+
+  const quantified = quantifiedSentence(body)
+  if (quantified !== undefined) {
+    return { claim: 'invariant', figures: [], quantified }
+  }
+
+  return { claim: 'neither', figures: [] }
+}
+
+interface RawDecision {
+  readonly heading: string
+  readonly line: number
+  readonly body: string
+}
+
+/**
+ * Splits the record into its `###` entries.
+ *
+ * A heading inside a fenced block is skipped, since the seed template shows the
+ * shape it asks a project to write and a template entry is not a decision.
+ *
+ * A heading carrying several decisions counts once, so the total reads low by
+ * however many it holds. The report states that rather than parsing for it,
+ * because splitting a decision from its heading needs a marker the standard
+ * does not ask a record to carry.
+ */
+export function splitDecisions(source: string): RawDecision[] {
+  const lines = bodyLines(source)
+  const decisions: RawDecision[] = []
+  let open: { heading: string; line: number; body: string[] } | undefined
+
+  for (const line of lines) {
+    if (line.fenced) {
+      open?.body.push(line.text)
+      continue
+    }
+
+    const heading = line.text.match(DECISION_HEADING)?.[1]
+    if (heading !== undefined) {
+      if (open) decisions.push({ ...open, body: open.body.join('\n') })
+      open = { heading, line: line.number, body: [] }
+      continue
+    }
+
+    // A decision runs to the next `###` or to the section that follows the
+    // decision list, so the risks below never read as the last entry's body.
+    if (SECTION_HEADING.test(line.text)) {
+      if (open) decisions.push({ ...open, body: open.body.join('\n') })
+      open = undefined
+      continue
+    }
+
+    open?.body.push(line.text)
+  }
+
+  if (open) decisions.push({ ...open, body: open.body.join('\n') })
+  return decisions
+}
+
+/** Cardinals a record spells rather than writes, which the corpus does for both. */
+const SPELLED: Record<string, number> = {
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+}
+
+const CARDINAL = String.raw`(\d+|${Object.keys(SPELLED).join('|')})`
+const FRAME_CLAUSE = new RegExp(String.raw`${CARDINAL}-line frame`, 'i')
+const PER_DECISION_CLAUSE = new RegExp(
+  String.raw`${CARDINAL}\s+lines?\s+a\s+decision`,
+  'i',
+)
+
+function readCardinal(token: string | undefined): number | undefined {
+  if (token === undefined) return undefined
+  const spelled = SPELLED[token.toLowerCase()]
+  if (spelled !== undefined) return spelled
+
+  const digits = Number.parseInt(token, 10)
+  return Number.isNaN(digits) ? undefined : digits
+}
+
+/**
+ * Reads the allowances a record declares for itself, or nothing.
+ *
+ * Both clauses have to be present, because half a formula is not one. A record
+ * whose wording drifts past these clauses falls back to reporting rather than
+ * to a stale ceiling held here, so the failure is visible in the run's own
+ * output instead of gating a project on a rule nobody can point at.
+ */
+export function readAllowances(source: string): Allowances | undefined {
+  const frame = readCardinal(source.match(FRAME_CLAUSE)?.[1])
+  const perDecision = readCardinal(source.match(PER_DECISION_CLAUSE)?.[1])
+
+  if (frame === undefined || perDecision === undefined) return undefined
+  return { frame, perDecision }
+}
+
+/** Whether a read failed because nothing sits at the path. */
+function isMissing(error: unknown): boolean {
+  const code = (error as { code?: unknown }).code
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+/** The ceiling the record's own formula derives from its decision count. */
+export function ceilingFor(allowances: Allowances, decisions: number): number {
+  return allowances.frame + allowances.perDecision * decisions
+}
+
+/**
+ * Measures the record, or reports nothing when the project carries none.
+ *
+ * Absent rather than empty, for the reason the sibling checks state: a project
+ * with no record and one whose record holds no decision are different answers,
+ * and a zeroed report reads as the second.
+ */
+export async function measureArchitecture(
+  root: string,
+): Promise<ArchitectureReport | undefined> {
+  const path = join(root, RECORD_REL)
+
+  let source: string
+  try {
+    source = await readFile(path, 'utf8')
+  } catch (error) {
+    // Only a record that is not there reads as absent. A record present and
+    // unreadable propagates the way every sibling reader here lets one
+    // propagate, since swallowing it reports a project with no record and the
+    // length gate passes over a file nobody opened.
+    if (!isMissing(error)) throw error
+    return undefined
+  }
+
+  const allowances = readAllowances(source)
+  const raw = splitDecisions(source)
+  const decisions = await Promise.all(
+    raw.map(async (entry) => {
+      const { claim, figures, quantified } = classifyDecision(entry.body)
+      return {
+        heading: entry.heading,
+        line: entry.line,
+        claim,
+        figures,
+        ...(quantified !== undefined && { quantified }),
+        checks: await namedChecks(root, entry.body),
+      }
+    }),
+  )
+
+  return {
+    rel: RECORD_REL,
+    lines: source.replace(/\n$/, '').split('\n').length,
+    ...(allowances !== undefined && {
+      allowances,
+      ceiling: ceilingFor(allowances, raw.length),
+    }),
+    decisions,
+  }
+}
+
+/**
+ * Whether the record is longer than the ceiling it derives for itself.
+ *
+ * False for a record declaring no allowances, which has no ceiling to be past.
+ * That is the answer rather than a gap, since the length rule is the record's
+ * own and a project that never wrote one owes nothing to it.
+ */
+export function isOverLength(report: ArchitectureReport): boolean {
+  return report.ceiling !== undefined && report.lines > report.ceiling
+}
+
+/** How many entries carry a claim a machine could test. */
+export function testableCount(report: ArchitectureReport): number {
+  return report.decisions.filter((entry) => entry.claim !== 'neither').length
+}
+
+/** How many testable entries name a check that exists. */
+export function coveredCount(report: ArchitectureReport): number {
+  return report.decisions.filter(
+    (entry) => entry.claim !== 'neither' && entry.checks.length > 0,
+  ).length
+}

package/src/context/gate.ts

@@ -4,6 +4,15 @@ import type { FolderDrift } from '@/context/index-drift'
 export interface GateInput {
   /** Cited paths that resolved to nothing, which gate under either mode. */
   readonly unresolvedCitations: number
+  /**
+   * Whether the architecture record is longer than the ceiling it derives for
+   * itself, which gates under either mode for the reason a citation does.
+   *
+   * False when the project carries no record and false under
+   * `--citations-only`, which never measures it. That mode runs one check by
+   * construction, so widening it here would gate on a reading it never took.
+   */
+  readonly recordOverLength: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
@@ -24,19 +33,24 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
 /**
  * Whether the audit found something that should fail the caller.
  *
- * An unresolved citation is a broken pointer and gates unconditionally. The two
- * findings `--gate` adds are the ones answerable from the file itself: a
- * required section it does not declare, and an index disagreeing with its
- * folder. Length, depth, bullet, table, and provenance findings are thresholds
- * a reader weighs, so they stay out under both modes.
+ * An unresolved citation is a broken pointer and gates unconditionally, and so
+ * does a record past its own ceiling: the record states the limit for itself
+ * and derives it from a count, which makes it the one measure here that is a
+ * fact rather than a threshold a reader weighs. The two findings `--gate` adds
+ * are the ones answerable from the file itself: a required section it does not
+ * declare, and an index disagreeing with its folder. Entry length, depth,
+ * bullet, table, provenance, and the record's claim coverage are judgments, so
+ * they stay out under both modes.
  */
 export function isGating({
   unresolvedCitations,
+  recordOverLength,
   sections,
   drift,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
+  if (recordOverLength) return true
   if (!widened) return false
 
   return sections.length > 0 || hasDrift(drift)