@erclx/canon 4.82.0 → 4.83.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.82.0",
+  "version": "4.83.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -17,6 +17,8 @@ The receipt half of that sweep was missing entirely. A review receipt was delete
 
 The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
 
+This skill writes canonical docs at the end of a long build and never reviews what it wrote. An appended figure or a branch-narrated re-measurement lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
+
 ## Must
 
 - Name the `.claude/` corpus in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
@@ -34,6 +36,10 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Leave the current branch's review receipt alone, since the chain that wrote it cites it in its own closing line and this skill cannot read whether that citation is still live
 - Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
 - Take a promotion destination as already decided, since the operator confirmed it where the page was produced
+- Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
+- Apply a `REPLACE` or `HISTORY` finding, and a regex-decided `MOVE` finding, against the quote it names, report a model-decided `MOVE` finding naming the surface it belongs on rather than cutting it, or keep a finding with a one-line reason, rather than leaving a finding unanswered
+- Rewrite a restated or superseded statement in place rather than appending the replacement beside it, on every canonical doc type this skill writes
+- Report a refusal or a missing `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
 
 ## Must not
 
@@ -45,6 +51,13 @@ The trigger side carries a gap of its own. "Sync the docs" names either corpus t
 - Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
 - Write an anchor onto a decision the run did not amend, or refresh one without re-reading the number. A date from a pass that measured nothing is the false confidence the marker exists to prevent.
 - Anchor an entry written before the rule, which dates it by blame rather than by a read
+- Pick or configure a classifier backend. The project setting decides it, and this skill reports the resolved `modelLayer` as returned.
+- Stop the fold on a classify finding, a refusal, or a missing subcommand. All three report and continue.
+- Apply a finding against a quote found more than once or not found at all. Report that it could not be located instead of guessing.
+- Re-run the classifier after applying a finding, which loops it over its own edit
+- Cut a model-decided `MOVE` finding. The model's own prompt defines `MOVE` more broadly than the regex layer does, for correct content sitting on the wrong surface rather than a deletion candidate, so cutting one can discard content that belongs elsewhere rather than removing detail that never belonged at all.
+- Paste a regex-decided `MOVE` finding's content into another canonical doc after cutting it. It never belonged on the wireframe surface at all, so cutting is the whole fix, not a relocation.
+- Scope Step 10 to the files Steps 3 and 7 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
 
 ## Guards
 

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

@@ -108,6 +108,7 @@ Read `ok` and `reason` out of that record rather than the exit. An operator's sh
 
 - Update only the sections affected by session decisions.
 - 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.
 - 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.
@@ -160,6 +161,7 @@ Reuse the diff from the baseline above, names and content both. For each domain
 
 - Map the entry's section headings, whether they sit in one flat file or spread across a nested domain's sibling files, to the changed files. An entry is relevant when its prose references files, modules, or decisions touched by the diff.
 - For each relevant entry, rewrite only the sections affected by the diff. Same pattern as `docs-sync`. Do not touch unrelated sections. Never rewrite a split domain's own `index.md` directly, since a regen overwrites it the same way it overwrites the top-level catalog. Rewrite the sibling file the affected section actually lives in instead.
+- Rewrite a restated or superseded statement in place rather than appending beside it, the same rule Step 3 applies to the other four canonical doc types.
 - Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/../../standards/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
 
 ### When the diff removes a capability
@@ -245,12 +247,30 @@ Output one line per file swept:
 
 If nothing qualifies, skip this step silently.
 
+## Step 10: classify the fold's diff baseline
+
+Skip this step silently only when the Diff baseline section could not resolve a base ref at all, reporting `⚠ No diff to scope against. Skipped the classify check.` The verb needs a resolvable ref to run against, which is the one condition it cannot answer for itself.
+
+Otherwise resolve `<base>` the way the Diff baseline section already does for Steps 2, 4, 5, and 7, and reuse it rather than resolving a second time. Run the check over the fold's whole baseline rather than scoping it to what Steps 3 and 7 wrote this run: earlier commits on the branch carry doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none.
+
+The invocation is:
+
+```bash
+canon context classify diff --base <base> --json
+```
+
+Never substitute a different verb for it, such as `canon autoship classify` (a different check, over a different scope) or `canon docs <name>` (a documentation lookup, not a classification). Read `${CLAUDE_SKILL_DIR}/references/classify.md` for the record fields, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape. `${CLAUDE_SKILL_DIR}` names this skill's own directory, resolved once when the skill loaded, several steps before this one. If Step 10's memory of that path is uncertain, read the reference by that resolved path rather than guessing a `.claude/skills/docs-fold/references/classify.md` path from the toolkit's install-time layout, which is a different root than the one this skill's own files live under. The invocation above runs either way, whether or not that reference resolves.
+
+Findings never stop the fold. A refusal or a missing subcommand on an older installed binary reports one line, per that reference, and the fold continues either way.
+
 ## After completion
 
 Output one line per file updated:
 
 `✅ Updated: .claude/<filename>`
 
+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:
 
 `✅ No changes needed.`

package/claude/skills/docs-fold/references/classify.md

@@ -0,0 +1,78 @@
+---
+title: Classify the fold's diff baseline
+description: The classify diff invocation, the record fields to read, applying a finding, the one-line keep reason, the unreachable and missing-subcommand lines, and the report shape
+---
+
+# Classify the fold's diff baseline
+
+Mechanics for Step 10 of `docs-fold`. The body owns the skip condition and the shared baseline, and this file owns the invocation, what the record carries, and what applying a finding does.
+
+## Invocation
+
+Call the verb rather than reimplementing its pattern or prompt in this skill:
+
+```bash
+canon context classify diff --base <base> --json
+```
+
+Reuse the base the Diff baseline section already resolved. Never pick or configure a backend here. The project setting decides it, and this step reports `modelLayer` as the record returns it.
+
+## Reading the record
+
+Branch on the record's `decision` field, never on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+- `decision: 'refused'`: a bad range or a file the verb could not read. Report the record's `message` and continue. See "When the verb is absent or refused" below.
+- `decision: 'ok'`: the record carries `modelLayer` (`'off'`, `'ran'`, `'skipped-no-model'`, or `'skipped-unreachable'`) and `findings`.
+
+Each finding carries `file`, a `verdict` of `KEEP`, `REPLACE`, `HISTORY`, or `MOVE`, and `decidedBy` (`'regex'` or `'model'`) naming which layer's reading won. Take the `quote` and `reason` from whichever of the finding's `regex` or `model` fields `decidedBy` names. Skip every `KEEP` finding: nothing decided against that text.
+
+## Scope
+
+Answer every non-`KEEP` finding the verb returns, not only the files Step 3 or Step 7 wrote this run. A branch carrying earlier commits from a prior session has doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
+
+## Applying a finding
+
+Locate the finding by its `quote` in the file's current content. The quote is often a narrow fragment rather than the whole clause it sits in, since the regex layer's own match is a short pattern hit, so the edit below targets the sentence or bullet the quote sits in rather than the literal substring alone.
+
+- **Found exactly once.** Apply the verdict:
+  - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3 and Step 7's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
+  - `HISTORY`: rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it, and a literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
+  - `MOVE`, regex-decided (`decidedBy: 'regex'`): cut the sentence or bullet carrying the quote and stop there. Do not also paste it into another canonical doc, however close a match the current diff makes one look. The regex layer only ever returns `MOVE` inside `canon/wireframes/`, on prose naming a source-file path, which is implementation detail a wireframe surface does not carry, so a regex-decided `MOVE` is always safe to remove outright, and removing it is the whole fix.
+  - `MOVE`, model-decided (`decidedBy: 'model'`): do not cut. The model's own prompt defines `MOVE` more broadly, for correct content sitting on the wrong surface, such as domain mechanism written into `canon/ARCHITECTURE.md` that belongs in a context entry. Cutting would delete content a fold with no model configured would never have flagged at all. Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited.
+- **Found more than once, or not found at all.** Report that the finding could not be located rather than guessing which occurrence or rewriting nothing silently. A model verdict paraphrasing the quote it read is the ordinary way this happens.
+
+Run the classifier once per fold. Do not re-run it after applying a finding to check the edit, since a second pass over what this step wrote is the loop the verb's own reference already warns against.
+
+## Keeping a finding
+
+Keep a non-`KEEP` finding without applying it only when the quote is itself the alternative a nearby decision states and lost, or the file already carries the current fact elsewhere. State the reason in one line in the report. A keep costs one line, where an incorrect apply costs a rewrite of prose nobody asked to change.
+
+## When the verb is absent or refused
+
+The verb ships with the CLI and this skill ships with the plugin, so a target holding an older installed binary carries no `context classify` subcommand. Report:
+
+`⚠ Classify: canon context classify not available on the installed binary. Skipped.`
+
+and continue. Never read a missing subcommand as a clean pass, which would report a run that never checked anything as one that found nothing.
+
+A refused range reports the same way, naming the verb's own message:
+
+`⚠ Classify: <message>`
+
+Neither case stops the fold. This step checks what the fold wrote, and a check that cannot run is not a reason to leave the fold's own output unshipped.
+
+## Report
+
+One line naming what ran:
+
+`✅ Classify: <n> findings, regex ran, model <modelLayer>`
+
+Then one line per non-`KEEP` finding:
+
+- `✏ Rewrote: <file>, "<quote>" (<reason>)`
+- `✂ Cut: <file>, "<quote>" (<reason>)`
+- `➡ Move needed: <file>, "<quote>" (<reason>)`, for a model-decided `MOVE` this step reported rather than cut
+- `⏭ Kept: <file>, "<quote>", <reason for keeping>`
+- `⚠ Not located: <file>, "<quote>" not found or found more than once`
+
+When every finding reads `KEEP`, output `✅ Classify: <n> findings, all KEEP` and nothing further.

package/claude/skills/draft-slides/SKILL.md

@@ -50,7 +50,7 @@ Pass `--variant light` or `--variant dark` to override the source variant for a
 Run this once after the first render, then stop.
 
 1. Convert the deck to images: `soffice --headless --convert-to pdf <deck>.pptx` then `pdftoppm -r 90 -png <deck>.pdf slide`. If `soffice` or `pdftoppm` is missing, skip the image pass and say so. Do not fail the render.
-2. Inspect the images with fresh eyes. Spawn a subagent to check every slide for overlap, overflow, low contrast, and empty regions.
+2. Open and inspect every rendered image in this session, checking each slide for overlap, overflow, low contrast, and empty regions.
 3. Fix the reported issues in `SLIDES.md` once, re-render, and stop. Do not loop indefinitely on aesthetics.
 
 ## Response

package/claude/skills/draft-wireframes/REQUIREMENT.md

@@ -11,7 +11,7 @@ Without this skill, a session drafting a wireframe for a surface with no file ye
 
 ## Must
 
-- Read `standards/wireframes.md` before drafting, since the frontmatter contract, the layout and variant rules, and the Transcription-wireframes branch are what make the file arguable against a sibling
+- Read `standards/wireframes.md` before drafting, since the frontmatter contract, the regions list, the states table, the exclusions section, and the Transcription-wireframes branch are what make the file arguable against a sibling
 - Walk the whole `canon/wireframes/` tree, including a grouped surface's own subfolder, before drafting, since a top-level-only check misses a nested match
 - Detect an existing higher tier from `canon/DESIGN.md` and the wireframes tree and report it, never build a companion render for it, since no shipped mechanism produces one
 - Draft in transcription mode, citing the real source, when the surface names an already-built component. Draft in role-intent mode otherwise.

package/claude/skills/draft-wireframes/SKILL.md

@@ -11,7 +11,7 @@ A project the surface move has not reached keeps its wireframes folder under `.c
 
 Read these files in parallel:
 
