@erclx/canon 5.37.0 → 5.39.0

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

@@ -12,7 +12,14 @@ metadata:
 - If no feature description is provided, stop: `❌ No feature description. Describe what you want to add.`
 - Do not implement anything. Output the plan and stop.
 - When the feature description spans two or more independent concerns, write one plan file per concern. Do not bundle them under a single slug.
-- Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each from the ask and the project context. An answer you can predict settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question. Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable. When you can predict none of the three, so no checkable success criterion can be stated, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session. The test reads the ask's success criteria, never the plan's open questions, which a `- Suggested:` line answers.
+
+### Predict the next three questions
+
+Before Step 3, name the next three questions you would ask about what the ask must achieve, and predict the operator's answer to each. The test reads the ask's success criteria, never the plan's open questions.
+
+- A predictable answer settles its criterion, which Step 3 writes as a `**Verification:**` bullet rather than a question
+- Only a prediction still open goes under `**Questions:**` with a `- Suggested:` line, so a fully specified ask carries none and Small mode stays reachable
+- When you can predict none of the three, ask before Step 3 through whatever route reaches the operator, including a message to a dispatching session
 
 ## Step 1: read the Claude setup
 
@@ -22,26 +29,29 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: feature scope and non-goals
 - `.canon/tasks/index.md`: current scope and status, then any task file the feature relates to
 
-Also read these when the feature touches code or UI. Skip them for prose, docs, catalog, or config-only changes:
+Also read `canon/DESIGN.md` when the feature touches code or UI, for visual intent and component rules, with values read from the stylesheet its lead names. Skip it for prose, docs, catalog, or config-only changes.
 
-- `canon/DESIGN.md`: visual intent and component rules, with values read from the stylesheet its lead names
-
-Coding standards live in `.claude/rules/`. Claude Code loads them automatically. Path-scoped rules apply to the files they match.
+Coding standards live in `.claude/rules/`. Claude Code loads them automatically, and path-scoped rules apply to the files they match.
 
 ## Step 2: scan relevant source files
 
-Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+Read the source files directly relevant to the feature, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+Measure against the tree rather than recall, since a count carried from an earlier session or a summary is the most common way a plan ships the wrong scope.
 
-Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. The tree tells a new path what exists beside it, not where it belongs, so a flat folder is a reading to place against rather than a pattern to copy. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
+- Open each file before describing what is in it
+- Grep for each construct the plan will name and count the sites
+- Confirm any work the plan sequences behind is still open
+- Read a flat folder as a reading to place against rather than a pattern to copy, since the tree shows what exists beside a new path, not where it belongs
 
-Open each file before describing what is in it. A count or a claim carried from an earlier session, a summary, or another document is the most common way a plan ships the wrong scope.
+### Outside sources
 
-When a decision the plan will make rests on an outside practice or a third-party behavior, invoke `canon:search-craft` before searching, fetch each source, and record the passage relied on. Skip this for a plan that rests on nothing outside the project.
+When a decision rests on an outside practice or a third-party behavior, invoke `canon:search-craft` before searching, fetch each source, and record the passage relied on. Skip this for a plan that rests on nothing outside the project.
 
-- Ask the fetch for the verbatim passage, and confirm the wording through `curl` where a decision turns on exact wording, since `WebFetch` returns a model's answer rather than the page.
-- Route a Claude Code subject to the `claude-code-guide` agent.
-- Mark a source that could not be fetched as unverified rather than citing recall.
-- Report it rather than proceeding silently when `canon:search-craft` does not resolve.
+- Confirm exact wording through `curl` where a decision turns on it, since `WebFetch` returns a model's answer rather than the page
+- Route a Claude Code subject to the `claude-code-guide` agent
+- Mark a source that could not be fetched as unverified rather than citing recall
+- Report it rather than proceeding silently when `canon:search-craft` does not resolve
 
 ## Step 3: build the plan
 
@@ -49,37 +59,30 @@ The section list, what each section holds, and the suggested-and-answer contract
 
 What this skill adds on top of the standard:
 
-- Reframe a vague ask as success criteria before writing `**Files to touch:**`. Each criterion names something observable and a check that decides it, such as a measure and the threshold it must stay under, drawn from the ask or the project context. "Make it faster" names no criterion, while a stated budget for one path does. Each criterion becomes one `**Verification:**` bullet.
-- Confirm a concrete project or use case drives the feature before shaping it, and lift patterns from that project where precedent exists. A feature with no named user is a guess about what one will want.
+- Reframe a vague ask as success criteria before `**Files to touch:**`, each an observable result and its check, which becomes one `**Verification:**` bullet. "Make it faster" names none.
+- Confirm a concrete project or use case drives the feature, and lift patterns from it where precedent exists. A feature with no named user is a guess.
 - Prefer one layout that serves both a new and a grown project over a dual-mode toggle or a migration shim. Two modes double what every later change has to hold.
 
 ### Suggestions and sections
 
-- Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
-- Suggest a real default when best practice, the codebase, or prior context points to one.
-- Load the `canon:codebase-layout` skill before writing the `**Files to touch:**` entries when any of them names a file or folder that does not exist yet, and give each new path its placement reason in its entry. Skip the load when every entry edits an existing file. Report it rather than proceeding silently when the skill does not resolve.
-- Write `**Verification:**` as one bullet per outcome naming the test or command that proves it, and `**Review focus:**` as the inputs or states that would break the change. You understood the risk before any diff existed, and these two sections carry it to the executing session and to the reviewer.
+Every `- Suggested:` line takes senior judgment, picking the best option in one line with its reason or main tradeoff, and naming alternatives only when they change the pick.
+
+- Suggest a real default when best practice, the codebase, or prior context points to one
+- Load `canon:codebase-layout` before `**Files to touch:**` when an entry names a path that does not exist yet, and give each new path its placement reason. Report it if it does not resolve.
+- Write `**Verification:**` as one bullet per outcome naming the test or command that proves it
+- Write `**Review focus:**` as the inputs or states that would break the change, carrying the risk you understood to the executor and the reviewer
 
 ### Sources and size
 
-- Cite the `**Sources:**` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`.
-- Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
+A small feature produces a short plan, not a padded one.
+
+- Cite the `**Sources:**` entry for every decision Step 2 sourced, each with its quoted passage or the word `unverified`
+- Prefer `None identified.` over low-signal fillers
 - When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 
 ## Pull request boundaries
 
-A plan sequencing its work into batches declares where one pull request ends, here rather than at ship time. A dependency chain cannot be split once it is built, so the choice exists only while the batches are still a plan.
-
-- One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename, so a `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that one branch across every batch, and the batch that merges first strands every batch behind it with nothing left to open a pull request against. Write a plan opening five batches as five files before the first line of any of them.
-- State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it. A batch that builds after another and shares most of its files with it folds into that batch as contiguous commits on one branch, since each pull request pays a fixed cost a same-file slice cannot earn back, and the rebases between stacked slices land on the same files. Keep a batch apart only where a reviewer or the operator would judge it apart: a contract a later batch is built against, a taste call the operator judges in its own sitting, or a fold that would exceed one review. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `**Constraints:**`. `canon records validate plans` reports a stacked batch that should have folded, and its thresholds live there.
-- Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request. One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
-
-### Slicing and sequence
-
-- Slice a batch by one user-visible path end to end rather than by layer, so each batch ships something a person can exercise. The slice decides what a batch contains, and the file-set comparison above still decides whether two batches depend on each other, so two slices sharing a file stay marked dependent. A path too thin to pay a pull request of its own folds forward into the next.
-- Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move. A sweep is the one exception and stays last even when it is the riskiest, per the next bullet.
-- Sequence a sweep last. A batch deliberately rewriting files earlier batches touched is coherent as the final one and forces every batch behind it into one review anywhere else.
-- Keep each batch's commits contiguous once the work starts. A later fix to an earlier batch belongs on that batch's own commits, since a batch interrupted by another cannot be lifted onto its own branch afterward.
+A plan sequencing its work into batches declares where each pull request ends, since a dependency chain cannot be split once it is built. Read `${CLAUDE_SKILL_DIR}/references/batches.md` when the plan carries more than one batch, for the one-file-per-batch rule, when a dependent batch folds, and the build order. A single-batch plan skips it.
 
 ## Step 4: output
 
@@ -88,11 +91,11 @@ Decide the mode based on what Step 3 produced:
 - **Small** when the plan touches 2 files or fewer, has no architectural or cross-cutting choices, and both Risks and Questions come out `None identified.`
 - **Full** otherwise
 
-A consumer list is a `Risks` entry, which already forces Full. Establishing a resource with more than one consumer, where at least one writes, is a cross-cutting choice wherever that list ends up living, so such a plan stays Full even at two files.
+A consumer list is a `Risks` entry, which already forces Full. A resource with more than one consumer, at least one writing, is a cross-cutting choice, so such a plan stays Full even at two files.
 
 ### Small mode
 
