@erclx/canon 5.41.0 → 5.43.0

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

@@ -5,9 +5,7 @@ description: The catalog reads, evidence list, argument resolution, gap handling
 
 # Detect and resolve
 
-What the `install` and `gov` phases both do before they write anything. Stated
-once here rather than twice in the body, since the two phases differ in what
-they install rather than in how they read the project.
+What the `install` and `gov` phases both do before they write anything. Stated once here rather than twice in the body, since the two phases differ in what they install rather than in how they read the project.
 
 ## Contents
 
@@ -19,25 +17,20 @@ they install rather than in how they read the project.
 
 ## Read the catalogs
 
-Run in parallel. Never hardcode stack, rule, or standards names. The
-catalog is the source of truth.
+Run in parallel. Never hardcode stack, rule, or standards names. The catalog is the source of truth.
 
-Run from the target project's current directory. Do not cd into the toolkit
-source tree. The `canon` CLI is global.
+Run from the target project's current directory. Do not cd into the toolkit source tree. The `canon` CLI is global.
 
 ```bash
 canon gov list --json 2>/dev/null
 canon tooling list --json 2>/dev/null
 ```
 
-The `gov` phase needs only the first. Run both anyway on a bare invocation,
-since the chain reaches the tooling resolution a moment later.
+The `gov` phase needs only the first. Run both anyway on a bare invocation, since the chain reaches the tooling resolution a moment later.
 
 ## Detect
 
-A monorepo keeps its languages in subfolders, so read the markers from every
-folder to depth two rather than from the root alone. Collect the language roots
-first:
+A monorepo keeps its languages in subfolders, so read the markers from every folder to depth two rather than from the root alone. Collect the language roots first:
 
 ```bash
 git ls-files --cached --others --exclude-standard \
@@ -45,25 +38,21 @@ git ls-files --cached --others --exclude-standard \
   | awk -F/ 'NF <= 3'
 ```
 
-Every folder holding a marker is a language root, and the repository root is
-one when it holds a marker itself. Going through git keeps ignored trees such as
-`node_modules/`, `vendor/`, and `.venv/` off the list, since each carries
-markers of its own. Outside a git repository, fall back to
-`find . -maxdepth 3 \( -path '*/.*' -o -name node_modules -o -name vendor \) -prune -o -type f -print`
-filtered to the same five names.
+Every folder holding a marker is a language root, the repository root included when it holds one itself. Going through git keeps ignored trees such as `node_modules/`, `vendor/`, and `.venv/` off the list, since each carries markers of its own.
 
-Depth two reaches a service folder at depth one and a workspace package under
-`packages/<name>/` at depth two. Deeper, the walk starts finding fixtures and
-examples as false roots.
+- Outside a git repository, fall back to `find . -maxdepth 3 \( -path '*/.*' -o -name node_modules -o -name vendor \) -prune -o -type f -print` filtered to the same five names
+- Depth two reaches a service folder at depth one and a workspace package under `packages/<name>/`. Deeper, the walk finds fixtures and examples as false roots.
 
-Then read these per language root in parallel, skipping any that do not exist:
+### Per root
+
+Read these per language root in parallel, skipping any that do not exist:
 
 - `package.json`: `dependencies` and `devDependencies`
 - The root's own configs: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `composer.json`, `Cargo.toml`
 
-A non-JavaScript marker outranks a `package.json` in the same folder. A Go or
-Composer service often carries a `package.json` only to host scripts, so that
-folder is a Go or PHP root rather than a JavaScript one.
+A non-JavaScript marker outranks a `package.json` in the same folder. A Go or Composer service often carries a `package.json` only to host scripts, so that folder is a Go or PHP root.
+
+### Once, at the root
 
 Read these once, from the repository root:
 
@@ -72,39 +61,56 @@ Read these once, from the repository root:
 
 ## Resolve arguments
 
