@erclx/canon 4.2.1 → 4.4.0

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

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

package/claude/skills/claude-orchestrate/SKILL.md

@@ -241,3 +241,42 @@ workers running a server take a port apiece without being told to, since a
 stack derives it from the worktree it runs in through `scripts/worktree-port.sh`.
 Read that value rather than assigning one, and set `WORKTREE_PORT_OFFSET` by
 hand only when two worktrees derive the same offset.
+
+### The review fallback
+
+Two conditions move the review itself out of this session rather than binding the
+track count. One is a diff too large for this session to hold. The other is three
+or more open pull requests awaiting a first pass. Either one makes review the
+bottleneck every track is waiting on, and both answer the same way: dispatch the
+narrow re-review and keep the first pass here.
+
+Three is the operator's number, set by hand on 2026-08-31 and marked as such so a
+measurement replaces it rather than argues with it. It is calibrated against a
+session that ran five workers across two waves and reviewed five pull requests in
+one stretch, several of them twice, where a sixth track was declined on judgment
+and on nothing else. What counts toward it is a pull request awaiting a first
+pass rather than every open one, since a branch already closed out and waiting on
+a merge costs this session nothing and counting it would fire the switch on a
+queue that is clear.
+
+Only the narrow re-review dispatches. A first pass reads across branches, and the
+findings that pay for its cost are the ones no single pull request shows: two
+branches regenerating one binary asset for the same count, three writing one
+context entry, a merge order making one branch's figure true only after another
+lands. A re-review asks whether the prior findings landed and whether the fix
+regressed anything, which is bounded to a delta and carries none of that reading,
+so it is the half that leaves cleanly.
+
+What it dispatches has no role skill yet. `claude-worker` and `claude-planner`
+each state what their session may not do and no third body states a reviewer's,
+so a dispatched re-review would hold its obligations in whatever launch string
+this session types. That is the defect those two skills were written to close, so
+write the third after the first trial rather than before it, since nothing has
+ever dispatched a reviewer and a body written now encodes a shape nobody has
+driven. Until it exists, say in the launch itself that the pass is bounded to the
+delta and that the cross-branch reading stays here.
+
+Nothing counts the pull requests. This is prose this session applies to itself,
+on the same standing as the poll's own start condition, so a wave past three
+reviewed one at a time is a rule that went unread rather than a check that
+failed.

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator dispatch runbook
-description: The collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
+description: The plan-answer gate, the collision check before a self-dispatch, the file-set disjointness gate, the branch and model the launch names, the planning and handback dispatch shapes, and the loop's stopping condition
 ---
 
 Run this at loop step 4, for a `## Run now` row whose plan is verified, in place of handing the worktree to a human. The disjointness gate below is where that row's file set is tested against every track in flight.
@@ -11,6 +11,25 @@ Resolve `<slug>` from `<plan>`, the row's plan file, the way `claude-worktree` S
 
 This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and a slug mismatch no longer fails the run downstream on its own, since `claude-autoship` now takes `<plan>` directly rather than resolving it from the worker's own branch. The check above is what has to catch a wrong candidate now.
 
