@erclx/canon 5.41.0 → 5.43.0

package/claude/skills/task-board/references/tasks.md

@@ -5,11 +5,10 @@ description: Folder layout, filename convention, file format, origin lines, and
 
 # Tasks reference
 
-Applies to `.canon/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task.
+Applies to `.canon/tasks/`. Tracks what is being built and why, at the level of features and outcomes, one file per task. Update a task when it starts, completes, or changes scope.
 
-Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
-
-The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
+- When to open a task at all is project policy rather than a shape rule, and lives in `CLAUDE.md`
+- The folder is gitignored, since committing board state would put a claim about the future into an unrelated pull request
 
 ## Contents
 
@@ -50,17 +49,19 @@ Does not govern:
 └── v13.0-toolkit-drift.md   # canon-allow-reference: illustrates the vXX.Y-slug filename this section defines
 ```
 
-One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
-
-Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md`, `priority.md`, and `backlog.md` are governed by `board.md`. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.
+One file per task keeps the board safe under parallel sessions, since a gitignored board has no history to recover a clobbered write from.
 
-The `task-board` skill creates and declines task files. The `task-complete` skill marks outcomes `[x]` in an existing file and archives a shipped one, and the archive carries the task's plan with it. Neither does the other's job.
+- Siblings are governed elsewhere, `index.md`, `priority.md`, and `backlog.md` by `board.md` and each `session-` file by `session.md`. A name outside that set is a task.
+- `task-board` creates and declines task files, and `task-complete` marks outcomes `[x]` and archives a shipped task with its plan
 
 ## Filenames
 
 `vXX.Y-<slug>.md`, where the version is the phase label zero-padded to two digits and the slug is kebab-case.
 
-Padding is load-bearing. Index entries sort by filename and nothing else, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` governs the label itself and permits free renumbering, so expect the occasional rename. Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse. <!-- canon-allow-reference: illustrates the padding rule's own sort collision, not a citation of a real task -->
+Padding is load-bearing. Index entries sort by filename alone, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. <!-- canon-allow-reference: illustrates the padding rule's own sort collision, not a citation of a real task -->
+
+- `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` governs the label and permits free renumbering, so expect the occasional rename
+- Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse
 
 ## Frontmatter
 
@@ -78,15 +79,19 @@ description: Record what a target installed and report the delta against the too
 
 ## File format
 
-Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable, findings are past and factual, and as flat bullets at the same indent they are visually identical. A heading separates them at no cost.
+Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable and findings are past and factual, yet as flat bullets they look identical, so a heading separates them at no cost.
 
-Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
+- Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
+- Outcomes stay a checklist, since the board tools read them by their `- [ ]` line
+- Open each finding with a bold label naming its source and date, as in `- **planner, 2026-10-11:** <finding>`. Keep it to a few sentences, moving anything longer into the plan or groundwork folder.
 
-Open each finding with a bold label naming its source and date, as in `- **planner, 2026-10-11:** <finding>`, and keep it to a few sentences. Anything longer moves into the plan or the groundwork folder. Outcomes stay a checklist, since the board tools read them by their `- [ ]` line.
+### Sizing outcomes
 
-Size the outcomes so one pull request closes all of them, and split the task before handing it off rather than after. A task closes whole or not at all, so outcomes spanning two pull requests leave the board showing in-progress work no branch carries.
+Size the outcomes so one pull request closes all of them, and split the task before handing it off rather than after. A task closes whole, so outcomes spanning two pull requests leave the board showing work no branch carries.
 
-A sliced task is the one allowed exception: a task the operator decided to ship across several pull requests on purpose, one slice each. Its `Pull request:` line lists every slice, so the board records which merged work covered which outcomes, and it closes whole when the last slice's merge finds every outcome ticked and no slice left pending.
+A sliced task is the one exception, shipped across several pull requests on purpose by the operator. Its `Pull request:` line lists every slice, and it closes when the last slice's merge finds every outcome ticked and no slice pending.
+
+### Title and template
 
 Prefix the H1 with the `vX.Y:` phase label, then a short title whose form depends on the task type:
 
@@ -126,29 +131,49 @@ Why this task exists and what it depends on.
 
 Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
 
-A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track, an intake folder, or an open issue that no task points at is work already decided and on its way to being forgotten.
+### Both directions
+
+A task with no origin is lost context or work nobody decided to do. The reverse bites harder, since a groundwork track, intake folder, or open issue no task points at is decided work being forgotten, and an intake folder fully answered with no task citing it, live, archived, or declined, is a dump nobody acted on.
+
+### Link form
 
-An intake folder answers that direction at folder scope rather than item scope. A folder with every item answered and no task citing it, live, archived, or declined, is a dump nobody acted on.
+`Plan:`, `Groundwork:`, `Intake:`, and `Ready:` name their target as a markdown link whose text is the stem, so the line resolves on a ctrl-click as `priority.md` rows do.
 