-Governance installs once, at the repository root, and a rule's `paths:` globs
-already reach every subfolder. Tooling installs per folder. So resolve one
-governance stack for the whole repository and one tooling stack per language
-root.
+Governance installs once, at the repository root, and a rule's `paths:` globs already reach every subfolder. Tooling installs per folder, so resolve one governance stack for the whole repository and one tooling stack per language root.
+
+### Governance stack
+
+Match the repository root's detected language against stack names in the catalog. Governance stacks are per language, so a framework never names one, and its rules arrive as extras.
+
+- If the root matched nothing, `base` is the stack, even when subfolders matched. No subfolder owns the repository, and picking one by order states a preference nobody gave.
+- Mark it `fallback` in the preview only when no root matched anywhere
+
+### Tooling stack
+
+For each language root, pick the closest tooling stack from `canon tooling list --json`, such as `vite-react`, `astro`, or `nextjs`. It is distinct from the governance stack.
+
+- Fall back to `base` for a root with no framework or language match, and carry that fallback into its preview row
+- Map `next` in a root's dependencies, or a `next.config.ts`, `.js`, or `.mjs` there, to the `node` governance stack and the `nextjs` tooling stack
+- The `next` dependency name alone matches no stack, and the Next.js rule arrives as an extra
+
+### Extras
+
+Run `canon gov detect <target> --stack <stack> --json` from the target and take its `proposals` array as the candidate extras. Each proposal names a `rule` and the `evidence` that matched it across every language root to depth two.
+
+- The verb already leaves out every rule the picked stack resolves, so do not dedupe again
+- Do not match a rule's `description` or `paths` by hand
+- The verb proposes no language rule, since a stack reaches each one
+
+A language root below the repository root whose language the stack does not carry contributes its language rule by name, read from `canon gov list --json`.
+
+### Subfolder tooling and skips
 
-- **Stack:** pick the governance stack by matching the repository root's detected language against stack names in the catalog. Governance stacks are per language, so a framework never names one, and its rules arrive as extras. If the root matched nothing, `base` is the stack, including when subfolders matched, since no subfolder owns the repository and picking one by order would state a preference nobody gave. Mark it `fallback` in the preview only when no root matched anywhere.
-- **Tooling stack:** for each language root, pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`, `nextjs`). Distinct from the governance stack. Fall back to `base` for a root with no framework or language match, and carry that fallback into its preview row.
-- **Next.js:** map `next` in a root's `package.json` dependencies, or a `next.config.ts`/`.js`/`.mjs` file in that root, to the `node` governance stack and the `nextjs` tooling stack. The dependency name does not match the tooling stack name by itself, and the Next.js rule arrives as an extra.
-- **Extras:** run `canon gov detect <target> --stack <stack> --json` from the target and take its `proposals` array as the candidate extras. Each proposal names a `rule` and the `evidence` that matched it across every language root to depth two. The verb already leaves out every rule the picked stack resolves, so do not dedupe again, and do not match a rule's `description` or `paths` by hand.
-- **Subfolder language rules:** a language root below the repository root whose language the picked stack does not carry contributes its language rule by name, read from `canon gov list --json`. The verb proposes no language rule, since a stack reaches each one.
-- **Subfolder tooling:** a language root below the repository root takes its own `canon tooling sync <stack> <path> --skip base`, since `canon init` already lands `base` once at the root. Leave a root whose stack resolves to `base` out of the commands, since that sync would land nothing. A repository-root `package.json` hosting only formatters and hooks is that case, and it adds no row.
-- **Skip (`--skip`):** `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
+A language root below the repository root takes its own `canon tooling sync <stack> <path> --skip base`, since `canon init` already lands `base` once at the root.
+
+- Leave a root whose stack resolves to `base` out of the commands, since that sync lands nothing. A root `package.json` hosting only formatters and hooks is that case and adds no row.
+- `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
 
 ## Gap handling
 
-If a detected technology has no matching rule or stack, do not guess. Surface
-the gap.
+If a detected technology has no matching rule or stack, do not guess. Surface the gap.
+
+On the full chain, either defer and author a rule in the toolkit before re-running, or proceed with the matched layer and list the gap in the final report. Rules and stacks are authored in the toolkit repository, never in the target project on the fly.
 
-On the full chain, either defer and author a rule in the toolkit before
-re-running, or proceed with the matched layer and list the gap in the final
-report. Rules and stacks are authored in the toolkit repository, never in the
-target project on the fly.
+### The gov phase
 
 On the `gov` phase, stop and present four options rather than picking:
 
-1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `${CLAUDE_SKILL_DIR}/../create-rule/references/rule.md`, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
-2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
+1. Author a rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` per `${CLAUDE_SKILL_DIR}/../create-rule/references/rule.md`, commit, and re-run install, when every project should get it.
+2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this when the rule is project-specific and no sync should overwrite it.
 3. Install the matching non-`<tech>` rules and skip the tech-specific layer.
 4. Abort.
 
