@erclx/canon 5.37.0 → 5.39.0

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

@@ -37,33 +37,41 @@ Every phase runs under `CANON_NON_INTERACTIVE=1` with no TTY. Three phases
 otherwise pause, and each takes an argument that answers its prompt ahead of
 time:
 
-- `indexes` confirms its folder list with the operator. `setup indexes --all`
-  takes every candidate the scan found, and `--folders <a>,<b>` takes a named
-  set. With neither, and with no TTY, the phase reports its candidates and stops
-  rather than choosing for the operator.
-- `install` and `gov` confirm the proposed extras with the operator.
-  `--extras <a>,<b>` takes a named set and `--extras none` takes none. With
-  neither, and with nobody to answer, both take every proposal and list each in
-  the report rather than stopping.
-- `gov` stops on a detected technology with no matching rule. `--skip-gaps`
-  proceeds with the matched layer and lists the gap in the report.
+| Phase               | Pauses to                                  | Answered ahead by                                          | With neither and no TTY                               |
+| ------------------- | ------------------------------------------ | ---------------------------------------------------------- | ----------------------------------------------------- |
+| `indexes`           | Confirm its folder list                    | `--all` for every candidate, `--folders <a>,<b>` for a set | Reports its candidates and stops rather than choosing |
+| `install` and `gov` | Confirm the proposed extras                | `--extras <a>,<b>` for a set, `--extras none` for none     | Takes every proposal and lists each in the report     |
+| `gov`               | Stop on a detected technology with no rule | `--skip-gaps`, which proceeds and lists the gap            | Stops on the gap                                      |
 
 Claude Code's tool permission dialog is the confirmation gate for everything
 else. Do not pause for a separate confirmation beyond the extras question.
 
 ## Scope
 
