@erclx/canon 4.82.0 → 4.84.0

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
 
@@ -242,6 +242,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:markdown-propose` | When a markdown claim needs rewriting and the change should wait for an answer per file |
 | `canon:ux-audit`         | To read UI source for missing states, edge cases, and inconsistencies                   |
 | `canon:ux-measure`       | To start the interface and measure paint, processor, and layout cost                    |
+| `canon:ux-walkthrough`   | To run a multi-finding inspection pass over a running app with the operator             |
 
 ### Ship it
 

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.
 
@@ -41,6 +41,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
 - Anthropic's `frontend-design` plugin optional for light visual steering
 

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.84.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -138,6 +138,11 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Tell me the paint and layout cost of this page right now.',
     expect: 'ux-measure',
   },
+  {
+    prompt:
+      'Sit with me while I go through my whole list of app findings one at a time, and write down each pick with what it beat.',
+    expect: 'ux-walkthrough',
+  },
   {
     prompt:
       'I am building this branch for another session. What am I on the hook for, and what is off limits?',

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),

package/src/context/audit.ts

@@ -77,6 +77,14 @@ const INSIDE_LIST = /^\s+\S/
  * and which release labelled it. A marker is a judgment rather than a defect,
  * so this is measured and reported and never gates.
  *
+ * The change pattern matches any digit count rather than the three-plus this
+ * used to require, since a project young enough to sit in single or double
+ * digits, `PR #7`, went entirely unread under the old floor. Widening it reads
+ * a change reference wherever a document is scanned as prose, so `provenance`
+ * masks a line's displayed spans first, which is what keeps a heading's own
+ * auto-derived link destination, `(#7-open-questions)`, from reading as a
+ * change number: `#7` there names the heading, not a pull request.
+ *
  * The release pattern accepts three segments without a leading `v`, since the
  * standard cuts a release label rather than a spelling of one and `a CLI at
  * 0.83.0` names a release exactly as `v0.83.0` does. Two segments still require
@@ -88,7 +96,7 @@ const INSIDE_LIST = /^\s+\S/
  */
 const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
   { kind: 'date', pattern: /\b\d{4}-\d{2}-\d{2}\b/g },
-  { kind: 'change', pattern: /#\d{3,}\b/g },
+  { kind: 'change', pattern: /#\d+\b/g },
   { kind: 'release', pattern: /\b(?:v\d+\.\d+(?:\.\d+)?|\d+\.\d+\.\d+)\b/g },
 ]
 
@@ -349,6 +357,12 @@ function catalogTables(entry: readonly BodyLine[]): TableFinding[] {
  * rather than a claim it makes, and a version pinned in an install line is the
  * ordinary shape of one.
  *
+ * Displayed spans are masked for the same reason. A code span quoting a hex
+ * color, `#000`, and a link destination naming a heading's own anchor,
+ * `(#7-open-questions)`, both read as text the entry shows rather than a claim
+ * it makes, which is the same distinction the fence skip draws at the block
+ * level.
+ *
  * A date stamping a measurement is dropped rather than reported under a kind of
  * its own. One list with one meaning is what lets every consumer read it
  * without filtering: the report names what the standard cuts, and the length
@@ -365,8 +379,10 @@ function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
   for (const line of lines) {
     if (line.fenced) continue
 
+    const text = maskDisplayed(line.text)
+
     for (const { kind, pattern } of PROVENANCE) {
-      for (const match of line.text.matchAll(pattern)) {
+      for (const match of text.matchAll(pattern)) {
         if (kind === 'date' && stampsMeasurement(line.text, match.index)) {
           continue
         }

package/src/context/gate.ts

@@ -1,5 +1,6 @@
 import type { SectionFinding } from '@/context/audit'
 import type { FolderDrift } from '@/context/index-drift'
+import type { WireframeStatesReport } from '@/context/wireframe-states'
 
 export interface GateInput {
   /** Cited paths that resolved to nothing, which gate under either mode. */
@@ -15,6 +16,22 @@ export interface GateInput {
   readonly recordOverLength: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
+  /**
+   * Every wireframe entry's states report, empty for a project carrying no
+   * `canon/wireframes/` folder. A states/evidence mismatch is a fact read off
+   * the file, the same standing the missing-section and index-drift findings
+   * already have, so it gates alongside them under the widened mode.
+   *
+   * A sketch beside existing evidence stays out of the gate on both modes.
+   * `sketchWithEvidence` reads the whole entry against whether any of its
+   * states has evidence, not the sketched layout against the evidence for
+   * that same layout, since the standard's `## States` table names states
+   * rather than layouts and the report has no narrower unit to match on. An
+   * entry with a captured default layout and a sketch for a breakpoint layout
+   * that is not built yet is conforming and still trips this reading, so the
+   * finding stays a judgment for a reader rather than a fact a push fails on.
+   */
+  readonly wireframes: readonly WireframeStatesReport[]
   /**
    * Whether the caller asked for the widened gate. False leaves a missing
    * section and a drifted index advisory, which is what the project-root stage
@@ -30,28 +47,49 @@ export function hasDrift(drift: readonly FolderDrift[]): boolean {
   )
 }
 
+/** Whether any wireframe's States table disagrees with its evidence folders. */
+export function hasStatesMismatch(
+  wireframes: readonly WireframeStatesReport[],
+): boolean {
+  return wireframes.some(
+    (entry) =>
+      entry.missingFolders.length > 0 || entry.unlistedFolders.length > 0,
+  )
+}
+
+/** Whether any wireframe carries a sketch beside evidence that already exists. */
+export function hasSketchWithEvidence(
+  wireframes: readonly WireframeStatesReport[],
+): boolean {
+  return wireframes.some((entry) => entry.sketchWithEvidence)
+}
+
 /**
  * Whether the audit found something that should fail the caller.
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
  * does a record past its own ceiling: the record states the limit for itself
  * and derives it from a count, which makes it the one measure here that is a
- * fact rather than a threshold a reader weighs. The two findings `--gate` adds
- * are the ones answerable from the file itself: a required section it does not
- * declare, and an index disagreeing with its folder. Entry length, depth,
- * bullet, table, provenance, and the record's claim coverage are judgments, so
- * they stay out under both modes.
+ * fact rather than a threshold a reader weighs. The findings `--gate` adds are
+ * the ones answerable from the file itself: a required section it does not
+ * declare, an index disagreeing with its folder, and a wireframe's States
+ * table disagreeing with its evidence folders. Entry length, depth, bullet,
+ * table, provenance, the record's claim coverage, and a sketch beside
+ * existing evidence are judgments, so they stay out under both modes. The
+ * `wireframes` field's own doc states why the sketch finding is a judgment
+ * rather than a fact.
  */
 export function isGating({
   unresolvedCitations,
   recordOverLength,
   sections,
   drift,
+  wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
   if (recordOverLength) return true
   if (!widened) return false
 
-  return sections.length > 0 || hasDrift(drift)
+  return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)
 }