@erclx/canon 5.14.0 → 5.15.0

package/claude/skills/role-orchestrator/scripts/watch.ts

@@ -0,0 +1,267 @@
+// Reports worker and pull request transitions as they happen. Reads only.
+//
+// The poll answers "what moved since the last run" on a schedule the session
+// holds. This answers "what just changed" on a loop of its own, and it exists
+// because the two readings a dispatch needs are not one reading: a worker that
+// finishes goes idle and a worker that crashes vanishes, so a watch matching
+// only the pull request list stays silent through the second. A third case is
+// neither: a worker that stops on a question or a prompt neither finishes nor
+// crashes, and sits reading "waiting" until something reports it, which is the
+// WORKER-STOPPED line below, or WORKER-UNMEASURABLE for a "waiting" row too old
+// to carry a stamp this reads.
+//
+// Run as `bun watch.ts`. A failed read never ends the loop, since it runs for
+// hours and one transient `gh` failure aborting it is a silent stop. Every read
+// states its own failure instead.
+import { baseBranch, baseRef, gitPath, mainRoot, run } from './repo'
+
+// Seconds between passes. A pass costs two cheap reads and the transitions it
+// watches take minutes, so the number trades staleness against little. Raise it
+// in a project whose workers run long.
+const INTERVAL_S = 60
+
+// Seconds a worker can sit in "waiting" before this reports it as stopped
+// rather than folding it into the ordinary status-change lines. "busy" and
+// "idle" resolve on their own; "waiting" does not, so a dwell that keeps
+// growing there is a session blocked on something outside itself. The number
+// sits well above INTERVAL_S, so a handful of passes confirm the row before it
+// reports, and well inside the ten-to-thirty-minute span a dispatched build
+// ordinarily runs. A permission prompt clears the moment a person approves it
+// and a question can sit legitimately, and one number serves both.
+export const STALL_THRESHOLD_S = 300
+
+export type Read<T> = { isOk: false } | { isOk: true; value: T }
+
+export interface Worker {
+  branch: string
+  dwellMs: number
+  name: string
+  status: string
+}
+
+export interface WatchState {
+  /** Names currently reported as stalled, so a stall prints once. */
+  stalled: ReadonlySet<string>
+  /** Null until a read succeeds, so each source keeps its own baseline flag. */
+  pulls: null | readonly string[]
+  workers: null | readonly Worker[]
+}
+
+export const initialState = (): WatchState => ({
+  pulls: null,
+  stalled: new Set(),
+  workers: null,
+})
+
+// `sort` orders by byte, so a title with a non-ASCII first character prints in
+// the order it always did rather than in UTF-16 code unit order.
+const byBytes = (a: string, b: string): number =>
+  Buffer.compare(Buffer.from(a), Buffer.from(b))
+
+const rowOf = (worker: Worker): string =>
+  [worker.name, worker.branch, worker.status, String(worker.dwellMs)].join('\t')
+
+// Identity leaves the dwell out. It grows every second, so keying on it
+// reported every worker as new on every pass.
+const identityOf = (worker: Worker): string =>
+  JSON.stringify([worker.name, worker.branch, worker.status])
+
+const unseen = <T>(
+  current: readonly T[],
+  previous: readonly T[],
+  key: (item: T) => string,
+): T[] => {
+  const known = new Set(previous.map(key))
+
+  return current.filter((item) => !known.has(key(item)))
+}
+
+const stallLines = (
+  workers: readonly Worker[],
+  previous: ReadonlySet<string>,
+  thresholdS: number,
+): { lines: string[]; stalled: Set<string> } => {
+  const stalled = new Set(previous)
+  const lines: string[] = []
+
+  for (const worker of workers) {
+    if (worker.name === '') continue
+
+    if (worker.status !== 'waiting') {
+      stalled.delete(worker.name)
+      continue
+    }
+
+    if (worker.dwellMs === -1) {
+      if (!stalled.has(worker.name)) {
+        lines.push(`WORKER-UNMEASURABLE ${worker.name} ${worker.branch}`)
+        stalled.add(worker.name)
+      }
+      continue
+    }
+
+    const dwellS = Math.trunc(worker.dwellMs / 1000)
+    if (dwellS < thresholdS) {
+      stalled.delete(worker.name)
+    } else if (!stalled.has(worker.name)) {
+      lines.push(`WORKER-STOPPED ${worker.name} ${worker.branch} ${dwellS}s`)
+      stalled.add(worker.name)
+    }
+  }
+
+  return { lines, stalled }
+}
+
+/**
+ * One pass over two reads. A failed read is reported and the previous baseline
+ * kept, since reading an empty result as the current state would report every
+ * worker gone and every pull request new on the pass after.
+ */
+export const pass = (
+  state: WatchState,
+  pulls: Read<string[]>,
+  workers: Read<Worker[]>,
+  thresholdS = STALL_THRESHOLD_S,
+): { lines: string[]; state: WatchState } => {
+  const lines: string[] = []
+
+  if (!pulls.isOk) {
+    lines.push(
+      'watch: the open pull request list failed to load, so none is classified this pass',
+    )
+  }
+  if (!workers.isOk) {
+    lines.push(
+      'watch: the session roster failed to load, so no worker is classified this pass',
+    )
+  }
+
+  if (pulls.isOk && state.pulls !== null) {
+    lines.push(
+      ...unseen(pulls.value, state.pulls, (line) => line).sort(byBytes),
+    )
+  }
+
+  let stalled = state.stalled
+  if (workers.isOk) {
+    const sorted = [...workers.value].sort((a, b) =>
+      byBytes(rowOf(a), rowOf(b)),
+    )
+    if (state.workers !== null) {
+      const changed = unseen(sorted, state.workers, identityOf)
+      lines.push(...changed.map((worker) => `WORKER ${rowOf(worker)}`))
+
+      const names = new Set(sorted.map((worker) => worker.name))
+      const gone = [...new Set(state.workers.map((worker) => worker.name))]
+        .filter((name) => !names.has(name))
+        .sort(byBytes)
+      lines.push(...gone.map((name) => `WORKER-GONE ${name}`))
+    }
+
+    const stalls = stallLines(sorted, stalled, thresholdS)
+    lines.push(...stalls.lines)
+    stalled = stalls.stalled
+  }
+
+  return {
+    lines,
+    state: {
+      pulls: pulls.isOk ? pulls.value : state.pulls,
+      stalled,
+      workers: workers.isOk ? workers.value : state.workers,
+    },
+  }
+}
+
+const readPulls = (): Read<string[]> => {
+  const listed = run('gh', [
+    'pr',
+    'list',
+    '--state',
+    'open',
+    '--json',
+    'number,headRefName,title',
+    '--jq',
+    '.[] | "PR-OPEN #\\(.number) \\(.headRefName) \\(.title)"',
+  ])
+  if (!listed.isOk) return { isOk: false }
+
+  return {
+    isOk: true,
+    value: listed.stdout.split('\n').filter((l) => l !== ''),
+  }
+}
+
+const asText = (value: unknown, fallback: string): string =>
+  typeof value === 'string' ? value : fallback
+
+/**
+ * Every session in this repository holding a branch other than the base one is
+ * a worker, whoever launched it. A match on the `orchestrator-` name prefix
+ * reads a dispatched worker and misses every hand-launched one. The name stays whole, since one
+ * this client writes carries spaces.
+ */
+const readWorkers = (repository: string, base: string): Read<Worker[]> => {
+  const listed = run('canon', ['sessions', 'list', '--json'])
+  if (!listed.isOk) return { isOk: false }
+
+  const last = listed.stdout.trimEnd().split('\n').at(-1) ?? ''
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(last)
+  } catch {
+    return { isOk: false }
+  }
+
+  const sessions =
+    typeof parsed === 'object' &&
+    parsed !== null &&
+    Array.isArray((parsed as { sessions?: unknown }).sessions)
+      ? (parsed as { sessions: unknown[] }).sessions
+      : []
+
+  const workers: Worker[] = []
+  for (const session of sessions) {
+    if (typeof session !== 'object' || session === null) continue
+    const row = session as Record<string, unknown>
+    if (row.repository !== repository) continue
+    if (
+      row.branch === null ||
+      row.branch === undefined ||
+      row.branch === base
+    ) {
+      continue
+    }
+
+    workers.push({
+      branch: asText(row.branch, ''),
+      dwellMs: typeof row.statusDwellMs === 'number' ? row.statusDwellMs : -1,
+      name: asText(row.name, ''),
+      status: asText(row.status, ''),
+    })
+  }
+
+  return { isOk: true, value: workers }
+}
+
+const main = async (): Promise<number> => {
+  const root = mainRoot()
+  if (root === null) {
+    console.error('watch: not a git repository, so nothing is watched')
+
+    return 1
+  }
+
+  const repository = gitPath(root)
+  const base = baseBranch(baseRef())
+  let state = initialState()
+
+  for (;;) {
+    const result = pass(state, readPulls(), readWorkers(repository, base))
+    for (const line of result.lines) console.log(line)
+    state = result.state
+    await new Promise((resolve) => setTimeout(resolve, INTERVAL_S * 1000))
+  }
+}
+
+if (import.meta.main) process.exitCode = await main()