-`--skip-gaps` takes option 3 ahead of the prompt, which is what keeps the phase
-non-interactive. This skill authors no rule itself. Option 1 writes in the
-toolkit repository, and option 2 hands the project-local file to `create-rule`.
+`--skip-gaps` takes option 3 ahead of the prompt, which keeps the phase non-interactive. This skill authors no rule itself, since option 1 writes in the toolkit and option 2 hands the file to `create-rule`.
 
 ## Preview
 
@@ -112,28 +118,37 @@ Before executing, output:
 
 - **Detected:** each technology with its evidence file, path included, so a subfolder marker reads as one
 - **Stack:** picked governance stack and resolved rule count. Mark it `fallback` when no detected language matched a catalog name.
-- **Tooling stack:** one row per language root, each carrying its path, its picked tooling stack, a `fallback` mark on the same test, and its own command. On the repository root's row, name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first. Omit these rows entirely on the `gov` phase, which syncs no tooling.
-- **Extras:** each proposal with the evidence the verb returned, plus each subfolder language rule, listed in full as the list the operator confirms. A second matched stack reaches the install only through this list, since `canon init --stack` takes one stack, so a shortened list reads as that stack dropped.
+- **Tooling stack:** one row per language root, each with its path, picked stack, a `fallback` mark on the same test, and its own command. Omit these rows on the `gov` phase.
+- **Extras:** each proposal with the evidence the verb returned, plus each subfolder language rule, listed in full as the list the operator confirms
 - **Skip:** any `--skip` entries with reason
 - **Target:** resolved target path
 - **Commands:** the full chain that will run
 
-A resolved name and a fallback read alike once written, so mark the fallback
-here rather than in the report. The preview is the last point before the first
-write, and the report runs after the files have landed.
+### The root tooling row
+
+On the repository root's row, name what `base` lands. Configs, seeds, and gitignore entries land in every case.
+
+- The JavaScript development dependencies, scripts, and hook activation land wherever a `package.json` exists to carry them
+- A project outside that ecosystem runs none of that second group and keeps the first
+
+### Why mark it here
+
+A resolved name and a fallback read alike once written, so mark the fallback in the preview rather than the report. The preview is the last point before the first write.
+
+The extras list stays whole for a similar reason. `canon init --stack` takes one stack, so a second matched stack reaches the install only through this list, and a shortened list reads as that stack dropped.
 
 ### Confirm the extras
 
-The extras are the one part of the preview the operator confirms before the
-install runs, since a proposal is evidence that a project might want a rule
-rather than proof that it does. Put the list through the structured question
-surface with three options: take every proposal, which is the recommended
-first option, take none, or name a subset, which the operator types as a
-comma-separated list. Pass what they kept to `--add` and drop the flag when
-they kept nothing.
-
-An `--extras` argument answers ahead of time and skips the question.
-`--extras <a>,<b>` takes the named rules, and `--extras none` takes none. With
-neither and no one to answer, take every proposal and list each in the report,
-since a proposed rule costs one file to delete and stopping would break every
-headless setup.
+The extras are the one part of the preview the operator confirms before the install runs, since a proposal is evidence that a project might want a rule rather than proof that it does. Put the list through the structured question surface with three options.
+
+- Take every proposal, the recommended first option
+- Take none
+- Name a subset, which the operator types as a comma-separated list
+
+Pass what they kept to `--add`, and drop the flag when they kept nothing.
+
+### Answering ahead
+
+An `--extras` argument answers ahead of time and skips the question. `--extras <a>,<b>` takes the named rules, and `--extras none` takes none.
+
+With neither and no one to answer, take every proposal and list each in the report. A proposed rule costs one file to delete, and stopping would break every headless setup.

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

