@erclx/canon 5.26.0 → 5.27.0

package/docs/agents/pr-preview.md

@@ -1,6 +1,6 @@
 ---
 title: The pull request preview deploy
-description: How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
+description: How canon pr preview finds a fenced Cloudflare Pages deploy, refuses a branch its push filter does not serve, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 ---
 
 # The pull request preview deploy
@@ -8,8 +8,8 @@ description: How canon pr preview finds a fenced Cloudflare Pages deploy, dispat
 `canon pr preview` publishes a pull request's branch to a Cloudflare Pages
 preview and reports the address. `git-pr` calls it after the evidence
 comparison, then re-renders that comment through `canon pr evidence --preview`
-so the link opens it. A reviewer gets a page to click into before merging
-rather than screenshots and a checklist alone.
+so the link sits on the address line under its heading. A reviewer gets a page
+to click into before merging rather than screenshots and a checklist alone.
 
 ```bash
 canon pr preview --json
@@ -31,6 +31,24 @@ the first file, in path order, that meets four tests:
 The workflow is read before the pull request, so a project with no fenced
 deploy is refused without a network call.
 
+## Which branches it serves
+
+A dispatch runs the workflow whatever its `on.push.paths` filter says, so a
+branch that touched nothing the site builds from would get a preview showing
+none of its change. The verb reads the pull request's changed paths and matches
+them against the picked workflow's own `on.push.paths` or `on.push.paths-ignore`
+list, applying `!` patterns in order the way GitHub does. When nothing matches,
+it refuses as `unserved` and dispatches nothing. `--check` answers `unserved`
+the same way.
+
+The push filter is the one statement of what the site builds from, since it
+already decides when production deploys. A workflow with neither list, with no
+push trigger, or that does not parse as YAML serves every change, so a project
+whose every change ships keeps minting for every branch.
+
+A removed path counts, the same as GitHub's own push filter counts it, so a
+branch whose only site change deletes a file still gets a preview.
+
 ## Why an unfenced deploy is refused
 
 Cloudflare Pages publishes a deploy that names no branch to production. A
@@ -62,19 +80,21 @@ keeps the match independent of the local clock.
 
 `reason` on the record is what a caller branches on, not the exit code:
 
-| Reason          | What it means                                                              |
-| --------------- | -------------------------------------------------------------------------- |
-| `ok`            | The preview was published. `url` carries the address and `runId` the run.  |
-| `no-deploy`     | No dispatchable workflow runs `pages deploy`.                              |
-| `unfenced`      | The deploy passes no `--branch`, so nothing was dispatched.                |
-| `no-alias`      | The workflow prints no alias line, or the finished run's log carried none. |
-| `run-failed`    | The deploy run finished without succeeding. `runId` names it.              |
-| `timeout`       | The run did not finish inside `--timeout` minutes, 15 by default.          |
-| `bad-timeout`   | `--timeout` was not a positive number.                                     |
-| `gh-missing`    | `gh` is not on the path.                                                   |
-| `gh-failed`     | `gh` could not read the pull request, or list or dispatch the workflow.    |
-| `no-branch`     | The pull request carries no head branch name.                              |
-| `check-timeout` | `--check` was combined with `--timeout`.                                   |
+| Reason               | What it means                                                              |
+| -------------------- | -------------------------------------------------------------------------- |
+| `ok`                 | The preview was published. `url` carries the address and `runId` the run.  |
+| `no-deploy`          | No dispatchable workflow runs `pages deploy`.                              |
+| `unserved`           | The push path filter matches no changed path, so nothing was dispatched.   |
+| `unreadable-changes` | The pull request's changed paths could not be read.                        |
+| `unfenced`           | The deploy passes no `--branch`, so nothing was dispatched.                |
+| `no-alias`           | The workflow prints no alias line, or the finished run's log carried none. |
+| `run-failed`         | The deploy run finished without succeeding. `runId` names it.              |
+| `timeout`            | The run did not finish inside `--timeout` minutes, 15 by default.          |
+| `bad-timeout`        | `--timeout` was not a positive number.                                     |
+| `gh-missing`         | `gh` is not on the path.                                                   |
+| `gh-failed`          | `gh` could not read the pull request, or list or dispatch the workflow.    |
+| `no-branch`          | The pull request carries no head branch name.                              |
+| `check-timeout`      | `--check` was combined with `--timeout`.                                   |
 
 The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
 going, so the preview may still land after the verb has given up on it.
@@ -107,10 +127,11 @@ reason but `fresh`.
 
 ## How the address reaches the pull request
 
-`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line
-of the evidence body. With no evidence image in the diff, the body is that line
-and the trailing marker alone, so a pull request whose screenshots did not
-change still gets one comment a later call can find and edit.
+`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the address
+line under the evidence body's `## Evidence` heading. With no evidence image in
+the diff, the body is the heading, that line, and the trailing marker alone, so
+a pull request whose screenshots did not change still gets one comment a later
+call can find and edit.
 
 A later `canon pr evidence` run without `--preview` reads the address off the
 marked comment and carries it into the new body. `git-followup` re-renders the