package/docs/agents/commands.md

@@ -34,6 +34,7 @@ One row per top-level command, in the order `canon --help` prints them. A domain
 | `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                   |
 | `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)           |
 | `canon teach <verb>`        | Open and author learning workspaces                                             |
+| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, and add pages and frames to it   |
 | `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                      |
 | `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive              |
 | `canon intake <verb>`       | Report intake folders and write answers into them                               |
@@ -95,6 +96,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`
 - `teach`, in `teach.md`: `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
+- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`
 - `sandbox`, in `sandbox.md`: `reset`, `clean`, `check`, `coverage`
 - `tasks`, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
 - `intake`, in `intake.md`: `list`, `answer`
@@ -127,6 +129,7 @@ Subcommands no other page describes:
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
 - `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
+- `canvas serve` serves the canvas on `127.0.0.1`, walks ports like `canon serve`, refuses a `Host` other than loopback on its own port, and runs until interrupted. A page is a folder under `.canon/canvas/`, a frame is one HTML file in it, and `layout.json` beside them holds each frame's box. Each frame gets the project's token stylesheet injected, being this toolkit's tokens in its own checkout, else `.claude/design/base.css` plus anything under `.claude/design/project/`, else none with a notice. An open canvas reloads a frame whose file changes. `canvas list --json` emits every page with its frames, and `page add`, `page rename`, and `frame add` (`--width`, `--height`) each emit one record under `--json`, refusing a name that is not one path segment, a page that already exists, or a root that is not a directory, with the reason on stderr.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
 - `repo metadata propose` compares a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing, and `repo metadata apply` writes an explicitly supplied set through `gh repo edit` (`--description`, `--homepage`, `--topics`).
 