-`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.canon/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Ready:` names the ready folder a task's plan copies from, as a link to `../ready/<nn>-<slug>/` with the trailing slash a folder carries. Include it only when the folder exists. `canon tasks archive` reads it to move the folder, and falls back to a `.canon/ready/<nn>-<slug>/` path in the plan when a task carries no line.
+- Write the path relative to `.canon/tasks/`, as `../plans/`, `../groundwork/`, and `../intake/`. A path from the project root resolves to nothing in an editor rooted there.
+- `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL writes the remote into a gitignored file
+- `Ready:` links `../ready/<nn>-<slug>/`, the folder the plan copies from, only when it exists. `canon tasks archive` reads it to move the folder, falling back to a path in the plan.
 
-`Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+### The `Plan:` line
 
-`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans/archive/feature-<slug>.md`, and at `../../plans/archive/feature-<slug>.md` once the task itself is archived a folder deeper. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
+`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Retarget both halves of the link as things move rather than dropping it, so a completed task still leads to its reasoning.
 
-A project that archived plans before the folder nested under `.canon/plans/` holds closed tasks pointing at `../plans-archive/` or `../.tmp/plans-archive/`. Leave those pointers where they are, since each resolves against the files it names and a task retargeted without its plan moving leads nowhere.
+| State                         | Target                                  |
+| ----------------------------- | --------------------------------------- |
+| Open                          | `../plans/feature-<slug>.md`            |
+| Shipped, plan archived        | `../plans/archive/feature-<slug>.md`    |
+| Task archived a folder deeper | `../../plans/archive/feature-<slug>.md` |
 
-One plan per task, or one per slice, which the board check reads as distinct plans on one line. A plan cited by two tasks is a misfile.
+- One plan per task, or one per slice as distinct plans on one line. A plan cited by two tasks is a misfile.
+- `canon tasks plan-link <task> <plan>` writes or corrects the line, and `--add` appends a slice's plan, so it is never hand-edited
+- Leave an older `../plans-archive/` or `../.tmp/plans-archive/` pointer alone, since it resolves and retargeting without moving the plan leads nowhere
 
-`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, and `--add` appends a slice's plan, so the line is never hand-edited.
+### The `Groundwork:` and `Intake:` lines
 
-`Groundwork:` points at `../groundwork/<slug>/`, the folder `plan-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
+`Groundwork:` points at `../groundwork/<slug>/`, the folder `plan-groundwork` fills. `Intake:` points at `../intake/<slug>/`, the folder an intake pass fills.
 
-`Intake:` points at `../intake/<slug>/`, the folder an intake pass fills. Use it rather than `Groundwork:`, so the line records which kind of pass produced the task. It names the folder rather than an item inside it, and the item numbers belong in that task's `## Findings`.
+- Use `Groundwork:` alone for its key. `Research record` and `Decision record` are earlier spellings and both convert to it.
+- Use `Intake:` rather than `Groundwork:` for an intake pass, so the line records which kind of pass produced the task
+- `Intake:` names the folder rather than an item, and item numbers belong in the task's `## Findings`
 
-`Pull request:` records which pull requests carry the task's work, each as a bare `#NNN` the way `Issue:` does. It lists every pull request that shipped part of the task, oldest first and separated by commas, as in `Pull request: #NNN, #NNN`, and a task shipped whole lists one. It is not an origin, so a task without one is well-formed. `git-pr` appends to it when a pull request opens.
+### The `Pull request:` line
 
-The line is what lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any number the line lists and archives it only on the last. One pull request, one task: two tasks naming the same number refuse to archive rather than both moving. `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number, since `canon tasks outcome` writes it and `canon tasks pull-request` clears it. `canon tasks outcome` skips the write when the branch's own pull request is already on the line.
+`Pull request:` lists every pull request that shipped part of the task as bare numbers, oldest first and comma-separated, as in `Pull request: #NNN, #NNN`. It is not an origin, so a task without one is well-formed, and `git-pr` appends to it when a pull request opens.
+
+The line lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any listed number and archives it only on the last.
+
+- One pull request, one task. Two tasks naming the same number refuse to archive rather than both moving.
+- `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number
+- `canon tasks outcome` writes that line, skipping it when the branch's pull request is already listed, and `canon tasks pull-request` clears it
 
 ## What goes in
 
@@ -161,20 +186,27 @@ The line is what lets a merge close its own task. `canon tasks archive --pull-re
 
 - Class names, file paths, function names, or prop names in any entry or title
 - Code-level steps or implementation detail. Behavioral specifics are fine.
-- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in the context entry of the domain it constrains.
+- Architectural reasoning that outlives the task. A decision the system keeps after the task closes belongs in the context entry of the domain it constrains.
 
 ### Narrative and sequencing
 
-- Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
+Session history and ordering both have homes off the task file.
+
+- Narrative of the session that produced the task. What was probed, what it cost, and who decided belongs in the groundwork folder, and a task with none cuts it, since the board is no fallback.
 - "In progress" or "Blocked" headings. Note status inline on the outcome instead.
-- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Rationale wider than one row has no home at all, so cut it rather than filing it here.
+- Sequencing rationale or which version is active. It goes on the task's `priority.md` row, and rationale wider than one row is cut.
 
 ## Archiving
 
-Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `canon tasks archive --help`.
+Never delete a task file. A shipped task moves to `.canon/tasks/archive/` under its own name through `canon tasks archive`, and the live index regenerates without it. What the verb does and refuses on is at `canon tasks archive --help`, and a flat `.claude/task-archive/` names an older binary rather than a second archive.
+
+### The plan and ready folder
+
+Archiving a task archives its plan alongside it when the task is that plan's last live citation. A plan several tasks share stays live with its ready folder, and the task archives anyway.
 
-The archive nests inside `.canon/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`, which is what a binary predating this convention still writes. Meeting the flat sibling names an older checkout rather than a second archive to reconcile.
+- The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`
+- The folder its `Ready:` line names moves to `.canon/ready/archive/<nn>-<slug>/`, and both pointers to it are retargeted
 
-Archiving a task archives its plan alongside it, when the closing task is that plan's last live citation. The archived task's `Plan:` line is retargeted at `../../plans/archive/feature-<slug>.md`. The ready folder its `Ready:` line names moves with the plan to `.canon/ready/archive/<nn>-<slug>/`, and both pointers to it are retargeted. A plan several tasks share stays live with its ready folder, and the task archives anyway.
+### Open outcomes
 
-A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. Cutting means striking the outcome's body: `- ~~<outcome>~~ <why>`. A struck body reads as cut whatever its checkbox holds, so a task carrying only cut outcomes still archives.
+A task with an open outcome stays on the board, and so does its plan. Close it, or cut an abandoned outcome by striking its body, as `- ~~<outcome>~~ <why>`, which reads as cut whatever its checkbox holds, so a task of cut outcomes still archives.

package/claude/skills/task-complete/references/archive.md

@@ -7,21 +7,22 @@ description: How task-complete confirms a task's work reached main, runs canon t
 
 The Archive mode of `task-complete`. The session reads this file when the request names a task file already shipped.
 
-The `post-merge` git hook archives the task a merge closed, so a request arriving here is usually one the hook could not resolve on its own. Run the steps below against whatever the hook left in place.
-
-Do not move the file, edit `priority.md`, or regenerate the index by hand. `canon tasks archive` owns all three as one unit and the hook calls the same command, so a hand-rolled move here drifts from the unattended path.
+- The `post-merge` git hook archives the task a merge closed, so a request here is usually one the hook could not resolve. Run the steps against whatever it left in place.
+- `canon tasks archive` moves the file, edits `priority.md`, and regenerates the index as one unit. The hook calls the same command, so a hand-rolled move drifts from the unattended path.
 
 ## Step 1: confirm the work reached main
 
-`task-complete` marks outcomes on the branch as step 2 of the ship chain, so an all-`[x]` task routinely describes a pull request that is still open. The command gates on the outcomes and cannot tell those two apart, which is what puts this check here:
+`task-complete` marks outcomes on the branch as step 2 of the ship chain, so an all-`[x]` task routinely describes a pull request still open. The command gates on the outcomes and cannot tell the two apart, which puts this check here:
 
 ```bash
 git fetch origin main --quiet && git log origin/main --oneline -20
 ```
 
-Match the shipped outcomes against that log, widening to `gh pr list --state merged --limit 20` when a remote is configured and the log does not settle it. When the work is not on `main`, name the task and stop: `❌ Work not on main. Archiving now loses the task if the pull request is abandoned.`
+Match the shipped outcomes against that log, widening to `gh pr list --state merged --limit 20` when a remote is configured and the log does not settle it.
 
-The board is gitignored, so an archived task has no history behind it and nothing restores one archived early. Skip this check when the task carries a `Pull request:` line and the last number it lists is merged, since the number already proves what the log is being read for.
+- When the work is not on `main`, name the task and stop: `❌ Work not on main. Archiving now loses the task if the pull request is abandoned.`
+- The board is gitignored, so nothing restores a task archived early
+- Skip the check when the task's `Pull request:` line lists a merged last number, which already proves what the log is read for
 
 ## Step 2: run the archive
 
@@ -31,28 +32,51 @@ Pass the task's filename stem, or the pull request number when the request names
 canon tasks archive <stem> --json
 ```
 
-The command refuses rather than reports, and the refusal reaches this skill through the record rather than through the exit. Branch on `ok`, then on `reason`. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, which masks every non-zero exit rather than only an absent verb. The binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike, so the record is the only signal that survives the wrapper.
+The command refuses rather than reports, so branch on the record's `ok`, then on `reason`, never on the exit.
+
+- An operator's shell profile may wrap `canon` in a function that takes a second command's status, masking every non-zero exit
+- The binary exits 1 for an unknown subcommand and an ordinary refusal alike, so the record is the only signal that survives the wrapper
+
+### Success record
+
+A successful archive returns one record naming what moved.
+
+| Field                | Holds                                                                 |
+| -------------------- | --------------------------------------------------------------------- |
+| `from`, `to`         | The task's old and new path                                           |
+| `priorityRowRemoved` | Whether a `priority.md` row was dropped                               |
+| `indexRegenerated`   | Whether the index changed                                             |
+| `plans`              | A `from` and `to` per live plan the task last cited, in `Plan:` order |
 