-- `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`: the three questions a wireframe must answer, its frontmatter, layout and variant rules, the Transcription-wireframes branch, and what moves to a context entry instead
+- `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`: the four questions a wireframe must answer, its frontmatter, the regions list and states table, the exclusions section, the Transcription-wireframes branch, and what moves to a context entry instead
 - `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for the prose around the fences
 - The `write-human` skill: voice, rhythm, and sentence construction for the prose around the fences
 
@@ -25,15 +25,18 @@ This skill stays fully independent of `docs-fold`'s wireframe coverage sweep, wh
 ## Tier detection
 
 - Read `canon/DESIGN.md` and every existing `canon/wireframes/` file for a tier signal: a Stitch, Excalidraw, or Figma reference, or a marker naming one of them.
-- State the detected tier at the confirm step. Always draft the tier-0 ASCII file regardless of what is detected, since that is the only shape this skill or any other shipped mechanism produces. Report a higher tier rather than attempting a companion render for it.
+- State the detected tier at the confirm step. Always draft the regions-and-states shape regardless of what is detected, since that is the only shape this skill or any other shipped mechanism produces, adding the ASCII sketch fence only when the layout is not built yet. Report a higher tier rather than attempting a companion render for it.
 - Default silently to tier 0 when nothing is detected.
 
 ## Draft
 
 - Decide the mode before drafting. When the surface names an already-built component or file, open that source and draft in transcription mode, citing the render function, the stylesheet rule, or the built file each region and label traces to, per the standard's Transcription-wireframes section.
 - Draft in role-intent mode otherwise: label each region by its role, never by a class name or a token value.
-- Draft `title` and `description` frontmatter, then one `##` heading per layout variant, each holding its own ASCII `plaintext` fence with `←` role annotations, followed by `## Copy` and `## Behavior` sections against `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`'s template.
-- Add a second layout variant only when the layout itself changes across a breakpoint or state, never for a spacing difference alone.
+- Draft `title` and `description` frontmatter, then a lead paragraph naming what the surface is for and what it covers, then `## Regions` as a bullet list naming every region and where it sits relative to the others.
+- Draw an ASCII `plaintext` fence with `←` role annotations only when the layout is not built yet. Skip the fence in transcription mode, which already cites the built source instead.
+- Draft `## States` as a table listing every state a visitor can reach, what reaches it, what it shows in words, and its evidence folder, reading `not captured` in the evidence cell until a capture lands.
+- Follow with `## Copy`, `## Behavior`, and `## Not on this surface`, against `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`'s template.
+- Give a layout that changes across a breakpoint or state its own entry in the regions list, named by what triggers it, never for a spacing difference alone.
 - Leave out algorithms, event-handler code, framework prop or class names outside transcription mode, and anything else the standard sends to a context entry instead.
 
 ## Confirm

