@erclx/canon 5.38.0 → 5.40.0

package/docs/target/scenarios.md

@@ -6,7 +6,7 @@ category: Agent surface
 
 # Target scenarios
 
-Three worked setups, each from the first session through ongoing maintenance. [Target projects](projects.md) carries the lifecycle they walk.
+Three worked setups from the first session through maintenance. [Target projects](projects.md) carries the lifecycle they walk.
 
 ## Markdown-heavy project
 
@@ -15,9 +15,7 @@ cd <your-project>
 claude
 ```
 
-In the session, invoke `canon:target-setup`. The skill detects no framework and resolves tooling to `base` and governance to `base`. The preview marks both stacks as fallbacks, since neither came from a match, then the chain runs `canon init`.
-
-Ongoing: run `canon sync --check .` to see what has drifted, then merge seed drift by hand against the toolkit copy, or run `canon sync .` for a catch-all refresh.
+Invoke `canon:target-setup`. It detects no framework, resolves tooling and governance to `base`, marks both as fallbacks in the preview, and runs `canon init`. Later, run `canon sync --check .` to see drift, merge seed drift by hand, or run `canon sync .` for a catch-all refresh.
 
 ## Web application
 
@@ -26,19 +24,15 @@ bun create vite my-app && cd my-app
 claude
 ```
 
-Invoke `canon:target-setup`. The skill reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `node`, proposes `react` and the other rules its manifest matches as extras, and runs `canon init` with the resolved flags.
-
-Ongoing maintenance:
+Invoke `canon:target-setup`. It reads `package.json` and the Vite config, resolves tooling to `vite-react` and governance to `node`, proposes the rules the manifest matches, and runs `canon init`.
 
-- What has drifted: `canon sync --check .`
-- Seed drift: merge by hand against the toolkit copy
-- Catch-all sync: `canon sync .`
-- Governance rule refresh only: `canon gov sync .`
-- Layer a new rule on top, for example `shadcn` after adopting shadcn: `canon gov install node --add shadcn .`
+- Check drift with `canon sync --check .` and sync everything with `canon sync .`
+- Refresh governance alone with `canon gov sync .`
+- Layer a rule on top, such as `canon gov install node --add shadcn .`
 
 ## Monorepo with multiple language roots
 
-The repo root owns the shared `base` layer, and each language lives in its own subfolder.
+The repo root owns the shared `base` layer, and each language lives in a subfolder.
 
 ```bash
 canon init --stack node --add react .
@@ -46,10 +40,6 @@ canon tooling sync vite-react ./frontend --skip base --write
 canon tooling sync python ./backend --skip base --write
 ```
 
-`--skip base` drops the `base` layer from each subtree sync, so husky, oxfmt, commitlint, and CI stay single at the repo root. The one exception is base's verify runner, `scripts/verify.ts` and `scripts/verify.json`, which every subtree still receives so it can verify on its own. Without it, every subtree re-drops husky, and since git honors only one `core.hooksPath` the extra hook dirs silently break. Each subtree still gets its own framework configs (oxlint, vitest, tsconfig, vite), and its own stack reference reads through `canon tooling reference <stack>`.
-
-A sync whose target sits below the git root knows it is writing into a subfolder:
+`--skip base` keeps husky, oxfmt, commitlint, and CI at the root. Every subtree still receives `scripts/verify.ts` and `scripts/verify.json`, and its own framework configs.
 
-- It withholds `.github/`, since GitHub reads workflows only at the repository root, and names each withheld file. Run the subtree from a job in the root workflow instead, with `working-directory` set to the subtree path the sync prints, such as `working-directory: frontend`.
-- It installs no dependencies and adds no scripts to a subtree without a `package.json`. It names what it skipped and ends on `run 'bun init' in <path>, then sync again`.
-- The subtree carries no `check` script, since that lives in the root's base layer, so run `bun scripts/verify.ts` there. It skips the format phase a subtree does not declare, since the root runs them, and still fails on a missing lint, typecheck, or test script, the phases its stack's `scripts/verify.json` requires.
+A sync into a subfolder withholds `.github/`, so run the subtree from the root workflow with `working-directory` set to the path the sync prints. It installs nothing into a subtree without a `package.json` and ends on `run 'bun init' in <path>, then sync again`. Run `bun scripts/verify.ts` in the subtree, since the `check` script lives at the root.

package/docs/target/sync.md

@@ -6,90 +6,49 @@ category: Agent surface
 
 # Target sync
 
-When the toolkit updates, a target project pulls changes per domain. There is one catch-all and several targeted entry points. A project scaffolded before a layout move runs the one-time moves in [target migrations](migrations.md) first.
+A target pulls toolkit changes per domain, through one catch-all and several targeted entry points. A project scaffolded before a layout move runs [target migrations](migrations.md) first. See [install and sync](../agents/install-and-sync.md) for what each verb writes.
 
 ## Check first
 
