@erclx/canon 5.56.0 → 5.57.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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.57.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/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.

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

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.56.0",
+  "version": "5.57.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/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,