@erclx/canon 4.100.0 → 4.102.0

package/README.md

@@ -99,7 +99,10 @@ Two of the outputs are documents you open rather than files you run. A `SLIDES.m
 
 The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
 
-![The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened](demos/agent-view.gif)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
+  <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
+</picture>
 
 That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.100.0",
+  "version": "4.102.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/auto-ship/SKILL.md

@@ -11,7 +11,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 ## Guards
 
 - All `.canon/plans/` and `.canon/review/` reads resolve at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree, the review receipt, the branch, and the memory proposal, regardless of which plan Step 1 reads.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `session-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree, the review receipt, and the branch, regardless of which plan Step 1 reads.
 - Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 
@@ -188,7 +188,7 @@ This chain owns the receipt's lifetime, which is what makes the Output block's c
 
 ## Step 8: ship
 
-Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, the CI watch, and the scoped memory review, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
+Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, memory capture, both doc syncs, staging, the commit grouping, the branch rename, the pull request, and the CI watch, along with the reason each step sits where it does. This step used to restate that list and the two drifted apart with nothing comparing them, so read the order there and never here.
 
 One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, then read the flag back:
 
@@ -207,21 +207,20 @@ Placement is why the call sits ahead of the watch rather than after it. Marking
 
 ## Output
 
-Respond with up to five lines:
+Respond with up to four lines:
 
 ```plaintext
 ✅ Autoshipped (<state>): <PR url>
 <N minor findings kept in .canon/review/branch-<slug>.md>
 <N facts routed to context entries>
 <N memories captured in .canon/memory/>
-<Memory proposal at .canon/memory/review/memory-review-<slug>.md>
 ```
 
 `<state>` is whatever the Step 8 read returned, being `draft` or `ready, unsupervised`, rather than the state the undo asked for. Writing the word `draft` there unconditionally is what this line used to do, and it named a state no step had read.
 
-Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth and fifth if `memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
+Omit the second line if there were no minor findings, and the third if nothing routed. Omit the fourth if `memory-capture` wrote no memory file this session. A run that routes every fact and writes none is the shape to expect, and it reports three lines.
 
-This block replaces the one `git-ship` closes on rather than following it. The two carry the same three trailing lines and differ on the two above them, since the first names the state the read returned and the second reports the minor findings Step 7 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
+This block replaces the one `git-ship` closes on rather than following it. The two carry the same two trailing lines and differ on the two above them, since the first names the state the read returned and the second reports the minor findings Step 7 kept, neither of which that body has a counterpart for. Emitting both reports one run twice and buries the state under a `✅ Shipped` that does not name it.
 
 ## Failure recovery
 

package/claude/skills/canon-cli/SKILL.md

@@ -31,7 +31,7 @@ Consult before running an unfamiliar `canon` verb, before a sync or install, or
 
 A golden config is any file a stack ships under `configs/`, and the category is wider than its name suggests. It carries the CI workflow, the git hooks, the end-to-end harness, the shell scripts under `scripts/`, and the editor settings, alongside the linters and compilers a reader expects. A stack inherits its parent's configs, so syncing `astro` also writes everything `web` and `base` hold.
 
-Run `canon tooling sync <stack> <target> --check` for the list resolved against a real target. It reports every path and writes nothing. The list below is what the stacks hold as shipped, before any chain resolution.
+Run `canon tooling diff <stack> <target>` for the list resolved against a real target. It reports every path, writes nothing, and exits 1 when any differs. The list below is what the stacks hold as shipped, before any chain resolution.
 
 <!-- generated:tooling-paths -->
 

package/claude/skills/git-ship/SKILL.md

@@ -32,7 +32,6 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
 9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending`, branching on that field rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
-10. If step 1 wrote or updated at least one memory file, invoke `canon:memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
 
 A caller wrapping this sequence may act between step 8 and step 9, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `auto-ship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
 
@@ -48,19 +47,16 @@ An installed binary carrying no `plan-reach` subcommand reports the reach unread
 
 Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
 
-Stop at the Propose phase. Do not run Apply. Promoting an entry to an always-loaded rule or a skill body ships as its own change, separate from this feature.
-
 ## After completion
 
-Output up to four lines:
+Output up to three lines:
 
 ```plaintext
 ✅ Shipped
 <N facts routed to context entries>
 <N memories captured in .canon/memory/>
-<Memory proposal at .canon/memory/review/memory-review-<slug>.md>
 ```
 