+## Check the plan waits on nobody
+
+Run `canon tasks plan-answers <plan> --json` and read `launchable` off the record.
+
+- `launchable: true`: the plan answers itself, so proceed to the branch check.
+- `launchable: false`: the row is not dispatchable. Report every entry in `open`, each carrying the question label and the reason its suggestion gave for needing a person, and hand the row to the human-launch line below. Never fill the slot on the operator's behalf, which is the one move the plan standard forbids outright.
+- `reason: archived`: the row's plan sits in `.claude/plans/archive/` and describes work that already shipped. Repoint the row at a live plan rather than dispatching, since `claude-autoship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
+- The command refuses for any other reason, or the record carries no `launchable` key: treat the row as unverified rather than clear, name what could not be read, and fall back to the human. A gate that reads nothing and proceeds is the gate not running.
+
+Branch on `launchable` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero and so read a held row as a clear one.
+
+This gate runs ahead of the two collision checks because it is the cheapest reading of the three, needing no roster and no ref, and because it is the only one asking about the row itself rather than about what else is in flight. A row nobody can launch does not need testing against the tracks already out.
+
+It also reads the plan rather than a cell describing one, which is the input the gate below it does not have. The disjointness gate compares the sets a dispatcher wrote into the constraints and the Touches column, so a cell omitting a file clears a check the tree would fail. That happened on 2026-08-31, when two rows were cleared against each other with one constraints block leaving out the context entry both were about to write, and what caught it was a worker sending a message rather than any check.
+
+A blank `- Answer:` is not an unanswered question. `${CLAUDE_SKILL_DIR}/../../standards/plan.md` fixes an empty slot as accepting the `- Suggested:` line above it, which is what makes a plan decision-ready in one pass. The narrow case this reads is `- Suggested: needs your call, <why>` over an empty slot, the form that same standard writes where the answer turns on preference rather than on a technical default. A gate reading every blank slot as open would refuse every plan in the folder.
+
+What it prevents is a halt nobody is watching for. `claude-worker` instructs a session to stop on a question written as needing the operator's call, correctly and by its own body, so a dispatch that never reads the plan lands a worker in a wait for a person who does not know it is waiting. The worker's halt is not the defect, and the dispatch that made it necessary is.
+
 ## Check the branch is unclaimed
 
 Run `canon sessions list --branch <type>/<slug> --json` and read `claimed` off the record.
@@ -43,7 +62,7 @@ The finding names which row contributed the containing path, and a bare-folder c
 
 Disjointness is necessary and not sufficient, so hold a candidate whose sets do not touch when a stated reason serializes it, and write the reason on the hold. One row creating a skill and another auditing that catalog and counting it write nothing in common, measured 2026-08-27, and dispatching both still leaves the audit counting a denominator that moves underneath it. Nothing verifies that a reason was written, so the rule holds only while the dispatcher applies it.
 
-What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session. No file here carries a number and this runbook does not either.
+What binds past that is review attention rather than a count, and `## Parallelism` in the skill body states it along with the cap an operator can set for a session. The one number this skill carries is the review fallback's count of three in `## Parallelism`, which moves a review rather than binding a track, and this runbook carries none.
 
 ## Pick the model
 
@@ -186,12 +205,16 @@ resolved off the row the way the build shape resolves one off a plan.
 reads `planner-` for the reason the worker's reads `worker-`, which is that it
 marks the role of the session it names rather than the one that launched it.
 
-Neither check above binds this shape. The branch check has no candidate to read,
-and the disjointness gate has nothing to compare, since a planner writes one file
-no track in flight can hold. What a planning dispatch owes instead is the
-reverse reading, because the plan it produces carries a constraint per track in
-flight and a row planned during a wave is planned against a tree that wave is
-changing. `claude-planner` states that read as a command over open pull
+None of the three checks above binds this shape. The branch check has no
+candidate to read, and the disjointness gate has nothing to compare, since a
+planner writes one file no track in flight can hold. The plan-answer gate
+reaches no plan at all, because the planner is dispatched to write the file a
+build would later read, so running it here would refuse every planning dispatch
+over a plan nobody has written yet.
+
+What a planning dispatch owes instead is the reverse reading, because the plan
+it produces carries a constraint per track in flight and a row planned during a
+wave is planned against a tree that wave is changing. `claude-planner` states that read as a command over open pull
 requests, which is why the brief carries no branch list for it.
 
 One row per dispatch. A session reused across a batch pays the context load once
@@ -202,7 +225,9 @@ session where the saving is worth it and say what the cap was.
 
 ## Fall back to the human
 
-Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.
+Hand the row to the human-launch line in step 4 instead of dispatching when any of these hold, and name which one: the plan still waits on the operator, the plan-answer read could not be taken, the collision check refused, the row's file set overlaps a track already out, or a stated reason holds the row behind one.
+
+The first of those five is the one that reaches a person rather than the board. A row held for a collision or for a serialize reason waits on the wave clearing, where a row held on its plan waits on an answer only the operator can give, so hand that one over with the question label and its stated reason attached rather than as a name and a refusal.
 
 ## Stop the loop
 

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -66,6 +66,12 @@ The five review headings the script matches are written by `claude-pr-review` an
 
 The state reaches every stalled dispatch, since one threshold governs the heading and the dispatch alike and a pass carrying anything posts the open heading. A minors-only pass therefore reports here on the same terms as a blocking one, which widens the state from what it caught while the two were split. It stays a heading test rather than a count test, so nothing here pins the summary line, which is a second string this script does not own.
 
