@erclx/canon 4.24.0 → 4.25.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.0",
+  "version": "4.25.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/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/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/key-changes.md

@@ -58,7 +58,7 @@ A span anywhere in the bullet has to survive all of these:
 | No whitespace, `<`, `>`, `$`, `*`, `\|`, `?`, `^` | A backticked command, a placeholder, a glob, a pattern |
 | No `://` and no leading `/`, `~`, `@`, `#`, `!`   | A URL, an absolute path, a module alias                |
 | Contains `/`                                      | A bare filename with no folder around it               |
-| Extension starts with a letter, or ends with `/`  | A dotted number such as an address                     |
+| Not a dotted-decimal segment, or ends with `/`    | A dotted number such as an address                     |
 | Not a single top-level folder                     | `src/`, which nobody claims to have rewritten whole    |
 | A `file:line` span leads its bullet               | A citation into a file the bullet is describing        |
 | The region carries no no-change marker            | A bullet recording a file it deliberately left alone   |

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/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.0",
+  "version": "4.25.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/pr/paths.ts

@@ -94,15 +94,18 @@ function isNotRepositoryPath(span: string): boolean {
 }
 
 /**
- * Whether the span's last segment carries a file extension.
+ * Whether the span's last segment is a bare dotted-decimal number, such as
+ * an address (`127.0.0.1`) or an unprefixed version number (`1.2.3`).
  *
- * The extension has to start with a letter, which is what keeps `127.0.0.1`
- * out. A bare dotted number reaching the comparison is the shape that put
- * `src/serve/127.0.0.1` in a report over a body that was correct.
+ * This is the one exclusion `resolveSpan` still applies to a non-directory
+ * span. A bare dotted number reaching the comparison is the shape that put
+ * `src/serve/127.0.0.1` in a report over a body that was correct, and every
+ * other segment carrying no extension, such as `.husky/post-merge`, now
+ * resolves.
  */
-function hasExtension(span: string): boolean {
+function isDottedNumber(span: string): boolean {
   const segment = span.slice(span.lastIndexOf('/') + 1)
-  return /\.[A-Za-z][A-Za-z0-9]*$/.test(segment)
+  return /^\d+(?:\.\d+)+$/.test(segment)
 }
 
 /** Blanks every backticked span so a cue search never fires inside one. */
@@ -285,7 +288,7 @@ function resolveSpan(span: string): ResolvedSpan | undefined {
       : { path: span, directory: true }
   }
 
-  return hasExtension(span) ? { path: span, directory: false } : undefined
+  return isDottedNumber(span) ? undefined : { path: span, directory: false }
 }
 
 /**

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/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.