-`canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.
+`canon sync --check <path>` reports drift without writing, split by cause. `canon:target-check` groups the same state by domain and repairs nothing.
 
-`canon:target-check` is the same reading grouped by domain rather than by cause, run from inside the project. It reports the toolkit version, the `canon/` folder, governance rules, tooling, and seeds from the verbs that own each comparison, and reports the Claude harness as unchecked because no verb reads it. It repairs nothing, so it is what to run before deciding rather than instead of deciding.
+The report opens with the binary version against the newest published one, and a version behind means run `canon upgrade` first.
 
-### The binary first
+| Cause             | Meaning                                     | Action                                   |
+| ----------------- | ------------------------------------------- | ---------------------------------------- |
+| `stale`           | Matches what the toolkit installed          | Take the update                          |
+| `customized`      | Carries local edits                         | Decide by hand against the toolkit       |
+| `stranded`        | Sits where an older toolkit installed it    | Relocate by hand                         |
+| `retired`         | A rule the toolkit no longer ships          | `canon gov sync` deletes it              |
+| `renamed`         | A rule shipped under a new name             | `canon gov sync` installs the new one    |
+| `seeds`           | A seed the project edited                   | Merge by hand                            |
+| `unmovedSurfaces` | A surface still at its `.claude/` spelling  | `canon migrate surface-roots`            |
+| `newRules`        | A rule your stack ships that you lack       | `canon gov install <stack> --add <rule>` |
+| `reverse`         | A folder at a path the toolkit once shipped | Read its verdict below                   |
 
-The report opens by naming the binary running it. The installed version reads against the newest published one, and a version behind that points you at `canon upgrade`, since every section under it is a reading taken by whichever toolkit you happen to have. An unreachable registry reports unknown with its reason rather than failing, so `--exit-code` still gates on the drift the check measured locally and an offline machine stays green.
+Attribution reads `canon/config/config.json`, falling back to `.claude/canon/config.json`. Without a stamp the report reads the toolkit's git history, which needs a clone. `newRules` installs nothing, and a target on a retired stack such as `react` or `astro` runs `canon gov detect . --stack node --json` for the rules its manifests propose.
 
-### Then the causes
+`reverse` marks each folder:
 
-A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision made by hand against the toolkit copy. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs. A `retired` rule is one under `.claude/rules/canon/` the toolkit no longer ships, and the next `canon gov sync` deletes it. A `renamed` rule is one the toolkit now ships under a new name, and the next sync installs the new name and deletes the old file.
+- `dropped` is the toolkit's copy, with the publishing commit
+- `unattributed` means the toolkit shipped the path, but the content matches no published version
+- `project` means it only shares a retired name
 
-That attribution comes from `canon/config/config.json`, which every install and sync now writes, falling back to `.claude/canon/config.json` for a target stamped before that move. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
-
-Each domain holds its own toolkit commit, so syncing governance today does not move the revision tooling measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
-
-A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
-
-Further causes sit outside the per-domain scan, each naming something that walk cannot see. A seed the project edited is reported under `seeds` and merged by hand, since no sync command touches a seed. A file a newer seed folder replaced is reported under `superseded`, such as `.claude/TASKS.md` against the `.canon/tasks/` that now ships, and nothing moves it because the content is the project's own. A domain sitting at the root layout with nothing under `.claude/` is reported under `unmigrated`, and no command moves it either. The project moves the content itself. A surface still at its `.claude/` spelling with nothing under `canon/`, such as `.claude/REQUIREMENTS.md`, is reported under `unmovedSurfaces`, since rules glob the `canon/` spelling alone, and `canon migrate surface-roots` moves it. <!-- canon-keep-surface-root -->
-
-`unmigrated` currently names no domain, since snippets is the one the toolkit ever installed at the project root, and it retired outright. A leftover `.claude/snippets/` reports under `reverse` below instead.
-
-### Rules you never received
-
-A sync refreshes the files you already hold and adds none, so your rule set is frozen at the date you installed governance while every file in it reports as current. `newRules` names a rule you could receive that your tree does not hold, which is the one section that reads your absence rather than your contents. `canon gov sync` reports the same rules per file, marked `missing`, so you see them either way you check.
-
-Take a clean section as reporting rather than as delivering. Nothing here installs, and it counts toward nothing, so pick the rules up with `canon gov install <stack>` or take one with `--add <rule>`. That separation is deliberate: adopting a rule changes what your project is governed by, which is a choice a sync has no business making for you.
-
-Since `canon gov install` records the stack you gave it, the list is read by comparing that stack's current rules against what you hold right now, with no date involved at all. That is what lets it name a rule the toolkit shipped before you last synced: nothing here depends on when you installed. A target stamped before this recording shipped falls back to the older read below.
-
-The fallback filters to what your stack can receive, read off the rule folders you already carry plus the folders holding a base rule. A rule under `lang/` or `ui/` belongs to some stacks and not others, so an unfiltered list would name rules you can never install. A target with neither a recorded stack nor a governance anchor reports nothing at all, since there is no date to measure against either.
-
-A target recorded on a stack the toolkit retired, such as `react` or `astro`, reads as having no recorded stack and takes this fallback, so it keeps receiving updates to the rules it holds and is offered new rules only in the rule folders it already carries. Run `canon gov detect . --stack node --json` to see which rules its manifests propose beyond those.
-
-In the fallback, an empty section is not proof either way when the toolkit running the check is not a full git clone. The read needs history to reach your anchor, and an install from the registry ships none, so the section goes quiet rather than saying it could not measure. Run the check from a clone before reading a clean result as a complete one. The stack-based read above is untouched by this, since it consults no history.
-
-This also closes the case where a rule arrives citing a sibling you do not have. A sync refreshing a rule can land a version pointing at a file it never installs, and the section names the missing sibling rather than the broken citation, which is enough to act on.
-
-### What the toolkit stopped shipping
-
-The last cause runs backwards. Every one above starts from what the toolkit ships and asks whether the target matches, so a folder the toolkit dropped appears in none of them. `reverse` walks the target instead and reports a folder sitting at a top-level path the toolkit once shipped and has since deleted.
-
-Each entry carries a verdict, since a dropped folder and one the project wrote are the same bytes at the same path.
-
-- `dropped` names the commit that published the content
-- `unattributed` means the toolkit shipped that path and the content matches no version it published
-- `project` means the folder only shares a retired name
-
-A `.claude/snippets/` folder an older toolkit installed is the case this walk exists for, since the toolkit retired the domain and deleted its `snippets/` root. It reports as `dropped`, and [target migrations](migrations.md) says what to do with it.
-
-Nothing acts on any of them, and the verdict is what makes the list safe to read.
-
-Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code, and neither do superseded artifacts, seed drift, tooling, or anything the reverse walk reports, since each names content the project is expected to edit or place itself. An unmigrated domain does count, because running the relocation closes it.
-
-Tooling reports under a section of its own, and `measured` there says whether the target ever recorded a chain. One that never ran a tooling sync reports unmeasured rather than clean, which is what separates tooling nobody has looked at from tooling that is current. A workspace root records nothing either way, since each package resolves its own chain.
-
-Reconcile the configs with `canon tooling diff <stack> <path>` to read which files differ, then run `canon tooling sync <stack> <path> --write` to apply them. The drift report counts categories and the diff names paths, which is the difference worth knowing before a golden config the project edited is replaced.
+Add `--json` for a machine-readable report and `--exit-code` to fail CI when a target falls behind. Project-authored files, superseded artifacts, seed drift, tooling, and `reverse` never count toward that code, and an unmigrated domain does.
 
 ## Catch-all
 
-`canon sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence.
-
-It never touches user-owned seed files. Governance rules in `.claude/rules/` and tooling configs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
+`canon sync <path>` runs every installed domain's sync and never touches user-owned seeds.
 
 ## Targeted
 