-- This skill and `canon init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `canon <domain> install` or `canon sync` paths instead.
+- This skill and `canon init` run once on a fresh scaffold, never on an existing project, and do not guard against clobbering existing configs
+- Add no guard, mode switch, or existing-project branch here. Extend the per-domain `canon <domain> install` or `canon sync` paths instead.
 - The chain stops at the project edge. `git-commit` also ships, reaching the project's history, and does not run here.
-- Claude Code plugins are a machine concern rather than a project one, so no phase here installs them. Install them with `claude plugin install <name> --scope user`, which applies in every project on the machine and is copied into none.
+- Claude Code plugins are a machine concern, so no phase installs them. `claude plugin install <name> --scope user` applies in every project on the machine and copies into none.
 
 ## Declined states
 
-Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends. The first two stop the chain outright and the third runs it on a default the person may not want.
+Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends.
 
-- **An existing project.** Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so any per-domain install picked here is a guess against configs nobody read. The Scope bullet above names the same commands as the authoring alternative, and this is the destination a person takes.
-- **An install wanting the `.claude/` folder alone.** Stop. Run `canon claude init` for the seed docs, then run the `indexes` phase over the project's own documentation folders. Neither needs the tooling sync the `install` phase runs.
-- **A language the toolkit carries no stack for.** The chain still runs, on `base`, with the fallback marked in the preview. A project that wants none of what `base` carries declines there and takes the `gov` phase, which is language-neutral and installs rules without the `base` development dependencies the tooling layer would drop on it. Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+### An existing project
+
+Stop and hand off to `target-check`, which reports what the target already carries before anything is repaired. This chain never reads that, so a per-domain install picked here is a guess against configs nobody read.
+
+### The `.claude/` folder alone
+
+Stop. Run `canon claude init` for the seed docs, then the `indexes` phase over the project's own documentation folders. Neither needs the tooling sync the `install` phase runs.
+
+### A language with no stack
+
+The chain still runs, on `base`, with the fallback marked in the preview. A project wanting none of `base` declines there and takes the `gov` phase, which is language-neutral and drops no `base` development dependencies.
+
+Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+
+### Route rather than build
 
 Do not add a stack, a mode switch, or an existing-project branch to satisfy one of these. Each destination already exists and routing to it costs a line.
 
@@ -91,32 +99,38 @@ CANON_NON_INTERACTIVE=1 canon init \
 
 Omit any flag whose resolved value is empty.
 
-Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `canon init`).
+Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, scripts, gitignore entries, seeds, golden configs, and the reference doc. It walks the extends chain, so `vite-react` also pulls `web` and `base`.
 
-`--write` is required. A headless run without it reports what it would replace and exits 1, since golden configs overwrite whatever the target holds at those paths. Scaffolding into a fresh target has nothing to lose, so pass it directly rather than reading a report first.
+- Skip it if the tooling stack is `base`, which `canon init` already synced
+- `--write` is required. Without it a headless run reports what it would replace and exits 1, since golden configs overwrite the target's files.
+- A fresh target has nothing to lose, so pass `--write` directly rather than reading a report first
 
 ```bash
 CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
 ```
 
-Monorepo with multiple language roots: run `canon init` once at the repo root so `base` (husky, prettier, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped. Take the subtree commands from the per-root rows the preview printed rather than picking folders by hand. Detection found each root and its stack, and the two commands below show the shape.
+### Monorepo with multiple language roots
+
+Run `canon init` once at the repo root so `base` (husky, oxfmt, commitlint, CI) lands once, then sync each subtree with `--skip base`. Take the subtree commands from the preview's per-root rows rather than picking folders by hand.
 
 ```bash
 CANON_NON_INTERACTIVE=1 canon tooling sync vite-react ./frontend --skip base --write
 CANON_NON_INTERACTIVE=1 canon tooling sync python ./backend --skip base --write
 ```
 
-Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs, and its own stack reference reads through `canon tooling reference <stack>`.
+- Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break
+- Each subtree keeps its own framework configs, and its stack reference reads through `canon tooling reference <stack>`
+- A subtree sync withholds `.github/`, since GitHub reads workflows only at the root, and names each withheld file with the `working-directory` a root CI job needs
+- A subtree needs its own `bun init` before its scripts and dependencies land, and the sync warns and skips them until then
 
-A subtree sync withholds `.github/`, since GitHub reads workflows only at the repository root, and names each withheld file with the `working-directory` a root CI job needs. A subtree needs its own `bun init` before its scripts and dependencies land. The sync warns and skips them until then.
+### Post-sync fixups
 
 Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
 
-- **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
 - **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
 - **Docs.** Run `canon tooling reference <tooling-stack>` and `canon tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
 
-Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
+Do not generate oxlint, ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
 
 ## Phase: gov
 
@@ -148,12 +162,9 @@ Read `${CLAUDE_SKILL_DIR}/references/indexes.md`. It holds the scan, the
 frontmatter drafting, the scaffold, the validate step, and the convention seed
 offer.
 
-This phase confirms candidate folders with the operator rather than running
-unattended, which is the one phase in the chain that pauses for a conversation
-unless `--all` or `--folders` answered it ahead of time. A fresh scaffold usually
-has no markdown-heavy folder yet, so this phase frequently finds nothing to
-present, which its reference defines as its own outcome rather than a failure of
-the chain.
+This is the one phase that pauses to confirm candidate folders with the
+operator, unless `--all` or `--folders` answered it ahead of time. A fresh scaffold usually has no markdown-heavy folder yet, so this phase often
+finds nothing, which its reference defines as an outcome rather than a failure.
 
 ## Report
 
@@ -161,7 +172,7 @@ After the chain, report:
 
 - Domains installed, with a check per domain
 - Tooling stack synced, or skipped. Name the layers pulled via the extends chain.
-- Any post-sync fixups applied (ESLint pin, filename renames)
+- Any post-sync fixups applied (filename renames)
 - `verify` outcome, naming the depth it ran at
 
 ### Outcomes and gaps

package/claude/skills/target-setup/references/verify.md

@@ -58,10 +58,11 @@ exit code is the whole verdict.
 | Order | Script      | Skip if                     |
 | ----- | ----------- | --------------------------- |
 | 1     | `lint:fix`  | absent                      |