package/docs/agents/demo.md

@@ -10,12 +10,27 @@ description: Compiling a screencast draft into a runnable plan, driving a served
 Two verbs, and they are separate because the artifact between them is edited.
 
 ```bash
-canon demo compile .canon/tmp/screencast/inline-edit.md
-canon demo run demos/inline-edit.json
-canon demo run demos/inline-edit.json --cursor ~/cursors/theme --out assets
-canon demo frames demos/inline-edit.webm --fps 2
+canon demo compile demos/inline-edit/beats.md --slug inline-edit
+canon demo run demos/inline-edit/plan.json
+canon demo run demos/inline-edit/plan.json --cursor ~/cursors/theme --out assets
+canon demo frames demos/inline-edit/take/inline-edit.webm --fps 2
 ```
 
+## One folder per demo
+
+Each demo owns a folder, `demos/<slug>/`, and `compile` writes the plan into it.
+
+| Path         | Committed | Holds                                                 |
+| ------------ | --------- | ----------------------------------------------------- |
+| `beats.md`   | yes       | The draft `draft-screencast` wrote                    |
+| `plan.json`  | yes       | The compiled plan, with its hand-tuned timing         |
+| `index.html` | yes       | The HyperFrames composition, when the demo is wrapped |
+| `demo.gif`   | yes       | The one deliverable a README embeds                   |
+| `take/`      | no        | The raw recording and its still, written by `run`     |
+| `renders/`   | no        | The composed mp4, written by the render               |
+
+A project carries `demos/*/take/` and `demos/*/renders/` in its `.gitignore`, since both are one command away and a webm is large. A plan compiled before this layout, at `demos/<slug>.json`, still runs by path, because only the default moved.
+
 ## The draft and the plan are different files
 
 `draft-screencast` drafts beats for a person. A beat carries what is on screen, one verb, what to watch for, an emphasis, and a caption, and none of that names a selector, a URL, a wait condition, or a timing. Those four are what an executor needs and what would ruin the draft, since the format is pre-seeded so the operator edits down rather than fills blanks.