-On success the record carries `from`, `to`, `priorityRowRemoved`, and `indexRegenerated`, which is what moved, what row it cleared, and whether the index changed. It also carries `plans`, one `from` and `to` for each live plan the task was the last live citation of, in the order its `Plan:` line links them. An empty `plans` means the task cited no live plan, or that a sibling still holds every one it cited.
+An empty `plans` means the task cited no live plan, or a sibling still holds every one it cited.
 
 ## Step 3: route on a refusal
 
-Each reason has one resolution and none of them is to archive around it:
+Each reason has one resolution, and none of them is to archive around it.
 
-- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `task-complete` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. When the work is being abandoned, cut it by striking the body, `- ~~<outcome>~~ <why>`, whatever the checkbox holds, so the board records what was dropped rather than meeting this refusal a second time.
-- `ambiguous`: two tasks name one pull request, which is the misfile `${CLAUDE_SKILL_DIR}/references/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
-- `earlier-slice`: the number is listed on the task but is not the last, so a later slice is still to merge. Leave the task on the board. Its last slice's merge archives it.
+- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `task-complete` when the work shipped unmarked, and leave the task on the board when the outcome is real.
+- `ambiguous`: two tasks name one pull request, the misfile `${CLAUDE_SKILL_DIR}/references/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
+- `earlier-slice`: the number is listed on the task but is not the last. Leave the task on the board, and its last slice's merge archives it.
+
+### Abandoned outcomes
+
+When the work behind an open outcome is abandoned, cut it by striking the body, `- ~~<outcome>~~ <why>`, whatever the checkbox holds. The board then records what was dropped rather than meeting this refusal again.
 
 ### Branches, matches, and input
 
-- `pending-branch`: a branch named in `detail` ticked an outcome before its own pull request number was recorded. Leave the task live, since that branch's merge archives it once `git-pr` records the number. When the operator decides a named branch was abandoned, archive by stem, which is the one case for it.
+The remaining three name a pending branch, a missing match, or a malformed call.
+
+- `pending-branch`: a branch named in `detail` ticked an outcome before its pull request number was recorded. Leave the task live, since that merge archives it once `git-pr` records the number.
+- An operator who decides the named branch was abandoned archives by stem, the one case for it
 - `no-match`: the stem or number names nothing on the board. Check the name against the listed stems.
-- `bad-input`: the command line was wrong rather than the board. Read the message, fix the arguments, and run it again. Nothing on the board needs repair, which is what separates this from the two above.
+- `bad-input`: the command line was wrong rather than the board, so nothing needs repair. Read the message, fix the arguments, and rerun.
+
+### What to leave alone
 
-Do not move a plan by hand from this skill. The command carries the plan with the task when no other live task cites it, and retargets the archived task's `Plan:` line at the new path. A second mover drifts into relocating the same file differently.
+Never move a plan by hand from this skill. The command carries the plan along when no other live task cites it and retargets the `Plan:` line, and a second mover relocates the same file differently.
 
-Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It records the single-file era in the shape that era used, and splitting it would fabricate per-task files nobody wrote.
+Leave `TASK-ARCHIVE.md` alone when it is present in the archive folder. It records the single-file era in that era's shape, and splitting it would fabricate per-task files nobody wrote.
 
 ## Step 4: clear prose naming the task
 
-The command drops the task's row from `.canon/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the rows that changed, since a stale count reads as board state.
+The command drops the row from `.canon/tasks/priority.md` and leaves prose alone. Remove any sentence that still names the archived task or counts the changed rows, since a stale count reads as board state.

package/claude/skills/task-complete/references/receipt-sweep.md

@@ -5,25 +5,39 @@ description: How task-complete's marking step sweeps branch review reports whose
 
 # Sweep consumed receipts
 
-Step 4 of `task-complete`'s Mark mode, reached in order on every marking run.
+Step 4 of `task-complete`'s Mark mode, reached in order on every marking run. Sweep the review receipts a shipped branch left behind.
 
-Sweep the review receipts a shipped branch left behind. Resolve all paths at the main worktree root, not the current worktree, the way `session-worktree` does.
+- Resolve all paths at the main worktree root, not the current worktree, the way `session-worktree` does
+- Every delete is a plain `rm`, one per call, routed the way `session-worktree` states
 
-Every delete below is a plain `rm`, one per call, routed the way `session-worktree` states.
-
-Plans are not swept here. A plan is settled by the merge rather than by an outcome this run marked, and `canon tasks archive` moves it with the task the `post-merge` hook archives. Sweeping it from this step would read a closure Step 3 wrote moments earlier and move a plan the branch is still building from.
+Plans are not swept here. A merge settles a plan, and `canon tasks archive` moves it with the task the `post-merge` hook archives, so sweeping it here would move a plan the branch is still building from.
 
 ## Reviews
 
 Leave the current branch's review receipt where it is. No skill writes one now, so one that exists is older and its branch is still live.
 