-Omit the second line if nothing routed. Omit the third and fourth if `memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.
+Omit the second line if nothing routed and the third if `memory-capture` wrote no memory file this session.
 
-Emit nothing here when a wrapping caller states it closes on its own block. `auto-ship` is that caller and its block carries these same three trailing lines above a first line naming the draft state, so emitting both reports one run twice. A caller that states no such thing gets this block, which is every direct invocation.
+Emit nothing here when a wrapping caller states it closes on its own block. `auto-ship` is that caller and its block carries these same two trailing lines above a first line naming the draft state, so emitting both reports one run twice. A caller that states no such thing gets this block, which is every direct invocation.

package/claude/skills/memory-capture/SKILL.md

@@ -100,12 +100,6 @@ When anything routed, add a line naming the handoff so the caller knows a `docs-
 
 Omit that line when the caller runs `docs-fold` itself later in its own chain.
 
-When at least one memory file was written or updated, add a closing line so the standalone caller proposes fixes while context is fresh:
-
-`→ Run /memory-review to propose fixes for the pen before the session ends.`
-
-The ship skills run review Propose themselves, so this line is for the standalone `/memory-capture` path.
-
 If nothing was captured, output:
 
 `✅ Nothing worth capturing.`

package/claude/skills/memory-review/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: What memory review is for, the gaps it closes, and why every action
 
 Without this skill, the memory folder grows and never drains. Entries pile up restating rules a durable surface already carries, nothing decides which memory has earned a place in one, and a rule that does get promoted arrives verbatim in a file whose voice it does not match. The folder then reads as a second source of truth that no surface points at.
 
-A pen the caller cannot face is the same gap wearing a different shape. Routing at capture takes the domain facts and whatever the ownership test leaves stays, in whatever mix of types that is, so the folder still reaches a size nobody reads in one sitting. A ship-time run is scoped to the entries that session captured for exactly that reason, and the full sweep is what an operator asks for when the cross-session duplicates are the point. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
+A pen the caller cannot face is the same gap wearing a different shape. Routing at capture takes the domain facts and whatever the ownership test leaves stays, in whatever mix of types that is, so the folder still reaches a size nobody reads in one sitting. The full sweep is what an operator asks for when the cross-session duplicates are the point. An entry leaving the pen is archived rather than deleted, because a folder git does not hold gives a wrong bulk call no undo.
 
 ## Must
 

package/claude/skills/memory-review/SKILL.md

@@ -30,12 +30,11 @@ If the user re-pings the skill with no new phrase and a receipt exists, default
 
 ## Propose phase
 
-Propose is the ship-time entry point. The ship skills run it right after capture, so the fix is written while session context is fresh.
+Propose is the entry point for a standalone run. The ship skills stop at capture and never invoke it.
 
 ### Scope
 
-- **Ship-scoped:** when a ship caller (`git-ship`, `auto-ship`) names the entries captured this session, classify only those entries. Read the full pen for merge and absorbed comparison, but do not propose actions on carried entries the captures do not touch. Each carried entry was already proposed on in its own ship cycle.
-- **Full sweep:** when invoked standalone with no named set, classify every entry in the pen, including entries carried from earlier sessions, so cross-session duplicates merge into one rule.
+- **Full sweep:** classify every entry in the pen, including entries carried from earlier sessions, so cross-session duplicates merge into one rule.
 
 ### Step 1: read the memory folder
 

package/claude/skills/plan-groundwork/SKILL.md

@@ -21,7 +21,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 
 - Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
 - One exception, at close only: write one task file recording what the track concluded.