-- Claude seed docs such as `CLAUDE.md` and `canon/REQUIREMENTS.md`: merge by hand against the toolkit copy, section by section, keeping the project's customizations. A `stale` seed is safe to take whole.
-- Governance rules already installed: `canon gov sync <path>` diffs and applies, and never adds new rules. A rule your recorded stack lists reports as `missing` instead.
-- Tooling configs and seeds: `canon tooling <stack> <path>` overwrites golden configs and copies each seed once, leaving an existing file alone
-- Reference docs for a stack: `canon tooling reference <stack>` reads and never writes, so there is nothing to sync
-- Index regeneration after markdown edits: `canon indexes regen`
+- Seed docs such as `CLAUDE.md` and `canon/REQUIREMENTS.md`: merge by hand, keeping the project's customizations
+- Installed governance rules: `canon gov sync <path>`, which adds no new rules
+- Tooling configs and seeds: read differences with `canon tooling diff <stack> <path>`, then `canon tooling sync <stack> <path> --write`, which overwrites golden configs and copies each seed once
+- Index regeneration: `canon indexes regen`
 
-Use a targeted entry point when only one surface moved upstream. Use the catch-all when the toolkit lands a bundled release.
-
-## Verify a sync
-
-Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../../canon/context/sandbox/index.md) for the scenario catalog and routing patterns.
+Try a scenario from [sandbox](../../canon/context/development/sandbox.md) before syncing a real project.
 
 ## Running sync from an agent session
 
