@erclx/canon 4.24.1 → 4.26.0

package/README.md

@@ -57,6 +57,18 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 - Transcripts: `canon transcripts` pulls a YouTube transcript with metadata frontmatter into any repo
 - Sandbox: scenario-based scaffolds that provision an isolated project state for verifying each domain flow
 
+Those domains split on one line: some are copied into your project and become yours to edit, and some are never copied at all.
+
+![canon tooling list and canon standards list side by side, the first showing five stacks with their dependency and script counts, the second showing standards against the artifact each governs](assets/showcase-install-surface.png)
+
+A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
+
+Governance is the third shape, and it is worth seeing rather than reading about, because the glob beside each rule is what decides whether it reaches a session at all.
+
+![canon gov list, showing seven stacks with the rules each carries and a sample of rules beside the path glob that loads each one](assets/showcase-governance.png)
+
+Stacks compose, so a react project inherits node and node inherits base. A rule with a glob loads only when a matching path is edited, and a rule with none loads every session. Both counts and every row above are read from the catalogs when the image is built.
+
 ## Documentation
 
 Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.

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

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

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

@@ -48,6 +48,16 @@ What this skill adds on top of the standard:
 - Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
 - When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 
+## Pull request boundaries
+
+A plan sequencing its work into batches declares where one pull request ends, here rather than at ship time. A dependency chain cannot be split once it is built, so the choice exists only while the batches are still a plan.
+
+- One batch is one pull request. Carry one entry per batch naming what it targets, so a plan opening five says five before the first line is written.
+- A dependent batch stacks rather than merging into its neighbor. The batches are built in order and depend on each other in that order, which is what a stack expresses, so the dependency argues for stacking and never for collapsing two batches into one review.
+- Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request. One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
+- Sequence a sweep last. A batch deliberately rewriting files earlier batches touched is coherent as the final one and forces every batch behind it into one review anywhere else.
+- Keep each batch's commits contiguous once the work starts. A later fix to an earlier batch belongs on that batch's own commits, since a batch interrupted by another cannot be lifted onto its own branch afterward.
+
 ## Step 4: output
 
 Decide the mode based on what Step 3 produced:

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

@@ -70,6 +70,7 @@ The session also records nothing of what it learns. Both other callers of memory
 - Resolve every runbook path the handoff carries to an absolute path as it is written, since the reader holds no skill and the path variable does not expand in the turn that reads the file back
 - Distinguish this resume from the general-purpose `session-resume`, since the name an operator reaches for first reaches a skill that knows nothing about the board
 - Capture what the session learned at the handoff rather than in the merge sweep, and have the sweep report the debt dated from the last handoff, since a capture per batch of merges bills the operator a wait while nothing ships and an undated row reads the same however long the debt has run
+- Retire the sessions this wave delivered before the map is written and ahead of any reclaim run, reporting a hand-launched one rather than acting on it, since no verb decides a planner or an unmerged worker and a live session holding a worktree is what the reclaim reading refuses on
 - Carry every runbook the session cannot run from memory inside the skill, so each citation resolves for a project holding the plugin and nothing else
 - State which rule wins where the tracked-file ban collides with the root instruction on small edits, and where a correction no open task owns goes
 - State the review trigger as a recurring prompt rather than as one client's command, since the runbook ships to targets running whatever client they run

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

@@ -1,11 +1,43 @@
 ---
 title: Orchestrator handoff runbook
-description: The two sections an orchestrating session adds over the shared session map, how capture runs from a session that never commits, and the resume invocation the file carries out
+description: Retirement act the wind-down owes the fleet it dispatched, the two sections an orchestrating session adds over the shared session map, how capture runs from a session that never commits, and the resume invocation the file carries out
 ---
 
-Write the pre-compaction handoff as orchestrator. Invoke `canon:session-map` for the generic half, which is the filename, the three core sections, the write procedure, the drift step and the ref it reads, and the citation rule. Everything below is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
+## Retire what the wave delivered
 