-Output the plan to chat. Do not write a plan file. The markers match the standard's, so a plan that later grows into a file keeps the shape it was drafted in.
+Output the plan to chat and write no plan file. The markers match the standard's, so a plan that later grows into a file keeps its shape.
 
 ```markdown
 **Files to touch:**
@@ -104,7 +107,7 @@ Output the plan to chat. Do not write a plan file. The markers match the standar
 - <outcome>: `<test or command that proves it>`
 ```
 
-Small mode carries no `**Review focus:**`, since it already requires Risks to come out `None identified.` and a change with no risk leaves the reviewer no breaking input to name.
+Small mode carries no `**Review focus:**`, since its Risks already came out `None identified.` and the reviewer has no breaking input to name.
 
 If real questions exist, include a numbered `**Questions:**` section below, each with a `- Suggested:` line and an `- Answer:` slot:
 
@@ -120,17 +123,20 @@ Omit empty sections. Do not print `None identified.` in chat.
 
 ### Full mode
 
-Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.canon/plans/feature-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `session-worktree` does. Create the directory if it does not exist.
+Derive a 2-to-4-word kebab-case slug from the feature description. Write the plan to `.canon/plans/feature-<slug>.md` at the main worktree root, resolved the way `session-worktree` does, creating the directory if needed.
+
+The plan is a main-root write, from a linked worktree and from a background session at the main root alike, so it goes out as a heredoc routed the way `session-worktree` states. Copy the shape from the template in `${CLAUDE_SKILL_DIR}/references/plan.md` rather than from this body, so one edit to the standard moves every plan.
 
-The plan is a main-root write, from a linked worktree and from a background session sitting at the main root with none entered alike, so it goes out as a heredoc, routed the way `session-worktree` states.
+### Checking the written plan
 
-The file follows the template in `${CLAUDE_SKILL_DIR}/references/plan.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every plan.
+Two commands check the file once it lands, and both write nothing.
 
-Run `canon records validate plans` after writing the file when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold, and it writes nothing.
+- Run `canon records validate plans` when the CLI is on PATH. It reports a section, a filename, or an answer slot that does not hold.
+- Run `canon markdown audit .canon/plans/feature-<slug>.md`, naming the file, since the gitignored plan reaches no other gate. Rewrite a hit's sentence rather than swapping the token.
 
-Run `canon markdown audit .canon/plans/feature-<slug>.md` beside it, naming the file. `.canon/plans/` is gitignored and the audit's default path set is what git lists, so no other gate ever opens a plan, and six ban hits landed across four plans written without this call. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
+When Step 1 resolved an existing task, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip it when Step 1 found no task, and report a refusal rather than stopping, since `canon tasks validate` still catches an unlinked task through `plan-uncited`.
 
-When Step 1 resolved an existing task for this feature, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip the call when Step 1 found no task, since there is nothing to link yet. Report a refusal rather than stopping on it. The plan file is already written, and `canon tasks validate` still catches an unlinked task through `plan-uncited` if this call cannot run.
+### Chat output
 
 Then output in chat:
 
@@ -145,7 +151,7 @@ Then output in chat:
 Next: /session-worktree
 ```
 
-Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored. Do not stage or commit the file.
+Show only the path line and the `Next:` line when there are no questions. The `.canon/plans/` directory is gitignored, so do not stage or commit the file.
 
 Do not proceed to implementation until the user explicitly says to continue.
 
@@ -153,6 +159,6 @@ Do not proceed to implementation until the user explicitly says to continue.
 
 After the plan is written, the user may re-ping with follow-up questions or pushback. Keep chat output to a decision-help shape.
 
-- State each pick as one-line pick plus one-line reason. Do not use section headers, context blocks, or multi-section breakdowns in chat. Those belong in the plan file.
-- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings.
-- When a finding needs more than two lines to explain, update `.canon/plans/feature-<slug>.md` in place with the detail and point the user at the file instead.
+- State each pick as one-line pick plus one-line reason. Section headers, context blocks, and multi-section breakdowns belong in the plan file.
+- Put numbered decisions to resolve at the bottom of the response, not interleaved with findings
+- When a finding needs more than two lines, update `.canon/plans/feature-<slug>.md` in place and point the user at the file

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

