@erclx/canon 4.88.1 → 4.90.0

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

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

package/claude/skills/docs-fold/REQUIREMENT.md

@@ -28,6 +28,8 @@ This skill writes canonical docs at the end of a long build and never reviews wh
 - Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
 - Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
 - Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
+- Write a decision to the domain context entry it constrains unless it fills an architecture slot, since reach admits nearly every decision to an always-loaded file
+- Merge or retire an architecture entry before adding one at the record's stated cap, and name which in the report, so the cap never turns into compressed prose or two decisions packed under one heading
 - Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
 - Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
 - Scan every memory-review receipt rather than the one matching this slug, since the skill that writes them runs after this one in the ship chain and a slug is unique per feature

package/claude/skills/docs-fold/SKILL.md

@@ -110,6 +110,8 @@ Read `ok` and `reason` out of that record rather than the exit. An operator's sh
 - Do not rewrite sections unrelated to what changed.
 - Rewrite a restated or superseded statement in place rather than appending the replacement beside it. State the fact that stands and keep the earlier reasoning only where it is the alternative that lost, per `${CLAUDE_SKILL_DIR}/../../standards/context.md` and `${CLAUDE_SKILL_DIR}/../../standards/architecture.md`.
 - Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` and the `write-human` skill for all edits.
+- Write a session decision into the `canon/context/` entry for the domain it constrains, under that entry's `## Decisions`, by default. Touch `canon/ARCHITECTURE.md` only for a decision that fills one of the slots `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` names, however many domains its reasoning reaches.
+- Read the entry cap the record states before adding a decision to it. At the cap, merge two decisions or retire one to the domain entry it constrains, and name which in the report. Never compress a decision's prose to fit, and never pack two decisions under one heading.
 - Close a decision entry in `canon/ARCHITECTURE.md` with its verification anchor whenever this run writes that entry or amends its reasoning and that reasoning cites a measured number. Re-read the number against the tree first, since the marker records the read rather than the edit. `${CLAUDE_SKILL_DIR}/../../standards/architecture.md` fixes the sentence.
 - Leave every decision entry this run did not write alone, anchored or not. The rule is scoped forward, so an entry written before it is dated by blame rather than by a read. Step 5 reports a stale anchor and no step writes one on an entry it did not amend.
 
@@ -269,6 +271,10 @@ Output one line per file updated:
 
 `✅ Updated: .claude/<filename>`
 
+When Step 3 met the architecture record's cap, add one line naming what it did there:
+
+`↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
+
 Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
 
 If no files were updated and nothing was swept, output:

package/docs/agents/audits.md

@@ -36,7 +36,7 @@ Each is invoked as the CLI the caller is running rather than as a global `canon`
 
 Five findings fail the run: an unresolved context citation, a banned character, word, or spelling, a relative link resolving to nothing on disk, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
 
-Four of the five are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
+Four of the five are the ones `canon gate run` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the toolkit already ranks content leaving the repository above content that stays.
 
 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.
 

package/docs/agents/commands.md

@@ -68,7 +68,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon worktrees list`           | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                                                                                                                                                                                   |
 | `canon worktrees reclaim`        | Remove every reclaimable worktree and the branch behind it, reporting without acting under `--dry-run` (`--json`)                                                                                                                                                                                                            |
 | `canon comments scan`            | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                                                                                                                                                                       |
-| `canon context audit`            | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record's word weight, and wireframe states against their evidence folders                                                                                            |
+| `canon context audit`            | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record against its own ceiling and entry cap and its word weight, and wireframe states against their evidence folders                                                |
 | `canon context classify diff`    | Classify the chunks a git range changed, each with its enclosing section, as keep, replace, history, or move (`--base`, `--doc-types`, `--json`)                                                                                                                                                                             |
 | `canon context classify sweep`   | Classify every section of the five canonical doc types, split at H3, as keep, rewrite, or move (`--doc-types`, `--json`)                                                                                                                                                                                                     |
 | `canon context classifier show`  | Report the resolved classifier backend and model and which source decided them (`--json`)                                                                                                                                                                                                                                    |

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

@@ -1,6 +1,6 @@
 ---
 title: Context audit checks
-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
+description: What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length and entry cap gates and claim coverage, which folders each check reaches, and what moved to the attribute tier
 ---
 
 # Context audit checks
@@ -91,7 +91,9 @@ The JSON record carries the findings per entry as `entries[].narration` and the
 
 ## The architecture record
 