-The body that writes a receipt owns its lifetime. This skill sweeps on behalf of whatever called it and has no way to read whether a file is still in use, where the chain that wrote this one cites it in its own output and knows. What reaps it is the branch sweep below, one branch later, once the branch it names is gone.
+The body that writes a receipt owns its lifetime. This skill cannot read whether a file is still in use, so the branch sweep below reaps it one branch later, once its branch is gone.
+
+### The branch sweep
+
+Sweep the branch reports this session never opened, deleting each whose slug matches no live branch.
+
+1. List `.canon/review/branch-*.md`.
+2. Run the slug transform in `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md` over every name `git branch --format='%(refname:short)'` prints.
+3. Delete a report whose slug matches none of them.
+
+Take the names from that format rather than `git branch --list`, which marks the current branch with `* ` and one checked out elsewhere with `+ `. Reading those marks as written turns a live branch into a slug nothing matches and sweeps a report a sibling worktree still uses.
+
+### Why sweep at all
+
+A branch report is read once, by the session addressing it. The durable record is the comment `review-pr` posts on the pull request, so a report outliving its branch holds nothing.
 
-Sweep the branch reports this session never opened. List `.canon/review/branch-*.md`, run the slug transform in `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md` over every name `git branch --format='%(refname:short)'` prints, and delete a report whose slug matches none of them. Take the names from that format rather than from `git branch --list`, which marks the current branch with `* ` and a branch checked out in another worktree with `+ `, so a transform reading the marked lines as written turns a live branch into a slug nothing matches and sweeps a report a sibling worktree is still working from. A branch report is read once, by the session addressing it, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so a report outliving its branch is holding nothing. Skipping this leaves them accumulating for the life of the checkout, since a slug is unique per feature and no later branch ever looks for one.
+- Skipping the sweep leaves reports piling up for the life of the checkout, since a slug is unique per feature and no later branch looks for one
+- The sweep also removes a local-only review on a branch deleted before it opened a pull request. It runs anyway, since nothing else clears them.
 
-What that removes is a local-only review on a branch deleted before it opened a pull request. The sweep runs anyway rather than keeping every report against the one case, since nothing else ever clears them.
+### What stays
 
-Do not sweep `ux-audit-*.md` or `ux-measure-*.md` (standalone deliverables). Those sit at `.canon/review/` itself rather than under a producer folder, so the glob above never reaches them.
+Do not sweep `ux-audit-*.md` or `ux-measure-*.md`, which are standalone deliverables. They sit at `.canon/review/` itself rather than under a producer folder, so the glob never reaches them.
 
 Output one line per file swept:
 

package/claude/skills/task-complete/references/unusable-baseline.md

@@ -12,8 +12,15 @@ The baseline is unusable in two cases:
 - No merge base resolves against either ref.
 - The base came from local `main` and equals HEAD. Nothing is pushed to compare against, so a narrow read reports no changes rather than admitting it cannot see them.
 
-An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
+An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
 
-Recover the committed half. Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, which is what lets Step 2 decide on behavior rather than on filenames. A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path carries the evidence rather than covering an edge case.
+## Recover the committed half
 
-On a fresh `git init` project the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route. The marking step tolerates that because it only reads the diff, and it matches conservatively against outcomes already on the board. Widening what a step reads is safe. Never carry the widened set into a step that writes per file.
+Read `git log -p -1`, widening to `git log -p -<n>` when the session spans several commits, and read the candidate task files against the working tree. That yields names and content both, so Step 2 decides on behavior rather than filenames.
+
+- A fresh `git init` on `main` with no remote is the ordinary shape of a scaffolded project, so this path is common rather than an edge case
+- There the last commit is the scaffold commit, so `git log -p -1` is the whole tree by another route
+
+## Why the widened read is safe
+
+The marking step tolerates the whole tree because it only reads the diff and matches conservatively against outcomes already on the board. Widening what a step reads is safe, and the widened set never carries into a step that writes per file.

package/claude/skills/teach-workspace/references/glossary.md

@@ -42,6 +42,8 @@ A glossary failing these is non-conforming even when it satisfies every shape ru
 
 ### Placement and order
 
+Each entry points at its first use and sits where a reader would look for it.
+
 - Name where the term first appears, so a reader can reach one use of it in context.
 - Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
 - Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
@@ -59,14 +61,16 @@ A glossary failing these is non-conforming even when it satisfies every shape ru
 - Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
 - Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
 - Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
-- State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
+- State a departure from any rule above in the file itself, naming what it departs from and why
+- A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name
 
 ## Rendered grouping
 
 Applies to a rendered glossary page, never to the source file above, which stays the flat alphabetical list the `## Grouping` rules above govern.
 
 - Group a rendered glossary by the lesson its own "First seen in" citation names, ordered by lesson order, under a sub-heading naming the lesson's title rather than its filename.
-- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page instead or carries no citation at all. Keep it in the alphabetical order the source file already carries.
+- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page or carries no citation
+- Keep "Other terms" in the alphabetical order the source file already carries
 - Keep the workspace-wide term filter matching against every group, and drop a group's own heading once filtering leaves nothing under it.
 
 ## Template

package/claude/skills/teach-workspace/references/lesson-build.md