@@ -0,0 +1,46 @@
+---
+title: Pull request boundaries reference
+description: How a plan sequencing its work into batches declares where each pull request ends, how dependent batches stack or fold, and the order batches build in
+---
+
+# Pull request boundaries reference
+
+Applies to a feature plan that sequences its work into more than one batch. A dependency chain cannot be split once it is built, so the boundary is declared while the batches are still a plan rather than at ship time.
+
+## One batch, one file
+
+One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename.
+
+- A `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that branch across every batch, so the first merge strands the rest
+- Write a plan opening five batches as five files before the first line of any of them
+
+## Dependent batches
+
+State a dependent batch's dependency on the ones before it in its own `**Constraints:**`, naming the earlier batch's slug and stacking rather than merging into it.
+
+A batch that builds after another and shares most of its files folds into that batch as contiguous commits on one branch. Each pull request pays a fixed cost a same-file slice cannot earn back, and the rebases between stacked slices land on the same files.
+
+### Judged apart
+
+Keep a batch apart only where a reviewer or the operator would judge it apart. Write that reason as ``Judged apart from `feature-<parent>`: <reason>`` in the batch's `**Constraints:**`.
+
+- A contract a later batch is built against
+- A taste call the operator judges in its own sitting
+- A fold that would exceed one review
+
+`canon records validate plans` reports a stacked batch that should have folded, and its thresholds live there.
+
+### Marking dependence
+
+Mark each batch dependent or independent by comparing the file sets rather than the descriptions. A batch sharing no file with another is independent and earns its own branch even where both arrived in one request.
+
+One run measured at 68 files carried three such batches into a single review because nothing drew the boundary.
+
+## Slicing and sequence
+
+Slice a batch by one user-visible path end to end rather than by layer, so each batch ships something a person can exercise. The file-set comparison still decides dependence, so two slices sharing a file stay marked dependent.
+
+- Fold a path too thin to pay a pull request of its own forward into the next
+- Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move
+- Sequence a sweep last, even when it is the riskiest. A batch rewriting files earlier batches touched forces every batch behind it into one review anywhere else.
+- Keep each batch's commits contiguous once the work starts, since a batch interrupted by another cannot be lifted onto its own branch afterward

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

@@ -14,56 +14,81 @@ Read `${CLAUDE_SKILL_DIR}/references/groundwork.md` before writing any file in t
 ## Guards
 
 - If no topic is given, stop: `❌ No topic. Name what needs measuring.`
-- Apply the qualifying test in open mode alone, after Step 1 resolves the mode and before the folder is created. Two of these three must hold: the current state is not known, more than one approach is live, and committing wrong costs more than a day of measuring. When one or fewer holds, stop: `❌ Already decided enough to plan. Run /plan-feature instead.`
-- Resume and close are exempt from the test above. A track that has already been measured fails it by definition, since its current state is now known and its approaches have narrowed, so applying the test to either mode refuses the folder that same test admitted.
-- A refused topic that is a broad dump rather than one question routes to `plan-intake`, not to the planning skill the stop names. Intake dispositions many findings in breadth from what the repository already holds, and one folder holding dozens of unrelated threads is what forcing them past this guard produces.
 - Do not pause for approval between steps. The write scope below is what makes that safe.
 
+### The qualifying test
+
+Apply it in open mode alone, after Step 1 resolves the mode and before the folder is created. Two of three must hold, being an unknown current state, more than one live approach, and a wrong commitment costing more than a day of measuring.
+
+- When one or fewer holds, stop: `❌ Already decided enough to plan. Run /plan-feature instead.`
+- Resume and close are exempt, since a measured track fails the test by definition and applying it would refuse the folder it admitted
+- A refused topic that is a broad dump rather than one question routes to `plan-intake`, which dispositions many findings in breadth, not to the planning skill the stop names
+
 ## Write scope
 
-- Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside that folder, so this one rule forbids every one of them.
-- One exception, at close only: write one task file recording what the track concluded.
-- A second exception, for what a spike reads as bulk input: write a large fixture under `.canon/tmp/runs/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`. An arm script and a checkout a claim rests on are not fixtures, and go inside the track under `scripts/` and `clones/`, per the standard.
+Write only inside `.canon/groundwork/<nn>-<slug>/`. A feature plan, source changes, a standard, a rule, and a reference doc all live outside it, so this one rule forbids every one of them.
+
+- One exception, at close only, is one task file recording what the track concluded
+- A second exception is a large fixture a spike reads as bulk input, under `.canon/tmp/runs/groundwork-fixtures/<slug>/` so mode detection never matches it as a track
+- A fixture a headless run is pointed at goes outside the repository instead, per `## Running a spike`
+- An arm script and a checkout a claim rests on are not fixtures, and go inside the track under `scripts/` and `clones/`, per the standard
 
 ### Evidence and drafts
 