-| 2     | `typecheck` | absent                      |
-| 3     | `check`     | absent                      |
-| 4     | `test:run`  | absent, fall back to `test` |
-| 5     | `build`     | absent                      |
+| 2     | `format`    | absent                      |
+| 3     | `typecheck` | absent                      |
+| 4     | `check`     | absent                      |
+| 5     | `test:run`  | absent, fall back to `test` |
+| 6     | `build`     | absent                      |
 
 Do not run composite scripts like `check:full`. Do not run `dev`, `preview`,
 `test:e2e`, `test:ui`, or `screenshot` at this depth. They belong to `deep`
@@ -80,7 +81,7 @@ server, and whether the screenshot harness produces output.
 | 3     | `test:e2e`   | absent  | leaf script: exit code  |
 | 4     | `screenshot` | absent  | leaf script: exit code  |
 
-`deep` runs the four above and not the five leaf scripts, which the default
+`deep` runs the four above and not the six leaf scripts, which the default
 depth already covers. The two sets are disjoint, so running both depths runs
 every declared script exactly once.
 

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

@@ -7,17 +7,28 @@ metadata:
 
 # Task board
 
-Owns the two operations that decide a task: bringing its file into existence, and declining one decided against. `task-complete` settles a task once its work exists, marking outcomes `[x]` and archiving a shipped one. Do not mark outcomes or archive here, and do not move a plan by hand.
+Owns the two operations that decide a task: bringing its file into existence, and declining one decided against. `task-complete` settles a task once its work exists, so do not mark outcomes, archive, or move a plan by hand here.
 
 Read `${CLAUDE_SKILL_DIR}/references/tasks.md` before writing any file. It holds the filename convention, the frontmatter contract, and the file format. Do not work them from memory.
 
 ## Guards
 
-- Resolve the board at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo. Every read and write below resolves against that root. The board is gitignored scratch shared across worktrees, so a linked worktree writing to its own `pwd` creates a second board nothing else reads.
-- A new task file is a main-root write, so it goes out as a heredoc. Declining already runs through `canon tasks decline`, which resolves the root in-process. Resolve that root and route the write the way `session-worktree` states.
+- Resolve the board at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo
+  - The board is gitignored scratch shared across worktrees, so a linked worktree writing its own `pwd` creates a second board nothing reads
+- A new task file is a main-root write, so it goes out as a heredoc, routed the way `session-worktree` states. Declining runs through `canon tasks decline`, which resolves the root itself.
 - If `.canon/tasks/` does not exist at that root, stop: `❌ No .canon/tasks/ board. Run canon claude init to set it up.`
-- Route on the request rather than on a flag. Creating names work that does not exist yet, and declining names a task file decided against. A request to archive a shipped task or mark its outcomes belongs to `task-complete`, so name it and stop. If the request fits neither, stop: `❌ Ambiguous. Say whether to create a task or decline one.`
-- Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter after a write. Do not run the regen command directly, except after a shell write from a linked worktree: the hook matches `Write|Edit|MultiEdit` and nothing fires on `Bash`, so that one case regenerates explicitly with `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`.
+- Never hand-edit `.canon/tasks/index.md`, which a hook regenerates from sibling frontmatter after a write
+
+### Routing the request
+
+Route on the request rather than on a flag. Creating names work that does not exist yet, and declining names a task decided against.
+
+- Archiving or marking outcomes belongs to `task-complete`, so name it and stop
+- If the request fits neither, stop: `❌ Ambiguous. Say whether to create a task or decline one.`
+
+### Regenerating the index by hand
+
+Do not run the regen command directly, except after a shell write from a linked worktree. The hook matches `Write|Edit|MultiEdit` and nothing fires on `Bash`, so that one case runs `canon indexes regen --no-stage --root <main-root> <main-root>/.canon/tasks/index.md`.
 
 ## Create
 
@@ -25,99 +36,96 @@ Read `${CLAUDE_SKILL_DIR}/references/tasks.md` before writing any file. It holds
 
 Every task traces to a plan, a groundwork folder, an intake folder, or a GitHub issue. Ask for it when the request does not carry one, and stop rather than guessing: `❌ No origin. Name the plan, groundwork folder, intake folder, or issue this task comes from.`
 