package/docs/agents/commands.md

@@ -66,7 +66,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, and index drift                                                                                                                                                                              |
+| `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 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

@@ -55,6 +55,8 @@ The table check reports a catalog that grows a row per shipped thing, not a tabl
 
 The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open.
 
+A change number matches at any digit count, so `PR #7` and `#49` report alongside a four-digit number. Displayed spans are masked before the match runs, which is what keeps a heading's own auto-derived link destination, `(#7-open-questions)`, and a hex color in a code span, `` `#000` ``, from reading as a change reference: both are text an entry shows rather than a claim it makes. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
+
 A date stamping a measurement is excluded, because the standard cuts a date attached to a change and permits one dating a figure. The check reads the clause in front of the date, back to the nearest sentence boundary, for one of five verbs: measured, verified, driven, passed, and fired. The noun `run` counts only where it sits against the date, so `A run on 2026-08-14` is excluded and `Runs on erclx/canon#632 and erclx/canon#634 landed 2026-08-02` reports. The set is closed, and a date it cannot place reports as a change marker rather than as a state of its own, which names one date too many rather than clearing one the rule cuts. <!-- canon-allow-reference: illustrates the input shape the rule reads -->
 
 A release label reports with or without its leading `v` at three segments, since the rule cuts the label rather than a spelling of it. Two segments still need the `v`, which keeps a dollar cost and a duration out. Another tool's version reports too, and the check cannot tell one from a release, so treat a version beside a tool name as a line to read rather than one to cut.