-Three findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
+Four findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first two are facts.
+
+The entry cap check counts the record's decisions against the cap it states for itself, in a clause of the form `This record holds at most 12 decisions.` Like the length check, the cap belongs to the record rather than to the toolkit, so a record stating none is measured and never gated. A decision is a `###` heading outside a fenced block, so the template a standard shows does not count, and a heading carrying two decisions counts once. The JSON record carries what it read as `architecture.entryCap`, absent where the record states no cap, and the audit catalog counts a record past it as `recordOverCount`.
 
 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`.
 

package/docs/agents/context-audit.md

@@ -37,7 +37,9 @@ 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. 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.
+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`. A record that states an entry cap gates the same way when it holds more decisions than the cap, and a record stating neither limit is reported and never gated.
+
+`bun run check` in the toolkit repository reads both limits through its own Architecture record stage rather than through this verb, since the verb's only gating stage there runs `--citations-only` and never opens the record.
 
 Entry length, reference form, table, provenance, narration, the record's claim classification, and every word figure print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around. Narration is the weakest of the printed measures, 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.
 

package/docs/agents/index.md

@@ -13,7 +13,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every project-level command and every domain subcommand, plus the shape each domain exposes
 - [Comments](comments.md): Comment density by language and kind, the two structural exclusions, and how the degradation sweep finds its vocabulary