-- A second exception, for what a spike reads: write an input under `.canon/tmp/runs/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
+- A second exception, for what a spike reads as bulk input: write a large fixture under `.canon/tmp/runs/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`. An arm script and a checkout a claim rests on are not fixtures, and go inside the track under `scripts/` and `clones/`, per the standard.
 - What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
 - A `draft-and-pick` run invoked from inside a live track follows its own branch for this, writing to `evidence/` here rather than `.canon/tmp/<slug>/`.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
@@ -33,12 +33,13 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 A track may run an experiment to settle an open question without stopping to ask. What it takes depends on what the experiment does.
 
 - Reading or computing: run it. Unrestricted reading already covers this, and it is what most spikes turn out to be.
+- Anything that processes an input: start against a sample and scale up after it works, per the sample rule in the standard's spikes section, which bounds it on size, duration, and spend.
 - Writing a fixture this session reads or provisions itself: run it, under the fixtures path above. Provisioning is the usual blocker rather than spend, and it costs nothing.
 - Spawning a billed headless session: run up to three, then ask before spawning more. The bound is a run count rather than a budget, because a headless run reports its total cost only after it finishes, so a dollar ceiling is reportable and not enforceable while a run count is checkable before spawning.
 
 A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.canon/tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md` and `.claude/rules/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
 
-Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it, and keep the arm scripts in `scripts/`. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
 
 ## Step 1: detect the mode
 

package/docs/agents/demo.md

@@ -26,6 +26,8 @@ The plan is committed, not scratch. Its timing is a starting point tuned by watc
 
 A plan can carry an optional `colorScheme` of `light` or `dark`, which the recording context starts in so a page following the system preference paints that scheme with no click beat of its own. An absent field keeps the engine's default, which is light, and `compile` never seeds it. Any other value makes the plan unreadable. A page keyed on a stored theme rather than the preference ignores the field.
 
+A recording that has to match both themes takes one plan per scheme, committed side by side, rather than one plan run twice. The pair shares its beats and differs in `colorScheme`, `slug`, and the `output` paths. Neither plan clicks a theme toggle, since a stored theme overrides the preference. Nothing checks that the two plans keep the same beats, so an edit to one is made to both.
+
 `record-screencast` is the routed way to run both verbs from a draft path: it compiles only when no plan exists yet, then runs, stopping to report any field still unresolved rather than guessing one.
 
 | Option          | Behavior                                                          |

package/docs/agents/install-and-sync.md

@@ -75,6 +75,12 @@ toolkit's own `snippets/`, so a session reaches one at its `@` reference with
 no copy to reconcile. `canon snippets list --json` carries the catalog and
 `canon snippets create` is the one verb left that still writes a file.
 
+## Tooling diff and sync
+
+`canon tooling diff <stack> [target]` is the read-only comparison, and a session asking what differs reaches for it by default. It writes nothing and exits 1 when anything differs and 0 when nothing does, so it gates CI. `--json` adds the scan record on stdout with `ok: true`, and the frame goes to stderr. A refusal such as an unknown stack, an excluded stack, or a toolkit-root target still exits 1 and answers `{ ok: false, reason, message }`, so a caller branches on the record and reads a typo'd stack name as a refusal rather than as drift.
+
+`canon tooling sync <stack> [target] --check` reports the same list and always exits 0. It stays for scripts that already call it. `sync` itself writes only under `--write`, and a headless run with neither flag reports and exits 1.
+
 ## Install guards
 
 `canon gov install` requires its first argument under
@@ -188,7 +194,7 @@ since `src/tooling/` runs its own inject machinery and has no walk to attribute.
 The chain is ordered nearest stack first, which is what a `--skip` run needs:
 recording the leaf alone would send the next report measuring against a layer the
 target deliberately does not carry. The report loads exactly those stacks, scans
-them the way `canon tooling sync` would, and counts what differs per category
+them the way `canon tooling diff` would, and counts what differs per category
 under `tooling.counts`.
 
 `measured` is the field the section exists for. A target carrying no chain

package/docs/agents/scripting.md

@@ -78,7 +78,7 @@ surface is in `skills-audit.md`.
 CANON_NON_INTERACTIVE=1 canon tooling create astro
 
 # Report what a stack would change, writing nothing
-CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --check
+CANON_NON_INTERACTIVE=1 canon tooling diff astro /path/to/project
 
 # Sync a stack into a target project, overwriting its golden configs
 CANON_NON_INTERACTIVE=1 canon tooling sync astro /path/to/project --write

package/docs/agents/tasks.md

@@ -292,6 +292,30 @@ Exit codes: `0` closed, `1` refused. The `reason` field adds `no-outcomes`, `out
 
 Both verbs exist because the write is an edit inside a file that already exists. `Edit` and `Write` refuse a main-root path from a linked worktree, and a shell stream editor is banned for in-place edits, so a verb resolving the board root in-process is the only route a skill body has. Creating a whole file needs no verb, because a heredoc through `Bash` writes it safely.
 
+## List
+
+`canon tasks list` reports each live task file with its readiness, so a reader learns which file is parked and which is live without opening `priority.md` or `backlog.md`. It reads and never writes, and every file stays in the folder it is in.
+
+```bash
+canon tasks list
+canon tasks list --json
+```
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `tasks`, one entry per file with its `stem` and its `readiness`. Readiness is one of `Run now`, `Up next`, `Needs a plan`, `backlog`, `unplaced`, or `both`. The first three are the group names the board standard fixes, `backlog` is a line on `backlog.md`, `unplaced` is a file neither surface names, and `both` is a file both surfaces name, which `validate` reports as a finding and this verb does not judge.
+
+The verb calls the parsers `validate` uses, so the two cannot disagree on what a surface names. It lists the live root only, never `archive/` or `declined/`, and skips the same siblings `validate` skips.
+
+Exit codes: `0` derived, `1` refused with `no-board`.
+
+```bash
+canon tasks list --json | jq -r '.tasks[] | select(.readiness == "backlog") | .stem'
+```
+
 ## Validate
 
 `canon tasks validate` reports what each row of `priority.md` claims against what the tree holds. It reads and never writes, because a row is a session's claim about readiness and a validator that repaired one would be asserting the claim it exists to test.

