@erclx/canon 5.56.0 → 5.58.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [5.58.0](https://github.com/erclx/canon/compare/v5.57.0...v5.58.0) (2026-10-24)
+
+
+### Features
+
+* **governance:** widen design-taste paths to component files ([#2645](https://github.com/erclx/canon/issues/2645)) ([01b1445](https://github.com/erclx/canon/commit/01b144514eced1150c90b18acc78f0be33990a23))
+* **rules:** route interface changes to api-design ([#2647](https://github.com/erclx/canon/issues/2647)) ([09a073c](https://github.com/erclx/canon/commit/09a073ca38324a399de5c2c2e702fbcede6bb38c))
+* **skills:** offer a restructure before document-repair rewrites ([#2648](https://github.com/erclx/canon/issues/2648)) ([7c2776a](https://github.com/erclx/canon/commit/7c2776a95b86a6626c44e399056b9eaa22418d65))
+
+
+### Bug Fixes
+
+* **context:** count table rows toward no folder paragraph ([#2646](https://github.com/erclx/canon/issues/2646)) ([a99b020](https://github.com/erclx/canon/commit/a99b02064105b81bc3a4f6e4820c73198942785e))
+
+## [5.57.0](https://github.com/erclx/canon/compare/v5.56.0...v5.57.0) (2026-10-24)
+
+
+### Features
+
+* **git-followup:** ship unpushed commits from a clean tree ([#2643](https://github.com/erclx/canon/issues/2643)) ([73bdfbd](https://github.com/erclx/canon/commit/73bdfbdb25ad0a8e76cfbaa57086c8fe058485fe))
+* **plan-feature:** run the existing surface before planning ([#2634](https://github.com/erclx/canon/issues/2634)) ([53c4b93](https://github.com/erclx/canon/commit/53c4b936ed89d42122e251f638e87791278ef883))
+* **pr:** claim root files named in Key changes code spans ([#2639](https://github.com/erclx/canon/issues/2639)) ([6d9e368](https://github.com/erclx/canon/commit/6d9e368d0b6dcda568c3140b1053206fd1038864))
+* **skills:** add run placement and binary rules to planner onboarding ([#2642](https://github.com/erclx/canon/issues/2642)) ([e211beb](https://github.com/erclx/canon/commit/e211bebbc35a709e907fb3dbb0eef75f1d791b42))
+* **skills:** run a repro during intake and triage ([#2638](https://github.com/erclx/canon/issues/2638)) ([82e1fb4](https://github.com/erclx/canon/commit/82e1fb4bdb54eefcea910cf745c80623a8f8368c))
+* **skills:** triage asks plan, ask, or decline ([#2641](https://github.com/erclx/canon/issues/2641)) ([2502248](https://github.com/erclx/canon/commit/2502248fe5ce4ad7dd11a4b27c8f4297ba654fa1))
+* **target-update:** write on a worktree or its own branch ([#2640](https://github.com/erclx/canon/issues/2640)) ([73f2603](https://github.com/erclx/canon/commit/73f2603e034f63397e1b878368aa69d8d4275aaf))
+* **tasks:** resolve closes from the checked-out branch ([#2637](https://github.com/erclx/canon/issues/2637)) ([873834c](https://github.com/erclx/canon/commit/873834c69b8de11efe16bbdaa06187b9328e9738))
+
 ## [5.56.0](https://github.com/erclx/canon/compare/v5.55.0...v5.56.0) (2026-10-23)
 
 

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.56.0",
+  "version": "5.58.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-feedback-triage/SKILL.md

@@ -53,10 +53,12 @@ For each remaining issue, measure its claim against the tree during this pass, n
 - Grep for the construct its defect names and count the sites
 - Check whether the behavior it asks for exists
 - Search the log for a commit or pull request that shipped it under another task
+- Run the issue's Repro section in a form that writes nothing when it is one command that works here, and say on `Problem:` what it showed
+- Mark the item `not reproduced here` when the repro names another project's paths or needs more, per `## Repro versus groundwork` in the intake standard
 
 Classify each against the toolkit's own surfaces:
 
-- **Direct fix.** One surface, one file, no architectural choice. A typo, a stale reference, a one-line correction.
+- **Direct fix.** A size, not an answer, so it suggests `plan` and `Fix:` says a short plan covers it. One surface, one file, no architectural choice. A typo, a stale reference, a one-line correction.
 - **Plan-worthy.** Multiple files, a new skill or rule, a behavior change, or a cross-surface move.
 - **Needs clarification.** The observed and expected behavior conflict or the surface is unnamed. The item asks the operator for the missing detail.
 
@@ -70,7 +72,7 @@ Write one item per issue in the intake item format, one cluster file per domain
 
 - `Problem:` states what this pass measured, with the count, path, or commit behind it
 - `Fix:` states the class from Step 4 and the change it names
-- `Open:` reads `fix, plan, ask, or decline?` on every item
+- `Open:` reads `plan, ask, or decline?` on every item
 - `Suggested:` opens with exactly one of those tokens, then the reason
 - `You:` ships empty
 
@@ -83,14 +85,14 @@ Write `00-overview.md` last, per the intake standard, with the counts by token,
 
 **Filed:** <N> issues across <N> clusters, measured against <sha>
 **Skipped:** <n> already carried
-**Suggested:** <n> fix, <n> plan, <n> ask, <n> decline
+**Suggested:** <n> plan, <n> ask, <n> decline
 
 Next: /canon:plan-intake-answer to answer the `You:` slots
 ```
 
-An answered fix or plan item promotes through `task-board` with an `Issue: #NNN` line, and the shipping pull request's `Closes #NNN` drains the queue. Closing a declined issue on GitHub stays the operator's act.
+An answered plan item promotes through `task-board` with an `Issue: #NNN` line, and the shipping pull request's `Closes #NNN` drains the queue. Closing a declined issue on GitHub stays the operator's act.
 
 ## Notes
 
 - The `feedback` label is what `canon feedback` and the `toolkit-feedback.yml` issue form both apply.
-- This skill files and never reimplements. `plan-intake-answer` owns the answers and `task-board` owns the task a fix becomes.
+- This skill files and never reimplements. `plan-intake-answer` owns the answers and `task-board` owns the task a plan item becomes.

package/claude/skills/context-fold/references/context.md

@@ -71,7 +71,7 @@ An entry carries three H2 sections and no other, being `Overview`, `Layout`, and
 
 Layout gives each folder doing real work its own H3, titled with the folder path in a code span, such as ``### `src/design/` ``.
 
-- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now
+- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now. A table after the lead counts toward neither, with one sentence to lead the bullets
 - Put every trivial folder under `### Other folders` as a one-line bullet in owns-X form
 - Name folders only, never files, and write no decisions and no history under any H3
 - Give each folder under the code roots one H3 or `Other folders` line, since a second entry may cite it but never claims it

package/claude/skills/document-health/REQUIREMENT.md

@@ -13,8 +13,8 @@ Length, placement, and staleness answer to different evidence, and one list hand
 
 ## Must
 
-- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class
-- Read length and placement through the verb owning each measurement, and take every checkpoint from the record the verb returns
+- Report per document across the length, placement, and staleness axes, marking each finding with its evidence class, read through the verb owning each measurement and its record's checkpoints
+- Propose a split or an owner as a structure line for each overgrown entry and doubled or unnamed coverage finding, with the headings and the reason
 - Ship the staleness axis as a reading rather than cutting it for lacking a verb
 - Report a refusal, an absent key, or a missing subcommand as an unread axis naming the cause, and say which layer answered the classifier sweep
 - Run standalone, read the requirements record for identity drift when the scope reaches it, and print the `canon records stale canonical` reminder

package/claude/skills/document-health/SKILL.md

@@ -47,6 +47,12 @@ The first names the backend, the model, and the source that decided both. Report
 
 Take the checkpoints from the record each verb returns rather than from a number written here. A checkpoint the CLI moves reaches this report with no edit, and a number held in this body goes stale on its own cadence.
 
+### The structure line
+
+The context audit record already carries what a restructure needs, so the placement axis gains a structure line per area folder and runs no further verb. `${CLAUDE_SKILL_DIR}/references/axes.md` holds how to read `length` and `coverage` into a proposed split or owner.
+
+Emit the line only for a folder with an entry past the line checkpoint whose Layout headings group into two or more domains, or with a doubled or unnamed coverage finding. A folder with neither gets no line, and `document-repair` goes straight to its rewrite.
+
 ### An unread axis is not a healthy one
 
 A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
@@ -106,4 +112,12 @@ When Step 3 read the canonical records, add one reminder line per doc the verb r
 
 Write `reviewed value is not a date: <value>` for a doc carrying `invalidReviewed`, and `no release tags to count` in place of the count when `tagged` is false. Name the unread cause instead when the verb refused or the binary carries no `canonical` kind.
 
+Under the table, add one structure line per area folder that earned one, naming the entry and the split, or the finding and its owner:
+
+```markdown
+Structure `canon/context/surfaces/`: `cli.md` (300 lines) splits into `cli.md` taking <headings> and `cli-<domain>.md` taking <headings>, because <reason>.
+```
+
+The line is a proposal for the operator, with the headings each entry takes and why. Health applies nothing, and `document-repair` offers the proposal before it rewrites.
+
 Keep the evidence line under the table on every run. A table read without it flattens a judgment into a measurement, which is the one shape the three classes exist to prevent.

package/claude/skills/document-health/references/axes.md

@@ -54,6 +54,18 @@ The sweep classifies each section as keep, replace or rewrite, history, or move.
 - A low-confidence `move` is a prompt to look rather than an instruction to cut
 - **Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
 
+### The structure line
+
+The audit record's `length` array lists each entry past the line checkpoint, and `coverage.findings` lists the `doubled` and `unnamed` ones. The structure line reads both, so it carries the `measured` class for the finding and `read` for the proposal built on it.
+
+- **Overgrown entry:** read its `causes` in `length` first, since `history: yes` points at cutting provenance and one domain at a trim, so neither earns a split
+- **Split:** group the Layout headings by domain, one new entry per group beyond the first, naming each entry's headings and one reason
+- **Domain boundaries:** no verb measures one, so state the grouping as a judgment.
+- **Doubled coverage:** two entries describe one source area. Propose the one that owns it, from which entry already holds the area's traps, and the other points at it.
+- **Unnamed coverage:** no entry names the area. Propose an owner among the existing entries before a new one, since a new entry is the larger change.
+
+A proposal names headings and a reason, so an operator judges a concrete split. A split nobody can act on names none of those.
+
 ### When a verb resolves nothing
 
 Both verbs resolve their folders by surface root rather than by a path written into them, so a project laid out differently resolves nothing. The two degrade differently.

package/claude/skills/document-repair/REQUIREMENT.md

@@ -15,14 +15,19 @@ A folder repaired by hand also drifts back, since a target gates nothing until a
 
 - Each batch takes one folder and leaves it at zero findings or reports it ungated
 - A folder gates only through `canon markdown gated add`, which refuses one with a finding left
-- A rewrite keeps every stated reason, command, and path the original carried
+- A rewrite keeps every stated reason, command, and path the original carried, and leaves a context entry no more shape findings than it started with
 - The body names the verbs and states no limit number
 - A requirement gates by its own path, never through a folder prefix
 
+## Restructure first
+
+An overgrown context folder is offered the restructure `document-health` proposes before any rewrite, and the restructure applies only on the operator's word.
+
 ## Must not
 
 - Edit `canon/config/markdown.toml` by hand
 - Report a folder gated that the verb refused
+- Reach zero density findings by growing the context shape findings
 - Change what a document claims to pass the audit
 - Be reachable only by its name, since `document-health` names it for every length finding
 

package/claude/skills/document-repair/SKILL.md

@@ -18,6 +18,15 @@ The CLI holds every number. `canon markdown audit` measures, and `canon markdown
 - `gated add` refusing with `canon-checkout`: stop. Canon's own checkout gates through a constant in its source, which a code change edits.
 - Branch on each record's own fields rather than on an exit status a shell wrapper can flatten. A call with no terminal on stdin already runs headless, so no command takes a prefix.
 
+## Step 0: offer the restructure
+
+Restructure an overgrown context folder before rewriting it, so the effort is spent once. Run this step only when `canon/context/` is a candidate, meaning it is not yet listed in `canon/config/markdown.toml`, and skip it silently otherwise.
+
+- Take the structure line `document-health` reports for each area folder, or read it from `canon context audit --json` the way that skill does
+- A folder with no overgrown entry and no doubled or unnamed coverage finding has no line, so go straight to Step 1 with no prompt
+- Show the operator each proposal and ask before applying it, since a split moves files other entries cite. Re-run the audit afterward to confirm the citations still resolve.
+- Take a declined proposal as a decision and rewrite the entry as it stands
+
 ## Step 1: read the audit
 
 Run the audit over the whole tree and take the density and reference shape findings from its record:
@@ -26,6 +35,12 @@ Run the audit over the whole tree and take the density and reference shape findi
 canon markdown audit --json
 ```
 
+When `canon/context/` is a candidate, read the context shape beside it and keep each entry's `shapeFindings` issues as the baseline Step 3 holds the rewrite to:
+
+```bash
+canon context audit --json
+```
+
 Take the candidate folders from the order table in `${CLAUDE_SKILL_DIR}/references/batches.md` rather than from the findings, since a clean folder carries no finding and would never be gated. Drop every folder `canon/config/markdown.toml` already lists, since a listed folder already gates.
 
 Sort what is left in two. A candidate the findings never name needs no rewrite, so gate it through Step 4 before the first batch. Group the findings under the rest, which Steps 2 and 3 rewrite.
@@ -46,6 +61,12 @@ canon markdown audit <prefix> --json
 
 Read `${CLAUDE_SKILL_DIR}/references/batches.md` for what a rewrite may cut. A stated reason survives every rewrite, and the audit reaching zero cannot see one that went missing.
 
+### Hold the context shape
+
+For a file under a folder the context audit resolves, also re-run `canon context audit --json` and compare the entry's `shapeFindings` issues with the baseline. A density fix that splits a Layout paragraph into several can grow `layout-paragraphs`.
+
+A rewrite leaving the entry with more shape issues than it started with is not done. Undo it, or fold the split into a table or a linked page, and report the entry as stopped when neither reaches the baseline. Zero density findings reached by growing shape findings only moves the failure.
+
 ## Step 4: gate the folder
 
 ```bash

package/claude/skills/git-followup/REQUIREMENT.md

@@ -9,19 +9,19 @@ description: What the follow-up push is for, the gaps it closes, and how it spli
 
 Without this skill, an edit made after a pull request opens ships as a bare push. The body still describes the scope from before the edit, and a review fix always changes what shipped, so the description a merge records is false by the time review ends. A reviewer who left comments gets no reply, or a second one under the caller's own.
 
-The push itself fails on two branch shapes. A caller that rebased before handing over hits a rejected push, and a branch entered through a worktree carries an open pull request with no tracking ref, which reads as a branch never pushed.
+The push itself fails on two branch shapes. A caller that rebased before handing over hits a rejected push, and a branch entered through a worktree carries an open pull request with no tracking ref, which reads as a branch never pushed. A session that committed in slices arrives with a clean tree and is stopped by a guard that reads only the tree.
 
 ## Must
 
-- Every follow-up commit syncs the body when it moves the scope, and the title when the shift makes it inaccurate, whether or not a reply runs
-- The message comes from `git-commit`, so a follow-up reads like every other commit
+- Unpushed commits ship like uncommitted ones, with staging and the commit skipped on a clean tree, and a commit this skill makes takes its message from `git-commit`
+- Every follow-up syncs the body when it moves the scope, and the title when the shift makes it inaccurate, whether or not a reply runs
 - A pull request carrying review comments gets one reply, scanned for banned characters and phase labels and posted through a file, and none when the caller owns it
 - The push lands on a branch with no tracking ref, and on a rebased one under a lease that protects a commit this session never read
 - The evidence is posted through `pr-evidence` and read back with `canon pr evidence <number> --check --json`
 
 ## Must not
 
-- Run on `main`, or with nothing changed
+- Run on `main`, on a detached head, or with nothing to stage and nothing to push
 - Open a pull request. A missing one is the stop.
 - Post a second reply when the caller has already replied
 - Emit anything after the result line

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

@@ -1,6 +1,6 @@
 ---
 name: git-followup
-description: Ships a small self-review edit on the current PR branch by staging, committing, pushing, and syncing the open PR, replying on the PR when it carries review comments. Use when asked to "ship a followup", "push the PR fix", "followup", or "commit and push this small change". Do NOT use when there is no open PR for the branch (use git-ship instead).
+description: Ships a small self-review edit on the current PR branch by staging, committing, pushing, and syncing the open PR, replying on the PR when it carries review comments. A clean tree with unpushed commits skips the staging and commit. Use when asked to "ship a followup", "push the PR fix", "followup", or "commit and push this small change". Do NOT use when there is no open PR for the branch (use git-ship instead).
 metadata:
   family: after-pr
 ---
@@ -15,7 +15,11 @@ its own reply, so skip the comment in step 7. The push and body sync still run.
 ## Guards
 
 - If `git branch --show-current` returns `main`, stop: `❌ On main. Switch to a PR branch first.`
-- If `git status --porcelain` is empty, stop: `❌ No changes to ship.`
+- If `git branch --show-current` is empty, stop: `❌ Detached HEAD. Checkout the PR branch first.` This runs ahead of the next guard, which reads `@{u}`.
+- If `git status --porcelain` is empty and no commit is unpushed, stop: `❌ No changes to ship.`
+  - A commit is unpushed when `git rev-list @{u}..HEAD` lists one
+  - Count against `origin/<branch>` when `@{u}` does not resolve and that ref does
+  - Every commit is unpushed only when neither ref resolves
 - Resolve `<number>` once, here, through `canon pr head --json`, reading the record's `number`. Every later step names this `<number>` rather than resolving it again.
 - A record refusing with `ambiguous-pull` stops: `❌ Two open PRs on this branch. Name the one to update.`
 
@@ -38,6 +42,8 @@ A missing tracking ref is not a guard, since an open pull request proves the bra
 
 ## Sequence
 
+Steps 1 to 3 run only when the tree is dirty. A clean tree carrying unpushed commits already holds its commits, so it starts at step 4.
+
 1. Run `git status` to confirm the changes are intentional
 2. Run `git add -A` to stage every change
 3. Invoke `canon:git-commit` to generate one conventional commit from the staged diff

package/claude/skills/git-pr/references/closing-issues.md

@@ -15,6 +15,14 @@ The plan is the one `task-number.md` names, so reuse the filename an earlier ste
 canon tasks closes --plan feature-<slug> --json
 ```
 
+A branch with no plan runs the verb bare:
+
+```bash
+canon tasks closes --json
+```
+
+The bare call matches the branch against `feat/<slug>` for each task's plan and the names the branch carried before a rename. A planned branch under any other name reads `no-match` and writes no closing line, so pass `--plan` for it.
+
 The verb reads the current branch itself and counts the names it carried before a rename, so pass nothing else. Branch on the record rather than the exit code.
 
 | Record                                              | Route                                                                              |

package/claude/skills/plan-feature/REQUIREMENT.md

@@ -13,7 +13,7 @@ A constraint naming a surface to leave alone forbids two acts at once, conformin
 
 ## Must
 
-- Read the project's Claude setup before scanning source, and name every file the work touches with the reason it is touched
+- Read the project's Claude setup and the domain's context entry, run the existing thing once read-only, then scan source, and name every file touched with its reason
 - Reframe a vague ask as observable success criteria, carry each into the plan's verification, and ask when none can be predicted
 - Slice by user-visible path with the riskiest batch first, and fold a stacked batch sharing most of its files into its parent unless the plan says why they differ
 - Quote the fetched passage behind each outside source, mark an unfetched one unverified, and place each new path against the layout guidance with a one-clause reason
@@ -23,6 +23,7 @@ A constraint naming a surface to leave alone forbids two acts at once, conformin
 
 - Implement, or edit any file the plan describes
 - Read directories speculatively, since context spent on files the feature does not touch is context the plan does not get
+- Run a form that writes to the tree being planned against, since a planner writes its plan and nothing else
 - Bundle independent concerns into one plan
 - Restate the plan in chat during follow-up rounds, since the file is the source of truth
 

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

@@ -13,6 +13,13 @@ metadata:
 - Do not implement anything. Output the plan and stop.
 - When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
 
+## Write scope
+
+Write the plan, and nothing else in the tree being planned against.
+
+- A file made only to look at goes to scratch under a topic slug, per `${CLAUDE_SKILL_DIR}/references/onboarding.md`
+- A fixture or headless session that must be its own project goes outside the repository, in a temporary directory
+
 ### Predict the next three questions
 
 Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each. The test reads the ask's success criteria, never the plan's open questions.
@@ -33,7 +40,15 @@ Also read `canon/DESIGN.md` when the feature touches code or UI, for visual inte
 
 Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
 
-## Step 2: scan relevant source files
+### Read the domain's context entry
+
+Onboard to each domain the feature touches before reading its code, through its context entry. Read `${CLAUDE_SKILL_DIR}/references/onboarding.md` for the lookup.
+
+## Step 2: run the surface, then scan relevant source files
+
+When the feature changes a verb, a route, or a rendered surface that already exists, run it once before reading its code and record what it showed. Read `${CLAUDE_SKILL_DIR}/references/onboarding.md` for the safe form per surface kind, the rules that keep the run from writing, and the not-run record.
+
+### Read the code
 
 Read the source files directly relevant to the feature, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
@@ -59,6 +74,7 @@ The section list, what each section holds, and the suggested-and-answer contract
 
 What this skill adds on top of the standard:
 
+- Record each command Step 2 ran and what it showed, or the not-run reason, under `## Current behavior`, and omit the section when nothing ran
 - Reframe a vague ask as success criteria before `## Files to touch`, each an observable result and its check, which becomes one `## Verification` bullet. "Make it faster" names none.
 - Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
 - Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
@@ -68,7 +84,7 @@ What this skill adds on top of the standard:
 Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
 
 - Suggest a real default when best practice, the codebase, or prior context points to one
-- Load `canon:codebase-layout` before `## Files to touch` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Before `## Files to touch`, load `canon:codebase-layout` for a new path (its reason) and `canon:api-design` for a changed verb, flag, output, record shape, or endpoint. Report either if missing.
 - Fill `## Design references` with the `canon/design/<surface>/` folder for each surface a UI file in `## Files to touch` renders, and write `None identified.` in a project with no folder
 - Write `## Verification` as one bullet per outcome naming the test or command that proves it
 - Write `## Review focus` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer

package/claude/skills/plan-feature/references/onboarding.md

@@ -0,0 +1,51 @@
+---
+title: Onboarding to a domain
+description: The context lookup, the safe run form per surface kind, and the not-run record a planner takes before reading code
+---
+
+# Onboarding to a domain
+
+Applies to the first two reads of `plan-feature` Step 1 and Step 2, taken ahead of the source. They go cheapest first, being the context entry, then one run of the existing thing, then the code. A plan starting from the source alone inherits whatever the running code gets wrong.
+
+## Read the context entry
+
+- Run `canon indexes list --json canon/context` and read the entries whose title or description matches the domain, rather than walking the folder
+- Report none and continue to the run when the project has no `canon/context/` folder or no entry matches
+- Treat an entry as a claim about the code, to be confirmed by the run
+
+## Run the existing thing once
+
+When the feature changes a verb, a route, or a rendered surface that already exists, run it once in a form that writes nothing. Record the command and what it showed.
+
+| Surface kind     | Safe form                                                                    |
+| ---------------- | ---------------------------------------------------------------------------- |
+| CLI verb         | its read verb, or the `--check` or `--dry-run` form, with `--help` for flags |
+| Route or API     | one read request against a running instance                                  |
+| Rendered surface | a capture against a running preview                                          |
+| Anything else    | the project's own read command, or a sandbox scenario                        |
+
+Three rules hold across every kind:
+
+- Write nothing into the planned tree beyond the plan, so never run a form that writes there. The exceptions are the scratch and outside-repository writes below.
+- Send a verb with no read form to a sandbox scenario or a temporary copy, and name which
+- Skip the step for a feature touching nothing that runs, such as prose or a config seed
+
+## Place the run and its output
+
+A checkout is often shared with sessions building other branches, so where a run happens matters as much as what it runs.
+
+- Keep a read-only run in the checkout and never switch its branch, since a switch changes the files under every other session reading it
+- Serve a preview on a free port only when it writes nothing, and run one that builds from a temporary copy, since a build leaves caches and output under the checkout
+- Send a file made only to look at, such as a capture or a dump, to a scratch topic slug under the scratch rule, which owns the path and the reserved slugs
+- Put an own-project fixture or headless session outside the repository, since a tool that walks up to a project root measures the enclosing repository
+- Keep the plan's own text as the record of what a run showed, since scratch is gitignored and no later session reads it
+
+### Name the binary a run measured
+
+A run against the toolkit itself can reach the installed binary or the checkout's own build, and the two answer differently once the branch has moved. State which one ran, with its version or path, beside the command in `## Current behavior`.
+
+## Record a run that did not happen
+
+Write the surface as not run with the reason, such as a broken build, a preview that will not start, or a verb with no read form that no sandbox scenario or temporary copy can reach. A skipped run with no record reads the same as one nobody considered.
+
+Step 3 writes each run, or its not-run reason, into `## Current behavior`.

package/claude/skills/plan-feature/references/plan.md

@@ -72,6 +72,7 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | Section                | Holds                                                                       | Required                                          |
 | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
 | `## Summary`           | three to five one-line bullets: the goal, the deliverables, the trade-off   | Always                                            |
+| `## Current behavior`  | each command run against the thing being changed and what it showed         | When the change touches something that runs       |
 | `## Constraints`       | durable rules the work must respect                                         | When supplied                                     |
 | `## Files to touch`    | each file with a one-line reason                                            | Always                                            |
 | `## Design references` | the tracked design folders the change builds against, each with its surface | When Files to touch names a rendered-surface file |
@@ -81,6 +82,8 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `## Questions`         | numbered open decisions, each with a suggestion and an answer slot          | Always                                            |
 | `## Sources`           | the outside sources a decision rests on, each with its quoted passage       | When a decision rests on an outside source        |
 
+### Writing a section
+
 Four rules govern how a section is written:
 
 - Write each section as the H2 the table gives, so a reader scans the plan by its outline
@@ -126,6 +129,15 @@ State every count and every claim about the tree as measured during the pass tha
 
 Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 
+### Current behavior
+
+A plan changing a verb, a route, or a rendered surface starts from what that thing does today, so the section records the run the planner made and not a reading of the source.
+
+- Write one bullet per run, leading with the command or request in backticks and ending on what it showed
+- Run only a read form, per the safe forms in `onboarding.md`, since a planner writes its plan and nothing else
+- Record a run that could not happen as not run with the reason. Never leave it out silently.
+- Leave the section out of a plan touching nothing that runs, such as prose or a config seed
+
 ### Constraints
 
 Work in flight reaches a plan as a hold or as a shared path. A hold leaves a surface alone and says which of two acts it forbids, rather than leaving the executing session to guess. Neither act is forbidden over a shared path.
@@ -259,6 +271,10 @@ Each H3 below shows where a section groups once it passes 5 bullets. A section o
 - <one-line bullet covering the main deliverables>
 - <one-line bullet covering the key decision or trade-off>
 
+## Current behavior
+
+- `<command or request>`: <what it showed, or not run and why>
+
 ## Constraints
 
 Measured against `<commit>` on <YYYY-MM-DD>.

package/claude/skills/plan-groundwork/SKILL.md

@@ -98,7 +98,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: scope and non-goals
 - `.canon/tasks/index.md`: what is already tracked, and what a prior track concluded. Open a task file only when its entry looks related.
 
-Then read only what a live question needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+Then read only what a live question needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at. For each domain the topic touches, read its context entry ahead of measuring, through the lookup in `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`.
 
 Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
 

package/claude/skills/plan-intake/REQUIREMENT.md

@@ -7,15 +7,15 @@ description: Why a brain dump gets a filed inventory rather than ten plans, and
 
 ## Gap
 
-A brain dump reaches a session with nowhere to put it. One plan per concern turns forty findings into ten plans before anything is measured, and what gets filed instead is a list of opinions, because nothing forces a count against the tree.
+A brain dump reaches a session with nowhere to put it. One plan per concern turns forty findings into ten plans before anything is measured, and what gets filed instead is a list of opinions, because nothing forces a count against the tree. A defect confirmed from source alone reads the same as one that was run.
 
 An empty operator slot reads as consent under a blank-means-accept contract, which ships changes nobody approved. A report naming only a path hides what moved. A question filed without a pick comes back unresolved, and a pass with no write scope starts fixing what it files.
 
 ## Must
 
 - Route each item on whether the repository can answer it today, sending experiments to `plan-groundwork` and decided work to `plan-feature`
-- Measure every problem line against the tree, close every item with a verdict, and pair every open question with a suggested pick
-- Treat an empty operator slot as unread, and keep answers on items with the index pointing at them
+- Measure every problem line against the tree, running a defect's one-command repro read-only or marking it not reproduced here
+- Close every item with a verdict and a suggested pick on each question, and treat an empty operator slot as unread
 - Reserve the index number, carry the domain in every other filename, and number a new folder past the highest ordinal across intake and groundwork
 - Confine writes to the intake folder and name the heading and the act beside every path written
 

package/claude/skills/plan-intake/SKILL.md

@@ -63,10 +63,14 @@ Read these in parallel from the project root, skipping any that do not exist:
 
 Then read only what a live item needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
+For each domain an item touches, read its context entry through the lookup in `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`, since the entry records the traps a grep will not show.
+
 ## Step 3: measure against the tree
 
 Grep for each construct an item names and count the sites. Every problem line carries a number or a file path taken during this pass.
 
+When an item reports a defect with a one-command repro, run it in a read-only form and say on the `Problem:` line what it showed, or that it was not reproduced here. Read `${CLAUDE_SKILL_DIR}/references/intake.md` for where one command ends and groundwork begins.
+
 - Never carry a figure from an earlier session, a summary, or another document. The tree states the size of a complaint, and that is what separates an inventory from opinions.
 - Confirm any work an item sequences behind is still open, so no item leads with something already shipped
 - Name the commit the pass measured against in the overview body, since that is the half a later reader can check

package/claude/skills/plan-intake/references/intake.md

@@ -19,6 +19,7 @@ The folder is gitignored. Where a records remote is configured, `canon records p
 - [Files](#files)
 - [Frontmatter and dating](#frontmatter-and-dating)
 - [00-overview.md](#00-overviewmd) <!-- canon-allow-reference: a heading anchor, not a pull request number -->
+- [Repro versus groundwork](#repro-versus-groundwork)
 - [Item format](#item-format)
 - [The answer contract](#the-answer-contract)
 - [Retrieval](#retrieval)
@@ -99,6 +100,15 @@ The index carries no answer slot. One question in two answerable places has no r
 
 Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
 
+## Repro versus groundwork
+
+An item whose claim is a defect may carry one run of its repro, and the run is where intake's measuring stops. A repro that needs more is groundwork's.
+
+- Run one command in a form that writes nothing, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/onboarding.md`, and put what it showed on `Problem:`
+- Mark the item `not reproduced here` on the same line when the repro needs a fixture project, repeated runs, a write, or another project's paths
+- Send the marked item to `plan-groundwork` only when its answer decides a plan, since a claim read from code alone is a reported defect and not a confirmed one
+- Never adapt a repro silently, because a changed command measures something the reporter did not
+
 ## Item format
 
 ```markdown

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

@@ -82,7 +82,7 @@ This skill owns the reply, so do not reimplement the followup flow here.
 
 - `git-followup` syncs the body and title on every invocation, `reply-owned` included, so the merge record reflects this pass. The reply still maps fixes to findings in the review's own thread.
 - A rebase in step 5 rewrote the branch, so the push is a force-push `git-followup` resolves from the tracking branch. Worker branches are single-owner, which makes that safe.
-- `git-followup` stops on an unchanged tree, as when every finding was a conscious-accept and the rebase left generated files alone. Push that with `git push --force-with-lease`.
+- `git-followup` runs on a clean tree too, since the rebased commits are ahead of the tracking branch. A pass of conscious-accepts after a rebase pushes through it and syncs the body like any other.
 
 Once the fixes are commits, re-run step 5's staleness test against the new head. A conflict appearing only now is one the fixes introduced against lines `main` moved, so rebase again under `${CLAUDE_SKILL_DIR}/references/rebase-conflicts.md` and force-push.
 

package/claude/skills/target-update/REQUIREMENT.md

@@ -17,6 +17,7 @@ The verbs report every fact, so the gap is the judgment between them. A session
 - Read every fact from a `canon` verb, so a later release changes what the skill reports with no edit to its body
 - Stop and ask on a refused migration, a stranded file, an unattributed folder, and a rule the stack newly ships
 - Keep a customized file and a drifted seed as the project wrote them, naming the toolkit change each one skipped
+- Keep the shared checkout on its branch, writing on a worktree or a declined-worktree branch the preview names
 - End on a clean `target-check` or on named remainders, with nothing written when nothing is pending
 
 ## Must not

package/claude/skills/target-update/SKILL.md

@@ -66,6 +66,8 @@ Target update: `<path>`, canon `<installed>` to `<running>`.
 
 **Drift:** <each non-empty cause from sync --check, with its count and paths>
 
+**Where it lands:** <the linked worktree this run is already in, or the worktree `.claude/worktrees/<name>/` it will enter, or the branch it will create in place when the operator declines a worktree>
+
 **Calls for you:** <each judgment call below this run meets, with the default this skill takes>
 
 **Commands, in order:** <the exact commands Steps 4 to 6 will run>
@@ -77,6 +79,26 @@ Summarize the changelog for this project, not for the toolkit. Drop an entry tha
 
 When the changelog range is empty, `migrate status` lists nothing pending or refused, and the drift lines hold nothing a step here would take, write nothing. Invoke `canon:target-check` and report the target current with its table.
 
+### Take a branch after the go-ahead
+
+The migrations, the sync, and the commits write the project, so they land on their own branch rather than on the one the shared checkout holds, where every other session in it would follow. Step 1 stays where it ran, since it writes the machine rather than the project.
+
+Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`, then take the first row that fits:
+
+| State                                      | This skill                                                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| Different, so already in a linked worktree | Uses it and enters nothing, since a second worktree would nest inside the first                   |
+| Equal, and the operator took the worktree  | Invokes `canon:session-worktree` with `chore/update-canon`, then runs Steps 4 to 6 from inside it |
+| Equal, declined, on `main` or `master`     | Invokes `canon:git-branch` for `chore/update-canon`, then runs Steps 4 to 6 in place              |
+| Equal, declined, on any other branch       | Stops and says so, since `canon:git-branch` would rename that branch under every session on it    |
+
+Four points govern the choice:
+
+- Offer the worktree as the default in the preview's `Where it lands` line, and take a decline from the operator's reply to it
+- Report it rather than proceeding silently when `canon:session-worktree` does not resolve, as in a project that installed governance without the plugin, then fall back to `canon:git-branch`
+- Stop when neither skill resolves, saying the run would otherwise write onto the shared checkout's branch
+- Run the Guards' dirty-tree test again from the new tree. A fresh worktree starts clean, so a refusal there is a real one.
+
 ## Step 4: migrate
 
 Run each pending migration in the order `migrate status` gave, one at a time, as the entry's `verb` with `--write --json` appended. The verb carries the flags its dry run used, so a bare `canon migrate <name>` would apply a plan the preview never showed.

package/docs/agents/context-audit.md

@@ -46,7 +46,7 @@ The shape kinds are `retired-section`, `gotcha-count`, `gotcha-heading`, `gotcha
 
 - A `## Decisions` H2, or a `Gotchas` section past five bullets or holding a heading or paragraph
 - A `Layout` H3 titled neither a code-spanned path nor `Other folders`, or a heading below H3 under `Layout`
-- A folder H3 past five bullets or its one-paragraph lead
+- A folder H3 past five bullets or its one-paragraph lead, where table rows and the sentence leading the bullets after a table count toward neither
 
 The development entry may carry a `Scripts` H3 exempt from both folder caps. `SHAPE_GATED_FOLDERS` lives in `src/context/shape-gated.ts`.
 

package/governance/rules/code/routing.md

@@ -1,5 +1,5 @@
 ---
-description: Routes code placement and shape decisions to the skills that carry them, and library calls to the official docs
+description: Routes code placement, shape, and interface decisions to the skills that carry them, and library calls to the official docs
 ---
 
 # Code standards
@@ -12,6 +12,10 @@ description: Routes code placement and shape decisions to the skills that carry
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
 
+## Interfaces
+
+- Load `canon:api-design` before shaping a public function, flag or output, record format, endpoint, or caller-handled error, and report it rather than proceeding silently when it does not resolve.
+
 ## Libraries
 
 - Before calling a library API the codebase does not already use, fetch the official docs for the installed version and match the call to them, since recall of an API goes stale.

package/governance/rules/ui/design-taste.md

@@ -1,6 +1,10 @@
 ---
 description: Route edits that decide how a surface looks to the design-taste skill for the layer ordering, the coherence locks, and the defaults a model reaches for
 paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
   - '**/*.css'
   - '**/*.scss'
   - 'canon/DESIGN.md'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.56.0",
+  "version": "5.58.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/tasks.ts

@@ -668,12 +668,15 @@ export function register(program: Command): void {
         '  no-board   the repository holds no `.canon/tasks/` board',
         '  no-match   no task matches the selector',
         '  ambiguous  more than one task matches the selector',
-        '  bad-input  a task and a plan both named, or neither',
+        '  bad-input  a task and a plan both named',
         '',
         'Exit codes:',
         '  0  the task is read, whether or not it closes',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
+        'With no task or plan named, the task whose plan derives the branch is read,',
+        'and a branch nothing owns is no-match.',
+        '',
         'Reads the `Issue:` lines, each `#NNN` or a comma list, and reports',
         '`issues` and `closing`. The pull request closes them only when it is',
         "the task's last slice, the condition the merge-time archive applies:",
@@ -1513,15 +1516,18 @@ async function runCloses(
   opts: ClosesCommandOptions,
 ): Promise<number> {
   const emitJson = opts.json ?? false
-  const selector = selectorFor(task, opts.plan)
+  const branch = opts.branch ?? (await workingBranch())
+  const branches = branch ? [branch, ...(await formerNames(branch))] : []
+  const selector =
+    !task && !opts.plan
+      ? ({ kind: 'branch', branches } as const)
+      : selectorFor(task, opts.plan)
 
   if ('ok' in selector) {
     return reportRecord('canon tasks closes', selector, emitJson, process.cwd())
   }
 
   const root = opts.root ?? (await mainWorktreeRoot())
-  const branch = opts.branch ?? (await workingBranch())
-  const branches = branch ? [branch, ...(await formerNames(branch))] : []
   const outcome = await readClosure(
     root,
     selector,

package/src/context/audit.ts

@@ -616,8 +616,16 @@ function shapeIssues(
   let inItem = false
   let inParagraph = false
   let afterBlank = false
+  let afterTable = false
+  let deferred = false
+
+  const settleDeferred = (): void => {
+    if (deferred && folder) folder.paragraphs++
+    deferred = false
+  }
 
   const closeFolder = (): void => {
+    settleDeferred()
     if (folder && !exempt.has(folder.text)) {
       if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
         issues.push({
@@ -661,6 +669,7 @@ function shapeIssues(
       inItem = false
       inParagraph = false
       afterBlank = false
+      afterTable = false
 
       if (level <= 2) {
         closeFolder()
@@ -697,11 +706,22 @@ function shapeIssues(
       inItem = true
       inParagraph = false
       afterBlank = false
+      afterTable = false
+      deferred = false
       if (gotchas) gotchas.bullets++
       if (folder) folder.bullets++
       continue
     }
 
+    if (folder && TABLE_ROW.test(line.text)) {
+      settleDeferred()
+      inItem = false
+      inParagraph = false
+      afterBlank = false
+      afterTable = true
+      continue
+    }
+
     const continues = inItem && (!afterBlank || INDENTED.test(line.text))
     afterBlank = false
     if (continues) continue
@@ -717,7 +737,12 @@ function shapeIssues(
         text: line.text.trim(),
       })
     }
-    if (folder) folder.paragraphs++
+    if (folder) {
+      settleDeferred()
+      if (afterTable) deferred = true
+      else folder.paragraphs++
+    }
+    afterTable = false
   }
 
   closeFolder()

package/src/pr/bijection.ts

@@ -150,6 +150,7 @@ function coversIgnoreAddition(
  * path written short from a path written wrong.
  */
 function covers(claim: PathClaim, path: string): boolean {
+  if (claim.bare) return path === claim.path
   if (claim.directory) {
     return claim.anchored
       ? path.startsWith(claim.path)
@@ -212,6 +213,8 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
       continue
     }
 
+    if (claim.bare) continue
+
     if (claim.anchored && claim.leading && !evidenceUnread) unmet.push(claim)
     else unresolved.push(claim)
   }
@@ -240,9 +243,8 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
  * and an unanchored claim never accuses, so the first branch to open one would
  * silently lose the graded direction.
  *
- * A path with no folder above it contributes nothing, since a claim carrying no
- * slash never reaches the extractor's output and no root would ever be read
- * against it.
+ * A path with no folder above it contributes nothing, since a bare claim is
+ * never anchored and no root would ever be read against it.
  */
 export function treeRoots(
   tracked: readonly string[],

package/src/pr/paths.ts

@@ -36,6 +36,16 @@ export interface PathClaim {
    * accuse with.
    */
   readonly leading: boolean
+  /**
+   * True when the span carried no slash, such as `README.md` or `bun`.
+   *
+   * A bare claim credits a changed file whose whole path is exactly that name
+   * and nothing else, so `package.json` never reaches `web/package.json`. It
+   * never accuses: nothing separates a bare file name from a word of prose, so
+   * one matching no changed file is reported nowhere. Same asymmetry as
+   * `anchored` and `leading`.
+   */
+  readonly bare: boolean
   /** The span exactly as the body wrote it, before the line suffix came off. */
   readonly span: string
   /** One-based index of the bullet inside the section. */
@@ -282,17 +292,22 @@ function splitBullets(section: string): string[] {
 interface ResolvedSpan {
   readonly path: string
   readonly directory: boolean
+  readonly bare: boolean
 }
 
 function resolveSpan(span: string): ResolvedSpan | undefined {
   if (span === '' || isNotRepositoryPath(span)) return undefined
 
-  // A bare name is the fourth observed false-positive class and it drops
-  // outright. Resolved as a sibling of a path earlier in the bullet it produced
-  // seven wrong paths across this corpus against two right ones, because a
-  // compound bullet names a sibling folder as often as a sibling file. Dropping
-  // it under-reports in the unnamed direction and never fires in the other.
-  if (!span.includes('/')) return undefined
+  // A bare name cannot be resolved as a sibling of a path earlier in the
+  // bullet: that produced seven wrong paths across this corpus against two right
+  // ones, because a compound bullet names a sibling folder as often as a sibling
+  // file. It resolves to itself as a root-level path and is marked bare, which
+  // keeps it from ever accusing.
+  if (!span.includes('/')) {
+    return isDottedNumber(span)
+      ? undefined
+      : { path: span, directory: false, bare: true }
+  }
 
   if (span.endsWith('/')) {
     // A single top-level folder is never a claim. Nobody reports having changed
@@ -300,10 +315,12 @@ function resolveSpan(span: string): ResolvedSpan | undefined {
     // something lives.
     return span.indexOf('/') === span.length - 1
       ? undefined
-      : { path: span, directory: true }
+      : { path: span, directory: true, bare: false }
   }
 
-  return isDottedNumber(span) ? undefined : { path: span, directory: false }
+  return isDottedNumber(span)
+    ? undefined
+    : { path: span, directory: false, bare: false }
 }
 
 /**
@@ -371,7 +388,9 @@ export function extractKeyChangePaths(
 
       const resolved = resolveSpan(bare)
       if (resolved === undefined) continue
-      claimed = true
+      // A bare span is no evidence a path claim came first, so it leaves the
+      // citation guard above reading only the claims it was written for.
+      if (!resolved.bare) claimed = true
       // First occurrence wins, across bullets as well as inside one. A path
       // named trailing here and leading three bullets later keeps the weaker
       // reading, which loses an accusation and can never add one.
@@ -381,8 +400,11 @@ export function extractKeyChangePaths(
       claims.push({
         path: resolved.path,
         directory: resolved.directory,
-        anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
+        anchored:
+          !resolved.bare &&
+          roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
         leading: match.start < accusesBefore,
+        bare: resolved.bare,
         span,
         bullet: index + 1,
         preview,

package/src/records/validate.ts

@@ -219,6 +219,7 @@ const QUESTION_ITEM = /^\d+[a-z]?\.[ \t]+\S/
 
 const PLAN_SECTIONS = [
   'Summary',
+  'Current behavior',
   'Constraints',
   'Files to touch',
   'Design references',

package/src/tasks/branch.ts

@@ -43,6 +43,11 @@ function slugOf(path: string): string {
   return stem.startsWith(PLAN_PREFIX) ? stem.slice(PLAN_PREFIX.length) : stem
 }
 
+/** The branch a plan file derives, from its filename alone. */
+export function branchOfPlan(path: string): string {
+  return `${PLAN_BRANCH_TYPE}/${slugOf(path)}`
+}
+
 /**
  * Derives the branch a dispatch checks and a worker takes, from the plan both
  * of them name. It is the one derivation, so the collision check and the
@@ -60,7 +65,7 @@ export function planBranch(root: string, reference: string): BranchOutcome {
   if (!resolved.ok) return resolved
 
   const slug = slugOf(resolved.path)
-  const branch = `${PLAN_BRANCH_TYPE}/${slug}`
+  const branch = branchOfPlan(resolved.path)
   const words = slug.split('-').filter((word) => word.length > 0).length
 
   return {

package/src/tasks/record.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 import { planCandidates } from '@/tasks/answers'
+import { branchOfPlan } from '@/tasks/branch'
 import {
   appendPlanLink,
   describeUnmatchedStem,
@@ -57,6 +58,7 @@ export interface RecordRefused {
 export type RecordSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'plan'; readonly plan: string }
+  | { readonly kind: 'branch'; readonly branches: readonly string[] }
 
 export type LineAction = 'added' | 'appended' | 'corrected' | 'unchanged'
 
@@ -383,6 +385,25 @@ async function resolveStem(
     return selector.stem
   }
 
+  if (selector.kind === 'branch') {
+    const matched = await matchByBranch(dir, stems, selector.branches)
+    const label = selector.branches[0] ?? 'no branch'
+
+    if (matched.length === 0) {
+      return refuse('no-match', `No task's plan derives branch ${label}.`)
+    }
+
+    if (matched.length > 1) {
+      return refuse(
+        'ambiguous',
+        `${matched.length} tasks derive branch ${label}. One task, one plan.`,
+        matched,
+      )
+    }
+
+    return matched[0]
+  }
+
   const matched = await matchByPlan(dir, stems, selector.plan)
 
   if (matched.length === 0) {
@@ -400,6 +421,29 @@ async function resolveStem(
   return matched[0]
 }
 
+/**
+ * Matches a branch to the tasks whose plan derives it. A task with no `Plan:`
+ * line carries no target and so never matches.
+ */
+async function matchByBranch(
+  dir: string,
+  stems: readonly string[],
+  branches: readonly string[],
+): Promise<string[]> {
+  const read = await Promise.all(
+    stems.map(async (stem) => ({
+      stem,
+      targets: readPlanTargets(await readFile(join(dir, `${stem}.md`), 'utf8')),
+    })),
+  )
+
+  return read
+    .filter((entry) =>
+      entry.targets.some((target) => branches.includes(branchOfPlan(target))),
+    )
+    .map(({ stem }) => stem)
+}
+
 export async function openTask(
   root: string,
   selector: RecordSelector,