@@ -12,26 +12,40 @@ Mechanics rather than judgment. `lesson-craft.md` covers what a lesson should be
 `canon teach render` takes a JSON array of blocks and renders it through the same components a lesson body composes. Six types, and every structural body composes from them:
 
 - `{"type":"heading","level":1|2,"text":"<text>"}`: an `<h1>` or `<h2>`.
-- `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the dek that opens the lesson. `cites` adds a footnote marker per reference number after the text, and a lede takes none.
+- `{"type":"paragraph","text":"<text>","lede":true,"cites":[1]}`: a `<p>`, marked `lede` for the opening dek. `cites` adds a footnote marker per reference number, and a lede takes none.
 - `{"type":"list","items":["<text>", ...],"ordered":true}`: a `<ul>` or, with `ordered`, an `<ol>`.
 
 ### Reference, code, and raw blocks
 
-- `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the lesson's one reference list, numbered from 1 in item order. `url` and `note` are optional, and a `url` must be http or https.
-- `{"type":"code","lang":"ts","text":"<source>"}`: a code sample, highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias. One the renderer does not register renders as plain escaped code.
+The other three carry sources, code, and markup the components cannot.
+
+- `{"type":"refs","items":[{"title":"<name>","url":"<https URL>","note":"<text>"}, ...]}`: the one reference list, numbered from 1. `url` and `note` are optional, and a `url` must be http or https.
+- `{"type":"code","lang":"ts","text":"<source>"}`: a sample highlighted at render time with no script. `lang` is optional and takes a highlight.js name or alias, and an unregistered one renders plain.
 - `{"type":"raw","html":"<markup>"}`: the escape hatch, passed through unescaped.
 
-Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a lesson body, so a sample written that way stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
+### Where code and raw go
+
+Code never travels through `raw`. A hand-written `<pre><code>` renders with no color, and `nav` never highlights markup already in a body, so it stays plain for good. A fenced block in a reference page's markdown is highlighted by `nav` on its own.
+
+The quiz and teach-back block in `lesson-craft.md` always need `raw`, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, and use `raw` nowhere the other types could carry the content.
 
-The quiz and the teach-back block in `lesson-craft.md` are the one case `raw` is always needed for, since their fixed contract is not a components concern. Give them the array's last `raw` entry, followed only by `refs`, rather than reaching for `raw` anywhere the other types could carry the content instead.
+### Citing
 
-A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than into the sentence. Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened. Render refuses a cite no reference resolves, so number the list before citing into it.
+A claim resting on a source carries a `cites` number, and the source goes in the lesson's one `refs` block rather than the sentence.
+
+- Draw every reference from what `canon teach resource --read` recorded, never from a lead, since a lead is a source nobody opened
+- Render refuses a cite no reference resolves, so number the list before citing into it
 
 ## Building the lesson body
 
-Step 4 of `teach-workspace` reads this section before writing a lesson, after the lesson verb has resolved its path and quiz order. Write the chrome as four empty marker pairs rather than composing it by hand: `<!-- canon:teach:style -->`/`<!-- /canon:teach:style -->` inside `<head>`, and `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->` each with its own close marker, in that order in `<body>`.
+Step 4 of `teach-workspace` reads this section before writing a lesson, after the lesson verb has resolved its path and quiz order. Write the chrome as four empty marker pairs rather than composing it by hand.
+
+- `<!-- canon:teach:style -->` and `<!-- /canon:teach:style -->` inside `<head>`
+- `<!-- canon:teach:header -->`, `<!-- canon:teach:footnav -->`, and `<!-- canon:teach:scripts -->`, each with its own close marker, in that order in `<body>`
+
+### Render the body
 
-Build the authored `<h1>`, lede, body, and quiz as a JSON array of blocks rather than composing markup by hand, and render it through the verb rather than through a component import:
+Build the authored `<h1>`, lede, body, and quiz as a JSON array of blocks, and render it through the verb rather than a component import:
 
 ```bash
 echo '[
@@ -45,9 +59,15 @@ echo '[
 ]' | canon teach render --json
 ```
 
-`## The block list` above states each type and where `raw` belongs. Take the call's `html` field and write it between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
+`## The block list` above states each type and where `raw` belongs. Write the call's `html` field between the header's close marker and the footnav's open marker, and nothing else anywhere in the file.
 
-Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it, and never compose the lesson body by hand as a fallback. That is the state this section exists to end, and a target holds this skill body before it holds the verb, since a plugin skill reaches a target the moment it merges while the CLI reaches one only when a release publishes.
+### When a verb does not resolve
+
+Every verb in this section can be missing from an installed CLI that predates it. Report that rather than proceeding silently, and never hand-compose the body, the chrome, or a palette as a fallback.
+
+A hand-composed body is the state this section exists to end. A target holds this skill body before the verb, since a plugin skill reaches a target on merge while the CLI arrives only when a release publishes.
+
+### Fill the chrome
 
 Then run:
 