-- [Context audit checks](context-audit-checks.md): What each non-gating check reports, the unit each checkpoint is measured in, the architecture record's length gate and claim coverage, which folders each check reaches, and what moved to the attribute tier
+- [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 and entry cap gates 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
 - [Doc classifier](context-classify.md): Classifying canonical-doc content as keep, replace/rewrite, history, or move in diff and sweep mode, the classifier setting pair, the record shape, and the exit codes
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates

package/docs/agents/review-classification.md

@@ -48,7 +48,7 @@ Most carry two spellings, the one a surface authors at and the one it reaches a
 
 `CLAUDE.md` is matched as a whole path rather than as a prefix, because a prefix reaches nothing that sits in no folder. A nested `docs/CLAUDE.md` stays informational.
 
-The set is data at `src/autoship/paths.ts`. That makes it permanently exempt from any later design that folds a machine-parsed list back into the surface citing it, per the machine-parsed clause in `canon/ARCHITECTURE.md`.
+The set is data at `src/autoship/paths.ts`. That makes it permanently exempt from any later design that folds a machine-parsed list back into the surface citing it, per the toolkit's machine-parsed clause: a rule restating the list a parser reads is two sources for one list.
 
 ## Exit codes and refusals
 

package/docs/agents/routing.md

@@ -5,7 +5,7 @@ description: Reading per CLAUDE.md section how many bullets name a path, what co
 
 # Routing report
 
-`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `.claude/rules/canon/claude/592-claude-md.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. `canon/ARCHITECTURE.md` names two further axes, conditional presence and updatability, that this verb does not check.
+`canon claude routing` reports, per `CLAUDE.md` section, how many top-level bullets name a path and how many of those a path-scoped rule already covers. It answers the firing axis of the tier test in `.claude/rules/canon/claude/592-claude-md.md`, whether a fact applies every session or fires on one path, and which until this verb existed was a judgment nothing counted. The tier test names two further axes, conditional presence and updatability, that this verb does not check.
 
 ```bash
 canon claude routing

package/docs/agents/state-scoped-risk.md

@@ -32,7 +32,7 @@ Three root files are read whether or not the field names them, being `package.js
 
 The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, and every test file. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
 
-A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the record's rule that content leaving the repository gates harder than content that stays.
+A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the toolkit's rule that content leaving the repository gates harder than content that stays.
 
 ### What it keys on
 

package/docs/agents/teach.md

@@ -7,6 +7,8 @@ description: Listing learning workspaces with what their records schedule next,
 
 Learning workspaces sit under `.canon/teach/<nn>-<topic>/`, and `standards/teach.md` fixes their layout, naming, and file formats, apart from the glossary, whose shape `standards/glossary.md` fixes, cited from the `teach-workspace` skill, so it travels with the file wherever a promotion lands it. Every verb here resolves that folder against the main worktree root rather than against the working directory, so a session standing in a linked worktree reaches the one workspace the learner has rather than opening a second.
 
+Passing `--root` a path already named `teach` reaches that folder directly rather than wrapping it in the `.canon/`-or-`.claude/` record-root lookup, which is what lets a workspace committed outside the record root, such as a worked example kept in version control on purpose, take every verb below the same as one under `.canon/teach/`.
+
 That root resolution is also why the writing verbs exist at all. The file-editing tools refuse a main-root path from a linked worktree and offer a worktree copy instead, and a caller naming only the destination reports a success that did not happen. A whole-file create still goes out as a shell heredoc. Changing a line inside a file that already exists has no shell route, because the stream editors are banned, so `resource` and `glossary` are the route for the two files a running workspace edits.
 
 ## List

package/governance/rules/claude/540-architecture.md

@@ -10,3 +10,4 @@ paths:
 ## Authority
 
 - Follow the architecture standard for the overview, named decision entries, and risks. It is the single source. Read it with `canon standards architecture`.
+- Add a decision here only when it fills one of the standard's slots, and write any other decision into the context entry for the domain it constrains. At the record's stated cap, merge or retire an entry before adding one.

package/package.json

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

package/src/audits/catalog.ts

@@ -168,6 +168,8 @@ function architectureCounts(
   // zero there would read as one measured and found conforming.
   const ceiling =
     typeof record.ceiling === 'number' ? record.ceiling : undefined
+  const entryCap =
+    typeof record.entryCap === 'number' ? record.entryCap : undefined
 
   let unverifiable = 0
   let unchecked = 0
@@ -188,6 +190,10 @@ function architectureCounts(
     ...(ceiling !== undefined && {
       recordOverLength: record.lines > ceiling ? 1 : 0,
     }),
+    // Absent on a record stating no entry cap, for the same reason.
+    ...(entryCap !== undefined && {
+      recordOverCount: decisions.length > entryCap ? 1 : 0,
+    }),
     recordUnverifiable: unverifiable,
     recordUnchecked: unchecked,
   }

package/src/autoship/paths.ts

@@ -7,7 +7,7 @@
  * application three times, so the set moved here and the body now calls a verb
  * that reads it. Being machine-parsed makes it permanently exempt from any
  * later design that folds a standard back into the surface citing it, per the
- * machine-parsed clause in `canon/ARCHITECTURE.md`.
+ * machine-parsed clause in `canon/context/standards/resolution.md`.
  */
 
 /**

package/src/commands/context.ts

@@ -20,6 +20,7 @@ import {
   architectureRel,
   type ArchitectureReport,
   coveredCount,
+  isOverCount,
   isOverLength,
   measureArchitecture,
   testableCount,
@@ -98,7 +99,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, index drift, the architecture record against its own ceiling and its word weight, and wireframe states against their evidence folders',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, index drift, the architecture record against its own ceiling, its own entry cap, and its word weight, and wireframe states against their evidence folders',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -124,9 +125,11 @@ export function register(program: Command): void {
         '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',
+        'measures it. A record stating an entry cap gates the same way when',
+        'it holds more decisions than the cap. A record stating neither 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.',
         '',
@@ -759,6 +762,7 @@ async function runAudit(
   const gating = isGating({
     unresolvedCitations: citations.unresolved.length,
     recordOverLength: record !== undefined && isOverLength(record),
+    recordOverCount: record !== undefined && isOverCount(record),
     sections,
     drift,
     wireframes,
@@ -1256,6 +1260,20 @@ function reportRecord(
     )
   }
 
+  if (report.entryCap === undefined) {
+    logInfo(
+      `${plural(decisions, 'decision')} and no entry cap stated, so the count is reported and never gated.`,
+    )
+  } else if (isOverCount(report)) {
+    logError(
+      `${plural(decisions, 'decision')} against a cap of ${report.entryCap}. Merge two or retire one, never compress.`,
+    )
+  } else {
+    logInfo(
+      `${plural(decisions, 'decision')} against a cap of ${report.entryCap}.`,
+    )
+  }
+
   if (decisions === 0) {
     logWarn('The record declares no decision, so nothing was classified.')
     return

package/src/context/architecture.ts

@@ -80,6 +80,12 @@ export interface ArchitectureReport {
   readonly allowances?: Allowances
   /** The frame plus the per-decision allowance, absent alongside it. */
   readonly ceiling?: number
+  /**
+   * The most decisions the record says it holds, absent when it states no
+   * cap. Declared by the record for the reason the allowances are, so a
+   * project that never adopted a cap is measured and never gated.
+   */
+  readonly entryCap?: number
   readonly decisions: readonly DecisionReport[]
 }
 
@@ -314,14 +320,32 @@ const SPELLED: Record<string, number> = {
   eight: 8,
   nine: 9,
   ten: 10,
+  eleven: 11,
+  twelve: 12,
+  thirteen: 13,
+  fourteen: 14,
+  fifteen: 15,
+  sixteen: 16,
+  seventeen: 17,
+  eighteen: 18,
+  nineteen: 19,
+  twenty: 20,
 }
 
-const CARDINAL = String.raw`(\d+|${Object.keys(SPELLED).join('|')})`
+// Longest first, so `fourteen` is tried ahead of the `four` it starts with.
+const SPELLED_ALTERNATION = Object.keys(SPELLED)
+  .sort((a, b) => b.length - a.length)
+  .join('|')
+const CARDINAL = String.raw`(\d+|${SPELLED_ALTERNATION})`
 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',
 )