package/docs/target-projects.md

@@ -265,7 +265,7 @@ Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job
 
 Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain.
 
-Reconcile the configs with `canon tooling sync <stack> <path> --check` to read which files differ, then re-run it with `--write` to apply them. The drift report counts categories and the sync names paths, which is the difference worth knowing before a golden config the project edited is replaced.
+Reconcile the configs with `canon tooling diff <stack> <path>` to read which files differ, then run `canon tooling sync <stack> <path> --write` to apply them. The drift report counts categories and the diff names paths, which is the difference worth knowing before a golden config the project edited is replaced.
 
 ### Catch-all
 

package/docs/workflow/ai-workflow.md

@@ -65,7 +65,9 @@ The routing test is whether the repository can answer an item today. A session g
 
 A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/runs/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 
-What a spike produces goes somewhere else again. An input the run reads is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it, while a recording or a render the track cites as evidence for a finding is what a later reader opens to check the claim. Evidence therefore lives in `evidence/` inside the track beside the file citing it, since the scratch tree holds only what can be deleted without loss.
+A spike starts against a sample, bounded on input size, duration, and spend, and scales up once the sample shows the method works. Nothing checks this, so it holds while a session reads the standard.
+
+What a spike leaves behind splits on whether a later reader needs the file to check a claim. Bulk input, such as a large fixture, is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it. Everything a reader opens to verify a result lives inside the track in one of three folders: `evidence/` for a recording or a render, `scripts/` for the arm scripts, and `clones/` for checkouts and copies of outside material a claim rests on. The scratch tree holds only what can be deleted without loss, which none of those is.
 
 #### Session 2
 
@@ -166,7 +168,7 @@ The list stays written in the skill body as the fallback for a target whose inst
 
 Capture leads rather than trails because a routed fact edits a tracked file, which has to reach the branch before the commit steps run.
 
-If capture wrote at least one memory file, `memory-review` then proposes a decision-ready fix scoped to those entries while context is fresh, otherwise it is skipped. It stops at Propose. Review the receipt and run Apply yourself, on its own commit separate from the feature.
+The chain ends at capture, and review is run on its own.
 
 Run `memory-review` standalone to curate the whole pen. An entry it retires moves to `.canon/memory/archive/` rather than being deleted, since a bulk pass has no undo.
 
