@erclx/canon 4.108.0 → 4.109.0

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
-  <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/brand/mark-accent.svg">
+ <img src="assets/brand/mark-accent-light.svg" alt="canon" width="56" height="56">
 </picture>
 
 # canon
@@ -17,12 +17,7 @@ canon is a CLI and Claude Code plugin that stops your AI conventions drifting ap
 
 </div>
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/arrival.png">
-  <img src="assets/evidence/arrival-light.png" alt="The first screen of the canon landing page, a project before and after one canon init, with the file counts each step lays down">
-</picture>
-
-The page is one real session the toolkit ran on itself, and every count on it is read from the repo when the page builds.
+That page is one real session the toolkit ran on itself, and every count on it is read from this repository when the page builds.
 
 ## Why
 
@@ -46,8 +41,8 @@ claude plugin install canon@canon
 ```
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
-  <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
+ <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
 </picture>
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
@@ -73,35 +68,21 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
 | Slides         | A `SLIDES.md` source format with a layout catalog                                                                        | `canon slides render` writes PowerPoint                         |
+| Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/catalog.png">
-  <img src="assets/evidence/catalog-light.png" alt="The canon catalog as a ledger of five rows, with the count each ships and a few real names: skills, rules, standards, commands, and stacks">
-</picture>
-
-Every count in that image is read from the catalogs when it is built, so they're what the repo ships today. 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. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
-
-Two of the outputs are documents you open rather than files you run. A `SLIDES.md` renders to a deck, and a learning workspace renders to a small site.
+Those domains reach you in three shapes. 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.
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="examples/slides/evidence/showcase-dark-04.png">
-  <img src="examples/slides/evidence/showcase-light-04.png" alt="A slide from the showcase deck rendered by canon slides render, a bulleted list under a heading on a warm background">
-</picture>
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="examples/teach/evidence/root-listing.png">
-  <img src="examples/teach/evidence/root-listing-light.png" alt="The learning workspace listing rendered by canon teach, three workspaces with their lesson and term counts, one still a stub">
-</picture>
+Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
 ## It runs on itself
 
 The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
-  <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
+ <source media="(prefers-color-scheme: dark)" srcset="demos/agent-view.gif">
+ <img src="demos/agent-view-light.gif" alt="The canon landing page scrolling from the dispatch section to the branch graph, three workers and a planner on disjoint file sets with the pull request each opened">
 </picture>
 
 That recording is the landing page's own `dispatch` and `workers` sections, driven by `canon demo run` against a local build. The branch graph beside the pull request numbers is authored rather than read, because nothing on a build machine records which files four sessions held.
@@ -110,6 +91,8 @@ That recording is the landing page's own `dispatch` and `workers` sections, driv
 
 Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
 
+Working with an agent rather than reading this yourself? It loads `CLAUDE.md` at your project root first, then whichever rules under `.claude/rules/` match the paths it edits. Run `canon docs agents` for the command catalog with flags, exit codes, and JSON shapes.
+
 - [AI workflow](docs/workflow/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [Operating model](docs/workflow/operating-model.md): orchestrator, planner, and worker roles for building across parallel sessions
 - [Visual design workflow](docs/workflow/visual-design-workflow.md): tiered guide for design and wireframe authoring
@@ -165,7 +148,9 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project.
+
+Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 

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

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

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

@@ -31,7 +31,7 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 6. Invoke `canon:git-stage` to group staged changes and commit by concern
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
-9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending`, branching on that field rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending` or the record carries `conflicted: true`, branching on those fields rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. On `conflicted`, stop the sequence and report that the branch conflicts with its base, since no run will start for it and polling on never ends. A rebase is the repair. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
 
 A caller wrapping this sequence may act between step 8 and step 9, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `auto-ship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
 

package/claude/skills/review-address/SKILL.md

@@ -30,7 +30,7 @@ Also read the CI check status so the fixes cover failing checks, not only review
 canon pr checks <number> --json
 ```
 
-Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. Fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb.
+Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. A record carrying `conflicted: true` is a third case: the branch conflicts with its base, so no run will start and the wait never ends. Stop and report it, since a rebase is the repair. Fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb.
 
 ## Step 2: address each finding
 
@@ -170,8 +170,9 @@ echo "${comment_url##*issuecomment-}" > .canon/tmp/pr/reply/reply-<number>.id
 ## Step 7: confirm resolution
 
 After the follow-up push, watch CI on the PR. Poll
-`canon pr checks <number> --json` until the record's `state` leaves `pending`,
-then read it. When every finding is addressed and the state is `passing`, append
+`canon pr checks <number> --json` until the record's `state` leaves `pending`
+or it carries `conflicted: true`, then read it. On `conflicted`, stop and report
+that a rebase is the repair rather than polling on. When every finding is addressed and the state is `passing`, append
 the closing confirmation to the reply file Step 6 already posted, so the thread
 carries one terminal state rather than a second comment under no heading:
 

package/claude/skills/task-board/REQUIREMENT.md

@@ -18,7 +18,7 @@ Placing a row without checking for another writer collides the same way. Two ses
 - Resolve the board at the main worktree root, since a linked worktree writing to `pwd` creates a second board nothing reads
 - Read the tasks standard before writing, rather than working the filename and frontmatter from memory
 - Require an origin at creation, because that is the only moment the invariant is enforceable
-- Read the phase label from `canon tasks next-label` rather than proposing one by hand
+- Claim the phase label with `canon tasks next-label --claim` rather than reading or proposing one by hand
 - Check the roster for a live orchestrator before writing a row, and hand off rather than write when one is found
 - Confirm the work reached the default branch before archiving
 - Run the archive command and route on the reason it refuses, since each reason has one resolution

package/claude/skills/task-board/SKILL.md

@@ -29,13 +29,13 @@ Accept work whose origin is the conversation itself only when the user says so e
 
 ### Step 2: allocate the phase label
 
-Run `canon tasks next-label --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows.
+Run `canon tasks next-label --claim --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows, and `--claim` reserves it under `.canon/ordinal-locks/` so a second session filing at the same moment gets the next one. Branch on the record's `reason` rather than the exit: `label-contended` means re-run the claim, and a usage error from an unknown `--claim` means the installed binary predates the flag, so report the verb as unavailable rather than falling back to a bare read, which reopens the race.
 
 Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../../standards/versioning.md` permits free renumbering, so the verb's two folders are the only surface that knows what a label currently means.
 
 ### Step 3: write the file
 