@@ -123,7 +144,9 @@ way, which is what keeps that push from wiping boxes a reviewer already ticked.
 A `pull_request` trigger on `closed` in the same workflow runs a cleanup job
 that deletes every preview deployment Cloudflare holds for the branch. The
 deploy job carries `if: github.event_name != 'pull_request'`, so a closed pull
-request never deploys.
+request never deploys. The same close runs `canon pr local --remove`, which
+drops the address line from the evidence comment, hosted link included, so the
+comment never links a deployment that no longer exists.
 
 ## What this does not cover
 

package/docs/agents/sandbox.md

@@ -39,15 +39,39 @@ The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.to
 
 Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
 
-An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
+An arm declaring `escape_scope` asserts a bound on the headless runner's own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `canon/context/sandbox/isolation.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 
 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.
 
+## Headless runs
+
+`canon sandbox run` provisions a scenario, drives one `claude -p` session over it, and scores the result with `canon sandbox check`. `sandbox/run.sh` is a wrapper that passes its arguments to the verb, so either spelling runs the same code.
+
+```bash
+canon sandbox run <category>:<command> "<prompt>" [arm]
+canon sandbox run claude:plan-feature "/canon:plan-feature add a widget" small
+```
+
+Every run bills a real session through the `claude` binary on `PATH`. The session runs with `--plugin-dir` pointed at this checkout's `claude/`, so it loads the branch's skills rather than an installed copy, and provisioning injects no skill into the tree for the same reason. Four variables override the flags it hands to `claude -p`:
+
+| Variable                           | Default                          |
+| ---------------------------------- | -------------------------------- |
+| `CANON_SKILL_TEST_MODEL`           | `sonnet`                         |
+| `CANON_SKILL_TEST_TOOLS`           | `Bash,Read,Glob,Grep,Edit,Write` |
+| `CANON_SKILL_TEST_MAX_TURNS`       | `30`                             |
+| `CANON_SKILL_TEST_PERMISSION_MODE` | `bypassPermissions`              |
+
+The max-turns value is the only budget a run has. An arm's `max_turns` is asserted after the run and cannot raise it.
+
+Stdout carries one JSON record: the session's envelope with `verdict`, `escapes`, and `sessions` merged in, described under the skills census below. Stderr carries the framed timeline, the provisioning output, the session's own stderr, the verdict report, and a warning for each escape, new session record, or reaped process. An envelope that does not parse still prints its verdict, under `is_error: true`.
+
+Exit codes follow whichever step stopped the run. Provisioning's code ends a run before the session starts, and a session that exits non-zero ends it with that code after writing a dead-run record, `{is_error, exit_code, raw_output}`, to the same runs folder the merged record uses. Otherwise the verdict's code stands, except that an envelope that does not parse forces 1. An interrupt reaps the session's process group before the runner exits.
+
 ## 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.
+`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 `canon sandbox run` or a `claude` binary, so no arm it runs bills a model.
 
 ```bash
 canon sandbox equivalence claude --base origin/main --json