@@ -29,7 +29,8 @@ before scanning.
 
 - Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
 - All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
-- This phase is where an install wanting the Claude layer without the tooling chain arrives, once `canon claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
+- An install wanting the Claude layer without the tooling chain arrives here once `canon claude init` has seeded the docs
+- The work is the same either way, since the scan prunes `.claude` and reads the project's own documentation folders whichever route reached it
 
 ## Scan
 
@@ -75,7 +76,8 @@ candidate list and stop rather than choosing on the operator's behalf.
 For each chosen folder, read every `*.md` sibling and draft frontmatter:
 
 - `title`: derived from the first H1. If absent, derive from the filename in sentence case.
-- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1. Follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` § Frontmatter descriptions for length and style.
+- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1
+- Follow `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` § Frontmatter descriptions for the description's length and style
 
 Surface every drafted entry to the user grouped by file:
 
@@ -131,10 +133,10 @@ canon indexes regen --json
 ```
 
 Count the `written` actions in that record and report the number. Read the real
-run the same way the dry run is read, since the exit carries nothing reliable
-back to a session. 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, so a
-regen that errored on a sibling missing `title` arrives here as a clean pass.
+run the way the dry run is read, since the exit carries nothing reliable back.
+
+- An operator's shell profile may wrap `canon` in a function that takes a second command's status
+- A regen that errored on a sibling missing `title` then arrives here as a clean pass
 
 ## Offer the convention seed
 

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

@@ -40,51 +40,104 @@ A board failing these is non-conforming even when it satisfies every shape rule
 
 `canon tasks list` reports each task's readiness from `priority.md` and `backlog.md`, so a reader never infers it from the folder.
 
-`backlog.md` is optional. A project small enough that every task it holds would be planned soon carries none, and the ordering rules below then describe the whole board.
+| File          | Rule                                                                                      |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `priority.md` | Required. Carries execution order and what each task waits on                             |
+| `backlog.md`  | Optional. A project whose every task would be planned soon carries none                   |
+| `index.md`    | Generated from sibling frontmatter by a hook passing the changed path. Never hand-edit it |
 
-`index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
-
-The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks, handoffs included. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
+The folder is gitignored, so the whole-repo index walk skips it. The catalog filters nothing and carries a row per sibling, handoffs included, so a reader taking every row as a task reports the handoffs as queued work.
 
 ## Ordering
 
-`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on, one line per row.
+`priority.md` carries execution order and what each task waits on. The generated index sorts by filename and says nothing about order, so without this file board state gets rebuilt by hand every session.
+
+### Where the rationale lives
+
+Why a row sits where it does is stated on the row, in the cell that already says what the task waits on, one line per row.
 
-That cell is the only home sequencing rationale has. Rationale spanning several rows, why one group of work runs before another, is carried by nothing and reaches a later session only through whoever remembers it. Naming the gap is deliberate: a second document holding it would be the version-sequencing surface this board replaced, and a row already states what it waits on, which is the part of the reasoning a reader acts on.
+- Rationale spanning several rows has no home, and the gap is deliberate. A second document holding it would be the version-sequencing surface this board replaced.
+- The row already states what it waits on, which is the part of the reasoning a reader acts on.
 
-Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
+### The shape
+
+Group tasks by readiness rather than by status, one row per task, under the columns each group fixes. Keep it to links and blockers, being tables plus at most one sentence per section.
+
+- A paragraph in `priority.md` is a defect whatever it says
+- Stating the shape lets a single diff fail. A size cap trips only after the fact, and every addition looks defensible on its own.
 
 ### Readiness groups
 
-Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. The names are the contract rather than a suggestion, because a board grouped by readiness under names of its own satisfies every other rule here and still reads as empty to anything counting rows under a heading. Add no fourth group. A task belongs to exactly one, and the tests are read in order.
+Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. A task belongs to exactly one, and the tests are read in order.
+
+| Group             | Test                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `## Run now`      | A written plan covers every open outcome, and nothing stated keeps the task from start |
+| `## Up next`      | A written plan exists, and the `Waiting on` column names why the task cannot start     |
+| `## Needs a plan` | Everything else. No plan, or a plan that no longer describes the work                  |
+
+The names are the contract. A board grouped by readiness under names of its own reads as empty to anything counting rows under a heading, so add no fourth group.
+
+### What blocks a run
+
+A collision with running work blocks a task only where no merge settles it, being a contract, a relocation, or a sweep. A shared file alone is none, since the branch merging second rebases.
+
+- A worker is handed a task from `## Run now` alone, and its `Touches` column states the set to read
+- Each group's columns follow from its test. Neither half of the `## Run now` test is checkable without the file set and the plan beside the task.
+
+### The `Touches` cell
 