@@ -89,7 +91,7 @@ The JSON record carries the findings per entry as `entries[].narration` and the
 
 ## The architecture record
 
-Two findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
+Three findings read `canon/ARCHITECTURE.md` rather than a folder, and only the first is a fact.
 
 The length check compares the record against the ceiling it derives for itself, and only a record that states its own allowances has one. No standard sets a length rule for this document, so the numbers belong to whichever record declares them. The check reads a frame allowance and an allowance per decision out of the record's own prose and puts the ceiling at the frame plus the allowance times the decision count. The JSON record carries what it read as `architecture.allowances` and the reading as `architecture.lines` against `architecture.ceiling`.
 
@@ -103,9 +105,27 @@ Three limits are stated on every run rather than hidden. The countable signal re
 
 The report gates nothing. Deciding whether a sentence states a claim is a judgment no parser settles, so the output names candidates for a reader. This answers a different question from the verification anchors `standards/architecture.md` describes, which record that one cited number was re-read. That mechanism says whether a marked figure held, and this one says how much of the record could be checked at all.
 
+The third finding is a word count, measured in words rather than lines: one figure for the whole record and one per decision. `standards/architecture.md` asks a session to judge the file's weight by reading it rather than by counting it, and reads the word figure alongside that judgment when one is available. A paragraph written one source line to a paragraph passes the rendered-line measure other checks use while still reading heavy, which is the gap a word count closes without turning into a second cap.
+
+The `## Risks / open questions` section is weighed the same way, reported apart from the whole-record figure since the standard singles it out for holding only what is still open. This finding gates nothing under any mode. The JSON record carries the whole-record figure as `architecture.words`, the section figure as `architecture.risksWords` where the record carries the heading, and the per-decision figure as `architecture.decisions[].words`.
+
+## Wireframe states
+
+Every entry under `canon/wireframes/` carrying a `## States` table is checked against its evidence folders on disk. `State` and `Evidence` are matched by header text rather than column position, since the standard's own template could still move a column during its own review. An entry with no such table is out of scope and reports nothing.
+
+An evidence cell's path is read as written and resolved against the project root, since the standard puts the path in the cell rather than a state name a convention would have to guess at. A state whose cited path resolves to no directory is a missing folder, measured in states: one finding per row. A directory sitting under a root at least one row already cites, but named in no row itself, is an unlisted folder, measured in folders: one finding per directory.
+
+Both are counted rather than only listed, since a count is what a reader compares run to run. A `not captured` cell is the one value the standard exempts from having a folder, and it drops out of both counts.
+
+The third finding reads the whole entry rather than one row: whether it carries a `plaintext`-fenced sketch while a state's evidence already exists on disk. The standard asks the fence to come out the moment a layout has a capture to show instead, so a sketch surviving past that point is a boolean per entry rather than a count.
+
+The unit here is the entry rather than the layout the standard's own rule is stated against. A table names states, not the layouts a wireframe's `## Regions` section can split into at a breakpoint, so this finding has no narrower unit to match a sketch against the evidence for its own layout alone. An entry with a captured default layout and a sketch for a breakpoint layout that is not built yet is conforming, and this finding still reports it, which is why it stays advisory under every mode rather than joining the states-mismatch gate below.
+
+All three wireframe findings are printed under a bare run. The states-mismatch finding, missing and unlisted folders together, gates at `2` under `--gate`, alongside a missing required section and index drift. The sketch finding stays advisory under both modes, for the reason above. The JSON record carries them per entry under `wireframes[]`, as `rows`, `missingFolders`, `unlistedFolders`, and `sketchWithEvidence` alongside `sketchLine`.
+
 ## Which folders each check reaches
 