-A task with no origin is either lost context or work nobody decided to do. This is the only moment the invariant is enforceable, because it is the only moment a task file comes into existence.
-
-Accept work whose origin is the conversation itself only when the user says so explicitly, and record what it was in the intro paragraph instead of writing a link line to a file that does not exist.
+A task with no origin is lost context or work nobody decided to do, and creation is the only moment the invariant is enforceable. Accept an origin in the conversation itself only when the user says so, recording it in the intro paragraph rather than a link line.
 
 ### Stop a worker before it claims a label
 
-A session that asserted `canon:role-worker` this run, or whose own name in `canon sessions list --self --json` starts with `worker-`, stops here. It claims no label and writes no file. Report the row's title, its origin, and the surface it would take to the controlling session instead, since a task file with no row is a dropped task and placing the row is that session's call.
+A session that asserted `canon:role-worker` this run, or whose own name in `canon sessions list --self --json` starts with `worker-`, stops here. It claims no label and writes no file.
 
-The guard sits ahead of Step 2 because `--claim` reserves a label on disk, so a stop after it leaves a reservation nothing uses. It names the worker role alone. A planner closing a groundwork track still writes its task file here and reaches Step 4's roster check as before.
+- Report the row's title, its origin, and the surface it would take to the controlling session instead, since placing the row is that session's call
+- The guard sits ahead of Step 2 because `--claim` reserves a label on disk, so a later stop leaves a reservation nothing uses
+- It names the worker role alone. A planner closing a groundwork track still writes its task file here and reaches Step 4's roster check.
 
 ### Step 2: allocate the phase label
 
-Run `canon tasks next-label --claim --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, so the label it returns accounts for what the board alone no longer shows, and `--claim` reserves it under `.canon/ordinal-locks/` so a second session filing at the same moment gets the next one. Branch on the record's `reason` rather than the exit: `label-contended` means re-run the claim, and a usage error from an unknown `--claim` means the installed binary predates the flag, so report the verb as unavailable rather than falling back to a bare read, which reopens the race.
+Run `canon tasks next-label --claim --json` and take its `label` field. The verb reads the live board and its `archive/` sibling together, and `--claim` reserves the label under `.canon/ordinal-locks/` so a concurrent session gets the next one.
 
-Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` permits free renumbering, so the verb's two folders are the only surface that knows what a label currently means.
+- Branch on the record's `reason` rather than the exit. `label-contended` means re-run the claim.
+- A usage error from an unknown `--claim` means the binary predates the flag. Report the verb unavailable rather than falling back to a bare read, which reopens the race.
+- Do not derive the label from a version file. `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` permits free renumbering, so only the verb's two folders know what a label means.
 
 ### Step 3: write the file
 
-Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file first if a session ever stubbed it, following the format in `${CLAUDE_SKILL_DIR}/references/tasks.md`. Include a link line only when the file or folder it names exists. A link to a plan nobody has written yet is the broken pointer the archive rules exist to prevent.
+Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file first if a session ever stubbed it, following the format in `${CLAUDE_SKILL_DIR}/references/tasks.md`. Write it immediately, since Claude Code's tool permission dialog is the confirmation gate.
 
-Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.canon/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`. Leave `Issue:` a bare `#NNN`. A task written in the older bare-path form still parses, so it costs the board a clickable line rather than an archive, but it leaves the board in two shapes for every reader after.
+- Include a link line only when the file or folder it names exists, since a link to an unwritten plan is the broken pointer the archive rules prevent
+- Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.canon/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`
+- Leave `Issue:` a bare `#NNN`. The older bare-path form still parses, but it leaves the board in two shapes for every later reader.
+- Never write a `Pull request:` line here. `git-pr` adds it when a pull request opens, and a number guessed now points at someone else's work.
 
-Never write a `Pull request:` line here. `git-pr` adds it when a pull request opens, and a number guessed at create time points at someone else's work.
+### Step 4: place it on a surface
 