-- What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
-- A `draft-and-pick` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as canvas pages under `.canon/canvas/` that its close deletes.
+What a spike produces stays inside the track, under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches only top-level entries, so a nested folder cannot be mistaken for a track, and scratch holds only what can be deleted without loss.
+
+A `draft-and-pick` run invoked from inside a live track follows its own branch for this. It writes its renders to `evidence/` here, and drafts its candidates as canvas pages under `.canon/canvas/` that its close deletes.
 
 ### Reading and backing
 
-- Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them. Invoke `canon:search-craft` with the skill tool before an outside search, and report it rather than proceeding silently when the skill does not resolve.
+Reading is not restricted, so read documentation, comparable projects, and papers whenever a live question needs them. Invoke `canon:search-craft` with the skill tool before an outside search, and report it rather than proceeding silently when the skill does not resolve.
+
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
-- Treat the folder as gitignored, and backed only where a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there and refuse with `no-remote` otherwise, and neither protects against a compaction dropping this session's own reasoning before anyone has pushed, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.
+- Treat the folder as gitignored. `canon records push` and `canon records pull` back it up where a records remote is configured, and refuse with `no-remote` otherwise.
+- Neither protects against a compaction dropping unpushed reasoning, so `07-next-session.md` repeats what it needs instead of pointing at its siblings
 
 ## Running a spike
 
 A track may run an experiment to settle an open question without stopping to ask. What it takes depends on what the experiment does.
 
-- Reading or computing: run it. Unrestricted reading already covers this, and it is what most spikes turn out to be.
-- Anything that processes an input: start against a sample and scale up after it works, per the sample rule in `${CLAUDE_SKILL_DIR}/references/groundwork-spikes.md`, which bounds it on size, duration, and spend.
-- Writing a fixture this session reads or provisions itself: run it, under the fixtures path above. Provisioning is the usual blocker rather than spend, and it costs nothing.
-- Spawning a billed headless session: run up to three, then ask before spawning more. The bound is a run count rather than a budget, because a headless run reports its total cost only after it finishes, so a dollar ceiling is reportable and not enforceable while a run count is checkable before spawning.
+| Experiment                                | What it takes                                                          |
+| ----------------------------------------- | ---------------------------------------------------------------------- |
+| Reading or computing                      | Run it, since unrestricted reading covers it                           |
+| Processing an input                       | Start on a sample and scale up after it works, per the sample rule     |
+| Writing a fixture this session provisions | Run it under the fixtures path above, since provisioning costs nothing |
+| Spawning a billed headless session        | Run up to three, then ask before spawning more                         |
+
+The sample rule in `${CLAUDE_SKILL_DIR}/references/groundwork-spikes.md` bounds an input run on size, duration, and spend. The headless bound is a run count because a run reports its cost only after it finishes, so a count is checkable before spawning and a dollar ceiling is not.
+
+### Headless fixtures
 
-A fixture a headless run is pointed at goes outside the repository, under `mktemp -d`, and never under `.canon/tmp/`. A session started anywhere beneath the project root loads that project's `CLAUDE.md` and `.claude/rules/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm. Record the fixture as contaminated and re-run it outside if this is discovered after the fact, because the result reads as evidence either way.
+A fixture a headless run is pointed at goes under `mktemp -d`, never under `.canon/tmp/`. A session started beneath the project root loads its `CLAUDE.md` and `.claude/rules/` through the ancestor chain, so an in-repo fixture measures the repository instead of the arm.
 
-Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the run produced that the record cites in `evidence/` beside it, so a reader checking a claim opens the artifact rather than taking the prose for it, and keep the arm scripts in `scripts/`. Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
+Record a fixture found in-repo after the fact as contaminated and re-run it outside.
+
+### Recording a spike
+
+Record method, result, measured cost, and caveats in `08-spikes.md`. Put whatever the record cites in `evidence/` beside it, so a reader opens the artifact rather than taking the prose for it, and keep the arm scripts in `scripts/`.
+
+Reach for a test harness the project already carries before building one, and copy how it isolates its fixture rather than only what it asserts.
 
 ## Step 1: detect the mode
 
