@erclx/canon 4.104.0 → 4.105.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.104.0",
+  "version": "4.105.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/tasks.md

@@ -325,22 +325,24 @@ canon tasks validate
 canon tasks validate --json
 ```
 
-Seven checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
-
-| Check      | What it reports                                                                                                         |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
-| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line        |
-| Mapping    | A row or backlog line naming no task file                                                                               |
-| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
-| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
-| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
-| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined     |
+Seven checks run. Collisions reaches one half of the `## Run now` test the board standard states, and Plan reaches every group, reading the Plan column under `## Run now` and the task file's own line under the other two. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
+
+| Check      | What it reports                                                                                                                                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed                                                                                                 |
+| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line, a `## Needs a plan` row whose task cites a live plan, or an `## Up next` row whose task cites none |
+| Mapping    | A row or backlog line naming no task file                                                                                                                                                                            |
+| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                                                                                                                          |
+| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all                                                                                              |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                                                                                                                    |
+| Blockers   | A parked row whose blocker has stopped holding, whose cited task resolves nowhere, or whose cited task was declined                                                                                                  |
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
 The Plan check reads the row and the task file both, because the two are written by different hands and only the task's own `Plan:` line reaches the archive. A row carrying a plan whose task states none is `plan-uncited`, and a pair naming two different plans is `plan-mismatched`. Both sides resolve against the board and against the project root before they compare, so a row writing `../plans/x.md` and a task writing `.canon/plans/x.md` name one file rather than two.
 
+The other two groups have no Plan column, so the same check reads the task file's own `Plan:` line against what the group name claims. A `## Needs a plan` row whose task cites a plan that sits live on disk is `plan-parked`, since the group says no such plan exists and the row is either misplaced or its plan is stale and belongs in the archive. An `## Up next` row whose task cites no live plan is `plan-absent`, since that group says one is written. A plan already archived, or a cited path with no file behind it, reads as not live on both sides. A row whose task file is gone is left to `task-unresolved`. An `## Up next` row with nothing left to build, waiting on an act only a person can take, reports `plan-absent` once its plan archives while the task stays live. That report is expected, since the check reads the task file and not the `Waiting on` prose, so a row in that state moves to `## Needs a plan` or closes.
+
 Mapping spans two surfaces, because a task sits on `priority.md` when it would plausibly be planned soon and on `backlog.md` otherwise. A row or a backlog line naming no task file is `task-unresolved`, and a file both surfaces name is `row-duplicated` for the reason a task in two groups is: it claims two things about itself and only one can hold. A task file neither surface names is `unplaced` rather than a finding, since that is the normal state between a session filing it and a live orchestrator placing it on the board. One check across both is what lets a task move between them without the move reading as a dropped file.
 
 A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name still lands in the `unplaced` array below rather than the findings. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.

package/governance/rules/ui/410-a11y.md

@@ -55,3 +55,8 @@ paths:
 - Alt text for functional images (icons, buttons) should describe the action, not the graphic.
 - Give the visual boundary of a control and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG Non-text Contrast, 1.4.11).
 - Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG Use of Color, 1.4.1).
+
+## Reflow
+
+- Let content reflow at a viewport 320 CSS pixels wide with no loss of content or function and no two-dimensional scrolling. Only content whose meaning depends on both axes, such as a data table, a map, or a diagram, may scroll sideways (WCAG Reflow, 1.4.10, Level AA).
+- Treat 320 as the criterion's own test condition rather than a device width. It is equivalent to a 1280 pixel window at 400 percent zoom, so a layout that breaks there breaks for a person who zooms.

package/governance/rules/ui/440-surface-capture.md

@@ -25,7 +25,13 @@ paths:
 
 ## What a capture covers
 
-- Capture the full page at the viewport its case declares. Do not capture a component in isolation.
+- Capture the full page. Do not capture a component in isolation.
+- Declare the widths a layout case captures. Always include 320, the reflow floor from the reflow criterion in `410-a11y`, then add each breakpoint bucket the project writes rules for, read from the `## Layout` section of `DESIGN.md`.
+- Fall back to the 320 floor alone when the project has no `DESIGN.md` or its record carries no `## Layout` section. Do not impose another project's breakpoints.
+- Apply the declaration to a case that covers layout only. A case driving a menu open or an answer chosen tests a state, so it takes one width rather than the full set.
+- Read a capture at 320 as proof that a frame was taken there, not that the page reflows correctly. The criterion is stated in `410-a11y` and nothing here enforces it.
+- Write the capture into a folder named `evidence`. The image is collected for the pull request comment when any segment of its path is literally `evidence` and its filename carries an image extension, so the folder name is fixed and its position in the tree is the project's own.
+- Several `evidence/` folders in one project is the ordinary shape rather than a problem to consolidate. One per surface is how a project with more than one rendered surface ends up.
 - Drive a state a screenshot cannot reach. An initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling.
 - Add a case to the capture record when adding a surface.
 - Remove a surface's case in the change that removes the surface.

package/package.json

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