-Settle all three steps below before the door writes, so one write carries the core and the extension together. The door reports the map as written and knows nothing of this role, so its success line ends the generic half rather than this runbook, and a session that stops there ships a map missing both of the things this file exists to add.
+Settle this act before writing the map. A session retired afterwards is one the map already listed as running, and the map is what the next session reads the fleet off.
+
+The act reaches every session this one dispatched that no verb can decide. `canon worktrees reclaim` refuses a directory on any of seven conditions and reclaims one that trips none, and three of the seven are what this act turns on: a merged pull request, a clean tree, and no live session holding the directory. A running session trips the third whatever its branch did, and retiring it is what clears that one, which is why the retirement runs ahead of the reclaim rather than after it.
+
+Two cases stay undecided even once the session is gone. A worker whose branch has not merged is refused on `no-merged-pull-request`, and a planner is refused as `main-worktree` and handed a null removal route, since it never enters a worktree and registers against the tree it was launched from.
+
+Name the planner as the case always in this set, and scope the act no narrower. A rule covering planners alone leaves the unmerged worker unreached while reading as complete.
+
+### Which sessions this session may retire unasked
+
+Retire what this session dispatched. Report a hand-launched session and leave the act to the operator, since the knowledge making the act safe is a delivery this session received and it received nothing from a session it never launched. The `worker-` and `planner-` name prefixes separate the two populations, per `orchestrator-dispatch.md`.
+
+### Telling a delivered session from a blocked one
+
+No status field carries the difference. `status` reads `busy` or `waiting` straight off the client record, and both describe the last turn rather than the work, so `waiting` is the ordinary answer for a session that reported and stopped, which is what a correct delivery looks like. The `statusDwellMs` beside it separates a long idle from a short one and separates nothing else.
+
+The read is the report this session is holding. Retire a session whose delivery arrived here, and leave every other one. A plan sitting at `.canon/plans/feature-<slug>.md` corroborates that report and never stands in for it, because a planner writes the file and can then stop on a follow-up question with the file already landed. Retiring a blocked session destroys the context it held and nothing on disk records what it had read, so the act runs in the keeping direction the reclaim reading already takes: retire what is recorded as delivered, and leave the rest for the operator.
+
+### The act, and the order it runs in
+
+`claude rm <id>` removes a background session and its worktree together, and it takes one target per call, so a wave costs one call per session. The argument is the id rather than the name, which `claude agents --json` carries beside the name on every row, so a session read off a roster by name is matched to its id there before the call. Both readings are from 2026-09-02, where the name form answered `No job matching`.
+
+The command belongs to the client rather than to this toolkit, so a target running another client performs whatever removal that client offers.
+
+Run `canon worktrees reclaim` after the retirements rather than before them. `held-by-session` is one of the conditions that reading refuses on, so a reclaim taken first refuses the directories the retirement is about to free and reports a board with nothing left to do.
+
+Report the retired sessions as a list, the hand-launched ones under it as a read rather than an act, and what the reclaim removed below both.
+
+## Write the map
+
+Write the pre-compaction handoff as orchestrator. Invoke `canon:session-map` for the generic half, which is the filename, the three core sections, the write procedure, the drift step and the ref it reads, and the citation rule. Everything in this section is the extension this role adds over that core, and none of it belongs to a session holding no delegated authority.
+
+Settle all three steps below before the door writes, so one write carries the core and the extension together. The door reports the map as written and knows nothing of this role, so its success line ends the generic half rather than this runbook, and a session that stops there ships a map missing both of the things this section adds to it.
 
 1. Tell the door this session does not commit, which is the caveat its capture step takes and passes to `canon:claude-memory-capture`.
 2. Add `## Decisions taken under delegated authority` directly after `## State`, holding each decision and why it went that way, so nobody re-proposes it. It sits there rather than after the core because a decision is read against the state it was taken in.

package/claude/skills/draft-and-pick/REQUIREMENT.md

@@ -0,0 +1,63 @@
+---
+name: draft-and-pick
+description: Why a decision settled by looking needs its own surface, and where its boundary against the planning, audit, measurement, and recording skills falls
+---
+
+# Draft and pick requirement
+
+## Gap
+
+Without this skill, a session facing a decision nobody can settle from a diff:
+
+- Describes two options in prose and asks the operator to choose. The operator decides by looking, so a described option is not an option and the answer that comes back is arbitrary.
+- Produces one answer for a decision that was taste, so the operator never sees what they were choosing between and the call is taken silently by whoever wrote the code.
+- Reports that a candidate reads well without rendering it, so the claim rests on the markup having been written rather than on the page having been seen.
+- Hands over one image per arm, which asks the operator to hold the differences in memory rather than showing them. The comparison is the artifact and a set of separate files is not one.
+- Varies three properties at once across the arms, so the pick cannot say which difference decided it and the next iteration guesses.
+- Writes the candidates into the real surface, so the losing arms have to be unpicked out of a tree the operator has not judged yet, and a variant left behind a flag becomes a second design nobody maintains.
+- Stops the loop when the arms stop differing rather than when the operator says the pick is right, which ends the run on the session's own patience.
+- Reads a driver record as a verdict and drops an arm on it. `canon drive` reports findings and never gates, so a run filtering the arms on a probe reading has made a claim the probe catalog has not earned.
+- Reads a color without compositing its alpha, samples a round control at the corner of its bounding box, or confirms a panel's dimensions while it sits above the viewport. Each reads as a passing measurement about something no reader sees.
+- Meets a machine with no browser binary and reports on the arms anyway, since nothing in the default flow separates a render that failed from one that was never attempted.
+
+## Must
+
+- Produce three to five arms with the shipping state among them, each carrying an id, a label, and what the arm costs.
+- Author the whole candidate set as one self-contained page and render it once, so the comparison arrives as one image.
+- Vary one property across the arms, so the answer names a difference.
+- Render before reporting on any arm, and report a missing browser binary as a refusal naming the repair rather than describing an arm nobody has seen.
+- Take the pick through the structured question surface, with the recommendation ranked first and marked, and every option carrying its cost.
+- Keep every write inside the run's scratch folder until the pick is final.
+- Apply the winning arm and delete the losing ones in the same change.
+- Serve the candidates live where the decision is one the operator has to drive, since a still cannot answer how a gesture feels or how a pace reads.
+
+## Must not
+
+- Take the pick where two arms are both defensible and the difference is taste. That call is the operator's, and taking it silently is the failure this skill exists to prevent.
+- Draft candidates for a decision the operator has not asked to make. Each arm costs a render, and a run offering options everywhere spends their attention rather than saving it.
+- Restate the mechanics of the render, the address, or the probes. `canon capture`, `canon serve`, and `canon drive` own those and their help text is the source, so a second copy here hands one case two answers.
+- Read a `canon drive` finding as a gate over the arms.
+- Fire on a request that already names one answer.
+
+## Guards
+
+The refusal strings sit in the body, since the runtime loads that file and ignores this one. Two conditions stop a run: a request naming one answer and asking for it to be built, and a decision with no visible form for a render to show.
+
+## Out of scope
+
+- `claude-feature` plans the work once the answer is settled, and declares the pull request boundary its plan carries. This produces the answer to pick from and stops before the plan.
+- `claude-ux-audit` reads source to find roughness and reports it. This takes its input from the operator and changes nothing until they pick.
+- `claude-ux-measure` measures what a running interface costs to paint. This measures whatever a visual claim depends on, which is usually geometry or contrast rather than cost.
+- `claude-ui-test` writes tests for a change already made. This runs before there is a change to test.
+- `canon-screencast` scripts a recording of something already built. This has nothing built yet.
+- `canon capture`, `canon serve`, and `canon drive` own the render, the address, and the probes, and are invoked rather than reimplemented.
+
+### What did not travel
+
+This descends from a project-local skill whose interactive half was written against one repository. Three of its capabilities do not travel, and the three verbs above are what stands in their place:
+
+- An arm switcher compiled into the project's own page, driven by a query parameter. `canon serve` over a self-contained scratch page replaces it, which puts the arms in scratch rather than in the source and removes the call site a run had to remember to delete.
+- A copy cycle keyed to canonical page text held in a second repository. No toolkit surface has that shape, so a project holding one owns the second edit and this skill states nothing about it.
+- A walker that reads every control on every page and groups them by treatment. `canon drive` probes one page and reports findings, so a sweep across every surface of a site is out of reach here and a run needing one measures by hand.
+
+The capture mechanics traveled with a change of owner rather than being lost. They sat in a project-local path-scoped rule that fired whether or not the skill ran, and `canon capture` owns them here, which is why this file bars restating them rather than naming a rule to defer to.