-List `.canon/groundwork/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder already there before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug derived from the wording would miss a live track and restart it.
+List `.canon/groundwork/` from the project root and match the topic against the slug half of each `<nn>-<slug>` folder before deriving anything. A resume pass rarely phrases the topic the way the folder was named, so a fresh slug would miss a live track and restart it.
 
 Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never a track.
 
-With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `ts-migration` over `migration-research`. That is open mode outright: no folder can carry a slug nothing matched yet, so there is nothing to route on. `<nn>` for it is claimed in Open mode Step 1 rather than here, since the qualifying test below has to run before the folder exists.
+### No match
+
+Derive a kebab-case slug named for the subject rather than the activity, preferring `ts-migration` over `migration-research`. That is open mode outright, since no folder can carry a slug nothing matched. Open mode Step 1 claims `<nn>`, after the qualifying test runs.
 
-A matched folder instead routes on its own `<nn>-<slug>/`:
+### A matched folder
+
+A matched folder routes on its own `<nn>-<slug>/`. Detect the mode from the folder rather than asking which one to run.
 
 - Present without `06-decision.md`: resume
 - Present and the user judges it ready: close
 
-Detect the mode from the folder. Do not ask which one to run.
-
 ## Step 2: orient
 
 Read these in parallel from the project root, skipping any that do not exist:
@@ -72,22 +97,23 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `canon/REQUIREMENTS.md`: scope and non-goals
 - `.canon/tasks/index.md`: what is already tracked, and what a prior track concluded. Open a task file only when its entry looks related.
 
-Then read only what a live question needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+Then read only what a live question needs, never whole directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
 Do not dispatch subagents. A groundwork track is a conversation, and fanning out loses the reasoning that makes the folder worth keeping. A search too large to run inline is a finding that the question is too broad.
 
 ## Open questions in chat
 
-The standard sets the open question format and requires it inside a topic file and in `00-scope.md`. Carry the same shape into the chat output, which sits outside the folder the standard governs. A bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
+The standard sets the open question format inside a topic file and in `00-scope.md`. Carry the same shape into the chat output, since a bare numbered list hands the reader a quiz and defers the judgment the track exists to inform.
 
 ## Open mode
 
-1. Claim the ordinal and create the folder in one act with `canon records ordinal groundwork <slug> --claim`, per `${CLAUDE_SKILL_DIR}/references/groundwork.md`. Where the installed binary carries no such subcommand, fall back to listing both `.canon/groundwork/` and `.canon/intake/` and creating `.canon/groundwork/<nn>-<slug>/` at the highest ordinal present across the two, incremented.
-2. Write `README.md` first. Writing it first forces the question of what the track is for.
-3. Write `01-current-state.md` by measuring now. Never carry a figure from a previous session or from recall without re-measuring it. Measure only what an open question in the folder needs. A number with no question attached is how groundwork turns into the work.
-4. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
-5. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the standard's format.
-6. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
+1. Claim the ordinal and create the folder in one act with `canon records ordinal groundwork <slug> --claim`, per `${CLAUDE_SKILL_DIR}/references/groundwork.md`.
+2. Where the binary carries no such subcommand, list `.canon/groundwork/` and `.canon/intake/` and take the highest ordinal across both, incremented.
+3. Write `README.md` first. Writing it first forces the question of what the track is for.
+4. Write `01-current-state.md` by measuring now, never carrying a figure from recall. Measure only what an open question needs, since a number with no question turns groundwork into the work.
+5. Write `00-scope.md` when the track is large enough to run away. Skip it on a small track.
+6. Add topic files at `02` through `05` as the subject demands. Close each one with its open questions in the standard's format.
+7. Keep going. Revise, reframe, and take correction as the questions move. The folder is meant to be rewritten.
 
 ## Resume mode
 
@@ -98,55 +124,15 @@ The standard sets the open question format and requires it inside a topic file a
 
 ## Close mode
 
-1. Write `06-decision.md`. It states the problem once, names the goal, lists what to do, and lists what was considered and dropped. Carry the "Overturned by" line of each lean that became the decision into a `## Revisit when` section, and carry none from a lean the decision did not take.
+1. Write `06-decision.md`, stating the problem once, the goal, what to do, and what was dropped. Carry each adopted lean's "Overturned by" line into `## Revisit when`.
 2. Write `07-next-session.md` self-contained, so it survives a compaction that loses the conversation.
 3. Update the file map in `README.md`.