@@ -260,7 +262,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:git-commit`     | When the staged set is one concern, or was staged hunk by hand                        |
 | `canon:git-branch`     | When a branch name needs generating or renaming to conventional form                  |
 | `canon:git-pr`         | When a pull request needs a title and body written from the diff                      |
-| `canon:memory-review`  | After capture writes an entry, to propose where each one belongs                      |
+| `canon:memory-review`  | When the pen has grown, to propose where each entry belongs                           |
 
 ### After the pull request opens
 

package/package.json

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

package/scripts/core/regen-web-favicon.ts

@@ -1,6 +1,6 @@
 /**
- * Writes web/public/favicon.svg from assets/brand/mark.svg and the design
- * source's two accent values.
+ * Writes web/public/favicon.svg from assets/brand/mark.svg and the favicon's
+ * own colors in src/design/favicon.ts, apart from the page accent tokens.
  *
  * The page is the fourth surface to carry the mark as a favicon and the only
  * one that can answer for itself. `regen-hero.sh` and `src/design/render.ts`
@@ -17,6 +17,8 @@
  */
 import { writeFileSync } from 'node:fs'
 
+import { FAVICON_COLORS, renderFavicon } from '../../src/design/favicon'
+
 const root = new URL('../..', import.meta.url).pathname
 
 const mark = (await Bun.file(`${root}assets/brand/mark.svg`).text()).trim()
@@ -25,43 +27,10 @@ if (!mark) {
   process.exit(1)
 }
 
-const tokenCss = await Bun.file(`${root}web/src/styles/tokens.css`).text()
-const read = (name: string): string => {
-  const match = tokenCss.match(
-    new RegExp(`--color-${name}:\\s*(#[0-9a-fA-F]{3,8})`),
-  )
-  if (!match) {
-    console.error(
-      `regen-web-favicon: tokens.css carries no --color-${name}, refusing to write a colorless favicon`,
-    )
-    process.exit(1)
-  }
-  return match[1] as string
-}
-
-const dark = read('accent')
-const light = read('light-accent')
-
-// The shapes only, with the source's authoring comment dropped. Both fills are
-// replaced by a rule rather than an attribute so one branch can flip both.
-const shapes = mark
-  .replace(/<!--[\s\S]*?-->/, '')
-  .trim()
-  .replace(/^<svg[^>]*>/, '')
-  .replace(/<\/svg>$/, '')
-  .replaceAll(' fill="currentColor"', '')
-  .trim()
-
-const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
-  <style>
-    path, rect { fill: ${light}; }
-    @media (prefers-color-scheme: dark) { path, rect { fill: ${dark}; } }
-  </style>
-  ${shapes.replace(/\n\s*/g, '\n  ')}
-</svg>
-`
-
-writeFileSync(`${root}web/public/favicon.svg`, svg)
+writeFileSync(
+  `${root}web/public/favicon.svg`,
+  renderFavicon(mark, FAVICON_COLORS),
+)
 console.log(
-  `regen-web-favicon: wrote web/public/favicon.svg (${light} / ${dark})`,
+  `regen-web-favicon: wrote web/public/favicon.svg (${FAVICON_COLORS.light} / ${FAVICON_COLORS.dark})`,
 )

package/src/commands/tasks.ts

@@ -14,6 +14,7 @@ import {
   planCitations,
 } from '@/tasks/archive'
 import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import { listTasks } from '@/tasks/list'
 import {
   type Claim,
   type Holder,
@@ -114,6 +115,11 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface NextLabelCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -522,6 +528,37 @@ export function register(program: Command): void {
     .action(async (opts: NextLabelCommandOptions) => {
       process.exitCode = await runNextLabel(opts)
     })
+
+  tasks
+    .command('list')
+    .description('Report each live task file with its readiness')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Readiness is one of Run now, Up next, Needs a plan, backlog, unplaced,',
+        'or both, read from priority.md and backlog.md through the parsers',
+        'validate uses. It lists the live root only, never archive/ or declined/.',
+        '',
+        'Exit codes:',
+        '  0  the list is derived',
+        '  1  refused with no-board',
+        '',
+        'It reports and never writes, and judges nothing: a file named on both',
+        'surfaces reads as both, and validate owns the finding.',
+        '',
+        'Examples:',
+        '  canon tasks list',
+        '  canon tasks list --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
 }
 
 function collectPosition(value: string, previous: string[]): string[] {
@@ -792,6 +829,38 @@ function reportOutcome(
   return 0
 }
 
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await listTasks(root)
+
+  if (!outcome.ok) {
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks list')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return 0
+  }
+
+  intro('canon tasks list')
+  logStep(`${outcome.tasks.length} task files`)
+  for (const task of outcome.tasks) logInfo(`${task.readiness}: ${task.stem}`)
+  outro()
+
+  return 0
+}
+
 async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await nextLabel(root)

package/src/commands/tooling.ts

@@ -39,6 +39,12 @@ interface SyncOptions {
   readonly skip?: string
   readonly check?: boolean
   readonly write?: boolean
+  readonly diff?: { readonly json: boolean }
+}
+
+interface DiffOptions {
+  readonly skip?: string
+  readonly json?: boolean
 }
 
 interface InjectOptions {
@@ -59,7 +65,7 @@ interface ListOptions {
 
 type Prepared =
   | { readonly ok: true; readonly chain: Manifest[]; readonly target: string }
-  | { readonly ok: false; readonly error: string }
+  | { readonly ok: false; readonly reason: string; readonly error: string }
 
 export function register(program: Command): void {
   const tooling = program
@@ -74,7 +80,10 @@ export function register(program: Command): void {
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--skip <stack>', 'Drop a layer from the extends chain')
-    .option('--check', 'Report what would change and write nothing')
+    .option(
+      '--check',
+      'Report what would change and write nothing, always exiting 0. Prefer `canon tooling diff`',
+    )
     .option('--write', 'Apply every change without prompting')
     .addHelpText(
       'after',
@@ -98,6 +107,42 @@ export function register(program: Command): void {
       },
     )
 
+  tooling
+    .command('diff')
+    .description('Report how a target differs from a stack and write nothing')
+    .argument('[stack]', 'Tooling stack name (e.g. base, vite-react)')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--skip <stack>', 'Drop a layer from the extends chain')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The comparison `canon tooling sync --check` reports, under a name that',
+        'says it only asks. Exit codes:',
+        '  0  the target matches the stack',
+        '  1  a file, script, dependency, or gitignore entry differs, or a refusal',
+        '',
+        '`sync --check` reports the same list and always exits 0. Use `diff` to',
+        'gate CI, and keep `--check` for scripts that already call it.',
+        '',
+        'Examples:',
+        '  canon tooling diff base',
+        '  canon tooling diff base --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (stack: string | undefined, target: string, opts: DiffOptions) => {
+        process.exitCode = await runSync(stack, target, {
+          skip: opts.skip,
+          check: true,
+          diff: { json: opts.json === true },
+        })
+      },
+    )
+
   tooling
     .command('inject')
     .description('Apply one stack to a target without scanning or prompting')
@@ -239,18 +284,27 @@ function prepare(stack: string, target: string, skip?: string): Prepared {
   if (mismatch !== undefined) logWarn(mismatch)
 
   if (!stackExists(PROJECT_ROOT, stack)) {
-    return { ok: false, error: `Stack not found: ${stack}` }
+    return {
+      ok: false,
+      reason: 'unknown-stack',
+      error: `Stack not found: ${stack}`,
+    }
   }
 
   if (skip !== undefined) {
     if (skip === stack) {
       return {
         ok: false,
+        reason: 'bad-skip',
         error: `Cannot --skip the stack being synced: ${skip}`,
       }
     }
     if (!stackExists(PROJECT_ROOT, skip)) {
-      return { ok: false, error: `Stack to skip not found: ${skip}` }
+      return {
+        ok: false,
+        reason: 'unknown-skip',
+        error: `Stack to skip not found: ${skip}`,
+      }
     }
   }
 
@@ -258,6 +312,7 @@ function prepare(stack: string, target: string, skip?: string): Prepared {
   if (resolved === PROJECT_ROOT) {
     return {
       ok: false,
+      reason: 'toolkit-root',
       error:
         'Cannot run against toolkit root. Files here are the source of truth.',
     }
@@ -275,40 +330,44 @@ async function runSync(
   target: string,
   opts: SyncOptions,
 ): Promise<number> {
-  intro('canon tooling sync')
+  intro(opts.diff === undefined ? 'canon tooling sync' : 'canon tooling diff')
 
   if (opts.check === true && opts.write === true) {
-    logWarn('Pass --check or --write, not both.')
-    outro()
-    return 1
+    return refuse(
+      opts,
+      'conflicting-flags',
+      'Pass --check or --write, not both.',
+    )
   }
 
   const selected = stack ?? (await promptForStack())
   if (selected === undefined) {
-    logWarn('No tooling stacks found')
-    outro()
-    return 1
+    return refuse(opts, 'no-stacks', 'No tooling stacks found')
   }
 
   if (isStackExcluded(selected)) {
-    logWarn(
+    return refuse(
+      opts,
+      'excluded-stack',
       'Claude is managed by `canon claude`, not `canon tooling`. Run `canon claude sync` instead.',
     )
-    outro()
-    return 1
   }
 
   const prepared = prepare(selected, target, opts.skip)
-  if (!prepared.ok) {
-    logWarn(prepared.error)
-    outro()
-    return 1
-  }
+  if (!prepared.ok) return refuse(opts, prepared.reason, prepared.error)
 
   const result = scan(prepared.chain, prepared.target)
 
   report(result)
 
+  if (opts.diff !== undefined) {
+    if (opts.diff.json) {
+      process.stdout.write(`${JSON.stringify({ ok: true, ...result })}\n`)
+    }
+    outro()
+    return result.totalChanges === 0 ? 0 : 1
+  }
+
   const mode = resolveWriteMode(opts)
   const { GREEN, NC } = palette(process.stderr)
 
@@ -353,6 +412,20 @@ async function runSync(
   return 0
 }
 
+/**
+ * A diff caller branches on the record rather than the exit, since a shell
+ * wrapper can flatten the status. Every refusal therefore answers with a reason
+ * on stdout under `--json`, beside the exit 1 that keeps a gate failing.
+ */
+function refuse(opts: SyncOptions, reason: string, message: string): number {
+  logWarn(message)
+  if (opts.diff?.json) {
+    process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
+  }
+  outro()
+  return 1
+}
+
 type WriteMode = 'apply' | 'prompt' | 'report' | 'unauthorized'
 
 type ApplyDecision = 'apply' | 'cancelled' | 'reported' | 'unauthorized'

package/src/design/favicon.ts

@@ -0,0 +1,33 @@
+export interface FaviconColors {
+  readonly light: string
+  readonly dark: string
+}
+
+/** The favicon's own fills, chosen for tab size and apart from the page accent tokens. */
+export const FAVICON_COLORS: FaviconColors = {
+  light: '#c42938',
+  dark: '#e54e40',
+}
+
+/**
+ * The shapes only, with the source's authoring comment dropped. Both fills are
+ * replaced by a rule rather than an attribute so one branch can flip both.
+ */
+export function renderFavicon(mark: string, colors: FaviconColors): string {
+  const shapes = mark
+    .replace(/<!--[\s\S]*?-->/, '')
+    .trim()
+    .replace(/^<svg[^>]*>/, '')
+    .replace(/<\/svg>$/, '')
+    .replaceAll(' fill="currentColor"', '')
+    .trim()
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
+  <style>
+    path, rect { fill: ${colors.light}; }
+    @media (prefers-color-scheme: dark) { path, rect { fill: ${colors.dark}; } }
+  </style>
+  ${shapes.replace(/\n\s*/g, '\n  ')}
+</svg>
+`
+}