@@ -55,19 +75,27 @@ Then run:
 canon teach nav <topic> --json
 ```
 
-It fills every marker pair from what the workspace holds on disk: the embedded stylesheet, the header with its breadcrumb and jump menus, the prev/next footer nav, and the behavior scripts, and it rewrites the workspace's contents page and the teach-root listing in the same run. It refuses a lesson missing one of the four marker pairs by name rather than guessing at the boundary, so a marker dropped while writing the lesson is caught here rather than read back later as a lesson nothing links to. Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it, and never compose the chrome by hand as a fallback.
+It fills every marker pair from what the workspace holds on disk, and rewrites the workspace's contents page and the teach-root listing in the same run.
 
-Seed the stylesheet through the verb rather than authoring a palette, on the first lesson in a workspace:
+- The markers take the embedded stylesheet, the header with its breadcrumb and jump menus, the prev and next footer nav, and the behavior scripts
+- It refuses a lesson missing a marker pair by name rather than guessing the boundary, so a dropped marker is caught here rather than read back as a lesson nothing links to
+
+### Seed the stylesheet
+
+On the first lesson in a workspace, seed the stylesheet through the verb rather than authoring a palette:
 
 ```bash
 canon teach stylesheet <topic> --json
 ```
 
-It writes the design tokens as custom properties and the components built on them, from the one source every other rendered surface reads. Add lesson rules under the seed and reach a value through its property rather than restating the hex, which is what let each workspace fork the palette from every other. It refuses to overwrite, so running it again on a workspace that has grown its own rules is safe and reports `written` as false.
+It writes the design tokens as custom properties and the components built on them, from the one source every rendered surface reads.
+
+- Add lesson rules under the seed, and reach a value through its property rather than restating the hex, which is how each workspace forked the palette
+- It refuses to overwrite, so a rerun on a workspace with its own rules is safe and reports `written` as false
 
-Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it. Do not fall back to writing a palette by hand.
+### Add glossary terms
 
-Add every term the lesson defines to `GLOSSARY.md` through the verb, which places the entries alphabetically in the shape the standard fixes:
+Add every term the lesson defines to `GLOSSARY.md` through the verb, which places entries alphabetically in the shape the standard fixes:
 
 ```bash
 canon teach glossary <topic> --json \
@@ -75,4 +103,4 @@ canon teach glossary <topic> --json \
   --first-seen <the lesson or reference page this batch comes from>
 ```
 
-`--term` repeats and one call writes the file once, which is what keeps a batch of terms from racing on it. A term already defined is refused, since a definition the subject has moved under is a revision of the entry rather than a second one.
+`--term` repeats and one call writes the file once, which keeps a batch of terms from racing on it. A term already defined is refused, since a definition the subject has moved under is a revision of the entry rather than a second one.

package/claude/skills/teach-workspace/references/lesson-craft.md

@@ -25,7 +25,8 @@ A workspace accumulates lessons over weeks. The learner reads them as one body o
 - `canon teach nav` embeds and re-embeds the shared stylesheet into every lesson on each run, so growing that stylesheet, by promoting anything used a second time into it, is the only step left by hand.
 - Keep the structural furniture identical across lessons: where the title sits, where the quiz sits, what a correct answer looks like
 - Do not restate styles inside a lesson. A local override is a decision the next lesson has to either copy or contradict.
-- Refer to another lesson in the same workspace as "lesson" followed by its four-digit number, such as "lesson 0003", and let `canon teach nav` turn the mention into a link and report a number naming no lesson. A hand-written link is the one form nav never checks.
+- Refer to another lesson in the workspace as "lesson" plus its four-digit number, such as "lesson 0003". `canon teach nav` links the mention and reports a number naming no lesson.
+- Never hand-write a link to another lesson, the one form nav never checks
 
 ## Typography
 
@@ -51,7 +52,7 @@ Decide the figure once per lesson, before writing the body.
 
 1. Name the one relationship, boundary, path, or before-and-after the lesson is about. A lesson about none ends here, with `Figure: none, <why it names no structure>` on the reply.
 2. Hold it against the bar in `${CLAUDE_SKILL_DIR}/../draft-figure/references/figures.md`, which also carries the drawing rules.
-3. Draw it hand-written through `canon:draft-figure` into a `raw` block before the quiz, never inside it or after its feedback, which breaks the stepper's gating. Report it, never draw it yourself, if the skill does not resolve.
+3. Draw it through `canon:draft-figure` into a `raw` block before the quiz, never inside it or after its feedback, which breaks the stepper's gating. Report an unresolved skill rather than drawing.
 4. Or write one line on why prose carries it better, such as a structure an earlier lesson gave.
 
 A structure lesson takes step 3 or 4, never neither. Put the outcome on the reply's `Figure:` line, off the lesson page. Never draw to satisfy the step, or on every section (`## Restraint`).
@@ -61,11 +62,13 @@ A structure lesson takes step 3 or 4, never neither. Put the outcome on the repl
 The quiz is the retrieval, so a leak in its construction turns it into a reading test.
 
 - Write every option to the same length, in words and in characters. A longer option reads as the considered one.
-- Write the correct option first and let the ordering verb place it. Position is not the author's to pick: an author who varies it by hand still varies it by judgment, and the judgment settles on the first slot.
+- Write the correct option first and let the ordering verb place it. An author varying position by hand varies it by judgment, which settles on the first slot.
 - Make each wrong option a misconception someone actually holds. An obviously wrong option removes itself and shrinks the question.