@@ -95,8 +119,8 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `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.
 
-`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.
+`canon sandbox run` 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.
 
-`run.sh` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.
+`canon sandbox run` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.

package/docs/agents/scripting.md

@@ -17,7 +17,7 @@ Use these to discover what's available instead of hardcoding names.
 | `canon standards list --json`     | Standards docs and the paths each governs                        |
 | `canon gov list --json`           | Governance stacks, rule sets, and unreferenced rules             |
 | `canon claude seeds list --json`  | Seed doc sources with content                                    |
-| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag                    |
+| `canon claude skills list --json` | Plugin skills, descriptions, requirement flag, family vocabulary |
 | `canon docs list --json`          | Consumer docs plus per-domain context                            |
 | `canon audits list --json`        | Audits the set runs, the corpus each reads, and whether it gates |
 
@@ -68,6 +68,13 @@ or unparseable returns an empty description rather than failing the listing, so
 one malformed file cannot hide the rest of the catalog. `--names` emits skill
 names one per line.
 
+Each skill in `--json` carries `family`, the `metadata.family` its frontmatter
+declares, or `null` where it declares none. A top-level `families` array holds
+the vocabulary as `{ key, group }` entries in skill map order, where `group` is
+the map heading the family's rows sit under. Read a new skill's family from it
+rather than from the map. `--by-family` prints the human listing as one step per
+family, with a trailing step for any skill whose family is missing or unknown.
+
 Each entry also carries `requirement`, whether the folder holds a sibling
 `REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
 close rather than a recorded exemption, and the flag answers which skills are

package/docs/agents/skills-audit.md

@@ -38,6 +38,7 @@ Each check traces to a line in the standard.
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
 - Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and each skill on the wider ledger list carrying `references/adopted.md`, reported together as `practiceShape`
 - Each file under `references/` running over 100 lines opening with a `## Contents` H2, reported as `referenceContents`
+- Each skill under `claude/skills/` declaring a `metadata.family` that names a key in `checkpoints.families`, reported as `family`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
@@ -61,7 +62,7 @@ A check with no rule behind it prints an opinion as a defect, which is where the
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, practice shape, and reference contents findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, two `bun run check` stages read the same report in-process and fail a push on dated provenance and on practice shape, since its own corpus is held at zero on both.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, practice shape, reference contents, and family findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, three `bun run check` stages read the same report in-process and fail a push on dated provenance, on practice shape, and on family, since its own corpus is held at zero on all three.
 
 No stage reads reference contents, so a long reference without a list stays a report.
 

package/docs/workflow/operating-model.md

@@ -11,8 +11,8 @@ loop and without losing the human review gate. One warm session holds the
 cross-feature call and reviews. Planning runs there or in a session of its own.
 Cold worker sessions build. The human launches workers and merges.
 
-This page covers the roles and the loop. For the worktree mechanism (isolation, merge
-order, port collisions), see [Claude Code and git worktrees](../../wiki/claude/worktrees.md).
+This page covers the roles and the loop. For merge order and fan-out rules, see
+[Parallel features](parallel-features.md), and for worktree gotchas, [Claude Code and git worktrees](../../wiki/claude/worktrees.md).
 
 ## Four roles
 
@@ -225,12 +225,11 @@ Unit checks run freely in many worktrees at once.
 A dev server, an end-to-end run, and a screenshot run alongside each other on a
 web stack, since every worktree derives its own port. Singleton resources (one
 local model server, one GPU) still serialize, as does any port a stack fixes by
-hand. See
-[Claude Code and git worktrees](../../wiki/claude/worktrees.md) for merge order and the
-port-collision detail.
+hand. See [Parallel features](parallel-features.md) for merge order and
+[Claude Code and git worktrees](../../wiki/claude/worktrees.md) for port collisions.
 
 ## Related
 