-The provenance, required-section, and narration checks cover `canon/context/` alone, the reference-form check covers the split folders inside it, and length and the table finding reach every audited folder.
+The provenance, required-section, and narration checks cover `canon/context/` alone, the reference-form check covers the split folders inside it, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
 
 What narrows the three is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere, and a diagram entry carries a heading per kind rather than a run of bullets deciding anything. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
 

package/docs/agents/context-audit.md

@@ -37,9 +37,11 @@ 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. Entry length, reference form, table, provenance, narration, and the record's claim classification print and return `0` under every mode, because each is a judgment and failing a push on one would make the check something to route around. Narration is the weakest of the five, since whether two bullets share a subject is a call the measure approximates from structure alone, and one of the shapes it matches is the rejected alternative the standard asks an entry to keep.
+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.
 
-Required-section and index findings sit between the two. Both are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
+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.
+
+Required-section, index, and wireframe-states findings sit between the two. All three are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. Sketch-with-evidence sits with the printed measures instead, for the reason `context-audit-checks.md` states: it reads a whole entry against whether any of its states has evidence, not one layout against its own evidence, so a conforming file can still trip it. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 
 ## The seed gate
 
@@ -81,3 +83,11 @@ Append `<!-- audit-ignore-citations: <path> -->` to the source line in either ca
 The marker itself stays out of anything that installs. A seed, a plugin skill body, and a stack reference all reach a target, so a marker there lands as toolkit bookkeeping in someone else's tree. Reword those lines to drop the path instead, and where a stop message has to spell it, move that message into a fenced block, which this check already skips.
 
 The pattern spells both record-root prefixes, so a citation into a folder that has moved still resolves and a folder resolved at the project root is measured by every other check while contributing nothing here. A pattern fixed at one root matches nothing after a move and reports nothing, which is a stale reference passing the check written to find it. Widening it to a bare `docs/x.md` would match prose that references nothing, which is a separate decision from where entries come from. A run whose folders all resolved at the root says the check is out of scope rather than reporting that zero paths resolved, and the same run under `--citations-only` refuses, because a gate exiting clean on a scope it could not build is the failure the gate exists to catch.