-Write `.canon/tasks/vXX.Y-<slug>.md` following the format in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
+Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file first if a session ever stubbed it, following the format in `${CLAUDE_SKILL_DIR}/../../standards/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
 
 Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.canon/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
 

package/docs/agents/capture.md

@@ -18,11 +18,11 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the three templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
+A capture set here spans two folders. `assets/captures/` holds three sources and the two templates they are written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them. A branch commits none of them for a moved count or token, since the refresh workflow regenerates them from `main` and opens one pull request, and `bun run check` runs the script with `--check`, which fills every template into a temp folder and fails when the regeneration cannot run.
 
-Two of the three templates take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
+The `hero` template takes catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
-The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `catalog` and `install` take the light half from the same template, which `regen-hero.sh` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
+The README shows each still in two themes through `<picture>`, so a frame is a pair named `<name>` and `<name>-light`. `install` takes the light half from its template, which `regen-hero.sh` fills a second time with the plain color roles pointed at the light ones, and each half is its own capture set with its own stamp. `arrival-light.png` is the same `.fold` capture of the same address taken without forcing dark, so it is retaken by hand alongside `arrival.png`, and nothing catches one drifting from the other.
 
 A stamp for a URL source digests the address string rather than the page it served, so two themes of one address carry one `source-sha256` and only `image-sha256` tells the frames apart. That holds for `examples/teach/evidence/root-listing-light.png`, which is retaken by serving a copy of the fixture with `data-theme="light"` on its `<html>` element at the same address, since the page follows the dark default and the command takes no scheme.
 

package/docs/agents/commands.md

@@ -5,7 +5,7 @@ description: Every project-level command and every domain subcommand, plus the s
 
 # Command catalog
 
-Full help: `canon <command> --help`. Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
+Full help: `canon <command> --help`. Bare `canon --help` lists every top-level command under five headings, Project, Domains, Author and render, Session and ship, and Repo reports, with descriptions cut at 80 columns. Piped into another command, the block prints without its frame glyphs and carries the same text. Behavior notes for the install and sync verbs live in `install-and-sync.md`.
 
 ## Project-level
 
@@ -92,7 +92,7 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon autoship classify`        | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                                                                                                                                                                                  |
 | `canon pr key-changes`           | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                                                                                                                                                                            |
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                              |
-| `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                                                                                                                                                                            |
+| `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean, and `conflicted` when the branch conflicts with its base (`--root`, `--json`)                                                                                                                                  |
 | `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                                |
 | `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`, `--preview`)                                                                                                                         |
 | `canon pr preview`               | Dispatch the Pages deploy on a pull request's branch and report the preview address the run prints, refusing a deploy that passes no `--branch` (`--root`, `--json`, `--timeout`)                                                                                                                                            |

package/docs/agents/pr-reads.md

@@ -74,6 +74,8 @@ Both empty cases report `pending` instead: a tip carrying no run yet, and a list
 
 The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
 
+A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. `mergeStateStatus` is the field that separates the two, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
+
 A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
 
 A count above the rows returned reports `pending` for the same reason. The query asks for 100 rows against the endpoint's default of 30, and a commit carrying more than that comes back short, so the verb reports the tip as unread rather than collapsing the page it happens to hold. `reported` against `matched` and `foreign` is where a reader sees which of the three shapes produced the answer.

package/docs/agents/tasks.md

@@ -7,25 +7,27 @@ description: Selecting a shipped task by stem or pull request, recording a numbe
 
 ## Next label
 
-`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. It reports and never writes.
+`canon tasks next-label` reports the next unused phase label, reading `.canon/tasks/` and its `archive/` sibling together. A scan confined to the live board is blind to every label the archive already spent, which is what let two sessions hand out the same label within minutes of each other. Bare, it reports and never writes. With `--claim` it reserves the label first.
 
 ```bash
 canon tasks next-label
 canon tasks next-label --json
+canon tasks next-label --claim --json
 ```
 
-| Option          | Effect                                      |
-| --------------- | ------------------------------------------- |
-| `--json`        | Emit a machine-readable record on stdout    |
-| `--root <path>` | Board root, defaulting to the main worktree |
+| Option          | Effect                                           |
+| --------------- | ------------------------------------------------ |
+| `--json`        | Emit a machine-readable record on stdout         |
+| `--claim`       | Reserve the label so a second claim gets another |
+| `--root <path>` | Board root, defaulting to the main worktree      |
 
-The record carries `label`, the next free `vXX.Y`, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
+The record carries `label`, the next free `vXX.Y`, `claimed`, whether the label was reserved, and `highest`, the label it was derived from. `highest` is absent when neither folder carries a label yet, and `label` reads `v01.0` in that case, matching the zero-padded-major shape every other label already takes. <!-- canon-allow-reference: illustrates the verb's answer for a board holding no label yet, not a citation of a real task -->
 