-- [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the isolation and fan-out mechanics
+- [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the worktree mechanism and its gotchas
 - [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism without worktrees, and [blocking subagents](../../wiki/claude/permissions.md#blocking-subagents) for the `permissions.deny` rule that stops every spawn
 - `canon/context/claude-plugin/skill-strategy/overview.md` for how the skills in the loop are categorized

package/docs/workflow/parallel-features.md

@@ -32,7 +32,7 @@ A constraint naming a track in flight carries the same problem past the handoff,
 
 ## Records at the main root
 
-`.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the full rule and the domain-level fan-out guidance.
+`.canon/plans/`, `.canon/review/`, and `.canon/memory/` all resolve at the main worktree root, so artifacts created in any session are visible from any sibling worktree. A session inside a worktree reads them directly, since the file-editing tools refuse a main-root path but `Read` resolves normally. It writes a whole file through the shell and makes a change inside an existing file through a `canon` verb, which resolves the main root in-process. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for why the tool refuses the write, and the fan-out section below for the domain-level guidance.
 
 The plan's shape is fixed by `standards/plan.md`: the section list, the filename, and the contract its questions keep. Its lifecycle, from the session that writes it to the archive, is `standards/plan-lifecycle.md`. Every question carries a `- Suggested:` line and an empty `- Answer:` slot, and a blank answer accepts the suggestion at execution time. That default is what makes a plan decision-ready in one pass, and it is the opposite of the contract an intake folder keeps, where an empty slot means nobody reached the item.
 
@@ -56,6 +56,27 @@ A branch review report takes the other route and is swept rather than archived.
 
 `canon:context-fold` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Architecture and design stay session-sourced, because a diff cannot carry a judgment, and an architecture write further needs a folded plan naming the slot decision. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
 
+## Shipping a fan-out
+
+A fan-out of N worktrees produces N pull requests. The order they merge in matters only when two branches touch the same file.
+
+**Collision profile.** Work confined to one domain directory, such as a new skill under its own folder or independent fixes in different subtrees of `scripts/`, rarely collides. These paths are shared hotspots, so a branch touching one serializes rather than fans out, because parallel edits almost always produce a conflict or a stale regenerated file:
+
+- `CLAUDE.md`, since cross-domain behavior lives there
+- `tooling/**`, since stack manifests, golden configs, and seeds are tightly coupled
+- `canon/context/context-model/overview.md` and `docs/agents/`, which several domains cross-reference
+- Any folder's `index.md`, since `canon indexes regen` rewrites it and two worktrees adding files to a regen-covered folder race on it
+
+Land any in-flight edit to a hotspot on `main` before fanning out. A worktree on a stale `CLAUDE.md` costs more to rebase than it saved.
+
+**Merge order.** Merge the branch with the smallest hotspot footprint first. A branch touching `CLAUDE.md`, a context entry, or a regenerated `index.md` merges last, and its siblings rebase on the new `main` once it lands.
+
+**Rebase before the next merge.** After one squash-merge, each sibling is behind `main` and may carry a stale copy of a shared file. Run `git fetch origin && git rebase origin/main` in the sibling, resolve any conflict in the worktree, push, then merge. Never force-merge a stale branch.
+
+**Clean up after merge.** Run `/git-worktree cleanup` to remove worktrees whose branches merged on GitHub and prune the local branches. The skill reads merge state through `gh pr view`. To start a fresh feature from a stale worktree, `ExitWorktree(action: "keep")` back to main, then `/session-worktree <new-name>`.
+
+**When fan-out was the wrong call.** If every sibling needs a rebase and every rebase conflicts on the same file, the branches should have serialized. Land one, wait, then start the next. The cleanup skill only tidies a flow that already worked.
+
 ## The task board
 
 `.canon/tasks/` is gitignored and resolves at the main worktree root, so every session shares one board. One file per task is what keeps concurrent sessions from overwriting each other, since a gitignored board has no history to recover a lost write from. Its `index.md` is generated by a hook rather than by `bun run check`, because the whole-repo index walk skips gitignored folders.

package/docs/workflow/skill-map.md

@@ -8,7 +8,9 @@ category: Workflow
 
 Groups run in the order a project meets them. They reconcile the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, so every moment either one names has a group. Each row says when to reach for a skill, and its description says what it does.
 
-This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment. The landing page's skills field renders from both pages, so its build refuses a skill with no row and a row naming no skill.
+This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment.
+
+Each row sits under the group its skill's `metadata.family` names. The landing page's skills field groups by that field and reads each row's text from both pages, so its build refuses a skill with no row, a row naming no skill, a row filed under another group, and a heading on either page naming no family group, even one with no rows under it. A new group takes its vocabulary entry in `src/claude/skills-families.ts` before its heading lands here.
 
 ## Set up a project
 

package/docs/workflow/zshrc-aliases.md

@@ -68,7 +68,7 @@ Use `clp` in any other repository where you want the toolkit skills available. W
 
 Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
 
-Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for fan-out rules.
+Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the worktree mechanism, and [Parallel features](parallel-features.md) for fan-out rules.
 
 Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Reach for `clpc` over `clc` wherever the resumed session needs the plugin, inside the toolkit repository as well as outside it, since neither resume re-runs discovery.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.26.0",
+  "version": "5.27.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.ts

@@ -20,7 +20,7 @@
  *
  * Only the HTML regenerates here. The PNG beside it is a chromium render whose
  * bytes move with the browser version. Rebuild the images with
- * `canon capture assets/captures --selector .window --out assets/evidence`
+ * `canon capture assets/captures --selector .window --out assets/frames`
  * after this script reports a change. That capture writes a .stamp beside each
  * PNG, which records the digest of the markup it rendered and is what the Hero
  * stage compares, so a frame's three files commit together. The frame carries

package/scripts/lib/sandbox-path.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# The sandbox tree lives outside the toolkit worktree. `sandbox/run.sh`
+# The sandbox tree lives outside the toolkit worktree. `canon sandbox run`
 # sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
 # filesystem root loads into the session. Under the repository the toolkit's own
 # instructions join that chain beside the seeded copy the scenario installed,
@@ -12,12 +12,11 @@
 #
 # Mints a short random per-run identifier the first time it is asked for, then
 # holds it in CANON_SANDBOX_RUN_ID for the rest of this process. A direct call
-# (not `$(...)`) exports it into the caller's own shell, which is what lets
-# `run.sh` mint once and have the provisioning and the check it shells out to
-# both inherit the same id as ordinary children. A call already carrying the
-# variable, inherited from such a parent, reuses it rather than minting a new one.
+# (not `$(...)`) exports it into the caller's own shell. A call already carrying
+# the variable, inherited from a parent such as `canon sandbox run`, reuses it
+# rather than minting a new one, which is what keeps a hook on the parent's tree.
 #
-# Twin of `mintSandboxRunId` in `src/commands/sandbox.ts`.
+# Twin of `mintSandboxRunId` in `src/sandbox/tree.ts`.
 mint_sandbox_run_id() {
   if [ -z "${CANON_SANDBOX_RUN_ID:-}" ]; then
     CANON_SANDBOX_RUN_ID="$(date +%s)-$$-$RANDOM"
@@ -33,7 +32,7 @@ sandbox_dir_prefix() {
   printf '%s/canon/sandbox\n' "${XDG_STATE_HOME:-$HOME/.local/state}"
 }
 
-# Twin of `sandboxTree` in `src/commands/sandbox.ts`. The exec boundary rules out
+# Twin of `sandboxTree` in `src/sandbox/tree.ts`. The exec boundary rules out
 # a shared constant, so a change to the default lands on both sides.
 #
 # A bare fall-through with no per-run component is one path per machine, so
@@ -49,158 +48,3 @@ resolve_sandbox_dir() {
   mint_sandbox_run_id
   printf '%s-%s\n' "$(sandbox_dir_prefix)" "$CANON_SANDBOX_RUN_ID"
 }
-
-# Collapses repeated separators, folds `.` and `..` segments, and strips every
-# trailing separator, leaving a bare root as `/`. Every comparison below is a
-# string test, so `//`, `$HOME//`, and `$HOME/../../usr` each read as a path no
-# rule names until this runs, and an unresolved `..` defeats the allowlist and
-# both directions of the repository test at once.
-#
-# The fold is lexical because the guard runs before provisioning creates the
-# tree, which rules out `cd` with `pwd -P` and any resolution needing the path
-# to exist. Nothing here follows a symlink, so a `..` below one resolves against
-# the link's own path rather than its target. A `..` climbing past the root
-# clamps to `/`, matching the kernel, which leaves the allowlist to refuse it
-# under the rule that already covers every root path.
-normalize_sandbox_path() {
-  local path="$1"
-
-  [ -n "$path" ] || return 0
-
-  while [ "$path" != "${path//\/\//\/}" ]; do
-    path="${path//\/\//\/}"
-  done
-
-  local root=""
-  if [ "${path#/}" != "$path" ]; then
-    root="/"
-    path="${path#/}"
-  fi
-
-  # `resolved` carries each kept segment behind its own separator, so a pop is
-  # one suffix removal and popping an empty stack is the no-op that clamps at
-  # the root. `climbed` holds the leading `..` a relative path has no segment to
-  # pop against, which dropping would change the directory it names.
-  local resolved="" climbed="" segment
-  local remaining=4096
-
-  while [ -n "$path" ] && [ "$remaining" -gt 0 ]; do
-    remaining=$((remaining - 1))
-
-    segment="${path%%/*}"
-    if [ "$segment" = "$path" ]; then
-      path=""
-    else
-      path="${path#*/}"
-    fi
-
-    case "$segment" in
-    "" | .) ;;
-    ..)
-      if [ -n "$resolved" ]; then
-        resolved="${resolved%/*}"
-      elif [ -z "$root" ]; then
-        climbed="$climbed../"
-      fi
-      ;;
-    *) resolved="$resolved/$segment" ;;
-    esac
-  done
-
-  if [ -n "$root" ]; then
-    path="${resolved:-/}"
-  else
-    path="${climbed}${resolved#/}"
-    path="${path:-.}"
-  fi
-
-  while [ "${#path}" -gt 1 ] && [ "${path%/}" != "$path" ]; do
-    path="${path%/}"
-  done
-
-  printf '%s' "$path"
-}
-
-# Whether `candidate` is `target` or a directory containing it. Removing the
-# former removes the latter, which is what makes an ancestor as dangerous as an
-# exact match.
-is_at_or_above() {
-  local candidate="$1"
-  local target="$2"
-
-  [ "$candidate" = "$target" ] || [ "${target#"$candidate"/}" != "$target" ]
-}
-
-# Prints the reason a location is unusable and returns non-zero, so the caller
-# reports one message naming the path rather than a bare refusal.
-#
-# Provisioning runs `rm -rf` on this path at three sites before staging, so the
-# test is an allowlist rather than a list of paths to refuse. A blocklist has to
-# name every system directory to be right once and stays wrong as soon as one is
-# missed, while requiring a strict descendant of the home directory or of the
-# temp root admits the default and every reasonable override and refuses `/`,
-# `/usr`, `/etc`, and `$HOME` itself without naming any of them.
-#
-# The repository test is separate and runs both ways. A path under the worktree
-# restores the ancestor chain the relocation removed, and a path above it is one
-# `rm -rf` away from deleting the repository. It resolves the main worktree root
-# rather than trusting `$PROJECT_ROOT`, since a linked worktree is itself inside
-# that root.
-assert_sandbox_dir_safe() {
-  local raw="$1"
-  local root="${2:-${PROJECT_ROOT:-$PWD}}"
-
-  if [ -z "$raw" ] || [ "${raw#/}" = "$raw" ]; then
-    printf 'CANON_SANDBOX_DIR must be an absolute path, got: %s\n' "${raw:-<empty>}"
-    return 1
-  fi
-
-  # `normalize_sandbox_path` stops at 4096 segments and drops the remainder,
-  # which would hand the tests below an ancestor of the path provisioning
-  # removes. Refusing past `PATH_MAX` keeps that bound out of reach, since a
-  # segment costs at least two bytes and no syscall accepts the string anyway.
-  if [ "${#raw}" -gt 4096 ]; then
-    printf 'Refusing the sandbox path. It is %s characters, past the longest path any filesystem here accepts.\n' "${#raw}"
-    return 1
-  fi
-
-  local dir home temp
-  dir="$(normalize_sandbox_path "$raw")"
-  home="$(normalize_sandbox_path "${HOME:-/root}")"
-  temp="$(normalize_sandbox_path "${TMPDIR:-/tmp}")"
-
-  # Every message below names `$raw`, which is what the operator set. The tests
-  # compare `$dir`, so a path carrying `..` is refused for a location its own
-  # spelling does not show.
-  local resolution=""
-  [ "$dir" = "$raw" ] || resolution=" It resolves to $dir."
-
-  if ! is_at_or_above "$home" "$dir" && ! is_at_or_above "$temp" "$dir"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s or %s.%s\n' "$raw" "$home" "$temp" "$resolution"
-    return 1
-  fi
-
-  if [ "$dir" = "$home" ] || [ "$dir" = "$temp" ]; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, so the path has to sit under %s rather than be it.\n' "$raw" "$dir"
-    return 1
-  fi
-
-  local main_root
-  main_root="$(git -C "$root" worktree list --porcelain 2>/dev/null |
-    grep -m 1 '^worktree ' | cut -d' ' -f2-)"
-  main_root="$(normalize_sandbox_path "${main_root:-$root}")"
-
-  if is_at_or_above "$dir" "$main_root"; then
-    printf 'Refusing %s as the sandbox. Provisioning removes the tree first, and that path contains %s.%s\n' "$raw" "$main_root" "$resolution"
-    return 1
-  fi
-
-  case "$dir" in
-  "$main_root"/*)
-    printf 'Sandbox at %s sits inside %s, which puts the toolkit CLAUDE.md back on the session ancestor chain.%s Point CANON_SANDBOX_DIR outside the repository.\n' "$raw" "$main_root" "$resolution"
-    return 1
-    ;;
-  esac
-
-  return 0
-}

package/src/audits/run.ts

@@ -7,7 +7,7 @@ import {
   classify,
   type Corpus,
 } from '@/audits/catalog'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { PROJECT_ROOT } from '@/project-root'
 
 /** Every value a corpus filter accepts, matching the `Corpus` union. */