+### The count behind the review fallback
+
+The report is also where the count in `## Parallelism` is legible. That threshold trips on open pull requests awaiting a first pass, which is what `OPENED` and a pull request with no prior pass name here and what `SEEN` excludes, so read the count off these lines rather than off `gh pr list`, which counts a branch closed out and waiting on a merge the same as one nobody has read. It is a separate condition from the poll-start fallback above, which decides when this loop runs rather than where a review runs.
+
+The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. Measured on `#1299` on 2026-08-31, where a pass written against `5653721` landed stamped `a5ceb40` and the delta it skipped was a real fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
+
 ## The watch beside it
 
 `${CLAUDE_SKILL_DIR}/scripts/watch.sh` is a long-running loop rather than a scheduled prompt. It reads the open pull request list and the session roster together every sixty seconds and prints one line per new pull request, per worker whose status changed, and per worker that dropped out of the roster. Start it in the background and read what it emits. It writes nothing.

package/claude/skills/repo-metadata/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: repo-metadata
+description: Why an About text nobody re-derives drifts from the README it summarizes, and why writing it stays a second, explicit step
+---
+
+# Repo metadata requirement
+
+## Gap
+
+Without this skill, a repository's GitHub About description, homepage, and topics are set once by hand and never checked again. Nothing in either skill corpus reads or writes them, so a README rewrite carries no signal back to the three fields a stranger reads before the README, and they drift silently. That already happened here: the About text disagreed with the README's own opening line, and nobody noticed until someone read both side by side.
+
+A session that fixes this by hand skips the gate a repeatable proposal would have given it. It reads the README once, writes a description from memory, and never records what it compared against or gives anyone else a chance to see the diff before it goes out. The write is also public and immediate: `gh repo edit` changes what every visitor to the repository page sees, with no draft state and no second confirmation from GitHub itself.
+
+## Must
+
+- Compute the proposal from the tree alone, through `canon repo metadata propose`, and report the diff against the remote before any write is discussed
+- Route the choice of which fields to write through the structured question surface, since which field to accept is the operator's preference to decide
+- Run `canon repo metadata apply` only in a turn separate from the one that ran propose, carrying only the fields the operator answered in this conversation
+
+## Must not
+
+- Call apply in the same invocation that ran propose, whatever the operator's request already names
+- Write a field the operator has not answered in this conversation, even when the CLI's own proposal suggested a value for it
+- Read an absent field in the proposal as a suggestion to clear what the remote already carries
+- Edit `README.md` or any repository setting other than description, homepage, and topics
+- Fire from a request with no repository-metadata content, since a skill invoked on a vague signal risks presenting a write path the operator never asked for
+
+## Guards
+
+- No `gh` remote resolves. Stop, naming the refusal `canon repo metadata propose` reports, since a proposal with nothing to compare against is a suggestion nobody asked for.
+- `canon repo metadata propose` or `apply` does not resolve on an older install. Report that rather than proceeding, since the fix without the verb reintroduces the hand-written write this skill exists to gate.
+
+## Out of scope
+
+- Editing the README's own content, which is a request against that file rather than against repository metadata
+- Repository settings outside description, homepage, and topics, such as visibility or branch protection, which carry a different blast radius and no local source to propose from
+- Any repeat run outside a target project's own tree, since the proposal is computed from that tree's README and manifest rather than from this toolkit's shape