-Exit codes: `0` derived, `1` refused with `no-board`.
+Exit codes: `0` derived, `1` refused with `no-board`, `2` refused with `label-contended` after five lost reservations, on `--claim` only.
 
 The minor digit rolls from 9 to 0 on the next major rather than growing a second digit, which is the single-digit-minor shape every phase label already takes. `canon tasks archive` moves a task's file from the live folder into the archive without renumbering it, so the same label counts toward the maximum wherever it currently sits, and a label claimed by two different files folds into the same scan without a dedicated check.
 
-It reports rather than gates. Two sessions calling it in the same second can still take the same answer, since the board is gitignored files rather than a store with a lock, and `standards/versioning.md` permits free renumbering, so a collision costs a rename rather than anything worse.
+A claim is an exclusive `mkdir` at `.canon/ordinal-locks/<label>`, and the scan counts every reservation beside the task files, since the file lands after the verb returns. Reservations never expire, so a claim that died leaves a gap, which `standards/versioning.md` permits. A bare read still reports without reserving, and it does not count reservations either, so it can return a label a claim already holds until that claim's task file lands. Two bare reads in the same second can also take the same answer.
 
 ```bash
 canon tasks next-label --json | jq -r '.label'

package/package.json

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

package/scripts/core/regen-hero.sh

@@ -96,11 +96,8 @@ GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
-# The catalog ledger names three commands, and the registered set is only
-# readable from the root help, which lists one per line under `Commands:`.
-COMMANDS_HELP="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts --help 2>/dev/null)"
 
-for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON" "$COMMANDS_HELP"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -120,7 +117,6 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
-printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
@@ -349,36 +345,8 @@ for (const [label, rows] of [
   }
 }
 
-// The ledger names a few real entries per domain. Chosen by hand for the same
-// reason FEATURED_SKILLS is, and asserted against the catalog so a rename fails
-// the run rather than leaving a name the repository no longer ships.
-const commandNames = readFileSync(PAYLOAD_DIR + "/commands-help.txt", "utf8")
-  .split("\n")
-  .map((line) => line.match(/^[│\s]{2,}(?<name>[a-z][a-z-]*)\s/)?.groups?.name)
-  .filter(Boolean)
-const LEDGER = [
-  ["skills", skills.length, ["plan-feature", "role-orchestrator", "review-pr"], skills],
-  ["rules", rules.length, ["behavior", "memory", "testing"], rules],
-  ["standards", standards.length, ["markdown", "plan", "teach"], standards],
-  ["commands", commandCount, ["gov", "tasks", "design"], commandNames],
-  ["stacks", toolingStacks.length, ["astro", "python", "web"], toolingStacks.map((stack) => stack.name)],
-]
-for (const [domain, , chosen, names] of LEDGER) {
-  const known = new Set(names)
-  const missing = chosen.filter((name) => !known.has(name))
-  if (missing.length > 0) {
-    console.error(`regen-hero: ledger ${domain} names missing from the catalog: ${missing.join(", ")}`)
-    process.exit(1)
-  }
-}
-const ledgerRows = LEDGER.map(
-  ([domain, count, chosen]) =>
-    `      <div class="row"><span class="count">${count}</span><span class="domain">${domain}</span><span class="names">${escape(chosen.join(", "))}</span></div>`,
-).join("\n")
-
 const values = {
   TOKENS: tokenCss,
-  LEDGER_ROWS: ledgerRows,
   GOV_STACK_ROWS: govStackRows,
   GOV_RULE_ROWS: govRuleRows,
   STANDARD_ROWS: standardRows,
@@ -417,7 +385,7 @@ if (templates.length === 0) {
 // same template with the plain roles pointed at the light ones rather than a
 // second copy of any hex value. The hero is a landing-page frame no README
 // shows, so it stays dark.
-const LIGHT_TEMPLATES = new Set(["catalog.html.tmpl", "install.html.tmpl"])
+const LIGHT_TEMPLATES = new Set(["install.html.tmpl"])
 
 const lightRoles = [...tokenCss.matchAll(/--color-light-([a-z-]+):/g)].map((match) => match[1])
 if (lightRoles.length === 0) {

package/src/cli.ts

@@ -43,169 +43,10 @@ import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-import { palette } from '@/ui'
-
-const HELP_WIDTH = 80
-const SIGNATURE_WIDTH = 19
-const ROW_INDENT = '│    '.length
-
-type CommandRow = [signature: string, description: string]
-
-// The grouping mirrors the README's domain table and has no other source, so a
-// command added to the program needs a row here or help-option.test.ts fails.
-const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
-  {
-    title: 'Project',
-    rows: [
-      ['init [path]', 'Bootstrap a project with toolkit domains'],
-      ['sync [path]', 'Sync all installed domains in a project'],
-      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
-      ['migrate [cmd]', 'Move a project off a retired name or layout'],
-      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
-    ],
-  },
-  {
-    title: 'Domains',
-    rows: [
-      ['gov [cmd]', 'Governance rules (install, sync, list)'],
-      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
-      ['snippets [cmd]', 'Prompt snippets (create, list)'],
-      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
-      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
-      ['wiki [cmd]', 'Wiki pages (init)'],
-      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
-      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
-    ],
-  },
-  {
-    title: 'Author and render',
-    rows: [
-      ['design [cmd]', 'Design system (render, board)'],
-      ['slides [cmd]', 'Slide decks (render, list)'],
-      ['capture [source]', 'Render HTML capture sources to PNG'],
-      ['serve [dir]', 'Serve a directory on localhost, print the link'],
-      ['demo [cmd]', 'Record a running app (compile, run)'],
-      ['inventory [subj]', 'Report one computed property across every route'],
-      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
-      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
-      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
-    ],
-  },
-  {
-    title: 'Session and ship',
-    rows: [
-      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
-      ['tasks [cmd]', 'Task board (validate, archive)'],
-      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
-      ['records [cmd]', 'Session records (validate, size, push, pull)'],
-      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
-      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
-      ['autoship [cmd]', 'Decide whether a changed set needs review'],
-      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
-      ['feedback', 'Write toolkit feedback from stdin'],
-    ],
-  },
-  {
-    title: 'Repo reports',
-    rows: [
-      ['audits [cmd]', 'Run every health check as one set (run, list)'],
-      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
-      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
-      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
-      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
-      ['comments [cmd]', 'Measure comment density and trend (scan)'],
-      ['context [cmd]', 'Report context folder health (audit)'],
-      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
-      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
-      ['census [path]', 'Report file count, extensions, and line totals'],
-    ],
-  },
-]
-
-// A row past the width is cut rather than wrapped, since a wrapped row breaks
-// the alignment the grouping exists to buy.
-function commandRow(signature: string, description: string): string {
-  const { GREY, NC } = palette(process.stdout)
-  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
-  const text =
-    description.length > room
-      ? `${description.slice(0, room - 1)}…`
-      : description
-  return `${GREY}│${NC}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
-}
+import { renderHelp } from '@/help'
 
 function showHelp(): void {
-  // The help text is the one framed surface written to stdout, so it asks
-  // about that stream rather than the stderr every other writer here uses.
-  const { GREY, NC, WHITE } = palette(process.stdout)
-  const lines = [
-    `${GREY}┌${NC}`,
-    `${GREY}├${NC} ${WHITE}Usage:${NC} canon [command]`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
-    ...COMMAND_GROUPS.flatMap((group) => [
-      `${GREY}│${NC}`,
-      `${GREY}│${NC}  ${WHITE}${group.title}${NC}`,
-      ...group.rows.map(([signature, description]) =>
-        commandRow(signature, description),
-      ),
-    ]),
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
-    `${GREY}│${NC}    canon sandbox             ${GREY}# Interactive scenario picker${NC}`,
-    `${GREY}│${NC}    canon sandbox git:commit  ${GREY}# Run specific scenario${NC}`,
-    `${GREY}│${NC}    canon sandbox reset       ${GREY}# Reset sandbox to baseline${NC}`,
-    `${GREY}│${NC}    canon sandbox clean       ${GREY}# Wipe the sandbox${NC}`,
-    `${GREY}│${NC}`,
-    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
-    `${GREY}│${NC}    canon sync ../my-app`,
-    `${GREY}│${NC}    canon sandbox git:commit`,
-    `${GREY}│${NC}    canon gov install react`,
-    `${GREY}│${NC}    canon gov sync ../my-app`,
-    `${GREY}│${NC}    canon gov restated --json`,
-    `${GREY}│${NC}    canon standards markdown`,
-    `${GREY}│${NC}    canon snippets list`,
-    `${GREY}│${NC}    canon init ../my-app`,
-    `${GREY}│${NC}    canon tooling sync base`,
-    `${GREY}│${NC}    canon tooling create`,
-    `${GREY}│${NC}    canon claude init`,
-    `${GREY}│${NC}    canon indexes regen`,
-    `${GREY}│${NC}    canon indexes regen --dry-run --json`,
-    `${GREY}│${NC}    canon docs list --json`,
-    `${GREY}│${NC}    canon docs agents`,
-    `${GREY}│${NC}    canon design render`,
-    `${GREY}│${NC}    canon design board`,
-    `${GREY}│${NC}    canon slides render`,
-    `${GREY}│${NC}    canon slides list --json`,
-    `${GREY}│${NC}    canon capture assets/captures/install.html --selector .window --out assets/evidence`,
-    `${GREY}│${NC}    canon serve .canon/teach`,
-    `${GREY}│${NC}    canon inventory focus --json`,
-    `${GREY}│${NC}    canon drive http://localhost:4173 run.json --json`,
-    `${GREY}│${NC}    pbpaste | canon feedback`,
-    `${GREY}│${NC}    canon transcripts https://youtu.be/VIDEO_ID`,
-    `${GREY}│${NC}    canon tasks archive --pull-request 673 --json`,
-    `${GREY}│${NC}    canon intake list toolkit-overview --unread --json`,
-    `${GREY}│${NC}    canon teach list --json`,
-    `${GREY}│${NC}    canon comments scan src --json`,
-    `${GREY}│${NC}    canon context audit --json`,
-    `${GREY}│${NC}    canon markdown audit .claude/rules --json`,
-    `${GREY}│${NC}    canon records validate plans`,
-    `${GREY}│${NC}    canon records size --json`,
-    `${GREY}│${NC}    canon records push --json`,
-    `${GREY}│${NC}    canon sessions list --json`,
-    `${GREY}│${NC}    canon worktrees list --json`,
-    `${GREY}│${NC}    canon worktrees reclaim --dry-run`,
-    `${GREY}│${NC}    canon secrets scan --json`,
-    `${GREY}│${NC}    canon deps audit --json`,
-    `${GREY}│${NC}    canon labels audit --json`,
-    `${GREY}│${NC}    canon repo metadata propose --json`,
-    `${GREY}│${NC}    canon census --json`,
-    `${GREY}│${NC}    canon audits run --json`,
-    `${GREY}│${NC}    canon gate run --all --no-write`,
-    `${GREY}│${NC}    canon upgrade --json`,
-    `${GREY}└${NC}`,
-  ]
-  console.log(lines.join('\n'))
+  console.log(renderHelp(process.stdout))
 }
 
 const program = new Command()