+const ENTRY_CAP_CLAUSE = new RegExp(
+  String.raw`\bat\s+most\s+${CARDINAL}\s+decisions?\b`,
+  'i',
+)
 
 function readCardinal(token: string | undefined): number | undefined {
   if (token === undefined) return undefined
@@ -348,6 +372,17 @@ export function readAllowances(source: string): Allowances | undefined {
   return { frame, perDecision }
 }
 
+/**
+ * Reads the entry cap a record declares for itself, or nothing.
+ *
+ * The clause is the record's own, like the allowances above, so a record
+ * whose wording drifts past it falls back to reporting rather than to a cap
+ * held here that no project wrote.
+ */
+export function readEntryCap(source: string): number | undefined {
+  return readCardinal(source.match(ENTRY_CAP_CLAUSE)?.[1])
+}
+
 /** Whether a read failed because nothing sits at the path. */
 function isMissing(error: unknown): boolean {
   const code = (error as { code?: unknown }).code
@@ -385,6 +420,7 @@ export async function measureArchitecture(
   }
 
   const allowances = readAllowances(source)
+  const entryCap = readEntryCap(source)
   const raw = splitDecisions(source)
   const decisions = await Promise.all(
     raw.map(async (entry) => {
@@ -416,10 +452,24 @@ export async function measureArchitecture(
       allowances,
       ceiling: ceilingFor(allowances, raw.length),
     }),
+    ...(entryCap !== undefined && { entryCap }),
     decisions,
   }
 }
 
+/**
+ * Whether the record holds more decisions than the cap it states.
+ *
+ * False for a record stating no cap, for the reason `isOverLength` gives. The
+ * count is by heading, so a heading carrying several decisions counts once,
+ * which is the undercount `splitDecisions` already names.
+ */
+export function isOverCount(report: ArchitectureReport): boolean {
+  return (
+    report.entryCap !== undefined && report.decisions.length > report.entryCap
+  )
+}
+
 /**
  * Whether the record is longer than the ceiling it derives for itself.
  *

package/src/context/gate.ts

@@ -14,6 +14,11 @@ export interface GateInput {
    * construction, so widening it here would gate on a reading it never took.
    */
   readonly recordOverLength: boolean
+  /**
+   * Whether the record holds more decisions than the cap it states, which
+   * gates under the same two modes and is false in the same two cases.
+   */
+  readonly recordOverCount: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
@@ -68,9 +73,9 @@ export function hasSketchWithEvidence(
  * Whether the audit found something that should fail the caller.
  *
  * 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 findings `--gate` adds are
+ * does a record past its own ceiling or its own entry cap: the record states
+ * each limit for itself, which makes those the measures here that are facts
+ * rather than thresholds a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
  * declare, an index disagreeing with its folder, and a wireframe's States
  * table disagreeing with its evidence folders. Entry length, depth, bullet,
@@ -82,13 +87,14 @@ export function hasSketchWithEvidence(
 export function isGating({
   unresolvedCitations,
   recordOverLength,
+  recordOverCount,
   sections,
   drift,
   wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
-  if (recordOverLength) return true
+  if (recordOverLength || recordOverCount) return true
   if (!widened) return false
 
   return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)

package/src/design/base.css

@@ -4,26 +4,26 @@
    file changes freely and nothing a project wrote lives in it. */
 
 :root {
-  --color-background: #191512;
-  --color-surface: #211c19;
-  --color-chrome: #241e1a;
-  --color-border: #2f2823;
-  --color-text: #f4efe9;
-  --color-text-body: #c9c0b7;
-  --color-text-secondary: #a79d94;
-  --color-muted: #948a81;
-  --color-accent: #e0724b;
+  --color-background: #0f0e0c;
+  --color-surface: #151412;
+  --color-chrome: #1b1a18;
+  --color-border: #2a2926;
+  --color-text: #d9d7d4;
+  --color-text-body: #aeada9;
+  --color-text-secondary: #8c8b86;
+  --color-muted: #7f7f7c;
+  --color-accent: #c76b5f;
   --color-success: #61c454;
-  --color-light-background: #faf7f2;
-  --color-light-surface: #f4efe6;
-  --color-light-chrome: #ede4d6;
-  --color-light-text: #1a1815;
-  --color-light-text-body: #3d3630;
-  --color-light-text-secondary: #5c544b;
-  --color-light-muted: #726b62;
-  --color-light-accent: #a4471c;
+  --color-light-background: #fbfaf8;
+  --color-light-surface: #f1f1ee;
+  --color-light-chrome: #e9e8e5;
+  --color-light-text: #2c2c29;
+  --color-light-text-body: #4b4947;
+  --color-light-text-secondary: #666561;
+  --color-light-muted: #6e6d6c;
+  --color-light-accent: #ad4a4b;
   --color-light-success: #2d6b22;
-  --color-light-border: #e4dcd0;
+  --color-light-border: #d5d4d1;
   --space-xs: 6px;
   --space-sm: 12px;
   --space-md: 18px;

package/src/design/tokens.ts

@@ -94,7 +94,7 @@ export const TOKENS: DesignTokens = {
     '',
     'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
     '',
-    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/ARCHITECTURE.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
+    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/context/scripts/framing.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),
 
   personality: [
@@ -108,58 +108,64 @@ export const TOKENS: DesignTokens = {
     '',
     'Warning and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes and no rendered surface implements an equivalent. Giving either a hex value would invent a mapping no file has, so they carry no contrast reading either.',
     '',
-    'Success is the one of the three that does have a rendered equivalent, which is why it carries a hex. `assets/captures/install.html` marks every confirmed step with it, and the shell writes `ANSI 32` for the same role, so the two are one role in two registers rather than one value in two spellings. The hex is what the rendered surface picked and no reading claims the terminal renders that value. It declares `background` alone as its ground, since that is the only role it is drawn on, where every other dark text role is drawn on both.',
+    'Success is the one of the three that does have a rendered equivalent, which is why it carries a hex. `assets/captures/install.html` marks every confirmed step with it, and the shell writes `ANSI 32` for the same role, so the two are one role in two registers rather than one value in two spellings. The hex is what the rendered surface picked and no reading claims the terminal renders that value. It declares `background` alone as its ground, since that is the only role it is drawn on, where every other dark text role is drawn on both. It is the one role below that is not derived.',
+    '',
+    "Every other role is derived rather than picked, solved in OKLCH by binary search for the lightness that hits a target contrast against its ground, using this module's own anchors. Six anchors are the whole system: ground lightness 0.985 light and 0.165 dark, neutral chroma 0.003 light and 0.004 dark, neutral hue 90 both, accent hue 22 light and 28 dark, accent chroma 0.13 light and 0.12 dark for a mark and 0.095 light and 0.09 dark for a fill. Only the mark step is rendered below, in `accent`. That token already stands in for a fill in practice: `assets/captures/hero.html`'s `.cmd` rule paints its whole background with `var(--color-accent)` and sets text on top, which is a fill use rather than a mark one. The fill chroma step has no token of its own yet, so a lower-saturation `accent-fill` would recolor that button rather than introduce a new consumer. Targets, which are inputs rather than results: text 13.5, body 8.6, secondary 5.6, muted 4.6, accent 5.2. Dark is its own anchor set rather than an inversion of light, and every arm measured in the groundwork behind this landed on identical neutral ratios, which is what made the accent choice a question about hue alone.",
+    '',
+    '`muted` and `light-muted` solve against `surface` rather than `background`. Both declare two grounds and the groundwork solved its target against one, so the recorded hex cleared 4.6 against `background` and read 4.40 dark, 4.24 light against `surface`, the tighter of the two since surface sits a step closer to its text color. The values here are re-solved for the same 4.6 target read against `surface` instead, which clears both: 4.58 dark, 4.56 light against `surface`, and 4.80 dark, 4.95 light against `background`.',
+    '',
+    'The accent is a quiet red at hue 22 light, 28 dark, chosen over a vivid red that read as an error state against a page reporting success, over indigo which carries less distinctiveness at hue 280 in tooling already dominated by that hue, and over rust at hue 42, a larger temperature shift than the problem required. The debt this accepts: `error` and `warning` now share a register with the most repeated element on every rendered surface, so both need differentiating by lightness or by an icon rather than by hue, and that work is unscheduled.',
   ].join('\n'),
 
   color: [
     {
       role: 'background',
       intent: 'page canvas',
-      value: '#191512',
+      value: '#0f0e0c',
     },
     {
       role: 'surface',
       intent: 'cards, panels, raised blocks',
-      value: '#211c19',
+      value: '#151412',
     },
     {
       role: 'chrome',
       intent: 'the window titlebar, one step above the canvas',
-      value: '#241e1a',
+      value: '#1b1a18',
     },
     {
       role: 'border',
       intent: 'every rule and panel edge',
-      value: '#2f2823',
+      value: '#2a2926',
     },
     {
       role: 'text',
       intent: 'headings, counts, emphasized runs',
-      value: '#f4efe9',
+      value: '#d9d7d4',
       grounds: DARK_GROUNDS,
     },
     {
       role: 'text-body',
       intent: 'default body copy',
-      value: '#c9c0b7',
+      value: '#aeada9',
       grounds: DARK_GROUNDS,
     },
     {
       role: 'text-secondary',
       intent: 'labels, captions, supporting copy',
-      value: '#a79d94',
+      value: '#8c8b86',
       grounds: DARK_GROUNDS,
     },
     {
       role: 'muted',
       intent: 'the faintest step, trailing notes',
-      value: '#948a81',
+      value: '#7f7f7c',
       grounds: DARK_GROUNDS,
     },
     {
       role: 'accent',
       intent: 'install command, mark, primary action',
-      value: '#e0724b',
+      value: '#c76b5f',
       grounds: DARK_GROUNDS,
     },
     {
@@ -173,46 +179,46 @@ export const TOKENS: DesignTokens = {
     {
       role: 'light-background',
       intent: 'page canvas on a light ground',
-      value: '#faf7f2',
+      value: '#fbfaf8',
     },
     {
       role: 'light-surface',
       intent: 'cards and panels on a light ground',
-      value: '#f4efe6',
+      value: '#f1f1ee',
     },
     {
       role: 'light-chrome',
       intent: 'the window titlebar, one step above the canvas',
-      value: '#ede4d6',
+      value: '#e9e8e5',
     },
     {
       role: 'light-text',
       intent: 'primary text on a light ground',
-      value: '#1a1815',
+      value: '#2c2c29',
       grounds: LIGHT_GROUNDS,
     },
     {
       role: 'light-text-body',
       intent: 'default body copy on a light ground',
-      value: '#3d3630',
+      value: '#4b4947',
       grounds: LIGHT_GROUNDS,
     },
     {
       role: 'light-text-secondary',
       intent: 'labels, captions, supporting copy on a light ground',
-      value: '#5c544b',
+      value: '#666561',
       grounds: LIGHT_GROUNDS,
     },
     {
       role: 'light-muted',
       intent: 'secondary text on a light ground',
-      value: '#726b62',
+      value: '#6e6d6c',
       grounds: LIGHT_GROUNDS,
     },
     {
       role: 'light-accent',
       intent: 'links and primary action on light',
-      value: '#a4471c',
+      value: '#ad4a4b',
       grounds: LIGHT_GROUNDS,
     },
     {
@@ -224,7 +230,7 @@ export const TOKENS: DesignTokens = {
     {
       role: 'light-border',
       intent: 'rules and panel edges on light',
-      value: '#e4dcd0',
+      value: '#d5d4d1',
       verify: true,
     },
   ],

package/src/gate/measures.ts

@@ -7,6 +7,11 @@ import {
   type ClientCommand,
   clientCommandCitationsIn,
 } from '@/client-commands'
+import {
+  isOverCount,
+  isOverLength,
+  measureArchitecture,
+} from '@/context/architecture'
 import { listRepositoryFiles } from '@/git-files'
 import {
   isShippedCorpus,
@@ -222,6 +227,41 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
   })
 }
 
+/**
+ * The architecture record against the two limits it states for itself: the
+ * line ceiling its allowances derive and the entry cap.
+ *
+ * Read in-process rather than through `context audit`, whose one gating stage
+ * here runs `--citations-only` and never opens the record, which is why the
+ * line ceiling went unenforced by `bun run check` until this stage. A project
+ * carrying no record, or a record stating neither limit, passes, since both
+ * limits belong to the record rather than to the toolkit.
+ */
+export const architectureRecord: Measure = async (ctx) => {
+  const report = await measureArchitecture(ctx.root)
+  if (report === undefined) {
+    return { emissions: [info('No architecture record to measure')] }
+  }
+
+  const decisions = report.decisions.length
+  const failures = [
+    isOverCount(report) &&
+      `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
+    isOverLength(report) &&
+      `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+  ].filter((failure): failure is string => typeof failure === 'string')
+
+  if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }
+
+  const cap =
+    report.entryCap === undefined
+      ? 'no entry cap stated'
+      : `a cap of ${report.entryCap}`
+  return {
+    emissions: [info(`${decisions} decisions against ${cap}`)],
+  }
+}
+
 /**
  * A second run of the records move should rewrite nothing, and the count is
  * only knowable once the folders themselves have landed.

package/src/gate/stages.ts

@@ -1,4 +1,5 @@
 import {
+  architectureRecord,
   auditSet,
   captureStamps,
   clientCommandCitations,
@@ -326,7 +327,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in .claude/ARCHITECTURE.md.
+    // recorded reason, per the criterion in canon/context/tooling.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [
@@ -362,6 +363,13 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Context citations resolve',
   },
+  {
+    // The record's two limits are facts it states about itself, unlike the
+    // judgment thresholds the stage above leaves out, so they gate here.
+    id: 'architecture-record',
+    label: 'Architecture record',
+    checks: [{ kind: 'measure', measure: architectureRecord }],
+  },
   {
     // A rule citing a file that moved fails silently. The consumed-copy drift
     // stage passes an authored rule and its copy that are wrong together, and

package/src/teach/workspace.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
@@ -230,9 +230,14 @@ export function refuse(
  * Every workspace sits under the main worktree root rather than under the
  * checkout the caller stands in. Resolving that root belongs to the caller, so
  * this takes one and never reads the working directory.
+ *
+ * A root already named `teach` is taken as the teach folder itself rather than
+ * a project root to wrap, which is what lets a caller point straight at a
+ * folder such as `examples/teach` that holds workspaces outside any `.canon/`
+ * or `.claude/` record root.
  */
 export function teachDir(root: string): string {
-  return recordDir(root, 'teach')
+  return basename(root) === 'teach' ? root : recordDir(root, 'teach')
 }
 
 async function listSlugs(dir: string): Promise<string[]> {

package/standards/architecture.md

@@ -5,7 +5,7 @@ description: Shape and content rules for canon/ARCHITECTURE.md
 
 # Architecture reference
 
-Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
+Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: session behavior lives there, and the system's shape lives here. Update when a decision is made or a risk is resolved.
 
 ## Scope
 
@@ -20,15 +20,26 @@ Does not govern:
 ## What goes in
 
 - A high-level overview of how the system is structured and why
-- Key technical decisions as named H3 entries: what was chosen and why over the alternatives, including stack and library choices
+- Key technical decisions as named H3 entries, each filling one of the five slots below: what was chosen and why over the alternatives
 - Risks and open questions still unresolved
 
+A decision belongs here only when it fills a slot:
+
+- Stack and runtime: the language, the runtime, and the major libraries the system is built on
+- Delivery: how the system's content or code reaches the place it runs
+- Enforced boundaries: a boundary the system checks mechanically, and what enforces it
+- Layout: how the project's top-level roots and context tiers divide what they hold
+- Build principles: a rule for how a behavior is built that changes work in more than one domain, stated in one sentence
+
+The slots come from a scale test. Ask whether the decision would still be in this file if the project were ten times its size. At that size an always-loaded file holding one entry per decision fits no context window, and what survives is the shape: the stack, the delivery, the boundaries, the layout, and the principles. A decision that fits no slot is a domain decision, and its home is that domain's `canon/context/<domain>.md` entry under `## Decisions`, however many domains its reasoning touches. Reach is not the test, since nearly every decision reaches a second domain.
+
 ## What does not go in
 
 - How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
-- A measurement paragraph specific to one domain's own mechanism. Route it to that domain's `canon/context/<domain>.md` entry instead. The choice and its rejected alternative stay here whatever their reach, since reach is what makes a decision cross-domain, not how many domains its supporting measurement happens to touch.
-- A decision that constrains one domain alone. It lives in that domain's context entry, and this file carries at most one line pointing at it.
+- A decision that fills no slot. It lives in the domain context entry it constrains, and this file carries at most one line pointing at it.
+- A measurement paragraph specific to one domain's own mechanism, even behind a slot decision. Route it to that domain's context entry and keep the choice, the alternative that lost, and one reason here.
+- The instances of a build principle. The principle takes one sentence here, and each instance lives in the domain entry where it applies.
 - The history of how a decision was reached or revised: rounds of candidates, a figure followed by its correction, a branch or change that moved a number. That trail goes to the decision log or the change that introduced it.
 
 ## Sections
@@ -38,7 +49,7 @@ Use `## Overview`, `## Key technical decisions` with one named H3 per decision,
 ## Keeping it current
 
 - Rewrite a decision a later one changed rather than appending the change beside it. A reader should find the design that stands in one place, with the alternative that lost stated once.
-- Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it constrains more than one domain and moving to that domain's context entry when it does not.
+- Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it fills a slot and moving to the domain context entry it constrains when it does not.
 
 ## Verification anchors
 
@@ -54,27 +65,41 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 - Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
 - Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
 
-## Length
+## Entry cap
 
-Every session pays for this file before any work starts, so a heavy read is a real cost. Judge weight by reading the file rather than by counting it: a file that reads heavy is carrying too many decisions, not decisions written too long. A word count, for the file and for each decision, is read alongside that judgment when one is available, and it never gates.
+Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
 
-- Bring a heavy file back by merging two decisions or retiring one, never by compressing a decision's prose.
+- State the cap in the record itself as a clause of the form `This record holds at most <n> decisions.` The cap is the record's own, so a checker reads it from the file, and a record stating none is measured and never gated.
+- Set the cap near one decision per slot plus a small margin.
+- At the cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never compress a decision's prose to fit, and never pack two decisions under one heading, which the count cannot see.
+- Retire a decision by moving it to the domain context entry it constrains, not by deleting its reasoning.
+- A word count, for the file and for each decision, is read alongside the judgment when one is available, and it never gates.
 - Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
 
 ## Template
 
-The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none.
+The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none. Each heading below names a slot, so a record starts with one decision per slot and renames each heading to the choice it records.
 
 ```markdown
 # Architecture
 
 ## Overview
 
+This record holds at most 12 decisions.
+
 ## Key technical decisions
 
-### Decision name
+### Stack and runtime
+
+What was chosen, the alternative that lost, and why. Measured at <short-sha> on <YYYY-MM-DD>.
+
+### Delivery
+
+### Enforced boundaries
+
+### Layout
 
-Reasoning and tradeoffs, carrying the measured number the choice rested on. Measured at <short-sha> on <YYYY-MM-DD>.
+### Build principles
 
 ## Risks / open questions
 ```

package/standards/context.md

@@ -13,7 +13,7 @@ Governs per-domain narrative entries under `canon/context/`: their structure, th
 
 Does not govern:
 
-- Cross-domain decisions and system-wide risks: `architecture.md`
+- Decisions filling a stack, delivery, boundary, layout, or build-principle slot, and system-wide risks: `architecture.md`
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
 - Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
@@ -82,7 +82,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## What goes in
 
 - Per-domain narrative on how the code is structured and why
-- Decisions specific to the domain. Broader cross-domain decisions belong in `canon/ARCHITECTURE.md`.
+- Decisions that constrain the domain, whether or not their reasoning touches another one. This is a decision's default home, and `canon/ARCHITECTURE.md` takes only a decision that fills one of the slots its standard names.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
 - A measured figure, anchored the way `architecture.md` states under `## Verification anchors`, so an entry and the architecture record date a number the same way.

package/tooling/claude/seeds/canon/ARCHITECTURE.md

@@ -4,10 +4,20 @@ Authoring guidance: the architecture standard.
 
 ## Overview
 
+This record holds at most 12 decisions.
+
 ## Key technical decisions
 
-### Decision name
+### Stack and runtime
+
+What was chosen, the alternative that lost, and why.
+
+### Delivery
+
+### Enforced boundaries
+
+### Layout
 
-Reasoning and tradeoffs.
+### Build principles
 
 ## Risks / open questions