@@ -33,7 +48,7 @@ A recording that has to match both themes takes one plan per scheme, committed s
 | Option          | Behavior                                                          |
 | --------------- | ----------------------------------------------------------------- |
 | `--out <dir>`   | Directory the plan and its output paths point at, default `demos` |
-| `--slug <slug>` | Plan name, defaulting to the draft filename                       |
+| `--slug <slug>` | Demo folder name, defaulting to the draft filename                |
 | `--force`       | Overwrite an existing plan, losing any field set by hand          |
 | `--json`        | Add a record on stdout carrying the beats and what is unfilled    |
 
@@ -60,7 +75,7 @@ A step waits on its `waitFor` selector becoming visible and then holds for its o
 
 ## What frames does
 
-`canon demo frames` pulls numbered PNG stills back out of a recorded video through the same `ffmpeg` binary the mp4 and gif conversion already shells to. Nothing reads a recording back today, so a broken one ships until a person opens it, and this verb is what a skill calls to read one instead. It writes one frame a second by default, sampling at a rate matched to how long a tuned recording runs rather than at a rate tuned for any one clip. Frames land beside the video by default, named `<video-basename>-frame-<NNN>.png`, so they fall under the same `demos/*.png` gitignore entry the still already uses.
+`canon demo frames` pulls numbered PNG stills back out of a recorded video through the same `ffmpeg` binary the mp4 and gif conversion already shells to. Nothing reads a recording back today, so a broken one ships until a person opens it, and this verb is what a skill calls to read one instead. It writes one frame a second by default, sampling at a rate matched to how long a tuned recording runs rather than at a rate tuned for any one clip. Frames land beside the video by default, named `<video-basename>-frame-<NNN>.png`, so they fall under the same `take/` ignore entry the still already uses.
 
 | Option            | Behavior                                                 |
 | ----------------- | -------------------------------------------------------- |
@@ -104,8 +119,20 @@ This command was the first browser command to ship, and `canon capture` has sinc
 
 The cost is stated rather than hidden: the browser binary installs separately, so a target runs `bunx playwright install chromium` once before a recording works at all. A run that cannot launch reports that command inside the frame and exits 1.
 
+## Composing the take into a finished video
+
+The take is raw. When the draft's `## Wrap` section asks for an intro, an outro, or music, `record-screencast` composes the take into `demos/<slug>/index.html` through [HyperFrames](https://hyperframes.heygen.com) and renders `renders/<slug>.mp4`, the deliverable. The skill loads HyperFrames' own `hyperframes` skill for the composition rules and runs `bunx -y hyperframes check` and `render`, then hands the render to `read-frames`. A wrap section reading `none` throughout stops at the take. The webm is only the raw take, and a gif is for a host that strips video.
+
+Canon neither ships nor installs HyperFrames, and there is no `canon` verb for composing, since the render is one command already. The operator installs it once per machine:
+
+```bash
+bunx -y hyperframes init
+```
+
+`hyperframes init` installs its skills machine-wide without asking, so run it knowing that. A machine without it stops the skill with this command and nothing else.
+
 ## What it does not do
 
-A generated recording is a raw take. Nothing trims it or scores it beyond the caption each beat already carries.
+Nothing in `canon demo` itself trims a take or scores it beyond the caption each beat already carries. Composing is the skill's step and HyperFrames' work.
 
 It also does not replace a narrated screencast. That has a hero moment, a cut list, and a voice, none of which survives being generated. This answers the case where the alternative is recording nothing.

package/docs/agents/migrate.md

@@ -15,7 +15,7 @@ description: What each canon migrate verb moves and rewrites, what it refuses, t
 
 A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the nearest non-blank line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
