@erclx/canon 4.81.0 → 4.83.0

package/src/context/wireframe-states.ts

@@ -0,0 +1,238 @@
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+import { type BodyLine, bodyLines } from '@/markdown/scan'
+
+/** `standards/wireframes.md`'s `## States` heading, matched by text alone. */
+const STATES_HEADING = /^##\s+States\s*$/i
+const SECTION_HEADING = /^##\s+\S/
+const TABLE_ROW = /^\s*\|/
+const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
+
+/** The one exception the standard admits to the states/evidence bijection. */
+const NOT_CAPTURED = 'not captured'
+
+/** A fenced block's opening delimiter naming the `plaintext` info string. */
+const PLAINTEXT_FENCE = /^`{3,}\s*plaintext\s*$/i
+
+export interface StateRow {
+  readonly line: number
+  readonly state: string
+  /** The evidence cell as written, backticks and all. */
+  readonly evidence: string
+}
+
+export interface MissingFolderFinding {
+  readonly line: number
+  readonly state: string
+  /** The cited path, so a report names what to go create or fix. */
+  readonly path: string
+}
+
+export interface UnlistedFolderFinding {
+  /** The evidence root the folder sits under, cited by at least one row. */
+  readonly root: string
+  readonly folder: string
+}
+
+export interface WireframeStatesReport {
+  readonly rel: string
+  readonly rows: readonly StateRow[]
+  /** A row whose evidence cell names a path with no folder at it. */
+  readonly missingFolders: readonly MissingFolderFinding[]
+  /** A folder under a cited root that no row names. */
+  readonly unlistedFolders: readonly UnlistedFolderFinding[]
+  /** Line of the `plaintext` fence, absent from an entry carrying no sketch. */
+  readonly sketchLine?: number
+  /** Whether that sketch sits beside a state whose evidence already exists. */
+  readonly sketchWithEvidence: boolean
+}
+
+function cells(row: string): string[] {
+  const parts = row.split('|')
+  if ((parts[0] ?? '').trim() === '') parts.shift()
+  if ((parts[parts.length - 1] ?? '').trim() === '') parts.pop()
+  return parts.map((cell) => cell.trim())
+}
+
+function columnIndex(headers: readonly string[], name: string): number {
+  return headers.findIndex(
+    (header) => header.toLowerCase() === name.toLowerCase(),
+  )
+}
+
+/**
+ * Reads the States table under the `## States` heading, matching its `State`
+ * and `Evidence` columns by header text rather than position.
+ *
+ * Column order is the one part of the standard's own table the standard could
+ * still move during its own review, per the plan this ships under. Matching
+ * position would break silently on a reorder, where matching text breaks the
+ * same way a renamed header would: visibly, by finding nothing.
+ */
+export function parseStatesTable(lines: readonly BodyLine[]): StateRow[] {
+  let index = 0
+  while (index < lines.length && !STATES_HEADING.test(lines[index].text)) {
+    index++
+  }
+  if (index >= lines.length) return []
+  index++
+
+  while (index < lines.length && !SECTION_HEADING.test(lines[index].text)) {
+    const separator = lines[index + 1]
+    if (
+      TABLE_ROW.test(lines[index].text) &&
+      separator !== undefined &&
+      TABLE_SEPARATOR.test(separator.text)
+    ) {
+      break
+    }
+    index++
+  }
+  if (
+    index >= lines.length ||
+    SECTION_HEADING.test(lines[index].text) ||
+    !TABLE_ROW.test(lines[index].text)
+  ) {
+    return []
+  }
+
+  const headers = cells(lines[index].text)
+  const stateCol = columnIndex(headers, 'State')
+  const evidenceCol = columnIndex(headers, 'Evidence')
+  if (stateCol === -1 || evidenceCol === -1) return []
+
+  index += 2
+  const rows: StateRow[] = []
+  while (index < lines.length && TABLE_ROW.test(lines[index].text)) {
+    const row = cells(lines[index].text)
+    rows.push({
+      line: lines[index].number,
+      state: row[stateCol] ?? '',
+      evidence: row[evidenceCol] ?? '',
+    })
+    index++
+  }
+
+  return rows
+}
+
+/** Line of the first `plaintext`-fenced sketch, or nothing. */
+export function findSketchLine(lines: readonly BodyLine[]): number | undefined {
+  for (const line of lines) {
+    if (PLAINTEXT_FENCE.test(line.text.trim())) return line.number
+  }
+  return undefined
+}
+
+/**
+ * Reads an evidence cell into the path it cites, or nothing for the one cell
+ * value the standard exempts from having one.
+ */
+function evidencePath(cell: string): string | undefined {
+  const stripped = cell.replace(/^`+|`+$/g, '').trim()
+  if (stripped.toLowerCase() === NOT_CAPTURED) return undefined
+  return stripped.replace(/\/+$/, '')
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+async function subfolders(path: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true })
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Measures one wireframe entry against its own States table.
+ *
+ * The evidence cell resolves as the literal path it names against `root`,
+ * per the plan's operator answer, since the standard puts the path there and a
+ * root guessed from convention reads wrong in a monorepo carrying more than
+ * one evidence tree.
+ *
+ * An unlisted folder is reported only under a root at least one row already
+ * cites, per the same operator answer, so a project holding evidence with no
+ * states table at all reports nothing. `roots` is built from the rows this
+ * loop already resolved rather than scanned separately, which is what keeps
+ * the two readings in the same pass.
+ */
+export async function measureWireframeStates(
+  root: string,
+  rel: string,
+  source: string,
+): Promise<WireframeStatesReport> {
+  const lines = bodyLines(source)
+  const rows = parseStatesTable(lines)
+  const sketchLine = findSketchLine(lines)
+
+  const missingFolders: MissingFolderFinding[] = []
+  const cited = new Map<string, Set<string>>()
+  let anyCaptured = false
+
+  for (const row of rows) {
+    const path = evidencePath(row.evidence)
+    if (path === undefined) continue
+
+    if (!(await isDirectory(join(root, path)))) {
+      missingFolders.push({ line: row.line, state: row.state, path })
+      continue
+    }
+
+    anyCaptured = true
+    const evidenceRoot = dirname(path)
+    const folder = basename(path)
+    const named = cited.get(evidenceRoot) ?? new Set<string>()
+    named.add(folder)
+    cited.set(evidenceRoot, named)
+  }
+
+  const unlistedFolders: UnlistedFolderFinding[] = []
+  for (const [evidenceRoot, named] of cited) {
+    for (const folder of await subfolders(join(root, evidenceRoot))) {
+      if (!named.has(folder)) {
+        unlistedFolders.push({ root: evidenceRoot, folder })
+      }
+    }
+  }
+
+  return {
+    rel,
+    rows,
+    missingFolders,
+    unlistedFolders,
+    ...(sketchLine !== undefined && { sketchLine }),
+    sketchWithEvidence: sketchLine !== undefined && anyCaptured,
+  }
+}
+
+/** Measures every wireframe entry in a resolved `wireframes` folder. */
+export async function measureWireframeFolder(
+  root: string,
+  folder: AuditedFolder,
+): Promise<WireframeStatesReport[]> {
+  const reports: WireframeStatesReport[] = []
+
+  for (const path of folder.entries) {
+    reports.push(
+      await measureWireframeStates(
+        root,
+        relative(root, path),
+        await readFile(path, 'utf8'),
+      ),
+    )
+  }
+
+  return reports
+}