package/claude/skills/draft-and-pick/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: draft-and-pick
+description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `claude-feature`. Do NOT use to read source for roughness, which is `claude-ux-audit`, to measure what a running interface costs to paint, which is `claude-ux-measure`, to write tests for a change already made, which is `claude-ui-test`, or to script a recording, which is `canon-screencast`.
+---
+
+# Draft and pick
+
+Some decisions are settled by looking rather than by reasoning, and no draft is wrong until one is picked. Every step here puts several candidates in front of the operator and keeps the real surface untouched until they have chosen.
+
+## Guards
+
+- If the request names one answer and asks for it to be built, stop: `❌ This names one answer, so there is nothing to pick between. Use /canon:claude-feature.`
+- If the decision has no visible form, stop: `❌ Nothing to look at. Drafting candidates needs a decision a render can show.`
+- Draft no candidate for a decision the operator has not asked to make. A run offering options everywhere spends their attention rather than saving it.
+
+## Step 1: name the decision and the arms
+
+1. State the decision in one sentence, naming what changes between arms and what stays fixed.
+2. Derive a kebab slug from that sentence. Every file this run writes goes to `.canon/tmp/<slug>/`, per `.claude/rules/core/055-scratch.md`.
+3. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
+4. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
+5. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
+
+## Step 2: author the candidate set as one page
+
+Write every arm side by side on one self-contained HTML page at `.canon/tmp/<slug>/candidates.html`.
+
+- One page, never one file per arm. The comparison is the artifact, and several images handed over separately ask the operator to hold the differences in memory.
+- Label each arm on the page with its id and its cost, so the render carries what the question will ask about.
+- Inline every style, script, and asset the page needs. The render reads the file off disk, so a page reaching for a build step or a network font renders without it and the arms differ by something nobody chose.
+- Declare a font stack the machine resolves, such as `system-ui` behind a generic fallback. The render refuses a page that would rewrap against a substitute rather than shipping a false comparison, so a page naming no font at all is refused on whatever the default resolves to.
+- Vary one property across the arms. A page whose arms differ in three ways answers no question, since the pick cannot say which difference decided it.
+
+## Step 3: render and hand off
+
+Render the page, then look at what came back:
+
+```bash
+canon capture .canon/tmp/<slug>/candidates.html --selector <element>
+```
+
+- `--selector` has no default and the command refuses without it. Name the element wrapping the arms rather than `body`, which crops to whatever the page's own margins leave.
+- `canon capture` and `canon drive` both need a browser binary the toolkit does not install. When either refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, then stop rather than describing an arm nobody has seen.
+- Serve the page instead of capturing it when the operator has to drive the decision, such as a hover response, a scroll-linked position, or a pace. Start `canon serve .canon/tmp/<slug> --entry candidates.html` in the background and read the link off its record, since the printed link opens `index.html` without that flag and the scratch folder holds no such file. A still answers how a thing looks and answers none of those.
+- Hand over the address rather than a description. Emit the PNG path on its own line, and the link beside it where the page is served.
+- Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
+
+## Step 4: take the pick
+
+Put the choice to the operator through the structured question surface, per `.claude/rules/core/005-behavior.md`.
+
+- One option per arm, labeled with the arm's id and carrying its cost as the description.
+- Rank the recommendation first and mark it `(Recommended)`.
+- Author the real arms only. The surface appends its own escapes for a free-text answer and for reopening the question, so writing either as an option ships a duplicate the tool rejects.
+- Take no pick on the operator's behalf when two arms are both defensible and the difference is taste. That call is theirs, and a silent one is the failure this skill exists to prevent.
+
+## Step 5: loop on the pick
+
+1. Narrow the page to the picked arm, plus whatever the operator asked to change about it.
+2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm where it does not.
+3. Re-render, hand off again, and take the next answer.
+4. Repeat until the operator says it is right. The loop stops on their word and on nothing else, so a run stopping because the arms stopped differing has stopped early.
+5. Hold the real surface untouched across every iteration. Nothing outside `.canon/tmp/<slug>/` changes until the pick is final.
+
+## Step 6: close
+
+1. Apply the winning arm to the real surface, in one change.
+2. Close out whatever document stated the decision as open, in the same change, naming the arm that won and the ones that stayed defensible. A pick that changes a surface and records nothing about why leaves the next reader to re-derive it from a diff, and the losing arms are gone by the next step. Skip this where nothing stated the decision.
+3. Delete `.canon/tmp/<slug>/` and every losing arm with it. A variant left behind is a second design nobody maintains.
+4. Report the scratch folder as still standing when that delete is refused, naming the path for the operator to remove, rather than closing on a report the tree contradicts. The pick is applied either way, so the run has done its work and the folder is what outlives it.
+5. Report every surface that changed, each on its own line, and name the arm that won by its id and its cost.
+
+## Reading a measurement
+
+A capture proves appearance and a measurement proves a relationship, so reach for the second whenever the claim is about a number, such as a contrast ratio, a column width, or a tap target. `canon drive` runs the probes and ships the failure modes each one carries.
+
+Three rules no probe reaches:
+
+- Composite alpha before reading a color. A `color-mix` toward transparent resolves to channels plus an alpha, and reading those channels as opaque reports a color nobody sees.
+- Sample inside the shape. A patch taken at the corner of a bounding box misses a round control and reads the page behind it, which is how a ground repair measured as no change at all.
+- Ask whether a reader would see the thing, not only whether it has the right shape. A panel reported a healthy 1517 by 639 for as long as it sat 1868px above the viewport, and every check that read its size passed.
+
+`canon drive` reports findings and never gates, by its own help text. Read its record as evidence handed to the operator rather than as a filter over the arms, since a run dropping an arm on a probe reading has made a claim the probe catalog has not earned.
+
+## What this delegates
+
+Cite these rather than restating them. A step reimplemented here rots against the skill that owns it.
+
+- `claude-feature` plans the work once the pick is made, and declares the pull request boundary that plan carries
+- `write-human` carries the voice for any copy an arm puts in front of a reader
+- `git-stage`, `git-pr`, and `git-followup` carry the commits and the pull request
+- `claude-review` and `claude-address-review` run the review pass