package/src/commands/pr.ts

@@ -20,7 +20,11 @@ import {
   compareKeyChanges,
   treeRoots,
 } from '@/pr/bijection'
-import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import {
+  type CheckRunListing,
+  collapseChecks,
+  withMergeState,
+} from '@/pr/checks'
 import {
   findEvidenceChecklist,
   findEvidenceCommentId,
@@ -307,6 +311,11 @@ export function register(program: Command): void {
         'an empty row list, and reading that as passing is the false green the',
         'sha key alone does not close.',
         '',
+        'A branch conflicting with its base gets no merge ref, so no run ever',
+        'starts for it and the state stays pending. The record carries',
+        '`conflicted: true` beside it when `mergeStateStatus` reads DIRTY and no',
+        'run belongs to the tip, and a caller stops waiting and rebases.',
+        '',
         'Exit codes:',
         '  0  the runs for the tip were read, whatever they say',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -865,6 +874,7 @@ interface PullIdentity {
   readonly number: number | undefined
   readonly branch: string
   readonly head?: string
+  readonly mergeState?: string
 }
 
 type IdentityRead =
@@ -911,12 +921,17 @@ async function readIdentity(
 
   const args = ['pr', 'view']
   if (number !== undefined) args.push(number)
-  args.push('--json', 'number,headRefName,headRefOid')
+  args.push('--json', 'number,headRefName,headRefOid,mergeStateStatus')
 
   const stdout = await gh(cwd, args)
   if (stdout === null) return { kind: 'refused', reason: 'gh-failed' }
 
-  let row: { number?: number; headRefName?: string; headRefOid?: string }
+  let row: {
+    number?: number
+    headRefName?: string
+    headRefOid?: string
+    mergeStateStatus?: string
+  }
   try {
     row = JSON.parse(stdout)
   } catch {
@@ -933,6 +948,9 @@ async function readIdentity(
       number: row.number,
       branch: row.headRefName,
       ...(row.headRefOid !== undefined && { head: row.headRefOid }),
+      ...(row.mergeStateStatus !== undefined && {
+        mergeState: row.mergeStateStatus,
+      }),
     },
   }
 }
@@ -1071,7 +1089,10 @@ async function runChecks(
     )
   }
 
-  const reading = collapseChecks(resolved.tip, listing)
+  const reading = withMergeState(
+    identity.mergeState,
+    collapseChecks(resolved.tip, listing),
+  )
 
   logStep('Scope')
   logInfo(
@@ -1101,6 +1122,10 @@ async function runChecks(
     logInfo('every run on the tip completed and none failed')
   } else if (reading.state === 'failing') {
     logWarn('a run on the tip failed, which no run still going can clear')
+  } else if (reading.conflicted) {
+    logWarn(
+      'the branch conflicts with its base, so no run will start for the tip. Rebase onto the base rather than waiting.',
+    )
   } else if (reading.matched === 0) {
     logInfo(
       `no run belongs to the tip yet${reading.reported > 0 ? `, against a reported count of ${reading.reported}` : ''}. That is unread rather than clean.`,

package/src/commands/tasks.ts

@@ -13,7 +13,12 @@ import {
   type PlanCitations,
   planCitations,
 } from '@/tasks/archive'
-import { type LabelOutcome, nextLabel } from '@/tasks/label'
+import {
+  type LabelOutcome,
+  type LabelRefused,
+  claimLabel,
+  nextLabel,
+} from '@/tasks/label'
 import { listTasks } from '@/tasks/list'
 import {
   type Claim,
@@ -122,6 +127,7 @@ interface ListCommandOptions {
 
 interface NextLabelCommandOptions {
   readonly json?: boolean
+  readonly claim?: boolean
   readonly root?: string
 }
 
@@ -503,6 +509,7 @@ export function register(program: Command): void {
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--claim', 'Reserve the label so a second claim gets another')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
       'after',
@@ -515,14 +522,18 @@ export function register(program: Command): void {
         'Exit codes:',
         '  0  the label is derived',
         '  1  refused with no-board',
+        '  2  refused with label-contended, on --claim only',
         '',
-        'It reports and never writes. Two sessions calling it in the same',
-        'second can still take the same answer, since the board is',
-        'gitignored files rather than a store with a lock.',
+        'Bare, it reports and never writes, so two sessions calling it in the',
+        'same second can take the same answer. --claim reserves the label',
+        'under .canon/ordinal-locks/ and counts every reservation in the',
+        'scan, so two claims return different labels. A dead claim leaves a',
+        'gap, which standards/versioning.md permits.',
         '',
         'Examples:',
         '  canon tasks next-label',
         '  canon tasks next-label --json',
+        '  canon tasks next-label --claim --json',
         '',
       ].join('\n'),
     )
@@ -864,11 +875,15 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
 async function runNextLabel(opts: NextLabelCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await nextLabel(root)
+  const outcome = opts.claim ? await claimLabel(root) : await nextLabel(root)
 
   return reportNextLabel(outcome, opts.json ?? false, root)
 }
 
+function refusalExit(outcome: LabelRefused): number {
+  return outcome.reason === 'label-contended' ? 2 : 1
+}
+
 function reportNextLabel(
   outcome: LabelOutcome,
   emitJson: boolean,
@@ -879,14 +894,14 @@ function reportNextLabel(
       process.stdout.write(
         `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
       )
-      return 1
+      return refusalExit(outcome)
     }
 
     intro('canon tasks next-label')
     logStep('Refused')
     logError(outcome.message)
     outro()
-    return 1
+    return refusalExit(outcome)
   }
 
   if (emitJson) {

package/src/help.ts

@@ -0,0 +1,196 @@
+import { palette } from '@/ui'
+
+const HELP_WIDTH = 80
+const SIGNATURE_WIDTH = 19
+const SANDBOX_SIGNATURE_WIDTH = 26
+const ROW_INDENT = '│    '.length
+
+type CommandRow = [signature: string, description: string]
+type HelpStream = { isTTY?: boolean }
+
+// The grouping mirrors the README's domain table and has no other source, so a
+// command added to the program needs a row here or help-option.test.ts fails.
+export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
+  {
+    title: 'Project',
+    rows: [
+      ['init [path]', 'Bootstrap a project with toolkit domains'],
+      ['sync [path]', 'Sync all installed domains in a project'],
+      ['upgrade', 'Reinstall the CLI with the manager that installed it'],
+      ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['targets [cmd]', 'Projects this toolkit installed into (list, pulls)'],
+    ],
+  },
+  {
+    title: 'Domains',
+    rows: [
+      ['gov [cmd]', 'Governance rules (install, sync, list)'],
+      ['standards [cmd]', 'Standards (install, sync, list, <name>)'],
+      ['snippets [cmd]', 'Prompt snippets (create, list)'],
+      ['tooling [cmd]', 'Tooling stacks (sync, ref, create)'],
+      ['claude [cmd]', 'Claude workflow (init, sync, setup)'],
+      ['wiki [cmd]', 'Wiki pages (init)'],
+      ['indexes [cmd]', 'Regenerate index.md files (regen)'],
+      ['docs [cmd|topic]', 'Emit toolkit reference docs (list, <topic>)'],
+    ],
+  },
+  {
+    title: 'Author and render',
+    rows: [
+      ['design [cmd]', 'Design system (render, board)'],
+      ['slides [cmd]', 'Slide decks (render, list)'],
+      ['capture [source]', 'Render HTML capture sources to PNG'],
+      ['serve [dir]', 'Serve a directory on localhost, print the link'],
+      ['demo [cmd]', 'Record a running app (compile, run)'],
+      ['inventory [subj]', 'Report one computed property across every route'],
+      ['drive <url> <run>', 'Walk a page through interactions, measure each'],
+      ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
+      ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
+    ],
+  },
+  {
+    title: 'Session and ship',
+    rows: [
+      ['sandbox [cat:cmd]', 'Provision and run sandbox scenarios'],
+      ['tasks [cmd]', 'Task board (validate, archive)'],
+      ['intake [cmd]', 'Intake folders under .canon/intake/ (list, answer)'],
+      ['records [cmd]', 'Session records (validate, size, push, pull)'],
+      ['sessions [cmd]', 'Resolve live sessions to worktree and branch'],
+      ['worktrees [cmd]', 'Reclaim worktrees whose branches merged'],
+      ['autoship [cmd]', 'Decide whether a changed set needs review'],
+      ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
+      ['feedback', 'Write toolkit feedback from stdin'],
+    ],
+  },
+  {
+    title: 'Repo reports',
+    rows: [
+      ['audits [cmd]', 'Run every health check as one set (run, list)'],
+      ['gate [cmd]', 'Run the merge gate stage by stage (run)'],
+      ['secrets [cmd]', 'Scan the shipped tree for credentials (scan)'],
+      ['deps [cmd]', 'Read the dependency set for advisories (audit)'],
+      ['labels [cmd]', 'Read a changed set against the label map (audit)'],
+      ['comments [cmd]', 'Measure comment density and trend (scan)'],
+      ['context [cmd]', 'Report context folder health (audit)'],
+      ['markdown [cmd]', 'Report markdown against the standards (audit)'],
+      ['repo [cmd]', 'Remote metadata (metadata propose, apply)'],
+      ['census [path]', 'Report file count, extensions, and line totals'],
+    ],
+  },
+]
+
+const SANDBOX_ROWS: CommandRow[] = [
+  ['canon sandbox', 'Interactive scenario picker'],
+  ['canon sandbox git:commit', 'Run specific scenario'],
+  ['canon sandbox reset', 'Reset sandbox to baseline'],
+  ['canon sandbox clean', 'Wipe the sandbox'],
+]
+
+const EXAMPLES = [
+  'canon sync ../my-app',
+  'canon sandbox git:commit',
+  'canon gov install react',
+  'canon gov sync ../my-app',
+  'canon gov restated --json',
+  'canon standards markdown',
+  'canon snippets list',
+  'canon init ../my-app',
+  'canon tooling sync base',
+  'canon tooling create',
+  'canon claude init',
+  'canon indexes regen',
+  'canon indexes regen --dry-run --json',
+  'canon docs list --json',
+  'canon docs agents',
+  'canon design render',
+  'canon design board',
+  'canon slides render',
+  'canon slides list --json',
+  'canon capture assets/captures/install.html --selector .window --out assets/evidence',
+  'canon serve .canon/teach',
+  'canon inventory focus --json',
+  'canon drive http://localhost:4173 run.json --json',
+  'pbpaste | canon feedback',
+  'canon transcripts https://youtu.be/VIDEO_ID',
+  'canon tasks archive --pull-request 673 --json',
+  'canon intake list toolkit-overview --unread --json',
+  'canon teach list --json',
+  'canon comments scan src --json',
+  'canon context audit --json',
+  'canon markdown audit .claude/rules --json',
+  'canon records validate plans',
+  'canon records size --json',
+  'canon records push --json',
+  'canon sessions list --json',
+  'canon worktrees list --json',
+  'canon worktrees reclaim --dry-run',
+  'canon secrets scan --json',
+  'canon deps audit --json',
+  'canon labels audit --json',
+  'canon repo metadata propose --json',
+  'canon census --json',
+  'canon audits run --json',
+  'canon gate run --all --no-write',
+  'canon upgrade --json',
+]
+
+// The frame follows stdout's TTY state rather than `palette`, whose blank
+// palette keeps every glyph so the stderr frames a captured run quotes stay
+// framed. A glyph is rendering rather than color, so NO_COLOR keeps it.
+function isFramed(stream: HelpStream): boolean {
+  return stream.isTTY === true
+}
+
+function gutter(stream: HelpStream): string {
+  if (!isFramed(stream)) return ''
+  const { GREY, NC } = palette(stream)
+  return `${GREY}│${NC}`
+}
+
+// A row past the width is cut rather than wrapped, since a wrapped row breaks
+// the alignment the grouping exists to buy. The cut is computed from the framed
+// prefix in both forms, so a pipe carries the same text as a terminal.
+export function commandRow(
+  signature: string,
+  description: string,
+  stream: HelpStream,
+): string {
+  const { GREY, NC } = palette(stream)
+  const room = HELP_WIDTH - ROW_INDENT - SIGNATURE_WIDTH - '# '.length
+  const text =
+    description.length > room
+      ? `${description.slice(0, room - 1)}…`
+      : description
+  return `${gutter(stream)}    ${signature.padEnd(SIGNATURE_WIDTH)}${GREY}# ${text}${NC}`
+}
+
+export function renderHelp(stream: HelpStream): string {
+  const { GREY, NC, WHITE } = palette(stream)
+  const bar = gutter(stream)
+  const usage = `${WHITE}Usage:${NC} canon [command]`
+  const lines = [
+    ...(isFramed(stream)
+      ? [`${GREY}┌${NC}`, `${GREY}├${NC} ${usage}`]
+      : [usage]),
+    bar,
+    `${bar}  ${WHITE}Commands:${NC}`,
+    ...COMMAND_GROUPS.flatMap((group) => [
+      bar,
+      `${bar}  ${WHITE}${group.title}${NC}`,
+      ...group.rows.map(([signature, description]) =>
+        commandRow(signature, description, stream),
+      ),
+    ]),
+    bar,
+    `${bar}  ${WHITE}Sandbox:${NC}`,
+    ...SANDBOX_ROWS.map(
+      ([signature, description]) =>
+        `${bar}    ${signature.padEnd(SANDBOX_SIGNATURE_WIDTH)}${GREY}# ${description}${NC}`,
+    ),
+    bar,
+    `${bar}  ${WHITE}Examples:${NC}`,
+    ...EXAMPLES.map((example) => `${bar}    ${example}`),
+    ...(isFramed(stream) ? [`${GREY}└${NC}`] : []),
+  ]
+  return lines.join('\n')
+}

package/src/pr/checks.ts

@@ -29,6 +29,35 @@ export interface ChecksReading {
   readonly collapsed: number
 }
 
+export interface ConflictedReading extends ChecksReading {
+  /** The branch conflicts with its base, so no run will ever start for the tip. */
+  readonly conflicted: boolean
+  /** The pull request's `mergeStateStatus`, absent when the read carried none. */
+  readonly mergeState?: string
+}
+
+/**
+ * Tells a conflicted pull request from a tip whose runs have not started.
+ *
+ * A branch that conflicts with its base gets no merge ref, so no
+ * `pull_request` workflow runs and the listing stays empty, which
+ * `collapseChecks` can only call pending. Only `DIRTY` separates the two, and
+ * only while no run belongs to the tip: a conflict arising after runs
+ * completed leaves those runs standing as a real answer. `UNKNOWN` is
+ * transient while GitHub computes it, so it reads as not conflicted and costs
+ * a caller one more poll.
+ */
+export function withMergeState(
+  mergeState: string | undefined,
+  reading: ChecksReading,
+): ConflictedReading {
+  return {
+    ...reading,
+    conflicted: mergeState === 'DIRTY' && reading.matched === 0,
+    ...(mergeState !== undefined && { mergeState }),
+  }
+}
+
 /**
  * Puts a check-run row into the shape `rollup` reads.
  *

package/src/tasks/label.ts

@@ -1,5 +1,7 @@
 import { existsSync } from 'node:fs'
+import { mkdir, readdir } from 'node:fs/promises'
 import { relative } from 'node:path'
+import { recordDir } from '@/record-root'
 import {
   archiveDir,
   declinedDir,
@@ -21,6 +23,12 @@ const FIRST_LABEL: Label = { major: 1, minor: 0 }
  */
 export const LABEL_PATTERN = /^v(\d+)\.(\d+)-/
 
+/** A reservation is named by the bare label, with no slug behind it. */
+const RESERVATION_PATTERN = /^v(\d+)\.(\d+)$/
+
+/** Bounds the claim loop. A fifth loss in a row is not a race. */
+const MAX_ATTEMPTS = 5
+
 interface Label {
   readonly major: number
   readonly minor: number
@@ -31,18 +39,23 @@ export interface NextLabel {
   readonly label: string
   /** The label this run was derived from, absent when neither folder holds one. */
   readonly highest: string | undefined
+  /** Whether this label was reserved on disk rather than only read. */
+  readonly claimed: boolean
 }
 
 export interface LabelRefused {
   readonly ok: false
-  readonly reason: 'no-board'
+  readonly reason: 'no-board' | 'label-contended'
   readonly message: string
 }
 
 export type LabelOutcome = NextLabel | LabelRefused
 
-function parseLabel(stem: string): Label | undefined {
-  const match = LABEL_PATTERN.exec(stem)
+function parseLabel(
+  stem: string,
+  pattern: RegExp = LABEL_PATTERN,
+): Label | undefined {
+  const match = pattern.exec(stem)
   if (!match) return undefined
 
   return { major: Number(match[1]), minor: Number(match[2]) }
@@ -71,6 +84,54 @@ function next(label: Label): Label {
     : { major: label.major, minor: label.minor + 1 }
 }
 
+function noBoard(root: string, dir: string): LabelRefused {
+  return {
+    ok: false,
+    reason: 'no-board',
+    message: `No task board at ${relative(root, dir)}.`,
+  }
+}
+
+function reservationsDir(root: string): string {
+  return recordDir(root, 'ordinal-locks')
+}
+
+async function listReservations(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(reservationsDir(root), {
+      withFileTypes: true,
+    })
+    return entries.filter((entry) => entry.isDirectory()).map((e) => e.name)
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return []
+    }
+    throw error
+  }
+}
+
+function highestOf(
+  names: readonly string[],
+  pattern: RegExp,
+): Label | undefined {
+  return names
+    .map((name) => parseLabel(name, pattern))
+    .filter((label): label is Label => label !== undefined)
+    .reduce<Label | undefined>(
+      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
+      undefined,
+    )
+}
+
+async function readStems(root: string): Promise<string[]> {
+  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
+    existsSync(candidate),
+  )
+  const dirs = [tasksDir(root), ...settled]
+
+  return (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+}
+
 /**
  * Reports the next unused phase label, read off the true maximum across
  * `.canon/tasks/` and its `archive/` and `declined/` siblings together. A scan
@@ -78,41 +139,87 @@ function next(label: Label): Label {
  * spent, which is what let two sessions hand out the same label within
  * minutes of each other.
  *
- * It reports and never writes. Two sessions calling it in the same second can
- * still take the same answer, since the board is gitignored files rather than
- * a store with a lock, and `standards/versioning.md` permits free renumbering,
- * so a collision costs a rename rather than anything worse. A duplicate label
- * already sitting in the tree, and a gap left by a renumbering, both fold into
- * the same max scan without needing a dedicated check.
+ * It reports and never writes. `claimLabel` is the variant that reserves. A
+ * duplicate label already sitting in the tree, and a gap left by a
+ * renumbering, both fold into the same max scan without needing a dedicated
+ * check.
  */
 export async function nextLabel(root: string): Promise<LabelOutcome> {
   const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
 
-  if (!existsSync(dir)) {
-    return {
-      ok: false,
-      reason: 'no-board',
-      message: `No task board at ${relative(root, dir)}.`,
-    }
+  const highest = highestOf(await readStems(root), LABEL_PATTERN)
+
+  return {
+    ok: true,
+    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
+    highest: highest === undefined ? undefined : formatLabel(highest),
+    claimed: false,
   }
+}
 
-  const settled = [archiveDir(root), declinedDir(root)].filter((candidate) =>
-    existsSync(candidate),
-  )
-  const dirs = [dir, ...settled]
-  const stems = (await Promise.all(dirs.map((d) => listTaskStems(d)))).flat()
+interface ClaimOptions {
+  /** Takes the reservation, resolving false when another claim holds it. */
+  readonly reserve?: (root: string, label: string) => Promise<boolean>
+}
 
-  const highest = stems
-    .map(parseLabel)
-    .filter((label): label is Label => label !== undefined)
-    .reduce<Label | undefined>(
-      (max, label) => (max === undefined || isHigher(label, max) ? label : max),
-      undefined,
+async function reserveLabel(root: string, label: string): Promise<boolean> {
+  await mkdir(reservationsDir(root), { recursive: true })
+
+  try {
+    await mkdir(recordDir(root, 'ordinal-locks', label), { recursive: false })
+    return true
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+      return false
+    }
+    throw error
+  }
+}
+
+/**
+ * Reserves the next label through an exclusive `mkdir` under
+ * `.canon/ordinal-locks/`, so a second claim lands on a different one.
+ *
+ * The scan counts every reservation beside the task stems. The skill writes
+ * the task file after this returns, so a reservation with no file behind it is
+ * the ordinary state for a few seconds, and a scan blind to it would offer the
+ * same label to every retry. Reservations are never expired: a claim that died
+ * leaves a gap, and `standards/versioning.md` permits gaps.
+ */
+export async function claimLabel(
+  root: string,
+  options: ClaimOptions = {},
+): Promise<LabelOutcome> {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) return noBoard(root, dir)
+
+  const reserve = options.reserve ?? reserveLabel
+
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    const stems = highestOf(await readStems(root), LABEL_PATTERN)
+    const held = highestOf(await listReservations(root), RESERVATION_PATTERN)
+    const highest =
+      stems !== undefined && (held === undefined || isHigher(stems, held))
+        ? stems
+        : held
+    const label = formatLabel(
+      highest === undefined ? FIRST_LABEL : next(highest),
     )
 
+    if (await reserve(root, label)) {
+      return {
+        ok: true,
+        label,
+        highest: highest === undefined ? undefined : formatLabel(highest),
+        claimed: true,
+      }
+    }
+  }
+
   return {
-    ok: true,
-    label: formatLabel(highest === undefined ? FIRST_LABEL : next(highest)),
-    highest: highest === undefined ? undefined : formatLabel(highest),
+    ok: false,
+    reason: 'label-contended',
+    message: `Could not reserve a label after ${MAX_ATTEMPTS} attempts. Re-run the claim.`,
   }
 }

package/standards/readme.md

@@ -63,6 +63,7 @@ The opening of a root README is a block of up to six elements in a fixed order.
 The description of 2-3 sentences follows the block and expands the claim rather than repeating it.
 
 - A project with no page omits the link and the screenshot. A library or a CLI reads as a complete block with a title, badges, and a claim.
+- A project whose own page carries the screenshot omits it here and keeps the live link, which answers the slot rather than skipping it. Say so in the pull request that drops it.
 - The order is the block's rather than the page's. The screenshot sits last inside the block, which puts it in the first row of content a reader meets below the title, badges, and claim.
 - A themed light and dark pair counts as one element in the slot rather than two. The block does not require a pair and leaves the handling of themes to the project.
 - Centering the block in an HTML wrapper is optional. Plain markdown reaches every host a README renders on, and a wrapper is styling a project can add.