package/src/design/tokens.ts

@@ -377,7 +377,7 @@ export const TOKENS: DesignTokens = {
   iconography: [
     'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
     '',
-    'The same mark ships as a favicon on every rendered surface, as three independently-maintained copies that track different accents by design rather than by drift, colored to fit the chrome each renders on: the dark accent (`#e0724b`) for a dark-chrome surface and the light accent (`#a4471c`) for a light-chrome one. Unifying the three or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+    'The same mark ships in six independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
   ].join('\n'),
 }
 

package/src/tasks/list.ts

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { listTaskStems, tasksDir } from '@/tasks/archive'
+import {
+  BOARD_GROUPS,
+  type BoardGroup,
+  backlogPath,
+  orderingPath,
+  readBacklog,
+  readBoard,
+} from '@/tasks/validate'
+
+/**
+ * The three board group names plus the states outside them. A file named on
+ * both surfaces is `validate`'s finding, so it reports as `both` rather than
+ * being judged here.
+ */
+export const READINESS_VALUES = [
+  ...BOARD_GROUPS,
+  'backlog',
+  'unplaced',
+  'both',
+] as const
+
+export type Readiness = (typeof READINESS_VALUES)[number]
+
+export interface ListedTask {
+  readonly stem: string
+  readonly readiness: Readiness
+}
+
+export interface TaskList {
+  readonly ok: true
+  readonly tasks: readonly ListedTask[]
+}
+
+export interface ListRefused {
+  readonly ok: false
+  readonly reason: 'no-board'
+  readonly message: string
+}
+
+export type ListOutcome = TaskList | ListRefused
+
+/**
+ * Reports each live task file's readiness from the board and the backlog. It
+ * reads through the parsers `validate` exports rather than reading either file
+ * a second time, so the two verbs cannot disagree on what a surface names. An
+ * absent ordering file or backlog reads as empty, since a file in neither
+ * surface is reported `unplaced` rather than refused.
+ */
+export async function listTasks(root: string): Promise<ListOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) {
+    return {
+      ok: false,
+      reason: 'no-board',
+      message: `No task board at ${dir}.`,
+    }
+  }
+
+  const ordering = orderingPath(root)
+  const { rows } = existsSync(ordering)
+    ? readBoard(await readFile(ordering, 'utf8'))
+    : { rows: [] }
+
+  const backlogFile = backlogPath(root)
+  const backlog = existsSync(backlogFile)
+    ? readBacklog(await readFile(backlogFile, 'utf8'))
+    : []
+
+  const groupOf = new Map<string, BoardGroup>()
+  for (const row of rows) {
+    if (row.stem) groupOf.set(row.stem, row.group)
+  }
+  const parked = new Set(backlog.flatMap((row) => (row.stem ? [row.stem] : [])))
+
+  const stems = await listTaskStems(dir)
+
+  return {
+    ok: true,
+    tasks: stems.map((stem) => ({
+      stem,
+      readiness: readinessOf(groupOf.get(stem), parked.has(stem)),
+    })),
+  }
+}
+
+function readinessOf(
+  group: BoardGroup | undefined,
+  isParked: boolean,
+): Readiness {
+  if (group && isParked) return 'both'
+  if (group) return group
+  if (isParked) return 'backlog'
+
+  return 'unplaced'
+}