-- `## Run now`: a written plan covers every open outcome, and the task carries no reason it cannot start. A collision with running work is one such reason only where no merge settles it, being a contract, a relocation, or a sweep. A shared file alone is none, since the branch merging second rebases. The `Touches` column states the set to read. A worker is handed a task from this group alone.
-- `## Up next`: a written plan exists, and the task carries a stated reason it cannot start. The `Waiting on` column names that reason.
-- `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
+A `Touches` cell is copied from its plan's list, so it states what the branch sets out to write rather than a bound on it. A branch outgrows it while the row still reads as it did at dispatch.
 
-Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task.
+- Once a branch runs, correct the cell from the diff rather than the plan, which is the prediction that already went stale
+- `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in the group
+- The row's owner writes the correction. A worker never edits this board.
 
-A `Touches` cell is copied from its plan's own list, so it states what the branch sets out to write rather than a bound on it, and a branch outgrows it while the row still reads as it did at dispatch. Correct the cell from the branch rather than from the plan once one is running, since the plan is the prediction that already went stale and only the diff says what was written. `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in this group, and the row's owner is the one who writes the correction: a worker never edits this board.
+### Cell width
 
-A cell holds no code span whose longest unbroken run passes 60 characters, since a span has no break point and a wider one makes its table scroll sideways in the preview. Write a brace-glob out as separate paths for the same reason. `canon tasks validate` reports both in its `wide` array and moves no exit code.
+A cell holds no code span whose longest unbroken run passes 60 characters. A span has no break point, and a wider one makes its table scroll sideways in the preview.
+
+- Write a brace-glob out as separate paths for the same reason
+- `canon tasks validate` reports both in its `wide` array and moves no exit code
 
 ### Row order
 
-Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, which is mechanical, and none of them answers which task is worth starting, which is a judgment no column holds. Position is where that judgment is recorded, so the top row is the answer to what to plan next and a reader needs no other surface to get it. The other two groups take the same reading, and it costs them little, since a group holding what is already planned is short by construction.
+Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, and none answers which task is worth starting, a judgment no column holds.
 
-Position alone carries it, and no rank column exists. A number beside each row is a second thing to keep in step with the order it duplicates, and the file is edited by one session at a time, so the order the rows are written in is already unambiguous. State on each row why it sits where it does, in the same cell that carries what it is waiting on. A position with no stated reason is re-derived from memory by the next session, which is the failure the ordering replaces rather than moves.
+- Position records that judgment, so the top row answers what to plan next. The other two groups read position the same way, and they are short by construction.
+- No rank column exists. A number beside each row duplicates the order, and one session edits the file at a time, so the written order is unambiguous.
+- A position with no stated reason gets re-derived from memory by the next session, the failure the ordering replaces
 
 ### The waiting-on cell
 
-The `Waiting on` column under `## Up next` carries that reason in one of three forms. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
+The `Waiting on` column under `## Up next` carries the reason in one of three forms. `## Needs a plan` states no file set, because a task with no plan has no bounded one. A group with no rows keeps its heading and header row.
+
+| Form               | The cell names                                                                |
+| ------------------ | ----------------------------------------------------------------------------- |
+| Collision          | The file the running task holds, and whether a contract, relocation, or sweep |
+| Sibling task       | That task                                                                     |
+| External condition | The condition and what would satisfy it                                       |
+
+Naming what would satisfy a condition separates a blocked row from one nobody examined, so a condition with no way out fails the test. The header text is the contract, since a reader resolves the column by header rather than position.
+
+### The needs-a-plan cell
+
+Under `## Needs a plan` the cell takes two clauses, being what the task needs before it can be planned and then why it sits at this position. The second clause names what the row ranks against, a sibling row or the class of rows it sits in.
 