-`canon sync .` applies every installed domain sync, then offers to commit the result and open a pull request. That last step needs a terminal. Under `CANON_NON_INTERACTIVE=1`, which is how an agent runs it, the domain syncs still apply and the git workflow is refused: the command reports the branch and commit it would have created, writes nothing to git, and exits 0. Review the working tree and commit it yourself, or rerun interactively to reach the commit and pull request options.
-
-Sync also refuses a target whose working tree is dirty, so commit or stash before running it. `canon sync --check .` has neither restriction, since it writes nothing.
+`canon sync .` applies every domain sync, then offers a commit and pull request that needs a terminal. Under `CANON_NON_INTERACTIVE=1` the syncs apply, the git step is refused, and the command exits 0. Commit yourself. Sync refuses a dirty working tree, and `canon sync --check .` does not.

package/docs/workflow/ai-workflow.md

@@ -6,13 +6,11 @@ category: Agent surface
 
 # AI workflow reference
 
-A concise reference for when to reach for which tool, organized by what you're trying to do.
-
-> **Mental model:** Claude Code for everything: planning, implementation, review, docs, git, and release.
+Which tool to reach for, by what you are trying to do.
 
 ## Documents
 
-Project docs split across three roots at the project root. What the project authors and commits lives in `canon/`, what Claude Code reads lives in `.claude/`, and every gitignored session record lives in `.canon/`, which a single ignore entry covers.
+Project docs split across three roots. `canon/` holds what the project authors and commits, `.claude/` holds what Claude Code reads, and `.canon/` holds every gitignored session record.
 
 ```plaintext
 canon/
@@ -24,96 +22,52 @@ canon/
 └── rules/           ← path-scoped governance rules, written by canon gov install
 
 .canon/
-├── tasks/           ← one file per task with a generated index.md, local scratch
-├── plans/           ← one plan per feature, archived inside itself once it ships
-└── tmp/             ← deletable scratch, safe to remove without loss
+├── tasks/           ← one file per task with a generated index.md
+├── plans/           ← one plan per feature, archived once it ships
+└── tmp/             ← deletable scratch
 ```
 
-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 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` and `canon/REQUIREMENTS.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.
+A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. See [target migrations](../target/migrations.md).
 
-Run `canon init` to seed the `.claude/` directory, a root `CLAUDE.md` file, and `.claude/rules/` in one pass. `canon init` chains claude init and governance install. Claude Code auto-loads every file in `.claude/rules/` at session start, applying always-on rules unconditionally and path-scoped rules to files matching their `paths:` glob.
+Context loads always (`CLAUDE.md` and `canon/REQUIREMENTS.md`), by path (`.claude/rules/` with a `paths:` glob), or on demand (`canon/context/`, found through its `index.md`). Run `canon init` to seed `.claude/`, `CLAUDE.md`, and the rules.
 
 ## Scenarios
 
 ### Bootstrap a new project
 
-See [target projects](../target/projects.md) for the scaffold decision, core domains and skips, and the full lifecycle across scaffold, add-a-domain-later, and upstream sync.
+See [target projects](../target/projects.md).
 
 ### New feature
 
-One session works for most features. Prefer splitting across two sessions only when the feature is large enough that you want a cold, independent reviewer on the diff. Plan and implement in session 1, then review and ship in session 2.
-
-#### Session 1
-
-Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
-
-- When the input is a pile of findings rather than one feature, invoke `canon:plan-intake` first. It files the dump into `.canon/intake/<nn>-<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled.
-- When the backlog has grown past what anyone rereads, invoke `canon:backlog-triage`. It files one item per backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, and once `canon:plan-intake-answer` has taken your answers, a second run applies the approved verdicts through the task verbs.
-- When the current state is unmeasured and more than one approach is live, invoke `canon:plan-groundwork` first. It opens a track folder under `.canon/groundwork/<nn>-<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled.
-
-Then plan and build:
-
-- Invoke `canon:plan-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
-- Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
-- For UI changes, invoke `canon:ui-checklist` to write what a reviewer has to look at and name any behavior shipping without a test
-  End the session once the feature works and tests pass. Invoke `canon:context-fold` to capture any decisions made during implementation before closing.
-
-The routing test is whether the repository can answer an item today. A session grepping handles the yes, and a groundwork track handles the no.
-
-A groundwork track may run experiments to settle a question, writing a fixture it reads itself under `.canon/tmp/runs/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
-
-A spike starts against a sample, bounded on input size, duration, and spend, and scales up once the sample shows the method works. Nothing checks this, so it holds while a session reads the standard.
+Plan and build in session 1, then review and ship in a fresh session 2 when you want a cold reviewer on the diff.
 
-What a spike leaves behind splits on whether a later reader needs the file to check a claim. Bulk input, such as a large fixture, is re-runnable and cited by nothing, so the scratch path above is the right lifetime for it. Everything a reader opens to verify a result lives inside the track in one of three folders: `evidence/` for a recording or a render, `scripts/` for the arm scripts, and `clones/` for checkouts and copies of outside material a claim rests on. The scratch tree holds only what can be deleted without loss, which none of those is.
+- For a pile of findings, invoke `canon:plan-intake`, and for a grown backlog `canon:backlog-triage`
+- For an unmeasured state with live approaches, invoke `canon:plan-groundwork`
+- Invoke `canon:plan-feature`, implement, and run the `CLAUDE.md` commands until they pass
+- For UI changes, invoke `canon:ui-checklist`
+- Invoke `canon:context-fold` before closing
 