package/src/surface-root.ts

@@ -43,6 +43,7 @@ export const SURFACE_ENTRIES: readonly string[] = [
   'DESIGN.md',
   'context',
   'wireframes',
+  'decisions',
   'canon',
 ]
 

package/standards/architecture.md

@@ -28,16 +28,26 @@ Does not govern:
 - 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.
+- 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
 
 Use `## Overview`, `## Key technical decisions` with one named H3 per decision, and `## Risks / open questions`. Name each decision and give the reasoning, especially for non-obvious choices. Skip entries where the rationale is self-evident.
 
+## 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.
+
 ## Verification anchors
 
 A decision's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
 
 - Close a decision entry whose reasoning cites a measured number with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Name a commit, never a pull request number or a branch. A branch is gone after merge, and a pull request number resolves only on the forge.
+- Carry one anchor per figure. When a number is re-measured, rewrite the number and its anchor in place, and leave the old value to the change that moved it.
+- Point at a generated file that already records a figure and its commit, rather than copying the figure and anchoring the copy.
 - Anchor on the number alone. A decision citing none takes no anchor whatever its reasoning rests on, because a marker over a claim nobody can re-measure is one no reader can falsify.
 - Anchor a decision when writing it or when amending its reasoning. Leave an entry written before the rule unanchored rather than dating it by blame, which is archaeology for a marker nothing reads back.
 - Read an absent anchor as unchecked rather than as current. On an entry citing no number there is nothing to check. On one citing a number the number is due a read.
