@erclx/canon 5.25.0 → 5.27.0

package/docs/workflow/ai-workflow.md

@@ -136,7 +136,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 
 ## Skills
 
-The [skill map](skill-map.md) gives every skill the plugin ships one row saying when to reach for it, grouped by the moment a project meets it.
+The [skill map](skill-map.md) and its sibling [skill map on request](skill-map-on-request.md) give every skill the plugin ships one row saying when to reach for it. The first groups rows by the moment a project meets them, and the sibling holds the skills that answer a request.
 
 ## Feedback routing
 

package/docs/workflow/index.md

@@ -15,6 +15,7 @@ How a person and their agents run a feature, from the design tier through the pa
 
 - [Operating model](operating-model.md): Orchestrator, planner, and worker roles for building across parallel sessions
 - [Parallel features](parallel-features.md): Run independent features in parallel worktrees, with the records and board every session shares
+- [Skill map on request](skill-map-on-request.md): When to reach for the plugin skills that serve a request rather than a moment in a project's life
 - [Skill map](skill-map.md): When to reach for each plugin skill, grouped by the moment a project meets it
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations

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.
 
@@ -54,7 +54,28 @@ A plan that ships is archived, never deleted. `canon tasks archive` moves it to
 
 A branch review report takes the other route and is swept rather than archived. `review-branch` writes it flat into `.canon/review/` as `branch-<slug>.md`, the session addressing it reads it once, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so `context-fold` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
 
-`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. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
+`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
 

package/docs/workflow/skill-map-on-request.md

@@ -0,0 +1,42 @@
+---
+title: Skill map on request
+description: When to reach for the plugin skills that serve a request rather than a moment in a project's life
+category: Workflow
+---
+
+# Skill map on request
+
+These two groups hold the skills no single moment in a project's life calls for, so they sit apart from the moment-ordered groups in the [skill map](skill-map.md). The two pages together are the corpus the coverage claim is measured against, and a skill takes one row across both.
+
+## Generate an artifact on demand
+
+| Skill                     | When to use                                                                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                               |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                           |
+| `canon:create-standard`   | For a new authoring convention                                                                                                                 |
+| `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
+| `canon:draft-figure`      | For a hand-drawn figure or an architecture view inside an existing doc, drafted in Mermaid or freehand SVG                                     |
+| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                             |
+| `canon:draft-slides`      | For a deck, drawn as HTML slides in its own folder and rendered to editable PowerPoint                                                         |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                                                  |
+| `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
+
+| Skill                       | When to use                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
+| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
+| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
+| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
+| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
+| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
+
+Every row answers a question rather than marking a point in a project's life, so filing one under a phase on the [skill map](skill-map.md) would send a reader to the wrong group.
+
+A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.

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 is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing. The landing page's skills field renders from this page, 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
 