-#### Session 2
-
-Start a fresh Claude Code session. The diff is sufficient context for ship.
-
-- Invoke `canon:git-ship` to run the project's verify commands, sync docs, commit by concern, rename branch, and open PR
+Session 2 invokes `canon:git-ship` to verify, sync docs, commit by concern, and open the pull request.
 
 ### Parallel features
 
-When features are independent, run them in parallel, one worktree and one session per feature. See [parallel features](parallel-features.md) for the loop in each worktree, the orchestrated flow, and the records and task board every session shares.
+Run independent features in parallel, one worktree and one session each. See [parallel features](parallel-features.md).
 
 ### Autonomous ship
 
-For features on a mature stack, chain the post-plan pipeline in one session. Approve the plan, invoke `canon:auto-ship`, and the skill runs implement → verify → ship sequentially.
-
-- Use when the plan is tight and the stack has real verify commands and test coverage
-- Autoship stops on: verify failure after one fix attempt, or hook failure
-- A produced UI checklist does not stop it. The checklist rides to the draft pull request's evidence comment, and the closing block names how many visual boxes are still unchecked and who owes them
-- Every stop leaves recoverable state. Fix and resume with `/git-ship`
-- Skip autoship for auth, migrations, security-sensitive changes, or work where the plan itself is uncertain
-
-### UI polish
-
-Verify the change manually in the browser. Invoke `canon:ui-checklist` if you need a written list of what to look at. For the fix itself, describe the change in Claude Code directly.
+On a mature stack, approve the plan and invoke `canon:auto-ship` to implement, verify, and ship in one session.
 
-### Quick fix
-
-- Verify failure or isolated bug → continue in Claude Code (it has the implementation context)
-- Design or planning conflict → escalate to a new Claude chat session with the relevant plan context
-- Fast file edit (a task file, config, renaming) → Claude Code directly, no chat needed
+- It stops on a verify failure after one fix attempt, or on a hook failure, and you resume with `/git-ship`
+- Skip it for auth, migrations, security-sensitive changes, or an uncertain plan
 
 ### Review
 
-Review runs on the pull request. An independent session invokes `canon:review-pr` once `canon:git-ship` has opened it, and the worker answers what it posts with `canon:review-address`.
+An independent session invokes `canon:review-pr` once the pull request is open, and the worker answers with `canon:review-address`. A verify failure goes to the session that built it, a design conflict to a new chat session with the plan, and a review finding to the worker.
 
 ### UI-heavy project
 
-Before the first feature session on a UI-heavy project, pick a design tier. The tier determines seed shape, installed MCP servers, and installed plugin skills. See [visual design workflow](visual-design-workflow.md) for the framework and decision guide.
+Pick a design tier before the first feature session. See [visual design workflow](visual-design-workflow.md).
 
 ## Skills
 
-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
-
-```plaintext
-verify fails  → Session 1 (it has implementation context)
-design fails  → new Claude chat session (planning problem)
-review finds  → Session 2 (fix alongside review, before ship)
-```
+The [skill map](skill-map.md) and [skill map on request](skill-map-on-request.md) give every plugin skill one row saying when to reach for it.

package/docs/workflow/operating-model.md

@@ -6,18 +6,10 @@ category: Workflow
 
 # Operating model
 
-A way to build fast and reliably across parallel Claude Code sessions without a
-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 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).
+One warm session holds the cross-feature call and reviews. Cold worker sessions build, and the human launches workers and merges. For merge order see [Parallel features](parallel-features.md), and for worktree gotchas see [Claude Code and git worktrees](../../wiki/claude/worktrees.md).
 
 ## Four roles
 
-The split is by vantage, not by capability. All four are Claude Code sessions.
-
 | Role         | Session                               | Owns                                                 | Does not                           |
 | ------------ | ------------------------------------- | ---------------------------------------------------- | ---------------------------------- |
 | Orchestrator | One warm, long-lived session          | The cross-feature call, review dispatch, merge order | Review in place, edit, merge PRs   |
@@ -25,204 +17,58 @@ The split is by vantage, not by capability. All four are Claude Code sessions.
 | Planner      | One session per row, warm or cold     | Measure the row against the tree, write one plan     | Enter a worktree, write the board  |
 | Worker       | One cold worktree session per feature | Implement, self-check, open PR, answer the reviewer  | Write the shared board, merge      |
 