-Under `## Up next` a collision names the file held by the task already running and which hold it is: a contract, a relocation, or a sweep. A sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
+- The row `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, or `outranks` what it names, or `sits under`, `above`, or `below` it
+- Either form puts something other than this row in the clause, which makes the position readable by anyone but its author
+- `canon tasks validate` reads that clause back and recognizes this vocabulary alone. A phrasing outside it reports as unranked, and widening it is a change to the check.
 
-Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. The second clause is comparative, and it names what the row is ranked against in one of two forms: a sibling row, or the class of rows it sits in. The row `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, or `outranks` whichever it names, or `sits under`, `above`, or `below` it. Either form puts something other than this row in the clause, which is what makes the position readable by anyone but its author.
+### What the cell drifts into
 
-Why the task matters is not that claim, and it is what the cell drifts into. A reason naming no other row ranks against nothing, so every row reads defensible on its own and the order records when each was filed. The comparison replaces that reason rather than joining it, since the cell still takes two clauses and no third one is licensed by naming a rival in the second. A cell running past that is the paragraph this file already deletes, arriving one row at a time rather than all at once, and the group is where it costs the most, since it holds the rows nobody has read recently and is the longest group on any board that needs a backlog at all.
+Why the task matters is not the comparative claim, and it is what the cell drifts into. A reason naming no other row ranks against nothing, so every row reads defensible and the order records only when each was filed.
 
-`canon tasks validate` reads that clause back, so a cell phrased comparatively and unusually reports as unranked. The vocabulary above is the whole of what it recognizes, and widening it is a change to the check rather than something the cell may decide for itself.
+- The comparison replaces that reason rather than joining it, and no third clause is licensed by naming a rival in the second
+- A longer cell is the deleted paragraph arriving one row at a time. It costs most in this group, which holds the rows nobody read recently.
+
+### Template
+
+The tests live here so the board does not carry them. A sentence under each heading produces the deleted paragraph, and a criterion with no home gets restated from memory each time.
 
 ```markdown
 ---
@@ -112,19 +165,22 @@ description: One line on what the board covers
 | [vXX.Y <slug>](vXX.Y-<slug>.md) | <what it needs before it can be planned, and which row or class it ranks against> |
 ```
 
-The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
-
 ## The backlog
 
-A task sits on the board when it would plausibly be planned within the next few waves, and on `backlog.md` otherwise. The call is a judgment, so restate it whenever the board is swept rather than making it once: a backlogged task rises when the work in front of it lands or the world changes under it, and a board row falls to the backlog when it stops being near-term.
+A task sits on the board when it would plausibly be planned within the next few waves, and on `backlog.md` otherwise. Restate that judgment whenever the board is swept, since a backlogged task rises when the work in front of it lands and a board row falls when it stops being near-term.
+
+### Why a split
+
+A test over age or origin was the alternative, and neither predicts what gets picked next. Leaving everything on the board produces a group too long to rank.
 
-A mechanical test over age or origin was the alternative and neither predicts what gets picked next, which is the judgment the ordering exists to carry. Leaving everything on the board is the other alternative, and it is what produces a group too long to rank, where the ordering means nothing because nobody can hold the whole list in one reading.
+- The split keeps the board short enough for its order to be read, at the cost of a second surface
+- The trade pays only while the backlog carries no order, no groups, and no readiness claim
 
-What the split buys is that the board is short enough for its order to be read, and what it costs is a second surface to keep. That trade only pays while the backlog stays honest about what it is, which is why it carries no order, no groups, and no readiness claim.
+### Shape
 