-`migrate surface-roots` moves the tracked surfaces from `.claude/` to `canon/`: `context/`, `decisions/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, respelled `canon/config/` since a project under `canon/` reserves the bare `canon` name for the CLI's own install. Every path is tracked, so each file moves with `git mv` and its history follows it, and every tracked citation of one is rewritten in the same run. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them. It reports until `--write` is passed, and a destination already present under `canon/` refuses the whole plan rather than splitting a surface across both roots.
+`migrate surface-roots` moves the tracked surfaces from `.claude/` to `canon/`: `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, respelled `canon/config/` since a project under `canon/` reserves the bare `canon` name for the CLI's own install. Every path is tracked, so each file moves with `git mv` and its history follows it, and every tracked citation of one is rewritten in the same run. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them. It reports until `--write` is passed, and a destination already present under `canon/` refuses the whole plan rather than splitting a surface across both roots.
 
 A line carrying `canon-keep-surface-root`, or the nearest non-blank line above it, keeps the old spelling. A rule's frontmatter `paths:` glob, a citation shaped like a path into another repository, and one inside a dated paragraph are reported by file and line and left alone. Running it twice rewrites nothing, which is the idempotence check. A project that never runs it keeps resolving each surface under `.claude/`, since every reader takes whichever root holds the entry.
 

package/docs/agents/pr-reads.md

@@ -52,7 +52,7 @@ Both values are taken at the top of the pass rather than at the post, so the com
 
 The last non-empty line is where it has to sit, and the reader looks nowhere else. Searching a body for the last match instead reads a marker the body was displaying rather than claiming, since a fenced block showing the format on its own line trims to exactly the pattern, and a pass carrying no marker of its own would then hand the next reader a commit taken from an illustration. That is the same defect through a second door, so position rather than shape is what separates a claim from a quotation.
 
-`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's jq, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
+`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's own filters, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
 
 `source` on the record says which reading answered, and a caller checks it before trusting the rest:
 

package/docs/agents/sandbox.md

@@ -9,7 +9,7 @@ description: Scenario routing, the expectation scoring surface, and the coverage
 
 ## Scenarios
 
-Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync canon sandbox infra:tooling
@@ -45,6 +45,31 @@ An envelope that parses but carries no `result` field skips the reply assertion
 
 Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
 
+## Provisioning equivalence
+
+`canon sandbox equivalence` proves a change moved nothing in what scenarios provision. It provisions every arm of the named targets on a base ref and on the working checkout, builds a manifest of each tree, and names what differs. It runs offline and never calls `sandbox/run.sh` or a `claude` binary, so no arm it runs bills a model.
+
+```bash
+canon sandbox equivalence claude --base origin/main --json
+canon sandbox equivalence claude:plan-feature/full --base HEAD
+```
+
+A target is `<category>`, `<category>:<command>`, or `<category>:<command>/<arm>`, defaulting to every category.
+
+| Flag               | Effect                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `--base <ref>`     | Ref the baseline is provisioned from, `main` by default                                     |
+| `--include-anchor` | Also run the arms that push to the shared GitHub anchor, one at a time, for an attended run |
+| `--out <dir>`      | Keep the provisioned trees, logs, and per-side manifests in this folder                     |
+| `--no-masks`       | Compare every path, which lists what each mask would hide                                   |
+| `--json`           | Emit the record on stdout                                                                   |
+
+The baseline is a detached worktree with full history, removed on exit including after `SIGINT`. Each arm provisions on the base side, is read into a manifest, is deleted, then provisions on the head side at the same path with the run id pinned. A manifest holds every file's mode and hash, every symlink's target, the exit status, the narration, and for the outer repository and each nested one the commit subjects, the staged index, and the branch.
+
+The record lists per arm `identical`, `differs` with the manifest keys that differ, `red-on-base` when both sides fail the same way, or `skipped-anchor`. It also carries `canonVersion`, `baseCommit`, `masksApplied`, `errors`, and `counts`. A declared arm adds a `check` entry from `canon sandbox check` on the head tree, whose `asserted` count shows its `expect.toml` resolved from `sandbox/fixtures/`.
+
+Exit 0 means every compared arm is identical or red the same way on both sides. Exit 1 means any `differs`, a base and head exit that disagree, or an armed arm that `canon sandbox coverage` lists and enumeration lacks.
+
 ## Scenario coverage
 
 `canon sandbox coverage` reports which scenarios declare expectations and which only provision a state. It reads the fixture tree, so it needs no provisioned sandbox and runs nothing. Where that tree does not ship it exits 1 and prints no percentage, since a denominator nobody looked at is not a coverage result. A tree that is present and holds no scenarios is a real zero and still reports one.