-Each role is asserted explicitly rather than inferred. The orchestrator loads
-`role-orchestrator` at the start of its session, a worker loads `role-worker`,
-which `auto-ship` invokes at Step 0 so a dispatched build and a
-hand-launched one reach it on the same path, and a planner loads
-`role-planner` and a reviewer `role-reviewer` from the launch that dispatches
-it. All four are framing and boundaries rather than logic.
-
-The planner is the one role the orchestrator also performs. Per-row planning
-runs warm inside the orchestrator's own session or cold in a dispatched one, and
-the boundary between them is the cross-feature call: which rows conflict, what
-merges before what, and whether a row should run at all stay with the
-orchestrator, because a session reading the board sees blockers and file sets
-and can write a confident merge order off a partial picture. The per-row
-measurement is free to go cold, since a cold planner reads the tree rather than
-trusting what the task file claims.
-
-A dispatched planner owes two messages: the plan's path as the file lands, with
-what the task file got wrong beside it, and a block before that block becomes an
-interactive prompt. The plan file is its only write. A stale count, a moved line,
-or a path that no longer resolves is reported rather than repaired, since the
-task file and the board stay the orchestrator's to write.
-
-A worker that halts on a plan question it may not answer, or argues back against
-an instruction the tree contradicts, is working correctly. It writes neither
-`.canon/tasks/priority.md`, the backlog, nor a task file for work it turns up,
-and hands the row to the orchestrator. `role-worker` gives the reason for each.
-
-The orchestrator's cell reads every tracked file rather than every feature, and
-it offers no exception for a small one. A correction found while orchestrating
-goes to the task that owns the surface, or folds into the next task touching it,
-because a session that writes a change cannot review it independently afterwards
-and no later session recovers that vantage.
-
-Filing that row stops at the defect and the surface it was seen on. How far the
-defect reaches and what causes it belong to whoever plans the row, so it arrives
-carrying neither a count nor an asserted mechanism, and the seat that found it
-says as much in a plain sentence rather than supplying either. What separates the
-two is what a measurement decides: the blocker re-test, the branch check, and
-the conflict check against every track in flight all decide whether a row can
-start, and only a count of the defect's extent decides how big it is.
+- The orchestrator loads `role-orchestrator`, a worker loads `role-worker` through `auto-ship` Step 0, and a planner and a reviewer load theirs from the launch that dispatches them
+- The orchestrator decides which rows conflict, what merges first, and whether a row runs at all. Per-row planning can go cold.
+- A dispatched planner writes only the plan, and reports what the task file got wrong rather than repairing it
+- A worker that halts on a plan question, or argues back against an instruction the tree contradicts, is working correctly
+- The orchestrator edits no tracked file. File a row with the defect and the surface, with no count or cause.
 
 ## The loop
 
-One feature travels this path end to end.
-
-1. The next feature is planned with `plan-feature`, writing a plan to `.canon/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a dependency on another row, and dispatches a planner under `role-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight by composing the live session roster with open pull requests. A bare branch or worktree is not evidence on its own, since this repository leaves both behind after a squash merge.
-2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks no conflict holds the plan behind a track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `session-worktree` and `auto-ship` when the plan still waits on an answer only the operator can give, the branch check refuses, or a conflict holds the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
-3. Orchestrator dispatches a reviewer under `role-reviewer` for every pull request but a release one, which posts `review-pr` findings, and `review-ui` drives any visual checklist beside it.
-4. The reviewer tells the session holding that branch to run `review-address` once the pass posted a finding at any severity, resolving it with `canon sessions list --branch` and falling back to the orchestrator when none is live. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first on a file it writes, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `review-pr` states that threshold and the heading follows it, so an open heading is itself the signal to send.
-5. The worker asks that reviewer for the re-review directly, and the reviewer closes the review out with `review-pr` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. A pass finding nothing where a close-out already stands rewrites that comment to cover what it read rather than posting a second one, so the thread carries one live verdict. Repeat from step 4 until a pass closes the review. Each reviewer then runs `canon pr lift`, which lifts the draft mark once every gate it reads is clear.
-6. The human reads the result and merges. After each merge, the orchestrator tells any trailing worker whose files the merged diff touches to run `review-address`, which rebases whether or not the review left anything open.
+1. Plan the next feature with `plan-feature` into `.canon/plans/`. Run it warm when the row turns on a contract other rows consume, and dispatch a planner otherwise.
+2. Check the plan waits on nobody, the branch is unclaimed, and no track in flight conflicts. Dispatch a background worker with `claude --bg`, naming the branch and the model.
+3. The worker enters its own worktree, builds, self-checks, opens a PR, and stops there.
+4. Dispatch a reviewer under `role-reviewer` for every PR but a release one. It posts `review-pr` findings, and `review-ui` drives any visual checklist.
+5. The reviewer tells the session holding the branch to run `review-address`, found with `canon sessions list --branch`, once a pass posts a finding at any severity.
+6. The worker addresses the findings, rebases onto `origin/main` if a sibling landed on its files, pushes, and asks that reviewer for a re-review of the added commits.
+7. A pass posts `## Review` while anything is open and `## Review closed` when nothing is. The reviewer then runs `canon pr lift`.
+8. The human merges. The orchestrator tells any trailing worker whose files the merge touched to run `review-address`, which rebases.
 