+
+## The wireframe states gate
+
+Every entry under `canon/wireframes/` carrying a `## States` table is checked one-to-one against its evidence folders, matching the table's `State` and `Evidence` columns by header text rather than position, so a project reordering the template's own columns still resolves. An entry with no such table reports nothing, which is what leaves a project on an older wireframe shape silent until it adopts one.
+
+An evidence cell resolves as the literal path it names, taken from the project root. A state whose cited folder does not exist is a states mismatch, and so is a folder sitting under a cited evidence root that no row names. A `not captured` cell is the one exception the standard admits, and it excuses that row from both readings. A `plaintext` sketch still carried once a state's evidence exists on disk is a third finding this check adds, reading the entry as a whole rather than one row.
+
+The states mismatch is printed under a bare run and gates at `2` under `--gate`, alongside a missing required section and index drift. The sketch finding is printed and stays advisory under both modes: it has no way to pair a sketched layout with that layout's own evidence, only the entry with any evidence at all, so a conforming file, a captured default layout beside a sketch of a breakpoint layout nobody has built, can still trip it.

package/docs/agents/context-classify.md

@@ -5,7 +5,7 @@ description: Classifying canonical-doc content as keep, replace/rewrite, history
 
 # Doc classifier
 
-`canon context classify` reads content from the five canonical doc types (`context/<domain>.md`, `ARCHITECTURE.md`, `wireframes/<surface>.md`, `DESIGN.md`, `REQUIREMENTS.md`) and reports whether each piece states the project as it stands or should be rewritten, narrated elsewhere, or moved to another surface. It reports and never gates: a finding is a judgment for a writer to act on, not a fact a push fails over. Wiring it into `docs-fold`, the merge gate, or `canon context audit` is separate work this verb does not do.
+`canon context classify` reads content from the five canonical doc types (`context/<domain>.md`, `ARCHITECTURE.md`, `wireframes/<surface>.md`, `DESIGN.md`, `REQUIREMENTS.md`) and reports whether each piece states the project as it stands or should be rewritten, narrated elsewhere, or moved to another surface. It reports and never gates: a finding is a judgment for a writer to act on, not a fact a push fails over. The `docs-fold` skill calls this verb in diff mode over its own diff baseline. Wiring it into the merge gate or `canon context audit` is separate work this verb does not do.
 
 Two modes read different units. Diff mode reads the chunks a git range changed, each with the section it landed in, which is what a session checks right after an edit. Sweep mode reads every section of the five doc types, split at H3, which is what a cleanup pass or a periodic re-scan runs over a whole corpus.
 

package/docs/workflow/ai-workflow.md

@@ -19,7 +19,7 @@ canon/
 ├── REQUIREMENTS.md  ← goals, non-goals, MVP scope
 ├── ARCHITECTURE.md  ← technical design decisions
 ├── DESIGN.md        ← visual intent and token decisions (UI projects)
-├── wireframes/      ← ASCII wireframes: layout, UI copy, and interaction rules (UI projects)
+├── wireframes/      ← regions, states, UI copy, and interaction rules (UI projects)
 ├── context/         ← per-domain narrative loaded on demand via index.md
 └── decisions/       ← decision history a canonical doc points at, never loaded eagerly
 

package/docs/workflow/visual-design-workflow.md

@@ -14,7 +14,7 @@ Two tools anchor tier 1 and tier 2. Stitch is the agent-addressable default thro
 
 ## Tier 0: prose only
 
-The default. `canon/DESIGN.md` holds visual intent as prose plus token tables for color, typography, spacing, borders, motion, and iconography. `.claude/WIREFRAMES.md` holds ASCII layouts.
+The default. `canon/DESIGN.md` holds visual intent as prose plus token tables for color, typography, spacing, borders, motion, and iconography. `.claude/WIREFRAMES.md` holds each surface's regions and states.
 
 Claude Code reads both and writes the implementation. Works for CLI tools, internal dashboards, admin panels, and backend-focused projects.
 

package/governance/rules/claude/520-wireframes.md

@@ -9,5 +9,5 @@ paths:
 
 ## Authority
 
-- Follow the wireframes standard for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `canon/context/`. It is the single source. Read it with `canon standards wireframes`.
+- Follow the wireframes standard for layout and interaction intent: regions, the states table and its evidence links, copy, behavior, exclusions, and what moves to `canon/context/`. It is the single source. Read it with `canon standards wireframes`.
 - Read it before adding or revising a surface.