package/standards/groundwork.md

@@ -130,9 +130,15 @@ Each spike carries four things:
 
 Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
 
-A spike also leaves files behind, and they split on whether the track cites them rather than on whether they are markdown. An input the run reads, being a fixture page, an arm script, or a copied asset, is re-runnable and cited by nothing, so it stays outside the track wherever the surface driving the spike puts it. Evidence the record cites, being a recording, a render, or a frame pulled from one, is what a later reader opens to check a claim, so it lives in `evidence/` inside the track beside the file citing it. Name the split rather than the file types, which is what keeps this from going stale on the next kind of artifact a spike produces.
+Start a spike against a sample and scale up only once the sample shows the method works. Bound the sample on all three of input size, duration, and spend, since fifty minutes of audio is a runtime and a bill before it is a file size, and three minutes of it usually shows whether the pipeline runs at all. The same holds for a dataset, an image set, or a batch of queries. Record the sample's bounds and the figure for the full input in the spike, so a reader can tell what the result was measured on and what the scale-up costs. The rule reaches only a track, since that is the surface that reads this standard, and nothing checks that a spike ran small first, so it holds only while a session reads it.
 
-`evidence/` takes no number, since numbering is the read order over the files a reader opens in sequence and an artifact is reached from the claim that cites it instead.
+A spike also leaves files behind, and they split on whether a later reader needs the file to check a claim rather than on whether it is markdown or re-runnable. A file a reader opens to verify how a result was produced or what it showed lives inside the track. A file that is only bulk input, such as a large fixture or a copied asset, stays outside it wherever the surface driving the spike puts it. Three subfolders inside the track carry the first kind, and none takes a number, since numbering is the read order over the files a reader opens in sequence and these are reached from the claim that cites them instead:
+
+- `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
+- `scripts/`: the arm scripts and harnesses a spike ran. An arm script is re-runnable, and it is also what a reader opens to check the method, so this refines the earlier split, which sorted on re-runnable alone, and does not contradict it.
+- `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
+
+`spikes/`, `web/`, and `research/` were considered and folded into these, so do not reopen them. A spike's files sit under the three above, and a fetched page belongs in `clones/`. The `web/` case is the arguable one, since a screenshot of a reference site could sit apart, and it folds into `evidence/` because that is where a cited artifact already lives.
 
 Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
 