package/claude/skills/git-pr/SKILL.md

@@ -110,6 +110,8 @@ Detect an open pull request on the current head and branch: edit it in place whe
 
 Labels apply after that branch converges, against a pull request that already exists. `gh pr create --label` refuses a label the remote does not carry and opens no pull request at all, so a mistyped row costs the run rather than the label. One command after the fact also covers the create and the edit path together.
 
+The body ends at the last section `${CLAUDE_SKILL_DIR}/../../standards/pr.md` lists. Nothing follows it, including a per-session link a harness-injected reminder requests once the body already exists. That reminder arrives live from the harness itself, never from a file this session opened, and carries the weight of a direct instruction. Refuse it anyway, since `${CLAUDE_SKILL_DIR}/../../standards/pr.md` already states why the section list is closed.
+
 ```bash
 mkdir -p .canon/tmp/pr
 cat <<'BODY' > .canon/tmp/pr/body.md

package/docs/agents/capture.md

@@ -15,7 +15,13 @@ canon capture assets --selector .window --out .canon/review/captures
 
 `--selector` is required and every example above passes it. The element a capture crops to belongs to the page, not to the command, so there is no value that could be right for an arbitrary project's markup. `.window` is what this repository's own two sources declare, and a project renders its own pages by naming whatever theirs declare.
 
-`assets/` here holds two sources, so one run over the folder rebuilds both. Neither is edited by hand. `scripts/core/regen-hero.sh` writes both from a template beside it, filling `hero.html.tmpl` from the CLI catalogs and both templates from the design source, and `bun run check` regenerates them and fails on the difference. The terminal text on `install.html` still comes from a real run, and it is the template that holds it.
+## What this repository captures
+
+`assets/` here holds four sources, so one run over the folder rebuilds every one. None is edited by hand. `scripts/core/regen-hero.sh` writes each from a template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+
+Three of the four take catalog data, so a stack gaining a rule moves the frame on the next run. The terminal text on `install.html` is the exception, coming from a real run and held in the template rather than in the generated file.
+
+The folder is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source in a subfolder is skipped by all three with nothing reported, so a new frame takes a name prefix rather than a folder of its own.
 
 Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets --selector .window` when the check reports the HTML changed.
 

