@erclx/canon 4.82.0 → 4.84.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/record-root.ts

@@ -46,8 +46,9 @@ const CANON_SCRATCH = 'tmp'
 /**
  * Every entry that lives under the record root, at the name `.claude/` gave it.
  *
- * These are the twelve ignore patterns the move to `.canon/` collapsed into one,
- * so the list counts entries rather than record folders: `.records.git` is the
+ * These are the twelve ignore patterns the move to `.canon/` collapsed into
+ * one, plus every record folder added since, so the list counts entries
+ * rather than record folders: `.records.git` is the
  * backup history rather than a record, and `README.md` is a file a records pull
  * writes back. `worktrees` is absent because the harness creates a worktree
  * under `.claude/` and requires its target to sit there.
@@ -72,6 +73,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   'review',
   'tasks',
   'teach',
+  'walkthroughs',
 ]
 
 /** Whether a name under `.claude/` is one the record root owns. */

package/src/records/backup.ts

@@ -6,8 +6,8 @@ import { RECORD_ROOTS, recordRoot } from '@/record-root'
 
 /**
  * The folders a backup carries, relative to the record root `workTree` resolves
- * rather than to either root specifically, since the same ten names sit under
- * whichever one a tree holds.
+ * rather than to either root specifically, since the same eleven names sit
+ * under whichever one a tree holds.
  *
  * Nothing bounds this list any more, and the move is what took the bound away.
  * The claude manifest used to ship a folder apiece, so the `# Claude` group
@@ -18,7 +18,7 @@ import { RECORD_ROOTS, recordRoot } from '@/record-root'
  * a name is written here.
  *
  * Three counts describe this surface and each is right about a different
- * question, so they are stated apart rather than reconciled. Ten is what a
+ * question, so they are stated apart rather than reconciled. Eleven is what a
  * disk loss would take, which is this list. Twelve is what sat under `.claude/`
  * as an ignored folder before the move, which adds the scratch folder that is
  * deletable without loss and `worktrees/`, whose contents belong to the
@@ -47,6 +47,7 @@ export const BACKED_FOLDERS = [
   'tasks',
   'teach',
   'transcripts',
+  'walkthroughs',
 ] as const
 
 /**

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/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/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/skill.md

@@ -210,7 +210,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, or `teach/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, `teach/`, or `walkthroughs/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.

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

@@ -15,7 +15,7 @@ canon/
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
 ├── decisions/         ← seeded. Decision history a canonical doc points at, never loaded eagerly. `<nn>-<slug>.md` records.
-└── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
+└── 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,5 +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/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