@@ -46,7 +56,7 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 
 ## Length
 
-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.
+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.
 
 - Bring a heavy file back by merging two decisions or retiring one, never by compressing a decision's prose.
 - Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.

package/standards/context.md

@@ -70,6 +70,7 @@ Pick by what the domain is. Add domain-specific headings as needed.
 ## Ordering
 
 - Order sections `Overview`, `Layout`, `Decisions`, `Gotchas`, then everything else.
+- Name a heading for its subject as it stands (`## Cache`), never for the event that shaped it (`## The cache was the untested part, and the test moved it`). A heading is what a scan reads, so a narrating heading turns the table of contents into a changelog.
 - Entries get read top-down and often partially, so irreducible content sits above recoverable content.
 
 ## The development entry
@@ -84,6 +85,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Decisions specific to the domain. Broader cross-domain decisions belong in `canon/ARCHITECTURE.md`.
 - 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.
 - A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
 
 ## What does not go in
@@ -98,12 +100,13 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Anything already in `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`.
 - The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
 - A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
+- The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. The route goes to the decision log or the change that introduced it.
+- Measured results a generated file already carries. Point at the file instead of copying the figure, so a re-run cannot leave the entry behind.
 
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
 - Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
-- Where a bullet sits past the weight checkpoint `markdown.md` states, the overflow to move is the incident that motivated the decision, which specializes that rule's instruction to send the overflow to prose. Keep the current design and the alternative that lost, and send the incident to the change that introduced it, the issue that tracked it, or the research record behind it.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.

package/standards/decisions.md