package/claude/skills/repo-metadata/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: repo-metadata
+description: Proposes a GitHub About description, homepage, and topic set computed from the README's opening line and package.json, reports the difference against what the repository's remote already carries, and stops without writing. A later invocation, carrying the operator's answered fields, writes the change through gh repo edit. Use when asked to "propose repo metadata", "check the github description", "does our github about text match the readme", "sync github topics", "update the repo homepage", or "apply the repo metadata answers". Do NOT use to edit README.md itself, or to change a repository setting other than description, homepage, or topics.
+---
+
+# Repo metadata
+
+Reads what `canon repo metadata propose` computes locally and reports it against the remote. Writing is a separate step: `canon repo metadata apply` never runs in the same invocation that ran propose, whatever the operator answers in the same breath. The gate is the two invocations, not a prompt inside one.
+
+## Guards
+
+- Report it rather than proceeding silently when `canon repo metadata propose` or `canon repo metadata apply` does not resolve. Both ship with the CLI, so a project on an older install meets a missing subcommand rather than a refusal.
+- The propose read refuses when the repository has no remote `gh` can read. Report that refusal verbatim and stop. A proposal with nothing to compare against is a suggestion nobody asked for.
+- Never call apply in the same turn that ran propose, even when the operator's request already names the fields to write. Surface the proposal, get the answer, then run apply as its own step.
+- Never write a field the operator did not confirm in this conversation. A field the proposal computed and the operator has not answered stays unwritten, whatever the CLI's own suggestion for it was.
+- A field absent from the proposal has no local source and is never a suggestion to clear what the remote already carries. Report it as unchanged, not as a removal.
+
+## Propose
+
+1. Run `canon repo metadata propose --json`.
+2. Read `diff` and `repo` from the record. `repo` is the `--repo` value the later apply step must carry. An empty `diff` means the remote already matches what this run computed: report that and stop, since there is nothing to answer.
+3. For each field `diff` carries, put the change to the operator through the structured question surface: which of the differing fields to write. Rank accepting the proposed value first for a field whose current value is stale or wrong, and give the reject option the cost of leaving the remote as it stands. Never pre-select an answer for the operator.
+4. Report the fields the proposal left absent as unchanged, naming that neither the README nor `package.json` carried a source for them.
+5. Stop. Do not run apply here even when the operator answers immediately, since answering is not yet an apply invocation.
+
+## Apply
+
+1. Confirm every field about to be written was answered by the operator in this conversation. Carry no field forward unanswered.
+2. Run `canon repo metadata apply`, always passing `--repo <owner/name>` from the propose record's `repo` field, plus the flags for the answered fields: `--description <text>`, `--homepage <url>`, `--topics <comma-separated list>`. `--topics` is the full desired set, and the command reads the current set itself to compute what to add and remove. The command refuses rather than writing when `--repo` does not match what `--root` resolves to, so never omit it and never guess it from anything but the propose record's `repo` field.
+3. Report the written state from the JSON record.
+
+## Output
+
+Propose:
+
+```plaintext
+📋 Repo metadata proposal
+description: "<current>" → "<proposed>"
+homepage: unchanged, no local source
+topics: +<added>, -<removed>
+
+Answer which fields to write, then ask again to apply.
+```
+
+Apply:
+
+```plaintext
+✅ Applied: <fields written>
+```
+
+Omit a line from the proposal block for a field `diff` did not carry.

package/docs/agents/commands.md

@@ -9,68 +9,70 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 
 ## Project-level
 