package/package.json

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

package/src/commands/context.ts

@@ -59,6 +59,10 @@ import {
   PRONOUN_HEADING,
   VERB_HEADING,
 } from '@/context/narration'
+import {
+  measureWireframeFolder,
+  type WireframeStatesReport,
+} from '@/context/wireframe-states'
 import { RENDER_WIDTH } from '@/markdown/structure'
 import {
   frameError,
@@ -94,7 +98,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, and the architecture record against its own ceiling',
+      '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',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -662,6 +666,15 @@ async function runAudit(
   // are different answers, and one value for both reports the second as the
   // first.
   const record = gateOnly ? undefined : await measureArchitecture(root)
+  const wireframes = gateOnly
+    ? []
+    : (
+        await Promise.all(
+          folders
+            .filter((folder) => folder.name === 'wireframes')
+            .map((folder) => measureWireframeFolder(root, folder)),
+        )
+      ).flat()
 
   if (gateOnly) {
     reportGate(citations)
@@ -677,6 +690,7 @@ async function runAudit(
     reportNarration(entries, folders, narration)
     reportDrift(drift)
     reportRecord(record, root)
+    reportWireframeStates(wireframes)
     outro()
   }
 
@@ -713,6 +727,11 @@ async function runAudit(
         // target that never wrote one is entitled to. Absent says the run
         // never looked, which is `--citations-only`.
         architecture: gateOnly ? undefined : (record ?? null),
+        // Absent under `--citations-only`, for the same reason as above. An
+        // empty array under the ordinary run says the project carries no
+        // wireframes folder or no entry carrying a States table, which is a
+        // fact rather than an unmeasured run.
+        wireframes: gateOnly ? undefined : wireframes,
         checkpoints: {
           lines: LENGTH_CHECKPOINT,
           renderWidth: RENDER_WIDTH,
@@ -742,6 +761,7 @@ async function runAudit(
     recordOverLength: record !== undefined && isOverLength(record),
     sections,
     drift,
+    wireframes,
     widened,
   })
 
@@ -1202,6 +1222,15 @@ function reportRecord(
   const decisions = report.decisions.length
   const { allowances } = report
 
+  logInfo(
+    `${plural(report.words, 'word')} across ${plural(report.lines, 'line')}, read alongside the weight judgment a session makes by reading the file. This never gates.`,
+  )
+  if (report.risksWords !== undefined) {
+    logInfo(
+      `\`## Risks / open questions\` holds ${plural(report.risksWords, 'word')}, weighed the same way and read alongside the same judgment.`,
+    )
+  }
+
   if (allowances === undefined) {
     logInfo(
       `Covers ${report.rel} alone. No standard sets a length rule for it and this record states none, so its ${plural(report.lines, 'line')} across ${plural(decisions, 'decision')} are reported and nothing is gated.`,
@@ -1261,7 +1290,7 @@ function reportRecord(
           entry.checks.length > 0
             ? `\n  checked by ${entry.checks.join(', ')}`
             : ''
-        return `${report.rel}:${entry.line}  ${kind}${evidence}\n  ${entry.heading}${checks}`
+        return `${report.rel}:${entry.line}  ${kind}${evidence}  ${plural(entry.words, 'word')}\n  ${entry.heading}${checks}`
       })
       .join('\n'),
   )
@@ -1283,3 +1312,43 @@ function reportDrift(drift: readonly FolderDrift[]): void {
   logWarn(plural(lines.length, 'disagreement'))
   pipeOutput(lines.join('\n'))
 }
+
+function reportWireframeStates(
+  wireframes: readonly WireframeStatesReport[],
+): void {
+  logStep('Wireframe states')
+
+  const withRows = wireframes.filter((entry) => entry.rows.length > 0)
+  if (withRows.length === 0) {
+    logInfo(
+      'No wireframe carries a States table, so nothing was checked against its evidence folders.',
+    )
+    return
+  }
+
+  const lines = withRows.flatMap((entry) => [
+    ...entry.missingFolders.map(
+      (finding) =>
+        `${entry.rel}:${finding.line}  ${finding.state}  no folder at ${finding.path}`,
+    ),
+    ...entry.unlistedFolders.map(
+      (finding) =>
+        `${entry.rel}  ${finding.root}/${finding.folder}  named in no row`,
+    ),
+    ...(entry.sketchWithEvidence
+      ? [
+          `${entry.rel}:${entry.sketchLine}  a plaintext sketch sits beside evidence that already exists`,
+        ]
+      : []),
+  ])
+
+  if (lines.length === 0) {
+    logInfo(
+      `${plural(withRows.length, 'wireframe')} checked, every state matched one-to-one with its evidence folder.`,
+    )
+    return
+  }
+
+  logWarn(plural(lines.length, 'finding'))
+  pipeOutput(lines.join('\n'))
+}

package/src/context/architecture.ts

@@ -57,11 +57,25 @@ export interface DecisionReport {
    * claim some check happens to cover without the entry saying so.
    */
   readonly checks: readonly string[]
+  /**
+   * The entry's own word count, read alongside the weight judgment the
+   * standard asks a session to make by reading the file rather than counting
+   * it. Never gates, per `standards/architecture.md`'s `## Length` section.
+   */
+  readonly words: number
 }
 
 export interface ArchitectureReport {
   readonly rel: string
   readonly lines: number
+  /** The whole record's word count, reported for the same reason. */
+  readonly words: number
+  /**
+   * Word count of the `## Risks / open questions` section, absent when the
+   * record carries no such heading. The standard asks that section to hold
+   * only what is still open, so its weight is read the same way the file's is.
+   */
+  readonly risksWords?: number
   /** What the record declared, absent when it states no length rule. */
   readonly allowances?: Allowances
   /** The frame plus the per-decision allowance, absent alongside it. */
@@ -71,6 +85,8 @@ export interface ArchitectureReport {
 
 const DECISION_HEADING = /^###\s+(.+?)\s*$/
 const SECTION_HEADING = /^##\s+\S/
+/** The one H2 the standard's `## Length` section asks to be weighed by words. */
+const RISKS_HEADING = /^##\s+Risks\s*\/\s*open questions\s*$/i
 const CODE_SPAN = /`[^`]*`/g
 /** Dropped ahead of the figure scan, since an anchor date is not a claim. */
 const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/g
@@ -238,6 +254,54 @@ export function splitDecisions(source: string): RawDecision[] {
   return decisions
 }
 
+/**
+ * Counts whitespace-delimited tokens, which is the unit the standard's
+ * `## Length` section reads alongside the weight judgment a session makes by
+ * reading the file. It is a report figure rather than a gate, so a fenced
+ * example or a code span inflating the count costs nothing a reader corrects
+ * for by reading, the same trade the line count above it already takes.
+ */
+function wordCount(text: string): number {
+  return text.match(/\S+/g)?.length ?? 0
+}
+
+/**
+ * Extracts the `## Risks / open questions` section, or nothing when the
+ * record carries no such heading.
+ *
+ * The section is read the same way `splitDecisions` reads a decision: capture
+ * starts at the heading and stops at the next H2, or at the end of the file
+ * when the section is last, which is where the standard's template puts it.
+ */
+export function risksSection(source: string): string | undefined {
+  const lines = bodyLines(source)
+  const body: string[] = []
+  let capturing = false
+  let found = false
+
+  for (const line of lines) {
+    if (line.fenced) {
+      if (capturing) body.push(line.text)
+      continue
+    }
+
+    if (RISKS_HEADING.test(line.text)) {
+      capturing = true
+      found = true
+      continue
+    }
+
+    if (capturing && SECTION_HEADING.test(line.text)) {
+      capturing = false
+      continue
+    }
+
+    if (capturing) body.push(line.text)
+  }
+
+  return found ? body.join('\n') : undefined
+}
+
 /** Cardinals a record spells rather than writes, which the corpus does for both. */
 const SPELLED: Record<string, number> = {
   one: 1,
@@ -332,13 +396,22 @@ export async function measureArchitecture(
         figures,
         ...(quantified !== undefined && { quantified }),
         checks: await namedChecks(root, entry.body),
+        words: wordCount(entry.body),
       }
     }),
   )
 
+  const risks = risksSection(source)
+
   return {
     rel,
     lines: source.replace(/\n$/, '').split('\n').length,
+    words: wordCount(
+      bodyLines(source)
+        .map((line) => line.text)
+        .join('\n'),
+    ),
+    ...(risks !== undefined && { risksWords: wordCount(risks) }),
     ...(allowances !== undefined && {
       allowances,
       ceiling: ceilingFor(allowances, raw.length),