-There is no loop construct here. Each worker is a single build that halts at the
-PR. The merge stays a manual human gate. Reliability comes from the plan being
-complete enough that the cold session does not come back with questions, and
-from merging promptly so the next PR does not rot against a moving main.
+Each worker halts at the PR, and the merge stays a human gate.
 
 ## The review layer
 
-The worker's chain carries no review step. The session that wrote the code is
-structurally blind to its own misreadings, because the same misreading wrote
-both the code and any review of it, so the first review a change gets is a
-dispatched reviewer's.
-
-- Worker gate, inside `auto-ship`: the session that wrote the code. Its job is "did I build the plan and does it pass?" The verify commands and the test order read decide whether the PR opens, and the draft mark holds the merge.
-- Reviewer pass, via `review-pr`: a fresh session holding one pull request, briefed with the cross-feature facts the orchestrator's wave pass found (a sibling PR in flight, a shared file, the merge order). Its job is "is this right and does it fit?" It can question the plan itself. This is the merge gate.
-
-The human read at merge is the final gate. No layer repeats another.
+The first review a change gets is a dispatched reviewer's. The worker's gate inside `auto-ship` decides whether the PR opens, and the draft mark holds the merge. The reviewer pass is the merge gate.
 
-The orchestrator's pass also reads the pull request body against itself, which is
-a vantage the worker never has. This repository squash-merges, so the body
-becomes the commit message and the record on the trunk once the branch is gone.
-`canon pr key-changes` compares the paths the body's Key changes claims against
-its own changed-file list, and a claim the diff does not carry is a finding on
-the body rather than on a file. See
-[Key changes bijection](../agents/key-changes.md).
+`canon pr key-changes` flags a Key changes claim the diff does not carry. See `canon pr key-changes --help`.
 
 ## The review channel
 
-Findings travel on the PR. `review-pr` posts them there.
-`review-address` reads them back, fixes each, replies or resolves the
-threads, and pushes a follow-up. `review-pr` then runs again, reading only
-what the follow-up added.
-
-Both halves of that loop key on a commit rather than on the pull request object,
-which trails the branch ref by up to a minute after a push and says nothing
-about the trail. `canon pr head` resolves the tip the review pass scopes its
-delta against, and `canon pr checks` reports the runs belonging to that tip, so a
-follow-up push cannot be read as green off the predecessor's completed run. See
-[Head-sensitive pull request reads](../agents/pr-reads.md).
-
-Three messages travel from the worker to its controller, each stated with its
-reason in `role-worker`: the pull request as it opens, carrying any row the
-build turned up, the end of each address-review pass with the new CI state, and
-a block before it becomes an interactive prompt. Nothing is sent on progress. An
-open pull request is what starts the controller's review poll, with a dispatch
-still silent after thirty minutes kept as a fallback.
-
-What the session channel carries is the handback instruction and the worker's
-reply to it, which is a notification layer over a record that stays on the PR. A
-reply that changes an outcome, such as a worker naming the plan question that
-already declined a finding, still belongs back on the PR, since the session
-holding it ends and the thread is what a later reader opens.
-
-Two rules put it there rather than leaving that to whoever remembers. A finding
-the worker declines carries the fact that settled it in the same reply body that
-already maps every finding, and a pass accepting that argument states the
-withdrawal or the regrade with what produced it instead of dropping the finding
-from its next comment.
-
-A reply that corrects the reviewing session rather than a finding stays off the
-thread. Which session holds which branch, or what gate a worker's edits pass
-through, changes no finding on a pull request that closes, so it goes to the task
-owning that surface. Nothing checks either rule, so both hold while a session
-applies them.
-
-A finding answered without a commit leaves the head where the first pass read it,
-which a gitignored record and a finding accepted as recorded both produce. The
-close-out is still owed there, since the newest heading is what tells an operator
-whether the branch is blocked, so the pass reads the worker's response rather than
-a delta and names its body from that response instead of from a tree that did not
-change.
-
-A branch `main` moved under during review, conflicting or not, is the worker's
-problem to close. `review-address` rebases onto `origin/main` between the fixes
-and the push, so one force-push carries both and the reviewer reads one delta.
-The staleness test sits ahead of the no-findings guard, so a branch whose review
-closed clean and then went stale still rebases when the skill is invoked. The
-re-read costs a full pass rather than a delta, since the prior reviewed commit no
-longer reaches the head, and `review-pr` detects that itself.
-
-The heading carries the state rather than the pass number. A pass carrying
-anything owed takes `## Review` and a pass carrying nothing takes
-`## Review closed`, so a thread can be scanned for what still owes work without
-opening a comment. One threshold governs the heading and the dispatch alike, and
-`review-pr` is where it is stated, so every other surface cites that skill
-rather than restating the grades.
-
-The merge decision comes off the counts on the summary line, since an open
-heading now covers a minor as well as a critical. One thing the pass posts sits
-outside those counts and inside the threshold anyway. It reads the description's
-Testing section against what the repository can drive, and asks about a box left
-unchecked for a person where a harness already covers the run. The question
-takes no severity, because whether a human is required is a judgment the author
-may hold a reason for, and it still opens the heading and sends the dispatch,
-because the author is the only party who can answer it.
-
-A minor the worker declines goes to the findings of the task the
-branch closes, since a thread does not survive the merge. Feedback kept on the
-PR outlives both sessions, so no human copies review between them.
+Findings travel on the PR. `review-pr` posts them, `review-address` fixes them and pushes, and `review-pr` runs again on the added commits.
+
+- `canon pr head` resolves the tip a pass scopes against, and `canon pr checks` reports the runs for it. See `canon pr head --help`.
+- A worker messages its controller when the PR opens with any row it turned up, when each address pass ends with the CI state, and before a block becomes a prompt. It sends nothing on progress.
+- A declined finding carries the fact that settled it in its reply body, and a minor goes to the findings of the task the branch closes
+- A finding answered without a commit still owes a close-out, read from the worker's response
+- A branch `main` moved under is the worker's to rebase, in the same force-push as the fixes
 
 ## Feature sizing
 