-| Command                     | Purpose                                                                                                                                                               |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                                                                                                     |
-| `canon sync [path]`         | Sync all installed domains in a target project                                                                                                                        |
-| `canon sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                                                 |
-| `canon sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                                                    |
-| `canon sandbox reset`       | Reset sandbox to baseline                                                                                                                                             |
-| `canon sandbox clean`       | Wipe the sandbox                                                                                                                                                      |
-| `canon sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                                                 |
-| `canon sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                                                        |
-| `canon indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                                                                                                  |
-| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                              |
-| `canon design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                     |
-| `canon slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                          |
-| `canon slides list`         | List the available slide layouts (`--json` for the catalog)                                                                                                           |
-| `canon feedback`            | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`                                                               |
-| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                 |
-| `canon tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                                                   |
-| `canon tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                              |
-| `canon tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                             |
-| `canon tasks validate`      | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                           |
-| `canon intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                 |
-| `canon intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                                        |
-| `canon teach list`          | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                                                    |
-| `canon teach open`          | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                       |
-| `canon teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                 |
-| `canon teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                   |
-| `canon records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                          |
-| `canon records migrate`     | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                        |
-| `canon records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
-| `canon records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
-| `canon records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
-| `canon migrate rename`      | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
-| `canon sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
-| `canon worktrees list`      | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
-| `canon comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
-| `canon context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
-| `canon markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |
-| `canon claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                        |
-| `canon standards audit`     | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                 |
-| `canon claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                             |
-| `canon claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                            |
-| `canon claude skills rank`  | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                       |
-| `canon claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                                        |
-| `canon gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                               |
-| `canon gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
-| `canon gov restated`        | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)  |
-| `canon gov citations`       | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`)                                                       |
-| `canon secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
-| `canon deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
-| `canon labels audit`        | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
-| `canon labels scan`         | Fail a pull request whose title or body carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--json`)          |
-| `canon autoship classify`   | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
-| `canon pr key-changes`      | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
-| `canon census [path]`       | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
-| `canon audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                                |
-| `canon audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |
-| `canon gate run`            | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
-| `canon inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
-| `canon capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
-| `canon serve [dir]`         | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
-| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
+| Command                       | Purpose                                                                                                                                                               |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon init [path]`           | Bootstrap a project with selected toolkit domains                                                                                                                     |
+| `canon sync [path]`           | Sync all installed domains in a target project                                                                                                                        |
+| `canon sync --check`          | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                                                 |
+| `canon sandbox [cat:cmd]`     | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                                                    |
+| `canon sandbox reset`         | Reset sandbox to baseline                                                                                                                                             |
+| `canon sandbox clean`         | Wipe the sandbox                                                                                                                                                      |
+| `canon sandbox check`         | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                                                 |
+| `canon sandbox coverage`      | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                                                        |
+| `canon indexes regen`         | Regenerate `index.md` files from sibling frontmatter                                                                                                                  |
+| `canon docs [topic]`          | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                              |
+| `canon design render`         | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                     |
+| `canon slides render`         | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                          |
+| `canon slides list`           | List the available slide layouts (`--json` for the catalog)                                                                                                           |
+| `canon feedback`              | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`                                                               |
+| `canon transcripts <url>`     | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                 |
+| `canon tasks archive`         | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                                                   |
+| `canon tasks pull-request`    | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                              |
+| `canon tasks outcome`         | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                             |
+| `canon tasks validate`        | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                           |
+| `canon intake list`           | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                 |
+| `canon intake answer`         | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                                        |
+| `canon teach list`            | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                                                    |
+| `canon teach open`            | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                       |
+| `canon teach resource`        | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                 |
+| `canon teach glossary`        | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                   |
+| `canon records validate`      | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                          |
+| `canon records migrate`       | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                        |
+| `canon records size`          | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
+| `canon records push`          | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                                            |
+| `canon records pull`          | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
+| `canon migrate rename`        | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
+| `canon sessions list`         | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
+| `canon worktrees list`        | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
+| `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
+| `canon context audit`         | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift                             |
+| `canon markdown audit`        | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                                                |
+| `canon claude skills audit`   | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                        |
+| `canon standards audit`       | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                 |
+| `canon claude skills drift`   | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                             |
+| `canon claude skills reach`   | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                            |
+| `canon claude skills rank`    | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                       |
+| `canon claude routing`        | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                                        |
+| `canon gov test-order`        | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                               |
+| `canon gov superseded`        | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
+| `canon gov restated`          | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)  |
+| `canon gov citations`         | Resolve every path a rule cites and every internal frontmatter glob, failing on one reaching nothing (`--json`)                                                       |
+| `canon secrets scan`          | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
+| `canon deps audit`            | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
+| `canon labels audit`          | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
+| `canon labels scan`           | Fail a pull request whose title or body carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--json`)          |
+| `canon autoship classify`     | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
+| `canon pr key-changes`        | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
+| `canon repo metadata propose` | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)      |
+| `canon repo metadata apply`   | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`) |
+| `canon census [path]`         | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
+| `canon audits run`            | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)                                |
+| `canon audits list`           | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                                             |
+| `canon gate run`              | Run every stage that guards a branch here, scoping shell, types, and tests to the changed set (`--all`, `--no-write`, `--nested`, `--json`)                           |
+| `canon inventory [subject]`   | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)                                  |
+| `canon capture [source]`      | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                                                 |
+| `canon serve [dir]`           | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)                               |
+| `canon upgrade`               | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                                                 |
 
 `canon serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
 

package/docs/agents/sandbox.md

@@ -68,4 +68,6 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.
+`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+
+Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.