@@ -0,0 +1,100 @@
+---
+title: Decisions reference
+description: Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
+---
+
+# Decisions reference
+
+Applies to `canon/decisions/`. Holds the history a canonical doc used to carry itself: pick rounds, superseded figures, and a decision's rejected alternatives, in a tracked folder nothing loads eagerly. A canonical doc points at a record from its own history section rather than restating it.
+
+## Scope
+
+Governs `canon/decisions/`: folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle.
+
+Does not govern:
+
+- Which canonical doc points here and when, and what stays behind in that doc's own body: `architecture.md`, `context.md`, `wireframes.md`, `design.md`, `requirements.md`, once each states its own retirement rule
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+
+## What a working record looks like
+
+A record works when a reader who has never opened the project can follow it from the file alone:
+
+- What was decided, stated once, without needing the canonical doc that points here
+- What else was considered, and why each alternative lost
+- Which claim rests on a measurement, and what commit that measurement was read against
+
+A record failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- `canon/decisions/`, resolved the way every tracked surface is: at `canon/decisions/` in a project that has moved, at `.claude/decisions/` in one that has not.
+- Never add `canon/decisions/index.md` to a `CLAUDE.md` `@` import. A log that loads eagerly rebuilds the bloat it exists to absorb. A canonical doc's own pointer is how a reader reaches a record, one file at a time.
+
+## Record filename
+
+- Name each record `<nn>-<slug>.md`, a two-digit zero-padded ordinal followed by a kebab-case slug, the same shape a groundwork track's folder takes.
+- The ordinal is the order the record was written in, which is what lets a listing sort by when a decision landed rather than alphabetically by subject.
+- Never renumber an existing record. A later reader cites it by that name, and a record whose number moved is a record a stale citation can no longer find.
+
+## Frontmatter
+
+- `title` (required): the decision in sentence case
+- `description` (required): one line naming what was decided
+
+## Sections
+
+Use `## Context`, `## Decision`, `## Alternatives`, and `## Measurements`.
+
+- `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
+- `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
+- `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
+- `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
+
+## Verification anchors
+
+A record's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
+
+- Close a `## Measurements` section with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Anchor on the number alone. A record citing none carries no `## Measurements` section at all.
+- Read an absent section as unchecked rather than as current. A record with no measurements has nothing due a re-read.
+
+## Lifecycle
+
+- Append-only. A written record is never edited to reflect a later reversal.
+- Write a new record when a later decision supersedes an earlier one, naming the record it supersedes. The old record stays as it was written, since it is history rather than a live statement of the current shape.
+- Never auto-loaded. A canonical doc's own history section links to a record by relative path, and a reader reaches it by following that link, not by the folder loading with the session.
+
+## Citation
+
+- Never cite `.canon/`. A record restates what it needs, since a clone without the gitignored records folder resolves nothing there.
+- Cite a same-repository pull request or commit the way `publish.md` fixes for any tracked document.
+
+## Template
+
+```markdown
+---
+title: <Decision, in sentence case>
+description: <one line naming what was decided>
+---
+
+# <Decision title>
+
+## Context
+
+<The problem as it stood, self-contained.>
+
+## Decision
+
+<What was chosen, and why.>
+
+## Alternatives
+
+- **<Alternative>.** <Why it lost.>
+- **<Alternative>.** <Why it lost.>
+
+## Measurements
+
+<The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.
+```

package/standards/design.md

@@ -27,6 +27,7 @@ Does not govern:
 
 - CSS classes and prop names. Those live in code.
 - Anything that needs updating every time the code is refactored
+- The history of how a value or a mark was chosen: the candidates, the rounds, the date of a pick. State the rule and the current value. The trail goes to the decision log.
 
 ## Format
 
@@ -48,6 +49,11 @@ A prose section takes its uncertainty inline instead, in a sentence saying what
 
 Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.
 
+Add either optional section when the project has content for it:
+
+- `## Layout`: page width, breakpoints, and grid rules, as current constraints
+- `## Mark`: the logo's construction rules and the files that carry it
+
 ## Template
 
 The column headers are the strings the renderer parses, read by exact key, so they stay verbatim. Row names are not. Each is slugged into the variable name it emits, which leaves a project free to rename a row, add one, or drop one it has no use for.

package/standards/index.md

@@ -11,6 +11,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Branch reference](branch.md): Branch naming format and type conventions
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
+- [Decisions reference](decisions.md): Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder

package/standards/requirements.md

@@ -30,10 +30,11 @@ Does not govern:
 
 - Implementation details, API names, or internal component references
 - Anything that describes how a feature is built rather than what it does
+- Measured results, such as scores, benchmark figures, or token counts. They move on every run and this file changes least. Name where the results live instead.
 
 ## Sections
 
-Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`, and `## Constraints`. Add `## Distribution` when the rule below applies. Drop a section rather than pad it with filler.
+Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`, and `## Constraints`. Add `## Distribution` when the rule below applies. Add `## Premise` when the project exists to answer a question, stated as the question and what would count as an answer, never as the answer measured so far. Drop a section rather than pad it with filler.
 
 ## Lifecycle
 