-The unit is fixed by the ceremony: one feature is one plan, one worktree, one
-PR, one review sitting. Split a feature down when a backend contract and its
-consumer both change, landing the contract first so no UI is built on a shaky
-contract. Merge a change up into an ordinary edit when it is a few lines with no
-new contract, skipping the plan and worktree entirely. The smell test: if the
-whole change does not fit in your head at review time it was too big, and if the
-coordination costs more than the change it was too small.
+One feature is one plan, one worktree, one PR, one review sitting. Split a feature when a backend contract and its consumer both change, landing the contract first. Make a few-line change an ordinary edit.
 
 ## Where work comes from
 
-Two tiers hold work at different altitudes.
-
-- Tasks (`.canon/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by the `task-board` skill. `priority.md` beside them carries execution order, and `backlog.md` carries what nobody is scheduling, both shaped by the same skill.
-- Edits: a few lines, done immediately with no ceremony.
-
-Nothing above these sequences work into versions. Scope is stated in
-`canon/REQUIREMENTS.md` and reaches the board as discrete tasks, so why one
-task runs before its neighbors is on its row and why one group of work runs
-before another is carried nowhere at all.
+Tasks in `.canon/tasks/` hold the active few, one file each. `priority.md` carries execution order and `backlog.md` carries what nobody schedules.
 
 ## Parallelism
 
-Review attention binds, and no number caps worker tracks, so stop adding once you cannot review every output. A row waits only on a conflict a merge cannot settle, which the `role-orchestrator` dispatch runbook states once. A shared file is not one: both rows build, and the branch merging second resolves any conflict in its own session after the first lands, since no practice source serializes on a file. [Fowler](https://martinfowler.com/articles/branching-patterns.html) has whoever integrates second check health "even if it's a clean merge", and [DORA](https://dora.dev/capabilities/trunk-based-development/) keeps branches to hours with no integration phase.
-
-Review splits by vantage. A reviewer under `role-reviewer` takes every pull
-request's read but a release one's and trades each round with the worker. The
-orchestrator keeps one cross-branch pass per wave over file sets and merge order.
-
-Inbound turns cost the controlling session as well, so weigh the spend before
-widening. A message from one of your other sessions arrives as a new turn
-carrying the whole accumulated context, and a recurring poll bills that window
-again on its own interval, which means a wide wave spends against the
-orchestrator rather than against any worker. `crossSessionInbound` is the one
-control over that and stays unset here, since `hold` and `refuse` both break the
-worker handback and `accept` bounds nothing.
+Stop adding worker tracks once you cannot review every output. A row waits only on a conflict a merge cannot settle, as the `role-orchestrator` runbook states. A shared file is not one, and the branch merging second resolves it. See [Fowler](https://martinfowler.com/articles/branching-patterns.html) and [DORA](https://dora.dev/capabilities/trunk-based-development/).
 
-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 [Parallel features](parallel-features.md) for merge order and
-[Claude Code and git worktrees](../../wiki/claude/worktrees.md) for port collisions.
+- The orchestrator keeps one cross-branch pass per wave
+- Checks, dev servers, and screenshots run in many worktrees at once, each on its own port, while singleton resources serialize
 
 ## Related
 
-- [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
+- [Claude Code and git worktrees](../../wiki/claude/worktrees.md) for the mechanism and port collisions
+- [Claude Code subagents](../../wiki/claude/subagents.md) for in-session parallelism, and [blocking subagents](../../wiki/claude/permissions.md#blocking-subagents) for the `permissions.deny` rule
+- [Skill map](skill-map.md) for how the skills in the loop are categorized