@@ -115,36 +117,3 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:canon-feedback`        | When something in the toolkit is broken, missing, or off, to open an issue on it       |
 | `canon:canon-feedback-triage` | In the toolkit repo, to work through the open feedback issues                          |
 | `canon:canon-rollout`         | In the toolkit repo, to take one change out to every consuming project at once         |
-
-## Generate an artifact on demand
-
-| Skill                     | When to use                                                                                                                                    |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                               |
-| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                           |
-| `canon:create-standard`   | For a new authoring convention                                                                                                                 |
-| `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
-| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
-| `canon:draft-figure`      | For a hand-drawn figure or an architecture view inside an existing doc, drafted in Mermaid or freehand SVG                                     |
-| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
-| `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 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
-
-| Skill                       | When to use                                                                                                                                                            |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
-| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
-| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
-| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
-| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
-| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
-| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
-
-Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
-
-A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.

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.25.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-git.sh

@@ -60,7 +60,7 @@ configure_sandbox_git_identity() {
 SANDBOX_ANCHOR_REPO="canon-sandbox"
 
 # A scenario calls this from its own use_anchor hook rather than this file
-# defining the hook. manage-sandbox.sh keys off `type -t use_anchor`, so
+# defining the hook. sandbox-hook.sh keys off `type -t use_anchor`, so
 # declaring it here would hand an anchor to the scenarios that source this file
 # for the identity helpers alone.
 use_sandbox_anchor() {
@@ -112,14 +112,6 @@ ensure_sandbox_anchor_repo() {
   log_info "Created ${GITHUB_ORG}/${repo_name} as a private repository."
 }
 
-# Mirrors the merge-base resolution the diff-baseline port already carries
-# across five skill bodies, so a checkout whose local main trails origin/main
-# does not pull in skill bodies other merged branches changed.
-resolve_sandbox_skill_diff_base() {
-  git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null ||
-    git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null
-}
-
 # A remote is useless without an author, so the scenarios that reach one always
 # configure both. configure_sandbox_git_identity stays callable on its own for
 # the scenarios that never push. The probe runs first so an absent remote is

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 manage-sandbox.sh 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/scripts/sandbox-hook.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# No `-u`. Scenarios ran under the retired dispatcher without it and read unset
+# variables as empty, so turning it on here changes what they provision.
+set -e
+set -o pipefail
+
+# Runs one scenario's hooks for the provisioning order in
+# `src/sandbox/provision.ts`. Scenarios and the library they call stay bash, so
+# the harness reaches them through this entry and nothing else.
+#
+#   probe <scenario>         runs `use_config` and `use_anchor` when declared
+#                            and prints every export they changed, closed by an
+#                            `@anchor=<0|1>` record
+#   stage <scenario> <file>  re-runs both hooks, runs `stage_setup` inside the
+#                            tree, and writes the exports it changed to <file>,
+#                            or an `@exited` record when the shell exits first
+#
+# Pairs are NUL-separated `NAME=value`, since a value can hold a newline. The
+# retired dispatcher ran `stage_setup` in its own shell, so an export, an `exit`,
+# or an `exec` there reached the harness, and the report carries all three: an
+# `exec` skips the EXIT trap and leaves no report at all. The stage re-runs the
+# hooks rather than receiving the probe's pairs, since they only export.
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+export PROJECT_ROOT
+
+# Globals carry a prefix, since the scenario sourced below shares this shell.
+_hook_die() {
+  echo "sandbox-hook: $1" >&2
+  exit 2
+}
+_hook_mode="${1:-}"
+_hook_scenario="${2:-}"
+_hook_report="${3:-}"
+
+[[ "$_hook_mode" == "probe" || "$_hook_mode" == "stage" ]] || _hook_die "mode must be probe or stage, got: ${_hook_mode:-<empty>}"
+[ -f "$_hook_scenario" ] || _hook_die "no scenario file at: ${_hook_scenario:-<empty>}"
+[ "$_hook_mode" = "probe" ] || [ -n "$_hook_report" ] || _hook_die "stage needs a file to report its exports to"
+[ "$_hook_mode" = "probe" ] || trap 'printf "@exited\0" >"$_hook_report"' EXIT
+
+declare -A _hook_before
+_hook_snapshot() {
+  local name
+  _hook_before=()
+  for name in $(compgen -e); do
+    _hook_before[$name]="${!name}"
+  done
+}
+
+# The shell moves PWD and OLDPWD itself on every `cd`, and neither is state.
+_hook_changed() {
+  local name
+  for name in $(compgen -e); do
+    [[ "$name" == "PWD" || "$name" == "OLDPWD" ]] && continue
+    if [[ ! -v _hook_before[$name] ]] || [ "${_hook_before[$name]}" != "${!name}" ]; then
+      printf '%s=%s\0' "$name" "${!name}"
+    fi
+  done
+}
+
+# Taken before `config.sh`, so a `GITHUB_ORG` it derives from the remote reaches
+# the harness as an export like any other.
+_hook_snapshot
+
+source "$PROJECT_ROOT/scripts/config.sh"
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-path.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-git.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-fixtures.sh"
+
+# Unexported, as the dispatcher held them, so a scenario reads both while a
+# child it spawns sees neither. Shellcheck cannot see the scenario reading them.
+# shellcheck disable=SC2034
+SANDBOX="$(resolve_sandbox_dir)" SANDBOX_DIR="$PROJECT_ROOT/sandbox"
+
+# shellcheck source=/dev/null
+source "$_hook_scenario"
+
+_hook_declared() { [[ "$(type -t "$1")" == "function" ]]; }
+_hook_run() {
+  if _hook_declared use_config; then use_config; fi
+  if _hook_declared use_anchor; then use_anchor; fi
+}
+
+if [ "$_hook_mode" = "probe" ]; then
+  # Stdout carries the pairs alone, so a hook that prints is moved off it.
+  _hook_run >&2
+  _hook_changed
+  if _hook_declared use_anchor; then printf '@anchor=1\0'; else printf '@anchor=0\0'; fi
+  exit 0
+fi
+
+_hook_run
+_hook_snapshot
+cd "$SANDBOX"
+stage_setup
+trap - EXIT
+_hook_changed >"$_hook_report"

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

package/src/canvas/capture.ts

@@ -196,14 +196,6 @@ async function serveFor<T>(
 /** The element a composite is captured by, holding every frame and no chrome. */
 export const COMPOSITE_SELECTOR = '#canvas-composite'
 
-/**
- * The container holds no text, so its family exists only for the engine's
- * font probe, which rejects a family the machine lacks. The browser default is
- * Times New Roman, which a Linux runner often lacks, and `system-ui` is the one
- * every platform maps. Each frame keeps its own fonts inside its iframe.
- */
-const COMPOSITE_FONT = 'system-ui'
-
 export interface Placement {
   readonly frame: string
   readonly url: string
@@ -255,7 +247,7 @@ export function buildComposite(
   const html = [
     '<!doctype html>',
     '<html><head><meta charset="utf-8">',
-    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative;font-family:${COMPOSITE_FONT}}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
+    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
     '</head><body>',
     `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
     ...iframes,