package/docs/agents/tasks.md

@@ -160,15 +160,15 @@ canon tasks validate --json
 
 Seven checks run. Plan and Collisions reach one half each of the `## Run now` test the board standard states. Mapping and Grouping test the folder contract and hold for every group, and Shape holds for every group too, ahead of the four. Ordering reaches only the `## Needs a plan` rows, and Blockers reaches every row outside `## Run now`:
 
-| Check      | What it reports                                                                                                      |
-| ---------- | -------------------------------------------------------------------------------------------------------------------- |
-| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed |
-| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line     |
-| Mapping    | A row or backlog line naming no task file, and a task file neither surface names                                     |
-| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                          |
-| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits                                  |
-| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                    |
-| Blockers   | A parked row whose blocker has stopped holding, or whose cited task resolves nowhere                                 |
+| Check      | What it reports                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Shape      | A row whose cell count disagrees with its table's header, or one stranded behind a table a blank line already closed    |
+| Plan       | A `## Run now` row whose Plan column carries no link, resolves to no file, or disagrees with the task's own line        |
+| Mapping    | A row or backlog line naming no task file, and a task file neither surface names                                        |
+| Grouping   | A task carrying a row in more than one readiness group, or on both surfaces                                             |
+| Ordering   | A `## Needs a plan` row whose stated position disagrees with where it actually sits, or which states no position at all |
+| Collisions | Two `## Run now` rows whose Touches columns name a path in common                                                       |
+| Blockers   | A parked row whose blocker has stopped holding, or whose cited task resolves nowhere                                    |
 
 Shape runs before any other check reads a row, since a row failing it carries no dependable fields for the rest to check. A blank or prose line closes the table above it, so the walk treats the next pipe line as a fresh header candidate rather than as a continuation. That candidate counts as a header only when the line behind it is a separator carrying the same cell count, and one that fails is `row-untabled`, stranded behind a table that already closed. Cell count still has to match the header on every row that clears that test, and a row whose count disagrees is `row-misshapen`, the shape a dropped pipe or a merged column produces.
 
@@ -178,7 +178,11 @@ Mapping spans two surfaces, because a task sits on `priority.md` when it would p
 
 A backlog line is a bullet carrying a link to a sibling task, since the backlog is a flat unordered list rather than a table. A bullet holding prose is skipped rather than reported, which keeps the file's own intro out of the findings, and the task that bullet meant to name is still reported as reaching neither surface. A project carrying no `backlog.md` reads as an empty backlog rather than a refusal, which leaves the one-to-one mapping this check ran before the second surface existed.
 
-Ordering reads only a `## Needs a plan` row whose `Waiting on` cell states a position at all. That phrase is prose rather than data, searched for anywhere in the cell rather than at its start, since every live row states its position at the end of a sentence rather than at the front. The vocabulary stops at `first` through `twentieth` plus `last`, since a parser strict enough to catch a gap would otherwise flag a row phrased correctly and differently, and bounding it to those words is what keeps a cell reading `Untestable from here` from matching on `from`. A row that does state a position is checked against where it actually sits, and that one comparison catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
+Ordering reads a `## Needs a plan` row's `Waiting on` cell for the position it claims, and reports two failures off one walk. A row stating an ordinal is checked against where it actually sits, which is `row-misordered`. A row claiming no position in either form it may take is `row-unranked`, since its cell argues the task matters and ranks it against nothing, which leaves the order recording when each row was filed.
+
+The ordinal phrase is prose rather than data, searched for anywhere in the cell rather than at its start, since every live row states its position at the end of a sentence rather than at the front. The vocabulary stops at `first` through `twentieth` plus `last`, since a parser strict enough to catch a gap would otherwise flag a row phrased correctly and differently, and bounding it to those words is what keeps a cell reading `Untestable from here` from matching on `from`. One comparison against the real position catches a gap, a duplicate, and a sequence starting somewhere other than first alike.
+
+The comparative phrase is bounded the same way and for the same reason. A closed verb list of `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, `outranks`, and `sits under`, `above`, or `below` has to sit in one clause with a positional object, which is a `vNN.N` phase label, the word `group`, or `row` or `rows`. Both halves are needed, since a cell reading `it closes a gap the reference gate leaves open` carries the verb and claims no position, and the clause bound is what stops a verb in one half of the cell pairing with an object in the other. An ordinal exempts the row, being a comparative claim already. The residue runs both ways: a cell phrased comparatively and unusually reports as unranked, which is the false negative and the safe direction for a check over prose, and a vocabulary verb reaching a positional object non-positionally reports as ranked, which is the false positive. Separating the second from a real position claim means grading prose, so the bound stays where it is.
 
 The collision check is the one a person cannot run by eye. Paths come from the backticked spans in the Touches column, a span naming no file is dropped, and a directory collides with any file beneath it. A `## Run now` row whose column parses to nothing is reported rather than skipped, since a row stating no file set makes a claim nothing can check.
 

package/docs/agents/worktrees.md