@@ -67,9 +92,9 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 
 A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/target-setup.sh` reaches the `target-setup` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make.
 
-`exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+`exempt` means no arm should be written and holds only with a reason, declared in `sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+`sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
 
 Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, `concurrent` for the records present both before and after, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
 

package/docs/agents/state-scoped-risk.md

@@ -22,7 +22,7 @@ canon secrets scan --json
 canon secrets scan ../my-app
 ```
 
-The corpus is the package's own `files` field rather than a list the check keeps. That field is the single statement of which trees leave this repository, so a second list beside it would answer the same question and drift. It also carries the negations the publish already makes, which is what puts the sandbox tree, the eval tree, and every test file out of scope by the rule that keeps them out of the tarball rather than by an exclusion this check invented.
+The corpus is the package's own `files` field rather than a list the check keeps. That field is the single statement of which trees leave this repository, so a second list beside it would answer the same question and drift. It also carries the negations the publish already makes, which is what puts the eval tree and every test file out of scope by the rule that keeps them out of the tarball rather than by an exclusion this check invented. The sandbox tree sits under no `files` entry at all, so the same field leaves it out without a negation.
 
 The plugin reaches a target by a different route, loading live from `claude/` rather than from a tarball. That folder is a `files` entry too, and its `standards` symlink resolves into a tree the field lists in its own right, so both routes land inside the same corpus.
 
@@ -30,7 +30,7 @@ Three root files are read whether or not the field names them, being `package.js
 
 ### What the corpus leaves out
 
-The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, and every test file. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
+The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/eval/` and every test file. The scenario tree was a third negation at that reading and now sits at `sandbox/` under no `files` entry, so it stays unread. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
 
 A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the toolkit's rule that content leaving the repository gates harder than content that stays.
 

package/docs/target/migrations.md

@@ -79,7 +79,7 @@ The order carries the reason. A sync replaces each toolkit-owned copy with one a
 
 ## Move the surfaces off `.claude/`, once
 
-Tracked surfaces moved out of `.claude/` and into a root of their own. `context/`, `decisions/`, `wireframes/`, the three loose documents (`ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`), and the install stamp folder, respelled `canon/config/`, now live under `canon/`, and `rules/`, `skills/`, `hooks/`, and `settings.json` stay put since Claude Code reads those by path.
+Tracked surfaces moved out of `.claude/` and into a root of their own. `context/`, `wireframes/`, the three loose documents (`ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`), and the install stamp folder, respelled `canon/config/`, now live under `canon/`, and `rules/`, `skills/`, `hooks/`, and `settings.json` stay put since Claude Code reads those by path.
 
 Run `canon upgrade` first if you have not, then run this from inside the project:
 

package/docs/workflow/ai-workflow.md

@@ -20,8 +20,7 @@ canon/
 ├── ARCHITECTURE.md  ← technical design decisions
 ├── DESIGN.md        ← visual intent and token decisions (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
+└── context/         ← per-domain narrative loaded on demand via index.md
 
 .claude/
 └── rules/           ← path-scoped governance rules, written by canon gov install
@@ -34,7 +33,7 @@ canon/
 └── tmp/             ← deletable scratch, safe to remove without loss
 ```
 