package/docs/agents/tasks.md

@@ -63,6 +63,41 @@ A `live` location with an empty `citedBy` is the sweep to run. One whose `citedB
 canon tasks plan-citations v28.1-trigger-escalation --json | jq -r '.location'
 ```
 
+## Plan answers
+
+`canon tasks plan-answers <plan>` answers whether a plan is launchable, which is whether it still waits on the operator for a call only they can make. It reports and never writes.
+
+Name the plan by its path or by its slug, which resolve to the same file:
+
+```bash
+canon tasks plan-answers dispatch-answer-gate
+canon tasks plan-answers .claude/plans/feature-dispatch-answer-gate.md
+canon tasks plan-answers ../plans/feature-dispatch-answer-gate.md
+```
+
+A relative path resolves against the project root first and against `.claude/tasks/` second. The third form above is what a board row writes, since its link is relative to the board, and a dispatcher copying the reference out of the row it is dispatching has that spelling to hand rather than either of the other two. A refusal names every base it looked under.
+
+`canon tasks plan-citations` reads a task's `Plan:` line against those same two bases in the opposite order, and tests that the target lands under the live plans folder, which this verb does not. Both answer the same file for every spelling a board writes. Liveness is a separate refusal here: a plan resolving inside `.claude/plans/archive/` returns `archived` rather than a launchable reading, since it answers every question and describes work that already shipped.
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `launchable` and `open`, the questions still waiting, each with the `label` that names it and the `why` its suggestion gave for needing a person. Exit codes: `0` launchable, `1` refused with `no-plan`, `archived`, or `bad-input`, `2` waiting on the operator.
+
+A blank `- Answer:` is not a waiting question. The plan standard fixes an empty slot as accepting the `- Suggested:` line above it, so the one shape this reads is `- Suggested: needs your call, <why>` over an empty slot, which is what that standard writes where the answer turns on preference rather than on a technical default. A verb reading every blank slot as open would report every plan in the folder.
+
+The question block is read through the same parser `canon tasks validate` runs, so the gate and the conformance check cannot drift into disagreeing about what a question is. A question carrying no suggestion at all is that check's finding rather than this one's, and it goes unread here.
+
+Branch on `launchable` rather than on the exit code, for the reason the section above states: a shell profile wrapping `canon` in a function can take a later command's status and mask every non-zero exit, which reads a waiting plan as a launchable one.
+
+The orchestrator dispatch runbook calls this before it checks the branch or the file sets, so a row whose plan still needs a person is handed back rather than launched into a worker that halts on the same question.
+
+```bash
+canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'
+```
+
 ## Pull request
 
 `canon tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.

package/docs/operating-model.md

@@ -70,7 +70,7 @@ and no later session recovers that vantage.
 One feature travels this path end to end.
 
 1. The next feature is planned with `claude-feature`, writing a plan to `.claude/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-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 from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
-2. Orchestrator checks the branch is unclaimed and the plan's file set is disjoint from every 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 `claude-worktree` and `claude-autoship` when the check refuses, the sets overlap, or a stated reason serializes 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.
+2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks the plan's file set is disjoint from every 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 `claude-worktree` and `claude-autoship` when the plan still waits on an answer only the operator can give, the check refuses, the sets overlap, or a stated reason serializes 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 reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `canon sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, 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. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
 5. Orchestrator closes the review out with `claude-pr-review` 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.
@@ -220,6 +220,14 @@ above it, and stop adding once you can no longer review every output properly.
 Serialize a track sharing a wiring seam with another, and serialize one whose
 sets are disjoint when a stated reason still puts it behind another.
 
+Past that, review moves rather than the track count, on either of two conditions:
+a diff too large for the controlling session to hold, or three or more open pull
+requests awaiting a first pass. Three is set by hand rather
+than measured, so a later measurement replaces it. Only the narrow re-review
+leaves: a first pass reads across branches and a re-review bounded to a delta
+carries none of that reading. Nothing counts the pull requests, so the switch
+holds only while the session applies it to itself.
+
 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

package/package.json

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