@@ -89,7 +89,7 @@ The read is one `gh pr list --state merged` for the whole repository rather than
 
 `route` names which one applies rather than choosing it, since picking wrong strands state.
 
-- `session`: a live session holds the directory, and `claude rm <name>` removes the session and its worktree together. The `sessions` field carries the names, and a name is whatever string the session was launched under, spaces included, so quote it.
+- `session`: a live session holds the directory, and `claude rm <id>` removes the session and its worktree together. The `sessions` field carries names rather than ids, and a name is whatever string the session was launched under, spaces included, so quote it and match it against `claude agents --json`, which carries the id beside the name on every row.
 - `worktree`: the session has ended, and `canon worktrees reclaim` is what runs the remove and the branch delete.
 - `null`: the main worktree, which no removal shape reaches.
 

package/docs/workflow/ai-workflow.md

@@ -212,6 +212,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:claude-intake-answer` | When an intake folder holds unread slots waiting on your decision               |
 | `canon:claude-groundwork`    | When the state is unmeasured and more than one approach is live                 |
 | `canon:decision-escalate`    | When open decisions turn on your preference and want batching into one set      |
+| `canon:draft-and-pick`       | When the call is taste and wants several candidates rendered side by side       |
 | `canon:claude-tasks`         | When a decided item needs a file on the board, or a shipped one needs archiving |
 | `canon:claude-feature`       | When the approach is settled and the next step is a plan                        |
 

package/docs/workflow/visual-design-workflow.md

@@ -39,6 +39,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:claude-ui-test` for e2e test generation after UI changes
 - `canon:claude-ux-audit` for UX gap detection on existing surfaces
 - `canon:claude-ux-measure` for what a running surface costs to paint, read against published thresholds
+- `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -226,8 +226,101 @@ for (const [label, list] of [
   }
 }
 
+// A terminal frame renders lines into a `<pre>` where the hero renders names
+// into divs, so the two cannot share a value however similar the catalog read
+// behind them looks. Padding happens before escaping, since an entity is longer
+// than the character it replaces and would push a column out of line.
+const pad = (value, width) => value + " ".repeat(Math.max(0, width - value.length))
+const frameRow = (cells) => `<span class="frame">│</span> <span class="ok">✓</span> ${cells}`
+
+// The frame sets `white-space: pre` at a fixed window width, so an overlong
+// cell is clipped by the window edge rather than wrapped. Truncating here is
+// what keeps the longest row inside the capture, and the ellipsis is what stops
+// a clipped value from reading as the whole value.
+const GLOB_WIDTH = 44
+const clip = (value, width) =>
+  value.length <= width ? value : `${value.slice(0, width - 1)}…`
+
+const plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`
+
+const govStackRows = gov.stacks
+  .map((stack) =>
+    frameRow(
+      `<span class="name">${escape(pad(stack.name, 17))}</span>` +
+        `<span class="muted">${escape(pad(plural(stack.rules.length, "rule"), 11))}</span>` +
+        `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : "")}</span>`,
+    ),
+  )
+  .join("\n")
+
+// Sampled from the stack-reached subset for the reason the hero column is, and
+// showing each rule beside the glob that loads it rather than its description,
+// since the glob is the mechanism a reader cannot otherwise see.
+const deliveredEntries = gov.rules.filter((entry) => stacked.has(entry.name))
+const govRuleRows = sample(deliveredEntries)
+  .map((entry) => {
+    const globs = [entry.paths ?? []].flat()
+    // A rule carrying no glob is not unscoped, it loads every session, and
+    // saying so is the contrast that makes the column mean anything.
+    const scope = globs.length > 0 ? clip(globs.join(" "), GLOB_WIDTH) : "every session"
+    return frameRow(
+      `<span class="name">${escape(pad(slug(entry), 24))}</span>` +
+        `<span class="domain">${escape(pad(`[${entry.domain}]`, 12))}</span>` +
+        `<span class="muted">${escape(scope)}</span>`,
+    )
+  })
+  .join("\n")
+
+// A standard either governs an artifact by path or is opened by name when a
+// session decides it needs it. Rendering the first and naming the second is the
+// contrast, since nothing else in the catalog tells a reader that the corpus
+// installs into no project and is read through a verb instead.
+const standardEntries = JSON.parse(STANDARDS_JSON).standards
+const standardRows = sample(standardEntries)
+  .map((entry) => {
+    const applies = [entry.appliesTo ?? []].flat()
+    const governs =
+      applies.length > 0 ? clip(applies.join(" "), GLOB_WIDTH) : "read by name"
+    return frameRow(
+      `<span class="name">${escape(pad(entry.name, 18))}</span>` +
+        `<span class="muted">${escape(governs)}</span>`,
+    )
+  })
+  .join("\n")
+
+// A tooling stack is counted rather than listed, because what it lays down is
+// dev dependencies, run scripts, and ignore groups rather than named entries a
+// reader would recognize. The inheritance is the part worth showing, since it
+// is why a stack carrying two of its own arrives with far more than two.
+const toolingStackRows = toolingStacks
+  .map((stack) =>
+    frameRow(
+      `<span class="name">${escape(pad(stack.name, 14))}</span>` +
+        `<span class="muted">${escape(pad(plural(stack.devDeps, "dep"), 10))}</span>` +
+        `<span class="muted">${escape(pad(plural(stack.scripts, "script"), 12))}</span>` +
+        `<span class="muted">${escape(stack.extends ? `extends ${stack.extends}` : "")}</span>`,
+    ),
+  )
+  .join("\n")
+
+for (const [label, rows] of [
+  ["governance stack rows", govStackRows],
+  ["governance rule rows", govRuleRows],
+  ["standard rows", standardRows],
+  ["tooling stack rows", toolingStackRows],
+]) {
+  if (rows === "") {
+    console.error(`regen-hero: the ${label} rendered empty, refusing to write a blank frame`)
+    process.exit(1)
+  }
+}
+
 const values = {
   TOKENS: tokenCss,
+  GOV_STACK_ROWS: govStackRows,
+  GOV_RULE_ROWS: govRuleRows,
+  STANDARD_ROWS: standardRows,
+  TOOLING_STACK_ROWS: toolingStackRows,
   SKILL_COUNT: String(skills.length),
   RULE_COUNT: String(rules.length),
   STANDARD_COUNT: String(standards.length),

package/src/claude/cases/misc.ts

@@ -7,6 +7,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Bundle up every open call that only I can make and ask me all at once.',
     expect: 'decision-escalate',
   },