-Write it immediately. Claude Code's tool permission dialog is the confirmation gate. Do not pause for approval.
+A task file with no row is a dropped task, so name its surface in the same pass that creates it. The test and both file shapes are in `${CLAUDE_SKILL_DIR}/references/board.md`.
 
-### Step 4: place it on a surface
+| Task                                        | Surface                                                                                                                         |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Plausibly planned within the next few waves | A row under `## Needs a plan` in `.canon/tasks/priority.md`, positioned against the rows there, with the reason in `Waiting on` |
+| Anything else                               | A line in `.canon/tasks/backlog.md`, which is unordered                                                                         |
 
-A task file with no row is a dropped task, so name the surface it lands on in the same pass that creates it. A task that would plausibly be planned within the next few waves takes a row under `## Needs a plan` in `.canon/tasks/priority.md`, positioned by where it sits against the rows already there, with the reason for that position in its `Waiting on` cell. Anything else takes a line in `.canon/tasks/backlog.md`, which is unordered and where in the file it goes means nothing.
+### Check for a live orchestrator
 
-The test and both file shapes are in `${CLAUDE_SKILL_DIR}/references/board.md`.
+Check the roster before writing either file. Read `canon sessions list --self --json` for this session's own `sessionId` and `name`, then match a row in `canon sessions list --json` against three tests.
 
-Check the roster for a live orchestrator before writing either file. Read `canon sessions list --self --json` for this session's own `sessionId` and `name`, then read `canon sessions list --json` and match a row whose `repository` matches this session's own, whose `sessionId` differs from it, and whose `name` starts with `orchestrator-`. That is the convention every hand-launched controller on this machine currently uses, and it excludes every `worker-` and `planner-` session cleanly. Treat a refusal from either call the same as a roster read that failed.
+- Its `repository` matches this session's own, and its `sessionId` differs
+- Its `name` starts with `orchestrator-`, the convention every hand-launched controller here uses, which excludes every `worker-` and `planner-` session
+- Treat a refusal from either call the same as a roster read that failed
 
-- **Found.** Do not write `priority.md` or `backlog.md`. Report the surface the row would take and the reason worked out above, then hand off by messaging that session with the same information so it places the row itself rather than two sessions writing the board at once.
-- **Not found, and this session's own name (already read above) starts with `worker-` or `planner-`.** Do not write either file. Those two role bodies ban a board write with no exception, and an orchestrator absent from the roster is not consent to break it. Report the row and the surface it would take, so the operator or a later orchestrator places it.
-- **Not found otherwise, or the roster read fails.** Write the row directly, as today. A failed read is indistinguishable from a solo project holding no orchestrator, and stopping would strand the row on the one path this section otherwise keeps unconditional. The row is a main-root write too, so it lands through the same heredoc route the file itself took.
+| Roster read                                                                | Act                                                                                                          |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Found**                                                                  | Write neither file. Report the surface and reason, and message that session so it places the row itself      |
+| **Not found**, and this session's name starts with `worker-` or `planner-` | Write neither file, since both role bodies ban a board write. Report the row and its surface.                |
+| **Not found otherwise**, or the read fails                                 | Write the row directly, through the same heredoc route as the file. A failed read looks like a solo project. |
 
-Say which branch fired and why in the report. The call is a judgment restated on every sweep rather than a property of the task, and a placement with no stated reason is one the next sweep re-derives from nothing.
+Say which branch fired and why in the report. A placement with no stated reason is one the next sweep re-derives from nothing.
 
 ### Step 5: report unlinked origins
 
 Scan for work that has been decided and would otherwise be forgotten. Three origins carry it, and every run reads all three.
 
-List `.canon/groundwork/` and run `gh issue list --state open` when a remote is configured, then grep the board for each track name and issue number. Report any with no task, one line each.
+- List `.canon/groundwork/` and run `gh issue list --state open` when a remote is configured, then grep the board for each track name and issue number
+- Read the dumps through `canon intake list --json`, which reports items, open, unread, and malformed per folder, and parses the contract `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` fixes
+- Grep `.canon/tasks/`, `.canon/tasks/archive/`, and `.canon/tasks/declined/` for each folder slug, since a dump with no live task is usually promoted and settled
 