package/standards/wireframes.md

@@ -24,11 +24,12 @@ Does not govern:
 
 A wireframe works when someone can rebuild the surface from it without opening the components:
 
-- What is on screen, and where does it sit relative to everything else?
-- Which states can a visitor reach, and what does each one look like?
+- What regions are on screen, by name, and where does each sit relative to the others?
+- Which states can a visitor reach, what triggers each, and where is its captured evidence?
 - What does its structural copy say, word for word, and where does its long-form content come from?
+- What was deliberately left off the surface?
 
-A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The sections are the means. These four questions are the test.
 
 ## Transcription wireframes
 
@@ -45,18 +46,20 @@ Route detail the source citation does not already carry to `canon/context/` as u
 
 Both fields feed `canon/wireframes/index.md` when regenerated.
 
-## Layout
+## Regions
 
-- Draw each surface as an ASCII block inside a `plaintext` fence. One fence per distinct layout.
-- Label regions with `←` annotations. Never use `#` for annotations.
-- Show a region's role, not its styling. `← status pill` reads better than a class name or hex value. A transcription wireframe is the exception: see `## Transcription wireframes`.
-- Keep the grid honest. The ASCII proportions should match the intended widths, since conveying proportion is the wireframe's job.
+- Name every region the surface holds, in a bullet list ordered as a reader scans the page, each with where it sits relative to the others: `- Act pane: right of the answer from 1024 up, an overlay below 1024`. These names are the vocabulary plans, picks, and tests use, and the placement is what a list without a sketch would otherwise lose. Pixel sizes stay in `canon/DESIGN.md`.
+- Draw an ASCII block inside a `plaintext` fence only for a layout that is not built yet. Label regions with `←` annotations, show a region's role rather than its styling, and keep the proportions honest.
+- Remove the fence in the change that first captures evidence for the layout. The capture is the exact picture, and a sketch kept beside it drifts from it. A wireframe carrying both a sketch and an evidence folder for the same layout is non-conforming.
+- Give a layout that changes across a breakpoint its own entry under the list, named by what triggers it (`At 1024 and wider`), not by an arbitrary label. A wider gutter alone is not a new layout.
+- Keep one surface per file, indexed by `index.md`.
 
-## Variants
+## States
 
-- Add a second fence only when the layout itself changes across a breakpoint or state. A wider gutter alone is not a new layout.
-- Name each variant by what triggers it (`## Desktop (≥768px)`, `## Empty state`), not by an arbitrary label.
-- One H2 per variant. Do not stack unrelated surfaces in one file. Keep one surface per file, indexed by `index.md`.
+- List every state a visitor can reach in one table: the state name, what reaches it, what it shows in words, and its evidence folder.
+- Name a state in plain kebab case (`answered`, `refused`) and name its evidence folder the same way, with no ordinal prefix. The table carries the reading order, so a state added in the middle renames nothing.
+- Keep the table and the evidence folders one-to-one. A state with no capture yet reads `not captured` in its evidence cell, which is the one exception, and it stays visible until the capture lands.
+- Add an H3 below the table only for a state that needs more than its row: what differs from the regions in words, and its own copy or behavior.
 
 ## Copy
 
@@ -66,9 +69,19 @@ Both fields feed `canon/wireframes/index.md` when regenerated.
 
 ## Behavior
 
-- Describe interaction intent: what the visitor does, what changes on screen, what each state looks like.
+- Describe interaction intent: what the visitor does and what changes on screen.
 - State the rule, not the mechanism. `The rail tracks the active section as the visitor scrolls` is intent. The scroll handler, throttle, and observer margins are not.