-Nothing is deleted. A backlogged task keeps its file, its findings, and its frontmatter, and the backlog row is a pointer at that file. The folder is gitignored and has no history behind it, so a row dropped without landing somewhere readable is gone with nothing to recover it from.
+Nothing is deleted. A backlogged task keeps its file, findings, and frontmatter, and the row points at that file. The folder has no history, so a row dropped without landing somewhere readable is gone.
 
-The backlog is a flat list of links under one heading, sorted by filename. Sorting mechanically is what keeps it from reading as a queue: the order is the same order the index already sorts in, so no position on it means anything.
+The backlog is a flat list of links under one heading, sorted by filename. The order matches the index, so no position on it reads as a queue.
 
 ```markdown
 ---
@@ -140,8 +196,8 @@ Unordered. Nothing here is scheduled, and a task rises to `priority.md` when it
 - [vXX.Y <slug>](vXX.Y-<slug>.md)
 ```
 
-Add no fourth readiness group in place of this file. The three group names are the contract, and a backlog is a separate surface rather than a group because it makes no readiness claim at all: it says nobody has scheduled the task, which is a fact about attention rather than about whether the work can start.
+Add no fourth readiness group in place of this file. A backlog makes no readiness claim, only that nobody has scheduled the task, a fact about attention rather than whether the work can start.
 
 ## Validation
 
-`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `canon tasks validate --help`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.
+`canon tasks validate` reads the board against the tree, and `canon tasks validate --help` states what it checks, refuses on, and reports. Run it when the readiness claim is made rather than on a schedule, since the board is per-machine scratch and no shared moment exists to hang it on.

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

@@ -7,15 +7,13 @@ description: How task-board gathers the reason a task is decided against, runs c
 
 The Decline mode of `task-board`. The session reads this file when the request names a task decided against.
 
-Read `${CLAUDE_SKILL_DIR}/references/tasks-decline.md` first. It holds the declined folder, the `Declined:` line, and what the move does to a plan and a board row.
-
-A task decided against carries no `post-merge` hook of its own, so every decline request arrives here directly rather than through work the hook already did.
-
-Do not move the file, edit `priority.md` or `backlog.md`, or regenerate the index by hand. `canon tasks decline` owns all three as one unit.
+- Read `${CLAUDE_SKILL_DIR}/references/tasks-decline.md` first, for the declined folder, the `Declined:` line, and what the move does to a plan and a board row
+- A declined task carries no `post-merge` hook of its own, so every decline request arrives here directly
+- `canon tasks decline` moves the file, edits `priority.md` or `backlog.md`, and regenerates the index as one unit. Do none of the three by hand.
 
 ## Step 1: gather the reason
 
-Ask for the reason when the request does not carry one, and stop rather than guessing: `❌ No reason. Say why the task is being declined.` The command takes it as `--reason <text>` and refuses without it, so gathering it here saves a round trip through that refusal.
+Ask for the reason when the request carries none, and stop rather than guessing with `❌ No reason. Say why the task is being declined.` The command refuses without `--reason <text>`, so asking first saves the round trip.
 
 ## Step 2: run the decline
 
@@ -25,18 +23,36 @@ Pass the task's filename stem:
 canon tasks decline <stem> --reason "<text>" [--by <name>] --json
 ```
 
-The command refuses rather than reports, and the refusal reaches this skill through the record rather than through the exit, the same wrapper hazard `canon tasks archive` carries. Branch on `ok`, then on `reason`.
+Branch on the record's `ok`, then on `reason`, never on the exit. A shell wrapper can flatten the exit, the same hazard `canon tasks archive` carries.
+
+### Success record
+
+A successful decline returns one record whose fields match `canon tasks archive` where the two overlap.
 
-On success the record carries `from`, `to`, `priorityRowRemoved`, `backlogRowRemoved`, and `indexRegenerated`, where `backlogRowRemoved` is decline's own field since a task can be declined straight off `backlog.md` and archive never checks that file. It also carries `plans`, one `from` and `to` for each live plan the task was the last live citation of, empty when nothing moved, the same shape `canon tasks archive` uses for its own `plans` field.
+| Field                | Holds                                                                    |
+| -------------------- | ------------------------------------------------------------------------ |
+| `from`, `to`         | The task's old and new path                                              |
+| `priorityRowRemoved` | Whether a `priority.md` row was dropped                                  |
+| `backlogRowRemoved`  | Whether a `backlog.md` row was dropped, a field archive lacks            |
+| `indexRegenerated`   | Whether the index was rewritten                                          |
+| `plans`              | A `from` and `to` per live plan the task last cited, empty if none moved |
+
+`backlogRowRemoved` is decline's own, since a task can be declined straight off `backlog.md` and archive never checks that file.
 
 ## Step 3: route on a refusal
 