-Read the dumps through `canon intake list --json`, which reports items, open, unread, and malformed per folder and owns the parse of the answer contract `${CLAUDE_SKILL_DIR}/../plan-intake/references/intake.md` fixes. Then grep `.canon/tasks/`, `.canon/tasks/archive/`, and `.canon/tasks/declined/` for each folder slug. A dump with no live task is the ordinary shape of one already promoted and either shipped or declined, so a check reading the board by itself reports every settled folder as abandoned.
+A dump is the stronger case for this scan. A track holds one question and stays visible, while a dump holds dozens of verdicts left with nothing carrying them forward.
 
-A dump is the stronger case for this scan rather than the weaker one. A track holds one question and stays visible, while a dump holds dozens of items whose verdicts were reached and then left with nothing carrying them forward.
+### The four dump states
 
-Those two reads give four states, and the first three earn a line each:
+Those reads give four states, and the first three earn a line each.
 
-- Every item answered, `malformed` at zero, and none of the board, the archive, or the declined folder cites it. Decided work nobody promoted, which is what this step exists to find.
-- Unread items. The folder is waiting on the operator rather than forgotten, so it takes its own wording and never lands in the block above.
-- `malformed` above zero. An item carrying no answer slot can be reached by no verb, so name the folder as a file to repair rather than as work in either state above.
-- The archive cites it. Promoted and shipped, so say nothing.
+| State                                                                   | Report                                                               |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Every item answered, `malformed` at zero, nothing on any board cites it | Decided work nobody promoted, which is what this step exists to find |
+| Unread items                                                            | Waiting on the operator rather than forgotten, in its own wording    |
+| `malformed` above zero                                                  | A file to repair, since no verb reaches an item with no answer slot  |
+| The archive cites it                                                    | Promoted and shipped, so nothing                                     |
 
-`malformed` is why the first state tests two counts rather than one. A malformed item is neither unread nor answered, so reading `unread` alone folds it onto the answered side and reports a broken file as decided work nobody promoted.
+The first state tests two counts because a malformed item is neither unread nor answered. Reading `unread` alone reports a broken file as decided work nobody promoted.
 
-Say which read fired. "No task points at this" is true of every reported state and useful about none of them.
+### How to report it
 
-Report rather than prompt. A track can be opened long after its task would have been written, so an offer to create one for each is noise on most runs, and that reasoning covers a dump unchanged.
+Say which read fired, since "No task points at this" is true of every state and useful about none of them.
 
-Say the origins were read even when nothing comes back, which is the ordinary result. A step going silent on a clean pass is indistinguishable from one that never ran.
+- Report rather than prompt. A track can open long after its task would have been written, so an offer per origin is noise on most runs.
+- Say the origins were read even when nothing comes back, since a silent clean pass looks like one that never ran
 
 ## Decline
 
-Read `${CLAUDE_SKILL_DIR}/references/decline.md` when the request names a task decided against. It carries gathering the reason, the `canon tasks decline` call, the route for each refusal, and the prose to clear afterwards. Never move the file, edit `priority.md` or `backlog.md`, or regenerate the index by hand, since the command owns all three.
+Read `${CLAUDE_SKILL_DIR}/references/decline.md` when the request names a task decided against. It carries gathering the reason, the `canon tasks decline` call, the route for each refusal, and the prose to clear afterwards.
 
-## Output
+Never move the file, edit `priority.md` or `backlog.md`, or regenerate the index by hand, since the command owns all three.
 
-Emit the full relative path from the project root for every file written or moved. A bare filename names a file the reader cannot open.
-
-Create:
-
-```plaintext
-✅ Created: .canon/tasks/vXX.Y-<slug>.md
-
-<label>, next after <highest>.
-<board or backlog, and why it landed there>.
-
-**Origin with no task:**
-
-- `.canon/groundwork/<slug>/`: open, touched <date>
-- `.canon/intake/<slug>/`: every item answered, nothing promoted
-- #NNN: <issue title>
-
-**Waiting on you:**
-
-- `.canon/intake/<slug>/`: <n> of <n> items unread
-- `.canon/intake/<slug>/`: <n> items carry no answer slot, so no verb reaches them
-```
+## Output
 