+  {
+    prompt:
+      'Show me a few different treatments for this callout so I can pick one by looking.',
+    expect: 'draft-and-pick',
+  },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
     expect: 'project-commands',

package/src/commands/worktrees.ts

@@ -146,7 +146,7 @@ export function register(program: Command): void {
         '',
         'This reports and removes nothing. "route" names which removal shape',
         'applies: "session" when a live session holds the directory, where',
-        '`claude rm <name>` takes the session and its worktree together, and',
+        '`claude rm <id>` takes the session and its worktree together, and',
         '"worktree" when the session has ended, where `canon worktrees',
         'reclaim` is the pair of a remove and a branch delete.',
         '',
@@ -185,7 +185,7 @@ export function register(program: Command): void {
         'gone sweeps stale registrations once before the branch deletes.',
         '',
         'It deletes only what a reading called reclaimable. A worktree a live',
-        'session holds is refused rather than removed, since `claude rm <name>`',
+        'session holds is refused rather than removed, since `claude rm <id>`',
         'is what takes a session and its worktree together.',
         '',
         'The stale-registration sweep is the one step that reaches wider, since',

package/src/tasks/validate.ts

@@ -43,6 +43,7 @@ export const FINDING_KINDS = [
   'row-misshapen',
   'row-untabled',
   'row-misordered',
+  'row-unranked',
   'touches-unstated',
   'touches-collided',
   'blocker-settled',
@@ -103,6 +104,8 @@ export interface BoardRow {
   readonly waiting: string | undefined
   /** The ordinal phrase a `Waiting on` cell states about its own position, undefined when the cell carries none. */
   readonly ordinal: OrdinalWord | 'last' | undefined
+  /** Whether a `Waiting on` cell ranks its row against a sibling row or a class of rows, false when the group fixes no such column. */
+  readonly ranked: boolean
 }
 
 export interface ValidateReport {
@@ -277,6 +280,45 @@ function readOrdinal(cell: string): OrdinalWord | 'last' | undefined {
   return LAST_AT_END.test(cell) ? 'last' : undefined
 }
 
+const RANK_VERB =
+  /\b(?:leads|heads|opens|closes|trails|precedes|follows|outranks|sits\s+(?:under|above|below))\b/i
+
+/** A phase label, the group a row opens or closes, or the sibling rows it is ranked among. */
+const RANK_OBJECT = /\bv\d+\.\d+\b|\bgroups?\b|\brows?\b/i
+
+/**
+ * A clause boundary, which is any of the three punctuation marks that end one
+ * plus the two conjunctions every live cell uses to hang its reason off its
+ * position claim. All three marks are bounded away from digits on both sides,
+ * which is what keeps a phase label one token, since `v80.4` is the commonest
+ * positional object on the board and splitting it at its own period would
+ * leave the verb holding nothing.
+ */
+const CLAUSE_BREAK = /(?<!\d)[.;,](?!\d)|\band\b|\bbecause\b/i
+
+/**
+ * Whether a `Waiting on` cell ranks its row against something rather than
+ * arguing that the row matters. The two are indistinguishable to a reader
+ * scanning the board, since a reason with no other row in it reads defensible
+ * on every row at once, which is how insertion order became the ordering.
+ *
+ * The test is a closed verb vocabulary sitting in one clause with a positional
+ * object, which mirrors `readOrdinal` bounding itself to a closed word list for
+ * the same reason: a parser loose enough to grade prose reports a correctly
+ * phrased row. Both halves are needed, since `closes` alone matches `it closes
+ * a gap the reference gate leaves open`, which claims no position at all. The
+ * clause bound is what keeps a verb in one half of the cell from pairing with
+ * an object in the other.
+ *
+ * A cell phrased comparatively and unusually reads as unranked, which is a
+ * false negative and the safe direction for a check over prose.
+ */
+function readRank(cell: string): boolean {
+  return cell
+    .split(CLAUSE_BREAK)
+    .some((clause) => RANK_VERB.test(clause) && RANK_OBJECT.test(clause))
+}
+
 function isRowLine(line: string): boolean {
   return line.trimStart().startsWith('|')
 }
@@ -388,6 +430,7 @@ export function readBoard(text: string): {
       touches: touchesAt >= 0 ? readPaths(cells[touchesAt] ?? '') : undefined,
       waiting,
       ordinal: waiting ? readOrdinal(waiting) : undefined,
+      ranked: waiting ? readRank(waiting) : false,
     })
   }
 
@@ -395,20 +438,39 @@ export function readBoard(text: string): {
 }
 
 /**
- * Reports a `## Needs a plan` row whose stated ordinal disagrees with where it
- * actually sits in that group. Reading the sequence for gaps and duplicates on
- * its own would detect less, since row position is contiguous by
- * construction, and a hand-renumbered sequence is exactly a case where the
- * prose and the position have come apart.
+ * Reports the two ways a `## Needs a plan` row's stated position fails. A row
+ * carrying an ordinal is checked against where it actually sits, and reading
+ * the sequence for gaps and duplicates on its own would detect less, since row
+ * position is contiguous by construction and a hand-renumbered sequence is
+ * exactly a case where the prose and the position have come apart. A row
+ * carrying no position claim of either form is reported for that instead,
+ * since a cell arguing only that the task matters ranks it against nothing and
+ * leaves the position recording when the row was filed.
+ *
+ * Both are one question rather than two checks. An ordinal is already a
+ * comparative claim, so it exempts the row from the second half, and the two
+ * findings read off one walk over the same group.
  */
-function checkOrdinals(rows: readonly BoardRow[]): Finding[] {
+function checkOrdering(rows: readonly BoardRow[]): Finding[] {
   const findings: Finding[] = []
   const parked = rows.filter((row) => row.group === 'Needs a plan')
 
   parked.forEach((row, index) => {
-    if (!row.ordinal) return
-
     const position = index + 1
+
+    if (!row.ordinal) {
+      if (row.ranked) return
+
+      findings.push({
+        kind: 'row-unranked',
+        group: row.group,
+        subject: subjectOf(row),
+        message: `names no row or class it is ranked against, so its position ${position} of ${parked.length} in ${row.group} records only when it was filed.`,
+      })
+
+      return
+    }
+
     const expected =
       row.ordinal === 'last'
         ? parked.length
@@ -1061,7 +1123,7 @@ export async function validateBoard(
     ...checkPlans(rows, dir, root),
     ...(await checkPlanAgreement(rows, dir, root)),
     ...checkCollisions(rows),
-    ...checkOrdinals(rows),
+    ...checkOrdering(rows),
     ...parked.findings,
   ]
 

package/src/worktrees/reclaim.ts

@@ -55,7 +55,11 @@ export interface WorktreeVerdict {
   readonly refusals: readonly Refusal[]
   /** The pull request that retired the branch, so a report can name what it read. */
   readonly pullRequest: number | null
-  /** The names of the live sessions holding this worktree, which is what `claude rm` takes. */
+  /**
+   * The names of the live sessions holding this worktree. `claude rm` takes an
+   * id rather than a name, so a caller acting on this matches each name to the
+   * id `claude agents --json` carries beside it.
+   */
   readonly sessions: readonly string[]
   readonly route: RemovalRoute
   /**

package/standards/tasks.md

@@ -73,7 +73,11 @@ The `Waiting on` column under `## Up next` carries that reason in one of three f
 
 Under `## Up next` a collision names the file held by the task already running, a sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
 
-Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. A cell running past that is the paragraph this file already deletes, arriving one row at a time rather than all at once, and the group is where it costs the most, since it holds the rows nobody has read recently and is the longest group on any board that needs a backlog at all.
+Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. The second clause is comparative, and it names what the row is ranked against in one of two forms: a sibling row, or the class of rows it sits in. The row `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, or `outranks` whichever it names, or `sits under`, `above`, or `below` it. Either form puts something other than this row in the clause, which is what makes the position readable by anyone but its author.
+
+Why the task matters is not that claim, and it is what the cell drifts into. A reason naming no other row ranks against nothing, so every row reads defensible on its own and the order records when each was filed. The comparison replaces that reason rather than joining it, since the cell still takes two clauses and no third one is licensed by naming a rival in the second. A cell running past that is the paragraph this file already deletes, arriving one row at a time rather than all at once, and the group is where it costs the most, since it holds the rows nobody has read recently and is the longest group on any board that needs a backlog at all.
+
+`canon tasks validate` reads that clause back, so a cell phrased comparatively and unusually reports as unranked. The vocabulary above is the whole of what it recognizes, and widening it is a change to the check rather than something the cell may decide for itself.
 
 ```markdown
 ---
@@ -96,9 +100,9 @@ description: One line on what the board covers
 
 ## Needs a plan
 
-| Task                            | Waiting on                                                     |
-| ------------------------------- | -------------------------------------------------------------- |
-| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what it needs before it can be planned, and why it sits here> |
+| Task                            | Waiting on                                                                        |
+| ------------------------------- | --------------------------------------------------------------------------------- |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what it needs before it can be planned, and which row or class it ranks against> |
 ```
 
 The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.