package/src/commands/tasks.ts

@@ -218,6 +218,7 @@ export function register(program: Command): void {
         '',
         'Checks:',
         '  every Run now row points at a plan file that resolves',
+        '  no Needs a plan row has a live plan, and every Up next row has one',
         '  every task file carries a board row or a backlog line, never both',
         '  no task carries more than one row',
         '  no two Run now rows touch the same file',

package/src/design/document.ts

@@ -134,6 +134,8 @@ export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
       ),
     ),
     '',
+    section('Layout', tokens.layout),
+    '',
     section('Motion', tokens.motion),
     '',
     section('Iconography', tokens.iconography),

package/src/design/tokens.ts

@@ -70,6 +70,7 @@ export interface DesignTokens {
   readonly spacingNote: string
   readonly borders: readonly BorderToken[]
   readonly bordersNote: string
+  readonly layout: string
   readonly motion: string
   readonly iconography: string
   readonly preamble: string
@@ -371,6 +372,9 @@ export const TOKENS: DesignTokens = {
     },
   ],
 
+  layout:
+    'Capture widths are 320, 768, 1280 and 1536 pixels, declared once in `tooling/web/configs/e2e/screenshot.ts`, with 320 and 1280 committed as evidence. 320 is the reflow floor and the rest are the breakpoint buckets. The landing page under `web/` sets its own `max-width` media queries between 430 and 1100 pixels per component rather than from a shared scale.',
+
   motion:
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
 

package/src/tasks/validate.ts

@@ -8,6 +8,7 @@ import {
   readOutcomes,
   readPlanTarget,
   readPullRequest,
+  resolveLivePlan,
   tasksDir,
 } from '@/tasks/archive'
 import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
@@ -38,6 +39,8 @@ export const FINDING_KINDS = [
   'plan-unresolved',
   'plan-uncited',
   'plan-mismatched',
+  'plan-parked',
+  'plan-absent',
   'task-unresolved',
   'row-duplicated',
   'row-misshapen',
@@ -747,6 +750,70 @@ async function planDisagreement(
   }
 }
 
+/**
+ * Tests the claim a group name makes about a plan. `## Needs a plan` says none
+ * is live and `## Up next` says one is written, and neither group has a `Plan`
+ * column, so the task file's own `Plan:` line is the only place either claim
+ * can be read against.
+ *
+ * A live plan is one the archive's resolution accepts and the disk holds, so a
+ * plan already archived reads as not live and a cited path with no file behind
+ * it reads the same way. A row whose task file is gone is left to
+ * `task-unresolved`, which owns that report.
+ */
+async function checkGroupClaims(
+  rows: readonly BoardRow[],
+  dir: string,
+  root: string,
+): Promise<Finding[]> {
+  const parked = rows.filter(
+    (row) => row.group === 'Needs a plan' || row.group === 'Up next',
+  )
+
+  const found = await Promise.all(
+    parked.map(async (row) => groupClaimFinding(row, dir, root)),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
+async function groupClaimFinding(
+  row: BoardRow,
+  dir: string,
+  root: string,
+): Promise<Finding | undefined> {
+  if (!row.stem) return undefined
+
+  const file = join(dir, `${row.stem}.md`)
+  if (!existsSync(file)) return undefined
+
+  const target = readPlanTarget(await readFile(file, 'utf8'))
+  const live = target ? resolveLivePlan(target, dir, root) : undefined
+  const hasLivePlan = live !== undefined && existsSync(live)
+
+  if (row.group === 'Needs a plan' && hasLivePlan) {
+    return {
+      kind: 'plan-parked',
+      group: row.group,
+      subject: row.stem,
+      message: `sits under ${row.group} and its task cites ${target}, a live plan. A row with a plan belongs under Up next or Run now, or the plan is stale and belongs in the archive.`,
+    }
+  }
+
+  if (row.group === 'Up next' && !hasLivePlan) {
+    return {
+      kind: 'plan-absent',
+      group: row.group,
+      subject: row.stem,
+      message: target
+        ? `sits under ${row.group}, which claims a written plan, and its task cites ${target}, which is not a live plan.`
+        : `sits under ${row.group}, which claims a written plan, and its task carries no Plan: line.`,
+    }
+  }
+
+  return undefined
+}
+
 /**
  * Where a plan pointer lands, resolved against the board and against the
  * project root the way the archive resolves the same line. Neither base
@@ -1186,6 +1253,7 @@ export async function validateBoard(
     ...checkMapping(rows, backlog, dir),
     ...checkPlans(rows, dir, root),
     ...(await checkPlanAgreement(rows, dir, root)),
+    ...(await checkGroupClaims(rows, dir, root)),
     ...checkCollisions(rows),
     ...checkOrdering(rows),
     ...parked.findings,

package/standards/design.md

@@ -51,7 +51,7 @@ Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `
 
 Add either optional section when the project has content for it:
 
-- `## Layout`: page width, breakpoints, and grid rules, as current constraints
+- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
 - `## Mark`: the logo's construction rules and the files that carry it
 
 ## Template