-- Keep it to a short list. A Behavior section longer than the layout is a sign implementation detail has leaked in.
+- Keep it to a short list. A Behavior section longer than the regions and states is a sign implementation detail has leaked in.
+
+## Not on this surface
+
+- State what was deliberately left off, one bullet per exclusion, as a present-tense rule: `- No navigation rail`. This is the section that stops a draft from proposing what was already ruled out.
+- Keep the reason to a clause where one is needed. The rounds that ruled it out go to the decision log.
+
+## What moves out
+
+- Which candidate beat which, and when: the decision log
+- Measurements such as contrast ratios and timings: `canon/DESIGN.md` for tokens and floors, the surface's context entry for the rest
 
 ## What moves to canon/context/
 
@@ -84,13 +97,12 @@ Reference the context entry from the wireframe by path when a reader needs the m
 ## Maintenance
 
 - When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
+- When a state is added, removed, or renamed, update its row and its evidence folder in the same PR.
 - The Behavior and Copy prose around an ASCII block is prose and follows `markdown.md` and the `write-human` skill. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
 
 ## Template
 
-One H2 per layout variant, each holding its own fence. A surface with a single layout carries one.
-
-````markdown
+```markdown
 ---
 title: <Surface name>
 description: <when and where the surface appears>
@@ -98,17 +110,18 @@ description: <when and where the surface appears>
 
 # <Surface name>
 
-## <what triggers this variant>
+<One paragraph: what the surface is for and what it covers.>
 
-```plaintext
-+------------------------------------------+
-| <region>                    ← <its role> |
-+------------------------------------------+
-|                                          |
-| <region>                    ← <its role> |
-|                                          |
-+------------------------------------------+
-```
+## Regions
+
+- <Region>: <what it holds>, <where it sits relative to the others>
+- <Region>: <what it holds>, <where it sits relative to the others>
+
+## States
+
+| State   | Reached when | Shows      | Evidence                   |
+| ------- | ------------ | ---------- | -------------------------- |
+| <state> | <trigger>    | <in words> | `<evidence-root>/<state>/` |
 
 ## Copy
 
@@ -119,5 +132,8 @@ description: <when and where the surface appears>
 ## Behavior
 
 - <what the visitor does, and what changes on screen>
-- <what each reachable state looks like>
-````
+
+## Not on this surface
+
+- <what was deliberately left out, as a present-tense rule>
+```

package/tooling/claude/reference.md

@@ -14,7 +14,8 @@ canon/
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
-└── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
+├── decisions/         ← seeded. Decision history a canonical doc points at, never loaded eagerly. `<nn>-<slug>.md` records.
+└── wireframes/        ← seeded. Per-surface regions and states. `index.md` is the discovery anchor; `<surface>.md` files hold the regions list, the states table, and the behavior bullets.
 
 .claude/
 ├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install

package/tooling/claude/seeds/CLAUDE.md

@@ -21,4 +21,5 @@
 - `src/`: [description]
 - `canon/DESIGN.md`: design tokens and the visual system
 - `canon/context/`: per-domain narrative (how a domain is structured, decisions, gotchas), indexed via `canon/context/index.md`
-- `canon/wireframes/`: per-surface ASCII layouts loaded on demand, indexed via `canon/wireframes/index.md`
+- `canon/wireframes/`: per-surface regions and states loaded on demand, indexed via `canon/wireframes/index.md`
+- `canon/decisions/`: decision history a project doc points at, never loaded eagerly

package/tooling/claude/seeds/canon/decisions/index.md

@@ -0,0 +1,8 @@
+---
+title: Decisions
+subtitle: Decision history a project doc points at, never loaded eagerly
+---
+
+# Decisions
+
+Decision history a project doc points at, never loaded eagerly

package/tooling/claude/seeds/canon/wireframes/index.md

@@ -1,8 +1,8 @@
 ---
 title: Wireframes
-subtitle: Per-surface ASCII layouts loaded on demand
+subtitle: Per-surface regions and states loaded on demand
 ---
 
 # Wireframes
 
-Per-surface ASCII layouts loaded on demand
+Per-surface regions and states loaded on demand