-- `no-match`: the stem does not name exactly one task. Either none matches, or exactly one starts with it and the full name is needed. Check the name against the listed stems.
-- `ambiguous`: the stem is a prefix more than one task starts with, unlike archive's own `ambiguous`, which fires on a shared pull request. Decline takes no pull-request selector, so this is the only route to it. Pass the full stem.
-- `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.
+Each refusal names its cause and the fix.
+
+| `reason`    | Cause                                                                | Fix                                        |
+| ----------- | -------------------------------------------------------------------- | ------------------------------------------ |
+| `no-match`  | No task matches, or one starts with the stem and needs its full name | Check against the listed stems             |
+| `ambiguous` | The stem is a prefix of more than one task                           | Pass the full stem                         |
+| `bad-input` | The command line was wrong rather than the board                     | Read the message, fix the arguments, rerun |
+
+Archive's own `ambiguous` fires on a shared pull request instead, and decline takes no pull-request selector. A `bad-input` leaves nothing on the board to repair, which separates it from the other two.
 
-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 declined 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.
 
 ## Step 4: clear prose naming the task
 
-The command drops the task's row from `.canon/tasks/priority.md` or `.canon/tasks/backlog.md` and leaves prose alone. Remove any sentence that still names the declined 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` or `.canon/tasks/backlog.md` and leaves prose alone. Remove any sentence that still names the declined task or counts the changed rows, since a stale count reads as board state.

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

@@ -27,12 +27,19 @@ A declined task works when a later reader can tell, from the folder and the file
 
 ## Declining
 
-A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. The two folders answer different questions: archive means the work shipped, declined means somebody decided against doing it. Neither reading fits a task that is merely unscheduled, which stays on `backlog.md` rather than moving anywhere, since nobody has decided against it and it may still rise when the board has room.
+A task decided against moves to `.canon/tasks/declined/` rather than `.canon/tasks/archive/`. Archive means the work shipped, and declined means somebody decided against doing it.
 
-`canon tasks decline` carries no outcome-state gate, so a task can be decided against at any outcome state, open outcomes included.
+- A merely unscheduled task fits neither. It stays on `backlog.md`, since nobody decided against it and it may still rise.
+- `canon tasks decline` carries no outcome-state gate, so a task can be declined at any outcome state, open outcomes included
+- The move clears whichever of `priority.md` or `backlog.md` holds the task's row
 
-The decision is recorded on the task itself with a `Declined:` line, in the `Plan:`/`Pull request:` family: `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors the same way `Pull request:` does, after the last origin line the task carries. The line is free prose after the colon, since it names no file to link.
+### The `Declined:` line
 
-Declining a task moves its plan alongside it the same way archiving does, when the declining task is that plan's last live citation. A plan several tasks share stays where it is, and a declined task's plan lands in `.canon/plans/archive/` indistinguishable from a shipped one by folder alone. The task file under `.canon/tasks/declined/` is what records which it was.
+The decision is recorded on the task with a `Declined:` line in the `Plan:` and `Pull request:` family, as `Declined: <reason>, <who> on <YYYY-MM-DD>`. It anchors after the last origin line the task carries, as `Pull request:` does, and stays free prose since it names no file to link.
 
-The move clears whichever of `priority.md` or `backlog.md` holds the task's row.
+### The plan
+
+Declining moves the plan alongside the task when the task is that plan's last live citation, as archiving does. A plan several tasks share stays where it is.
+
+- A declined task's plan lands in `.canon/plans/archive/`, indistinguishable from a shipped one by folder alone
+- The task file under `.canon/tasks/declined/` records which it was