-Drop either block when it carries no rows. When both are empty, which is the ordinary result, replace them with one line naming what was read: `Read <n> tracks, <n> dumps, and <n> open issues. Nothing unlinked.`
+Emit the full relative path from the project root for every file written or moved, since a bare filename names a file the reader cannot open. A create run reads `${CLAUDE_SKILL_DIR}/references/create-report.md` for the report block and when each part drops. A decline run skips it.
 
 A refusal reports the reason and the resolution the mode's reference routes it to under its Step 3, on one line each.

package/claude/skills/task-board/references/create-report.md

@@ -0,0 +1,36 @@
+---
+title: Create report
+description: The report a task-board create run closes on, being the created path, the label and surface lines, and the two blocks Step 5's origin scan fills
+---
+
+# Create report
+
+Read from `## Output` of `task-board` when the run created a task. A decline run skips this file and reports through its own reference.
+
+## Report block
+
+```plaintext
+✅ Created: .canon/tasks/vXX.Y-<slug>.md
+
+<label>, next after <highest>.
+<board or backlog, and why it landed there>.
+
+**Origin with no task:**
+
+- `.canon/groundwork/<slug>/`: open, touched <date>
+- `.canon/intake/<slug>/`: every item answered, nothing promoted
+- #NNN: <issue title>
+
+**Waiting on you:**
+
+- `.canon/intake/<slug>/`: <n> of <n> items unread
+- `.canon/intake/<slug>/`: <n> items carry no answer slot, so no verb reaches them
+```
+
+## When a block drops
+
+Drop either block when it carries no rows. When both are empty, which is the ordinary result, replace them with one line naming what was read:
+
+```plaintext
+Read <n> tracks, <n> dumps, and <n> open issues. Nothing unlinked.
+```

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

@@ -82,6 +82,8 @@ Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable
 
 Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
 
+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.
+
 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.
 
 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.
@@ -115,7 +117,7 @@ Why this task exists and what it depends on.
 
 ## Findings
 
-- What constrains the task, dated where it matters.
+- **<source>, <YYYY-MM-DD>:** What constrains the task.
 
 > Test strategy: <unit | component | e2e | visual | manual>, what is being verified
 ```

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

@@ -11,9 +11,12 @@ Owns the two operations that settle a task once its work exists: marking the out
 
 ## Guards
 
-- Resolve the board at the main worktree root, not `pwd`. Run `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo. The board is gitignored scratch shared across worktrees, so a linked worktree reading its own `pwd` finds no board at all.
-- If `.canon/tasks/` does not exist at that root, Mark has nothing to mark: report `⏭️ No .canon/tasks/ board, so no outcomes to mark.` and return, still running Step 4's receipt sweep, since `git-ship` invokes Mark on every ship and a project with no board is not a failed one. Archive stops instead: `❌ No .canon/tasks/ board. Run canon claude init to set it up.`
-- Route on the request rather than on a flag. A request naming a shipped task to archive, or a task file the `post-merge` hook left in place, takes Archive. Every other request takes Mark, which is what the ship chain invokes.
+- Resolve the board at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd` outside a git repo
+  - The board is gitignored scratch shared across worktrees, so a linked worktree reading its own `pwd` finds no board
+- With no `.canon/tasks/` at that root, Mark reports `⏭️ No .canon/tasks/ board, so no outcomes to mark.` and returns, still running Step 4's sweep
+  - `git-ship` invokes Mark on every ship, and a project with no board is not a failed one
+- With no board, Archive stops instead: `❌ No .canon/tasks/ board. Run canon claude init to set it up.`
+- Route on the request rather than on a flag. A shipped task to archive, or a task file the `post-merge` hook left, takes Archive, and every other request takes Mark.
 - Never hand-edit `.canon/tasks/index.md`. A hook regenerates it.
 
 ## Mark
@@ -26,21 +29,17 @@ Resolve the base ref once:
 git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
 ```
 
-Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD`, and `git ls-files --others --exclude-standard`. Read content with `git diff <base> HEAD` and `git diff HEAD`.
+- Take the union of `git diff --name-only <base> HEAD`, `git diff --name-only HEAD`, and `git ls-files --others --exclude-standard`
+- Read content with `git diff <base> HEAD` and `git diff HEAD`
+- Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set.
 
-Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and this step goes blind to the work it is meant to read.
-
-The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD. On an unusable baseline, read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 2 for what to read instead.
+The baseline is unusable when no merge base resolves against either ref, or when the base came from local `main` and equals HEAD. Then read `${CLAUDE_SKILL_DIR}/references/unusable-baseline.md` before Step 2 for what to read instead.
 
 ### Step 2: match the diff against the board
 
-Read `.canon/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths, and read them.
-
-Path matching only chooses which files to open. Behavior decides each outcome. For each unchecked outcome, decide whether the diff shipped the behavior that outcome names.
-
-Completion is a fact about the repository rather than a fact about the conversation, so the diff decides it and the session does not.
+Read `.canon/tasks/index.md` at the main worktree root, pick the task files whose title or description relates to the changed paths, and read them. Path matching only chooses which files to open.
 
-Keep the match conservative:
+For each unchecked outcome, decide whether the diff shipped the behavior it names, since completion is a fact about the repository and not the conversation. Keep the match conservative:
 
 - Mark only outcomes already written on the board. Never infer a new task from the diff.
 - Match on the behavior an outcome describes, not on filenames or commit subjects. The path match above only narrowed which task files to open.
@@ -49,11 +48,12 @@ Keep the match conservative:
 
 ### Step 3: close the matched outcomes
 
-Mark each completed outcome `[x]` in the task's own file through `canon tasks outcome <stem> --close <n> --json`, repeating `--close` for each. Positions count every outcome checkbox in file order from 1, which the read above already gives. Do not move or archive the file, even when every outcome now reads `[x]`, since the pull request has not merged and the `post-merge` hook archives the task once it does.
+Mark each completed outcome `[x]` in the task's own file through `canon tasks outcome <stem> --close <n> --json`, repeating `--close` for each. Positions count every outcome checkbox in file order from 1.
 
-The verb resolves the board at the main worktree root in-process, which is the route `session-worktree` states for an edit inside an existing main-root file.
-
-Read `ok` and `reason` out of that record rather than the exit. 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 flattens every non-zero exit to zero. A refusal arriving as success leaves the outcome unmarked while the chain moves on, so the board reports shipped work as open and the next session re-plans it.
+- Do not move or archive the file, even when every outcome reads `[x]`. The pull request has not merged, and the `post-merge` hook archives the task once it does.
+- The verb resolves the board at the main worktree root in-process, the route `session-worktree` states for an edit inside a main-root file
+- Read `ok` and `reason` from the record rather than the exit, since a shell function wrapping `canon` can flatten a refusal to zero
+- A refusal read as success leaves the outcome unmarked, so the board reports shipped work as open and the next session re-plans it
 
 ### Step 4: sweep consumed receipts
 
@@ -61,7 +61,9 @@ Read `${CLAUDE_SKILL_DIR}/references/receipt-sweep.md` for which review receipts
 
 ## Archive
 
-Read `${CLAUDE_SKILL_DIR}/references/archive.md` when the request names a shipped task to archive. It carries the check that the work reached `main`, the `canon tasks archive` call, the route for each refusal, and the prose to clear afterwards. Never move the file, edit `priority.md`, or regenerate the index by hand, since the command owns all three.
+Read `${CLAUDE_SKILL_DIR}/references/archive.md` when the request names a shipped task to archive. It carries the check that the work reached `main`, the `canon tasks archive` call, each refusal's route, and the prose to clear.
+
+Never move the file, edit `priority.md`, or regenerate the index by hand, since the command owns all three.
 
 ## Output