-A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it, and `canon migrate record-tree` follows it to reach the citations inside the records themselves, which the first verb passes over because it enumerates through git. A project scaffolded before the surface move keeps its context, decisions, wireframes, and loose documents under `.claude/` the same way, and `canon migrate surface-roots` moves those to `canon/` with the history following each file.
+A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it, and `canon migrate record-tree` follows it to reach the citations inside the records themselves, which the first verb passes over because it enumerates through git. A project scaffolded before the surface move keeps its context, wireframes, and loose documents under `.claude/` the same way, and `canon migrate surface-roots` moves those to `canon/` with the history following each file.
 
 Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `canon/REQUIREMENTS.md`, `canon/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`canon/context/<domain>.md`, or `canon/context/<domain>/` once a domain outgrows one file, discovered via `canon/context/index.md`). See [the context model](../../canon/context/context-model/overview.md) for the full picture.
 

package/docs/workflow/skill-map.md

@@ -134,7 +134,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                |
 | `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                             |
 | `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                     |
-| `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                                         |
+| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap      |
 | `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                       |
 
 ## Answer a question at any point

package/governance/renames.toml

@@ -6,10 +6,13 @@
 # An entry declares one-to-one identity and nothing else. A fold of several
 # rules into one, or a split of one into several, is a retirement plus an
 # addition and takes no entry here. Add the entry in the same change as the
-# rename or renumber, and never prune one: a target can sit any number of
-# releases behind, and a chain A to B to C resolves A only while both links
-# stay. A key must name no live rule and every chain must end on one, which
-# `src/gov/renames.test.ts` checks against this file.
+# rename or renumber. Prune an entry only once its target rule is retired and
+# the retire path covers it, since a chain ending on a rule nothing ships
+# resolves to nothing and a sync deletes the held file instead. Otherwise leave
+# it: a target can sit any number of releases behind, and a chain A to B to C
+# resolves A only while both links stay. A key must name no live rule and every
+# chain must end on one, which `src/gov/renames.test.ts` checks against this
+# file.
 [renamed]
 "005-behavior" = "565-behavior"
 "015-output" = "566-output"
@@ -25,7 +28,6 @@
 "520-wireframes" = "620-wireframes"
 "530-requirements" = "630-requirements"
 "540-architecture" = "640-architecture"
-"545-decisions" = "645-decisions"
 "550-design" = "650-design"
 "555-tasks" = "655-tasks"
 "556-groundwork" = "656-groundwork"

package/governance/rules/canon/630-requirements.md

@@ -9,4 +9,4 @@ paths:
 
 ## Authority
 
-- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source. Read it with `canon standards requirements`.
+- Follow the requirements standard for what belongs in the problem, goals, non-goals, MVP features, and constraints. It is the single source. Read it with `canon standards requirements`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.14.0",
+  "version": "5.15.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -17,7 +17,6 @@
     "docs",
     "tsconfig.json",
     "assets/brand/mark.svg",
-    "!scripts/sandbox",
     "!scripts/eval",
     "!**/*.test.ts",
     "!**/*.test.tsx"
@@ -27,9 +26,9 @@
   },
   "scripts": {
     "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
-    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
+    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ sandbox/ tooling/ claude/",
+    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ sandbox/ tooling/ claude/",
+    "check:shell": "find scripts sandbox tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",
@@ -53,11 +52,13 @@
     "web:e2e": "cd web && playwright test"
   },
   "dependencies": {
+    "@preact/signals": "^2.11.3",
     "commander": "^13.1.0",
     "execa": "^9.5.2",
     "highlight.js": "^11.12.0",
     "playwright-core": "1.59.1",
-    "pptxgenjs": "^4.0.1"
+    "pptxgenjs": "^4.0.1",
+    "preact": "^11.0.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.8",
@@ -71,6 +72,7 @@
     "@types/micromatch": "^4.0.10",
     "astro": "^6.1.9",
     "cspell": "^8.17.1",
+    "happy-dom": "^20.14.5",
     "husky": "^9.1.7",
     "micromatch": "^4.0.8",
     "prettier": "^3.8.1",

package/scripts/core/check-color-source.sh

@@ -6,6 +6,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
+SANDBOX_ROOT="$PROJECT_ROOT/sandbox"
 PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
 
 # `find` writes to stderr and returns non-zero for a missing root, inside a
@@ -16,6 +17,15 @@ if [ ! -f "$PALETTE_SOURCE" ]; then
   exit 1
 fi
 
+# The same silence follows a root that moved, so a walked root that is gone
+# fails here rather than shrinking the corpus with no message.
+for root in "$SCRIPTS_ROOT" "$SANDBOX_ROOT"; do
+  if [ ! -d "$root" ]; then
+    echo "No shell root at ${root#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
+    exit 1
+  fi
+done
+
 # Any SGR sequence in either spelling. The cursor and erase sequences an
 # interactive prompt writes end in a letter instead, and they run only where a
 # terminal already exists, so they are not what this measures.
@@ -31,7 +41,7 @@ while IFS= read -r file; do
   if grep -qE "$SGR" "$file"; then
     offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
   fi
-done < <(find "$SCRIPTS_ROOT" -type f -name '*.sh')
+done < <(find "$SCRIPTS_ROOT" "$SANDBOX_ROOT" -type f -name '*.sh')
 
 if [ -n "$offenders" ]; then
   echo "A color escape is defined outside the shared library:" >&2