package/standards/tasks.md

@@ -37,6 +37,8 @@ Does not govern:
 └── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
 
+`canon tasks list` reports each file's readiness from those two surfaces, so a reader never infers it from the folder.
+
 One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
 
 Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md`, `priority.md`, and `backlog.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.

package/tooling/base/manifest.toml

@@ -18,9 +18,9 @@ packages = [
 
 [scripts]
 "check:spell" = "cspell '**' '.*/**' '.*' --no-progress --color --show-context"
-"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/"
+"check:format" = "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --diff --indent 2 {} +"
 "check:shell" = "find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
-"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/"
+"format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && find scripts -name '*.sh' -exec shfmt --write --indent 2 {} +"
 "prepare" = "husky"
 "check" = "./scripts/verify.sh"
 

package/tooling/base/reference.md

@@ -35,7 +35,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
 - Formatting: Prettier for what it parses, shfmt for shell. Two formatters because Prettier has no shell parser.
 - Spelling: cspell over the whole tree, with project vocabulary split into a project-terms dictionary and a tech-stack one.
-- Shell: shfmt formats and shellcheck lints at warning severity. shfmt takes a directory argument, shellcheck has no directory mode and needs `find`.
+- Shell: shfmt formats and shellcheck lints at warning severity. Both take their files from `find scripts -name '*.sh'`, since `scripts/` can mix shell with TypeScript and shellcheck has no directory mode. A shell script with a shebang and no `.sh` extension is covered by neither, so give it the extension.
 - Commits: commitlint against conventional commits, wired through the husky `commit-msg` hook. Format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
 - Dev dependencies: `prettier`, `cspell`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
 

package/tooling/web/configs/e2e/screenshot.ts

@@ -137,10 +137,15 @@ async function settle(
       for (const frame of document.querySelectorAll('iframe')) {
         try {
           const inner = frame.contentDocument
-          if (inner !== null && inner.readyState !== 'complete') return false
+          if (inner === null) continue
+          if (inner.readyState !== 'complete') return false
+          // A frame's own fonts load after its `readyState` reads complete, and
+          // the swap reflows its text. The outer document's fonts never cover
+          // them.
+          if (inner.fonts.status !== 'loaded') return false
         } catch {
-          // Cross-origin, so there is no readyState to read and nothing here
-          // can wait on it.
+          // Cross-origin, so there is nothing here to read and nothing to
+          // wait on.
         }
       }
       return true