package/src/canvas/address.ts

@@ -9,6 +9,12 @@
 /** Marks the token stylesheet the server injects, which the file never holds. */
 export const TOKENS_ATTRIBUTE = 'data-canvas-tokens'
 
+/**
+ * Marks a document wrapper the server writes because the file leaves it to the
+ * browser to imply, so the shell counts only what the file states.
+ */
+export const IMPLIED_ATTRIBUTE = 'data-canvas-implied'
+
 /** On that same element, the hash of the file the frame was served from. */
 export const HASH_ATTRIBUTE = 'data-canvas-hash'
 
@@ -22,8 +28,9 @@ export interface ElementAddress {
   readonly tag: string
   /**
    * Every element the shell counted. A browser implies elements the file never
-   * states, such as a `tbody` or the document wrapper, and each one shifts the
-   * count, so a total that differs from the server's is what exposes it.
+   * states, such as a `tbody`, and each one shifts the count, so a total that
+   * differs from the server's is what exposes it. The server marks an implied
+   * document wrapper itself, so only the marked ones leave the count.
    */
   readonly count: number
   /**
@@ -53,7 +60,9 @@ export function excerpt(text: string): string {
 
 export function documentElements(doc: Document): Element[] {
   return [...doc.querySelectorAll('*')].filter(
-    (element) => !element.hasAttribute(TOKENS_ATTRIBUTE),
+    (element) =>
+      !element.hasAttribute(TOKENS_ATTRIBUTE) &&
+      !element.hasAttribute(IMPLIED_ATTRIBUTE),
   )
 }