-4. Write one task file in `.canon/tasks/` recording what the track concluded, even when the conclusion is to do nothing. Follow `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` for the filename and frontmatter. Place the row through `task-board` Step 4, which checks the roster for a live orchestrator before writing `priority.md` or `backlog.md` directly. Aside from an experiment fixture, this and the routing in Step 5 are the only ways close mode reaches outside the folder.
+4. Write one task file in `.canon/tasks/` recording the conclusion, even when it is to do nothing, per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`. Place its row through `task-board` Step 4.
 5. When the task written in Step 4 does not cover every finding the track surfaced, route what it leaves out through `plan-intake`. Skip this step when it does.
-6. Report uncited external claims. Closing already reads every file in the folder, so list any statement about a source outside the project that carries neither a link nor a lead entry. Report and do not block, because judging whether a sentence makes an external claim is the call a checker gets wrong.
+6. Report each statement about an outside source carrying neither a link nor a lead entry. Report and do not block, because judging what counts as an external claim is the call a checker gets wrong.
 
-Do not close while an open question quietly fails an outcome. Resolve it, or record it in `06-decision.md` as knowingly accepted.
+Aside from an experiment fixture, Steps 4 and 5 are the only ways close mode reaches outside the folder. Do not close while an open question quietly fails an outcome. Resolve it, or record it in `06-decision.md` as knowingly accepted.
 
 ## Output
 
-Emit the full relative path from the project root for every file written or updated. A bare filename names a file the reader cannot open.
-
-Open and resume:
-
-```plaintext
-📂 Opened .canon/groundwork/<nn>-<slug>/
-
-**Written:**
-
-- `.canon/groundwork/<nn>-<slug>/README.md`
-- `.canon/groundwork/<nn>-<slug>/01-current-state.md`
-
-**Open questions:**
-
-1. <question>
-   - Leaning: <where the evidence currently points>
-   - Overturned by: <the finding that would change it>
-```
-
-Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
-
-Close:
-
-```plaintext
-✅ Closed .canon/groundwork/<nn>-<slug>/
-
-**Written:**
-
-- `.canon/groundwork/<nn>-<slug>/06-decision.md`
-- `.canon/groundwork/<nn>-<slug>/07-next-session.md`
-
-**Uncited external claims:** <count, or none>
-
-- `<file>`: <the claim>
-
-<the decision in one line>
-
-Next: /plan-feature
-```
-
-Omit the uncited-claims block when the count is zero.
+Emit the full relative path from the project root for every file written or updated, since a bare filename names a file the reader cannot open. Read `${CLAUDE_SKILL_DIR}/references/output.md` on reaching this step for the open and resume template and the close template. A run that stops on a guard skips it.

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

@@ -33,8 +33,8 @@ Governs a groundwork track under `.canon/groundwork/<nn>-<slug>/`: folder layout
 Does not govern:
 
 - **`groundwork-spikes.md`**: `08-spikes.md`, what each spike records, and the folders holding what a spike produced
-- **`intake.md`**: A dump of many findings filed by domain, each carrying its own verdict
-- **`plan.md`**: the feature plan a closed track feeds, and the contract its answer slots keep
+- **`intake.md`**: A dump of many findings filed by domain, each with a verdict
+- **`plan.md`**: the feature plan a closed track feeds, and its answer contract
 - **`tasks.md`**: the task file a closing track writes, and the origin line pointing back at the folder
 - **the `write-human` skill**: voice, rhythm, and sentence construction
 - **`markdown.md`**: headings, punctuation, word choice, and file references
@@ -42,9 +42,9 @@ Does not govern:
 
 ## Folder name
 
-- Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
-- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
-- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one creation-order line.
+- Name the folder `<nn>-<slug>`, a two-digit ordinal and a kebab-case slug.
+- The ordinal marks a folder per track, opened once and worked over time, unlike a file addressed by name, one with its own sorting prefix, or one overwritten on purpose.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one order.
 - With neither folder holding an entry, the first one opened takes `01`, whatever number a track's own files start at.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
@@ -53,17 +53,17 @@ Does not govern:
 A track works when a session that has never seen it re-enters from the folder alone and can answer each of these:
 
 - Which single question is being measured, and why is it running now?
-- What is the current state, measured during this pass rather than carried in from an earlier one?
-- Which questions are still open, where does the evidence point, and what would overturn that?
+- What is the current state, measured this pass rather than carried in?
+- Which questions are open, where is the evidence, and what overturns it?
 - What was decided, and what was considered and dropped?
 
-A track failing these is non-conforming even when it satisfies every shape rule below.
+A track failing these is non-conforming even when it meets every shape rule.
 
 ## Frontmatter and dating
 
 - `title` (required): the track subject in sentence case
 - `description` (required): one line naming what the track measures
-- `date` (required, `README.md` only): the day the folder opened, as `YYYY-MM-DD`
+- `date` (required, `README.md` only): the day it opened, as `YYYY-MM-DD`
 
 Carry the opening date as a frontmatter field rather than a sentence in the body, since nothing that walks the folder reads prose. Date the folder once rather than every file, because a per-file date goes stale on the first edit. The checkable half is the commit each measurement was taken against, which the file holding that measurement names.
 
@@ -90,13 +90,13 @@ Orients. Holds no findings.
 
 - A one-line definition of the investigation
 - A `## Why` section stating why the track is running now