-- Write one feedback block per question, covering the correct option and why each distractor fails, saying why rather than whether. One block reads as an explanation where a block per option reads as four verdicts, and only the explanation names what separates a wrong option from the answer.
+- Write one feedback block per question, covering the correct option and why each distractor fails, saying why rather than whether
 - Give feedback after the attempt, never alongside the question
 
+One feedback block reads as an explanation where a block per option reads as four verdicts, and only the explanation names what separates a wrong option from the answer.
+
 ### The markup
 
 The quiz shape is a contract rather than a convention. `canon teach nav` splices a stepper into the lesson that gates on exactly these class names and this nesting, so a quiz written in any other shape renders with every question on screen at once and nothing reports it.
@@ -85,7 +88,9 @@ The quiz shape is a contract rather than a convention. `canon teach nav` splices
 - Mark the correct option with `data-a="1"` and leave the others without the attribute
 - Carry `data-k` on the `label`, since the workspace stylesheet renders the key letter from it
 
-#### Structure and the legacy button
+### Structure and the legacy button
+
+The nesting matters as much as the class names.
 
 - Keep `.fb` the last child of its `.q`. The stepper reveals it as a direct child, and a feedback block nested deeper stays hidden.
 - Put the option text in a `<span>` inside the label rather than bare beside the input, so the workspace can lay the two out
@@ -97,9 +102,9 @@ The stepper hides and shows and sets nothing else, so how a selected option look
 
 A quiz is recognition and a teach-back is production, which is the form retrieval practice prefers. Carry both: the quiz places the learner against options someone could hold, and the teach-back is where the learner finds out what they cannot say without help.
 
-- Ask for an explanation to a named audience rather than for an answer. Asking the learner to explain to somebody who has never written a pattern why a lazy quantifier is not an optional one gives the explanation a floor, where asking them to explain lazy quantifiers gives it none.
+- Ask for an explanation to a named audience rather than for an answer. Telling a non-programmer why a lazy quantifier is not an optional one has a floor, and "explain lazy quantifiers" has none.
 - Ask about the thing the lesson was for, not a detail beside it. A teach-back on a footnote tests attention rather than the material.
-- Carry a self-check the learner can open, as a `<details>` listing what a complete explanation covers, closed by default. A learner reading with no session in the room otherwise gets an ask they cannot grade, and closed leaks nothing.
+- Carry a self-check as a closed `<details>` listing what a complete explanation covers. A learner with no session in the room otherwise cannot grade the ask, and closed leaks nothing.
 - Write the self-check as what the explanation has to cover rather than as the explanation itself. A model answer is read instead of produced, which turns the block back into reading.
 
 ```html

package/claude/skills/teach-workspace/references/pedagogy.md

@@ -25,11 +25,13 @@ Pulling an answer out of memory strengthens it far more than reading it again. R
 - Let the learner fail an attempt before correcting it. A failed retrieval followed by the answer beats being told first.
 - Do not cue the answer in the question. A question restating the material tests reading rather than memory.
 
-The teach-back block is the production form this section prefers, and it is why a lesson carries one beside its quiz rather than a quiz alone. A quiz is recognition, so a lesson offering only one tests the weak form and reports it as retrieval. Asking the learner to explain the material to somebody who does not have it makes them produce the whole structure rather than pick from four, and what the explanation leaves out is the gap the next session places from.
+The teach-back block is the production form this section prefers, which is why a lesson carries one beside its quiz. A quiz is recognition, so a lesson offering only one tests the weak form and reports it as retrieval.
+
+Explaining the material to somebody who lacks it makes the learner produce the whole structure rather than pick from four. What the explanation leaves out is the gap the next session places from.
 
 - Carry a teach-back block in every lesson, asking for an explanation rather than an answer
 - Name the audience the explanation is for, since an explanation with no reader has no floor to sit above
-- Record what the explanation left out under what the learner got wrong. A produced answer and a selected one are both retrieval failures, and splitting them across two sections splits one placement input.
+- Record what the explanation left out under what the learner got wrong. A missed production and a missed selection are both retrieval failures, and two sections would split one placement input.
 
 ## Spacing
 
@@ -41,7 +43,8 @@ The same total time spread across days beats the same time in one sitting. Forge
 
 The ladder is 1, 3, 7, 16, and 35 days. A topic retrieved unaided moves up a rung and a miss drops it back one, held inside the ladder at either end, so a topic the learner keeps missing stays on the shortest gap rather than restarting a sequence.
 
-Do not compute a date from that ladder by hand. `canon teach list <topic> --json` reports the schedule with both dates already resolved for every item, which is what turns the ladder into a number to copy rather than a rule to apply. An author told to widen a gap still picks the gap by judgment, and this is the same reason quiz option order is drawn by a verb rather than stated here.
+- Do not compute a date from that ladder by hand. `canon teach list <topic> --json` reports both dates resolved for every item, a number to copy rather than a rule to apply.
+- An author told to widen a gap still picks it by judgment, the same reason quiz option order is drawn by a verb rather than stated here
 
 ## Interleaving