-- A file-map table of filename and what it holds, kept current as files are added or retired
+- A file-map table of filename and what it holds, kept current
 - A `## Method` section splitting internal sources from external ones, naming which were used and which were not yet done, and listing under a leads heading any external source found but not opened
 
 ### Closing sections and phase
 
 - A `## Prior art` section
-- A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
+- A `## Source citation` section stating the rule below, so a returning session finds it in the folder
 - The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
 
 Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. Without one, a later reader cannot tell a fetched page from recall. A source found and not read is listed as a lead and is never cited, since a link to a page nobody opened is worse than no link. Listing it stops a later pass re-searching for it.
@@ -109,23 +109,19 @@ Facts before opinion. Verified measurement only, taken during this pass.
 
 - Never carry a figure from a previous session without re-measuring, since every number built on a stale one is quietly wrong.
 - Mark an inference as an inference where one is unavoidable.
-- Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
+- Measure only what an open question needs. A number with no question attached is how the groundwork becomes the work.
 
 ## 00-scope.md
 
-Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it.
+Written when the subject is large enough to run away. Holds constraints, risks, the open questions, and what a decision would touch. A small track skips it.
 
 ## 06-decision.md
 
-Closes the folder. Everything above it is input.
+Closes the folder. Everything above it is input. Write it from the skeleton under `## Template`, with an H3 per dropped alternative.
 
-- The problem stated once
-- The goal
-- The items to do
-- What was considered and dropped
-- `## Revisit when`: the "Overturned by" line of each lean that became the decision, carried over as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
+`## Revisit when` carries the "Overturned by" line of each lean that became the decision, as written. A lean the decision did not take carries nothing, and a track whose deciding leans carried no overturn line omits the section.
 
-The dropped list is what stops a future session re-proposing something already rejected.
+The dropped list stops a future session re-proposing a rejected idea.
 
 ## 07-next-session.md
 
@@ -141,8 +137,8 @@ Every open question carries a lean, wherever it appears. A bare numbered list ha
    - Overturned by: <the finding that would change it>
 ```
 
-- Pair every lean with what would overturn it. A lean with no falsifier is an opinion.
-- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
+- Pair every lean with what would overturn it. A lean with no falsifier is opinion.
+- On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse.
 - Mark each question open or answered, and repeat the open ones at the end of the file they belong to. That gives the decision file its agenda for free.
 
 A lean is weaker than a plan's suggestion: it records the current read on an open question, not a decision to accept at execution time.
@@ -155,13 +151,15 @@ A lean is weaker than a plan's suggestion: it records the current read on an ope
 
 ## Anti-patterns
 
-- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
+- **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question.
 - **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
 - **Recording a constraint discovered while defending a decision.** Check it against the alternative design first, or a fact about the current shape reads as inherent to the problem.
 - **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.
 
 ## Template
 
+### README.md
+
 ```markdown
 ---
 title: <Track subject>
@@ -195,10 +193,41 @@ Groundwork phase. Nothing here is a feature plan.
 
 ## Prior art
 
-<Earlier plans, folders, or decisions this track supersedes or builds on.>
+### <earlier plan or folder>
+
+<What it decided and how this track supersedes or builds on it. Say not to go looking for it again.>
 
 ## Source citation
 
 Every claim about a source outside the project carries a link. A source found
 and not read is listed as a lead and is never cited.
 ```
+
+### 06-decision.md
+
+```markdown
+---
+title: <Track subject> decision
+description: <one line naming what the track decided>
+---
+
+# <Track subject> decision
+
+## Problem and goal
+
+<The problem stated once, then what done looks like.>
+
+## What to do
+
+1. <item>
+
+## Considered and dropped
+
+### <alternative>
+
+<Why it was dropped, and what would revive it.>
+
+## Revisit when
+
+- <an "Overturned by" line, as written>
+```