@erclx/canon 5.45.0 → 5.47.0

package/claude/skills/git-pr/references/pr.md

@@ -52,15 +52,30 @@ A body describes the new behavior and nothing the diff or the commits already sa
 
 ## Sections
 
-- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
-- `## Key changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Summary`: one paragraph following `<Action Verb> <Direct Object> to <Result>`, then the closing lines
+- `## Key changes`: bullets only, one change each, naming actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler")
+- Name every changed path in a Key changes bullet. A trim may cut a clause and never a path, since `canon pr key-changes` reports a path no bullet claims.
+
+### Key changes groups
+
+Past 5 bullets, group Key changes under bold labels, 5 bullets a group at most.
+
+- A label sits on its own line, names the area a reviewer opens together, and ends with no period
+- Write a label in plain words, since a code span inside bold renders unbolded
+- Open each group on a bullet, never on prose
+
+### Closing lines
+
+The closing lines end `## Summary`, one `Closes #NNN` per issue and no trailing period. A task shipped in slices carries them on its last slice only. `closing-issues.md` states how the list is decided, and `canon labels scan --closes` fails a body that disagrees with it.
 
 ### Context section
 
-`## Technical context` is optional and carries 1-2 lines of architectural reasoning explaining why, not what.
+`## Technical context` is optional and says why, naming the decisions the code can't show and any shortcoming of the approach.
 
 - Omit Technical context for docs, config, or trivial changes
-- Use bullet points for multiple reasons, one sentence for a single reason
+- Take one form per section, never bullets and paragraphs mixed
+- Use bullets when every reason fits one sentence under 200 characters
+- Otherwise write one paragraph per decision, opening on a bold lead-in that ends with a period and runs into the paragraph
 
 ### Testing section
 
@@ -68,6 +83,7 @@ A body describes the new behavior and nothing the diff or the commits already sa
 
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- Write one box per command, pointing at a test file rather than listing its cases
 
 ### Reviewer section and visuals
 
@@ -86,6 +102,8 @@ A body describes the new behavior and nothing the diff or the commits already sa
 - A ticked box describes the tree as it stands. A later commit removing or replacing what it names makes the box false.
 - The branch that made that commit corrects the box in the same pass, as with any other stale claim in the body
 
+Leave the `UI pass` line to `canon pr tick`, and carry it on a rewrite.
+
 ### Human-only boxes
 
 Leave a box unchecked only when a human is required, and name which human and why on the same line. The agent runs everything else.
@@ -106,6 +124,17 @@ A live agent session is never the human a box waits on.
 ## Formatting
 
 - End every bullet point with a period
+- Carry no H3 or H4 anywhere in a body. GitHub draws an H3 one step under an H2, so stacked H3s compete with the sections.
+- Group with a bold label or lead-in instead, in the forms the Sections rules above state
+
+### Density
+
+`canon labels scan` reports each section's density under `density`, naming the section, the kind, and the line in the whole body. Its help lists every limit.
+
+- Every section but Testing holds bullets to 200 characters and 5 in a row, and paragraphs to 350 characters and 2 in a row
+- Any section reports a `subheading`, and Technical context reports a `mixed-form`
+- A bold label alone on a line breaks a Key changes run, and a bold lead-in starts a new Technical context run
+- Fix a finding by regrouping or splitting, never by cutting a path
 
 ## Examples
 
@@ -118,19 +147,29 @@ Every section a body may carry, in order.
 
 <Action Verb> <Direct Object> to <Result>.
 
+Closes #<number>
+
 ## Key changes
 
+**<Area a reviewer opens together>**
+
 - <Verb> <specific component/file/function> (<reason if non-obvious>)
 - <Verb> <specific component/file/function>
 
+**<Next area>**
+
+- <Verb> <specific component/file/function>
+
 ## Technical context
 
-- <Architectural reasoning explaining why, not what>
+**<Decision in a few words>.** <Why this approach, what the code can't show, and any shortcoming>
+
+**<Next decision>.** <Why>
 
 ## Testing
 
 - [x] <Command run> <observed result>
-- [x] <Edge case verified> <what was observed>
+- [x] <Test file run> <observed result>
 - [ ] <Human-only check> (<which human, why>)
 
 ## For the reviewer
@@ -149,12 +188,20 @@ Update auth middleware to enforce jwt expiration checks. # imperative + direct o
 
 ## Key changes
 
+**Validation** # bold label on its own line, no period
+
 - Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Add the clock skew window to `src/auth/config.ts`. # one change per bullet
+
+**Session handling** # one label per area a reviewer opens together
+
 - Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
 
 ## Technical context
 
-- Migration to stateless session management for horizontal scalability. # why, not what
+**Stateless sessions.** Expiry lives in the token, so any instance can reject it without a shared store. # bold lead-in + why
+
+**Clock skew.** A 30-second window absorbs drift between instances, so a token can outlive its expiry by that much. # decision + shortcoming
 
 ## Testing
 
@@ -178,9 +225,17 @@ This PR updates the authentication system to be more robust. # "This PR" opener
 
 ## Key changes
 
+### Middleware # H3 inside a body
+
 - Updated auth middleware files # vague, no specific component, no period
 - The old system used to check tokens differently # describes historical behavior
 
+## Technical context
+
+- Tokens are stateless now. # a bullet
+
+The skew window trades precision for no shared store. # mixed with a paragraph in one section
+
 ## Testing
 
 - Tested manually # no specific command or case

package/claude/skills/git-ship/REQUIREMENT.md

@@ -7,39 +7,26 @@ description: What the ship chain is for, the gaps it closes, and why it does not
 
 ## Gap
 
-Without this skill, the post-feature sequence runs from memory. Doc sync gets skipped, so the pull request ships with planning docs describing the previous scope, or it runs after staging has already closed and its output never reaches a commit. Chaining by hand is also where a session narrates between steps, which turns one flow into a conversation and invites a decision at every boundary.
+Without this skill, the post-feature sequence runs from memory. Doc sync gets skipped, or runs after staging has closed so its output never reaches a commit. A session chaining by hand narrates between steps, which turns one flow into a conversation and invites a decision at every boundary.
 
-The sequence also reaches the remote on work nothing re-checked. This skill is the resume point `auto-ship` names at three of its stop points, including the one a failed verify takes, so the fix the user makes by hand after that stop is pushed with no suite run against it. Every branch shipped so far passed that verify on its first attempt, which is why the path has produced no instance rather than being closed.
+The sequence also reaches the remote on work nothing re-checked. This skill is where an `auto-ship` stop resumes, so a fix the user makes by hand after a failed verify is pushed with no suite run against it. A chain that ends on its CI watch line, or never reads the evidence thread, reports done on a pull request still owed a result.
 
 ## Must
 
-- Run the project's verify commands before the sequence starts, and stop on a failure rather than fixing it
-- Say so and continue when the project names no verify command, since silence there reads as a suite that passed
-- Invoke each step through the Skill tool in the stated order and continue without waiting
-- Stage after the sync skills write, so what they produced reaches a commit
-- Reach the pull request on a branch whose work is already committed and whose sync steps wrote nothing, since `git-stage` stops on an empty index and a session building in slices leaves one
-- Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
-- Name the one point a wrapping caller may act at, so a chain built on this one is not left to pick a gap of its own
-- Name the condition under which the closing block is not emitted, since a caller that closes on its own block leaves two instructions about the last line and nothing deciding between them
-- Watch continuous integration to a terminal state in the background, so the session stays reachable while CI runs, and stop on a failure naming the check
-- Read the evidence thread with `canon pr evidence <number> --check --json` once CI passes, run what it reports owed, and report done only on `settled`, since a chain that never reads the thread ships a regenerated image with no comment and no preview and leaves the controller to repair it
+- The project's verify commands run before the sequence and a failure stops it, and a project naming none is said so rather than read as passing
+- Each step runs through the Skill tool in the stated order, with staging after the sync skills write, and the chain reaches the pull request on a branch already committed
+- No text appears between steps beyond a stop report and the background watch line, and the body names the one point a wrapping caller may act at and when the closing block is not emitted
+- CI is watched to a terminal state in the background, and a failure stops the chain naming the check
+- Done is reported only once `canon pr evidence <number> --check --json` reads `settled`, re-read once after running what it owed, and a binary lacking `--check` reads as unread
 
 ## Must not
 
-- Auto-trigger. Shipping is a decision the user takes, and the tool permission dialog on the push and the pull request is the gate that holds it now that the frontmatter no longer disables model invocation.
-- Fix a failing check. The stop is the point, since a green pull request reached by auto-fix hides what broke.
-- Attempt a fix for a failing verify. The user is already making one, which is what brought the run back here.
-- Implement or review. This chain starts from work already believed done.
-- Report the chain done before the CI watch exits. A turn ending on the watch line leaves a pull request still waiting on CI, and a `✅ Shipped` there claims a result nothing has read.
-
-## Guards
-
-- A failing verify stops the run before the sync skills write, so the tree is left as the user left it
-- A binary lacking `--check` reports the thread unread, never settled, since reading the absence as a pass repeats the failure the read exists to close
-- Re-read the thread once after running what was owed and stop on anything but `settled`, so a refused preview cannot loop the chain
-- A failing check stops the sequence. A stop report and the line announcing the background watch are the two places text is allowed between steps.
+- Auto-trigger
+- Fix a failing check or attempt a fix for a failing verify
+- Implement or review
+- Report the chain done before the CI watch exits
 
 ## Out of scope
 
-- Implementation and review, which `auto-ship` chains ahead of this same sequence. That skill is the full pipeline and this one is the resume point after a stop, which is why the two overlap by design. Verification is the one of the three that belongs on both, since a resume point that trusts the caller's verify trusts a run that stopped.
-- The behavior of each step, owned by the skill invoked. This skill owns the order and nothing else.
+- Implementation and review, which `auto-ship` chains ahead of this same sequence
+- The behavior of each step, which the skill it invokes owns

package/claude/skills/git-split/REQUIREMENT.md

@@ -7,33 +7,26 @@ description: What branch splitting is for, the gaps it closes, and how it differ
 
 ## Gap
 
-Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.canon/tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer skims because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on, and a dirty tree loses its uncommitted work across the checkouts.
+
+Merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body leaves through `gh`, which the audit hook never watches, so a banned character survives into a published pull request.
 
 ## Must
 
-- Refuse a dirty tree, since cherry-picking across branches abandons uncommitted work with no record of it
-- Group by concern from both the commit messages and the file paths, preferring fewer branches over a branch per commit
-- Classify the groups as independent or stacked before generating any command, because the base of every branch follows from that one call
-- Account for every commit ahead of main in the preview
-- State the merge order and the reason behind it, since the order is not recoverable from reading the pull requests afterward
-- Carry the restack loop for stacked mode, where each branch is rebased onto main once the one below it merges
-- Scan every generated title and body for banned characters and internal phase labels as an explicit step before opening a pull request
+- Groups follow concern from both commit messages and file paths, preferring fewer branches, and every commit ahead of main is accounted for in the preview
+- Each group is classified independent or stacked before any command is generated, and stacked mode carries the restack loop
+- The merge order and its reason are stated
+- Every generated title and body is scanned for banned characters and phase labels before a pull request opens
 
 ## Must not
 
+- Run on a dirty tree, on `main`, or with no commits ahead of main
 - Split when one concern already covers the branch
 - Rename a branch whose name already matches its concern
-- Leave a commit unaccounted for. A dropped commit is silent and the branch it came from may already be gone.
+- Leave a commit unaccounted for
 - Merge the pull requests it opens
 
-## Guards
-
-- Dirty working tree: stop and name both recoveries
-- On `main`: stop
-- No commits ahead of main: stop
-
 ## Out of scope
 
-- Partitioning a staged diff into commits, which `git-stage` owns. The two resemble each other and take different input: this one starts from commits that already exist and emits branches.
+- Partitioning a staged diff into commits, which `git-stage` owns
 - The message on each commit, which `git-commit` owns
-- Merging, which stays the user's call. The skill states the order and stops.

package/claude/skills/git-stage/REQUIREMENT.md

@@ -7,33 +7,27 @@ description: What commit grouping is for, the gaps it closes, and how it differs
 
 ## Gap
 
-Without this skill, a staged diff spanning several concerns lands as one commit, so a later revert takes unrelated work with it. A renamed file staged as two separate paths records an add and a delete, losing the rename git would otherwise detect. Commits also land in the order the files happened to be listed rather than the order they depend on, so a bisect stops on a commit that cannot build.
+Without this skill, a staged diff spanning several concerns lands as one commit, so a later revert takes unrelated work with it. A renamed file staged as two paths records an add and a delete, and commits land in listing order rather than dependency order, so a bisect stops on a commit that cannot build.
 
-The routing failure sits on top of those. A description claiming every commit request pulls in the single-concern one this skill has no grouping to do on, and a staged set carrying a hunk-level selection reaches the unstage below and comes back widened to whole files, which is the one case the staged-set rule cannot hold.
+The routing fails on top of that. A description claiming every commit request pulls in single-concern sets with nothing to group, and a hunk-level selection reaching the unstage comes back widened to whole files.
 
 ## Must
 
-- Read the commit format reference and the prose standard before generating
-- Decline the single-concern and the hunk-level staged set in the description, naming the sibling that takes each. The widening is a property of the unstage, so it cannot be fixed here and has to be routed around.
-- Derive the groups from the staged diff, with lockfiles excluded from the derivation context
-- Account for every staged file in the preview, so a dropped file is visible before execution
-- Order the commits so a dependency lands before the file that imports it
-- Keep a rename pair in one group and restage both paths together, so git still detects the rename at commit time
-- Unstage everything first, then restage per group, since the incoming staged set is one undifferentiated blob
-- Count each subject against the length limit and shorten before executing
+- Each message follows the commit format reference, derived from the staged diff with lockfiles excluded, with each subject counted against the length limit before executing
+- Every staged file is accounted for in the preview, and no file the user did not stage is committed
+- Commits are ordered so a dependency lands before the file that imports it
+- A rename pair stays in one group, so git still detects the rename
+- The description declines single-concern and hunk-level staged sets and names `git-commit` for both
 
 ## Must not
 
-- Stage a file the user did not stage. The staged set is the input and widening it changes what ships.
+- Stage a file the user did not stage
 - Split a rename pair across groups
-- Emit anything after the result line. This runs inside a longer flow and prose here buries the next step.
-
-## Guards
-
-- Nothing staged: stop and name the command that stages
+- Run when nothing is staged
+- Emit anything after the result line
 
 ## Out of scope
 
-- Composing a single commit from the whole staged diff, which `git-commit` owns. That skill commits the staged set untouched, so a hunk-level selection belongs there and never here.
-- Splitting commits across branches, which `git-split` owns. The two partition different things: this one takes a staged diff and emits commits, that one takes commits and emits branches.
+- Composing one commit from the whole staged diff, which `git-commit` owns
+- Splitting commits across branches, which `git-split` owns
 - Pushing and opening the pull request, which `git-pr` owns

package/claude/skills/git-worktree/REQUIREMENT.md

@@ -7,32 +7,28 @@ description: What worktree listing and cleanup is for, the gaps it closes, and w
 
 ## Gap
 
-Without this skill, linked worktrees accumulate past the point where any of them is remembered. Merge state does not appear in the worktree list, so a cleanup either removes a worktree still holding unmerged work or, lacking a way to tell, removes nothing. Removing a worktree also leaves its local branch behind, so the branch list keeps growing even when cleanup runs.
+Without this skill, linked worktrees accumulate past the point where any of them is remembered. Merge state does not appear in the worktree list, so a cleanup either removes a worktree still holding unmerged work or removes nothing.
+
+A plain ancestry read misses the whole set, since `git branch --merged` decorates every branch checked out in a worktree. Removing a worktree also leaves its local branch behind, so the branch list keeps growing even when cleanup runs.
 
 ## Must
 
-- Resolve merge state per branch from the pull request first, and fall back to local ancestry when no pull request exists
-- Match the ancestry fallback against the branch name alone. `git branch --merged` decorates the current branch and every branch checked out in a linked worktree, which is the whole set this skill enumerates.
-- Remove the worktree and its local branch together, since either one left alone is the state the skill exists to prevent
-- Exclude five kinds of row from the remove set: the main root, the current session's worktree, any dirty tree, any worktree registered from outside the path prefix `session-worktree` creates under, and any worktree a live session is occupying
-- Give every skipped row a one-word reason, so the skip is a decision the user can overturn rather than a silence
-- Pick exactly one mode. Listing and removing are different requests and inferring both from one invocation removes worktrees the user meant to read about.
+- Merge state comes from the pull request first and from local ancestry matched on the branch name alone when no pull request exists
+- A worktree and its local branch are removed together
+- The main root, the current session's worktree, a dirty tree, a worktree outside the prefix `session-worktree` creates under, and one a live session occupies are never removed
+- Every skipped row carries a one-word reason, and an empty remove set says why each row was held
+- Each run is exactly one of listing or removing
 
 ## Must not
 
-- Enter or create a worktree. The description states the boundary so the model routes entry elsewhere rather than discovering it here.
-- Remove a worktree with uncommitted work, whatever its merge state
-- Remove a worktree a live session is occupying, whatever its merge state
-- Remove the worktree the session is currently running in
+- Enter or create a worktree
+- Remove a dirty or occupied worktree, whatever its merge state
+- Remove the worktree the session runs in
+- Run outside a git repository
 - Emit anything after the result line
 
-## Guards
-
-- Not a git repository: stop
-- Remove set is empty: stop and say why every row was held back
-
 ## Out of scope
 
-- Entering a worktree, which `session-worktree` owns. That skill derives the name and aligns the branch, and this one never creates.
-- Deciding which features can run in parallel, which is a planning call rather than a git operation
-- The pull request lifecycle, which `git-pr` and `git-followup` own. This skill reads pull request state and never writes it.
+- Entering a worktree, which `session-worktree` owns
+- Writing pull request state, which `git-pr` and `git-followup` own
+- Deciding which features can run in parallel, which the planning skills own

package/claude/skills/make-deck/REQUIREMENT.md

@@ -7,38 +7,30 @@ description: Why the skill draws a deck as HTML in the project's tokens inside i
 
 ## Gap
 
-Without this skill, a deck request turns into hand-built output. The session writes a deck into whatever path occurs to it, so a second deck overwrites the first and nothing lists either. It writes pptxgenjs code or hex colors per deck, so the deck takes neither the project's design nor any other deck's, and it invents attributes the converter does not read, so a section, a chart, or an entrance silently goes missing. Every slide comes out as a title over bullets, which is the shape that needs no decision and reads as a document rather than a deck.
+Without this skill, a session writes a deck into whatever path occurs to it, so a second deck overwrites the first and nothing lists either. It writes pptxgenjs code or hex colors, so the deck ignores the project's design. Every slide comes out as a title over bullets, which reads as a document rather than a deck.
 
-A first render shipped unread hands the audience the overlap, the overflow, and every element the converter fell back to a picture for, since markup that looks correct says nothing about the file it produces.
+It invents attributes the converter does not read, so a section, a chart, or an entrance silently goes missing. A first render shipped unread hands the audience the overlap, the overflow, and every element the converter fell back to a picture for.
 
 ## Must
 
-- Read the existing decks and the slide format from the CLI before drawing, and pick a deck name no listed deck carries unless the request names one
-- Write each deck into its own folder under the slides record folder, one HTML file per slide in filename order
-- Draw with the project's custom properties so the deck takes the project's design
-- Vary the composition across the deck rather than repeating one shape
-- Size content to fit the slide frame, keeping titles short and lines tight
-- Shell out to the render command for the deck itself
-- Read every fallback and refusal the render reports, run one QA pass over the rendered images, and fix what both report
+- The existing decks and the slide format are read from the CLI before drawing, and a new deck takes a name no listed deck carries unless the request names one
+- Each deck lands in its own folder under the slides record folder, one HTML file per slide in filename order, drawn with the project's custom properties
+- The composition varies across the deck, and content fits the slide frame with short titles and tight lines
+- The render command produces the deck itself
+- Every fallback and refusal the render reports is read, one QA pass runs over the rendered images, and what both report is fixed once
 
 ## Must not
 
-- Hardcode a deck name, an attribute, or a chart type, which goes stale the moment the CLI changes
-- Reimplement the conversion, the master, or the packaging, which the CLI owns
+- Hardcode a deck name, an attribute, or a chart type, or reimplement the conversion, the master, or the packaging the CLI owns
 - Write a deck into the shared layouts folder, which is never listed as a deck
-- Invent token values when the project has no token stylesheet
+- Invent token values when the project has no token stylesheet, rather than saying the deck renders unstyled
 - Write centered body text or content that overflows a slide
-- Loop on aesthetics past a single fix pass
-
-## Guards
-
-- No token stylesheet: draw the deck anyway and say it renders unstyled.
-- Image conversion tools missing: skip the image pass and say so. Do not fail the render over a verification step.
+- Loop on aesthetics past a single fix pass, or fail the render when the image tools for the QA pass are missing
 
 ## Out of scope
 
 - Converting HTML to PowerPoint, which the CLI owns end to end
-- The project's palette and faces, which live in its token stylesheet rather than in the slides
-- Writing the content the deck is about, which the caller brings
-- Drafting a deck as a canvas page, which waits on a measurement of that authoring surface
+- The project's palette and faces, which its token stylesheet owns
+- Writing the content the deck is about, which the caller owns
+- Drafting a deck as a canvas page, which no skill owns until that authoring surface is measured
 - Recording a demo, which `script-screencast` owns

package/claude/skills/markdown-craft/REQUIREMENT.md

@@ -7,9 +7,9 @@ description: Why the markdown format rules travel in a skill, and where the boun
 
 ## Gap
 
-Without this skill, the markdown format rules sat in a standard that a session opened only when a rule told it to. The banned characters and the structure rules are facts a scan settles, yet a session wrote the whole document from memory and learned the result only from the audit's exit.
+Without this skill, the markdown format rules sit in a standard that a session opens only when a rule tells it to. The banned characters and the structure rules are facts a scan settles, yet a session writes the whole document from memory and learns the result only from the audit's exit.
 
-The rules also had three carriers, a standard, a generated rule pointing at it, and a second hand-written rule routing voice. Each stated one routing and each drifted from the others.
+The rules also have three carriers, a standard, a generated rule pointing at it, and a hand-written rule routing voice. Each states one routing and each drifts from the others.
 
 ## Must
 
@@ -20,4 +20,10 @@ The rules also had three carriers, a standard, a generated rule pointing at it,
 ## Must not
 
 - Restate the banned characters in the body
-- Carry voice, rhythm, or word guidance, which `write-human` owns
+- Carry voice, rhythm, or word guidance
+
+## Out of scope
+
+- Voice, rhythm, and word choice, which `write-human` owns
+- A Mermaid fence or a figure, which `draw-figure` owns
+- The banned-character scan itself, which `canon markdown audit` owns

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

@@ -7,37 +7,28 @@ description: What feature planning is for, the gaps it closes, and why it stops
 
 ## Gap
 
-Without this skill, implementation starts before anyone knows what it touches. A session reads no project context and rediscovers a settled constraint halfway through, the file list emerges as the work goes rather than before it, and the ambiguities that needed a decision get resolved silently in whichever direction the first edit happened to go. A constraint naming a surface to leave alone forbids two different acts at once, so the executing session picks one and the branch either grows an excluded concern or ships a reference to a file the change deleted.
+Implementation starts before anyone knows what it touches. A session rediscovers a settled constraint halfway through, and an ambiguity gets resolved silently in whichever direction the first edit went. A feature stacked into pull requests over the same files pays the review cost once per slice.
+
+A constraint naming a surface to leave alone forbids two acts at once, conforming it and retargeting a pointer into it. A vague ask reaches the plan with no checkable criterion, and a decision rests on a practice recalled from memory.
 
 ## Must
 
-- Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
-- Reframe a vague ask as observable, checkable success criteria before listing any file, and carry each criterion into the plan's verification, so a plan never ships a check with nothing measurable to prove
-- Slice batches by a user-visible path rather than by layer, and sequence the riskiest batch first while a sweep stays last, so the batch most likely to change the plan lands while later ones can still move, and fold a stacked batch that shares most of its files into its parent unless the plan writes down why the two are judged apart, since a canvas inspector built as five stacked pull requests over 26 files paid the full review, rebase, and merge cost five times
-- Predict the operator's answers to the next three questions about the ask's success criteria, proceed on the ones it can predict, and ask when it can predict none, since a plan built on a guessed goal proves the wrong thing
-- Fetch the outside source a decision rests on, quote the passage relied on in the plan's `**Sources:**` section, and mark a source it could not fetch as unverified, since a planner that paraphrases a practice from model memory ships an unaudited claim. A measured planner run fetched its sources only after a follow-up message asked, and the `search-craft` measured run shows a plain research request never loaded that skill unprompted
-- Name every file the work touches with the reason it is touched
-- Place each new path against the layout guidance with a one-clause reason, loading that guidance only when the plan creates a file or folder, since the planner decides placement and the worker copies whatever path it is given
-- Name how each outcome is proven and which input or state would break the change, so the executing session has a check to run and the reviewer has a place to look
-- Surface each unresolved ambiguity as a numbered question carrying a suggested answer and an empty answer slot, so the plan is decision-ready in one pass
-- State which act a constraint forbids when it names a surface to leave alone, since conforming that surface and retargeting a pointer into it are different acts and only one is out of scope
-- Scale the output to the work. A two-file change with nothing to decide should not produce a plan file.
-- Stop at the plan and wait to be told to continue
+- Read the project's Claude setup before scanning source, and name every file the work touches with the reason it is touched
+- Reframe a vague ask as observable success criteria, carry each into the plan's verification, and ask when none can be predicted
+- Slice by user-visible path with the riskiest batch first, and fold a stacked batch sharing most of its files into its parent unless the plan says why they differ
+- Quote the fetched passage behind each outside source, mark an unfetched one unverified, and place each new path against the layout guidance with a one-clause reason
+- Surface each ambiguity as a numbered question with a suggested answer and an empty slot, and stop at the plan
 
 ## Must not
 
 - Implement, or edit any file the plan describes
-- Read directories speculatively. Context spent on files the feature does not touch is context the plan does not get.
-- Bundle independent concerns into one plan, since a plan covering two things gets executed as neither
-- Restate the plan in chat during follow-up rounds. The file is the source of truth and a chat copy of it goes stale immediately.
-
-## Guards
-
-- No feature description: stop and ask for one
-- No predictable success criterion: ask before planning rather than guessing the goal
+- Read directories speculatively, since context spent on files the feature does not touch is context the plan does not get
+- Bundle independent concerns into one plan
+- Restate the plan in chat during follow-up rounds, since the file is the source of truth
 
 ## Out of scope
 
-- Executing the plan, which is the ship pipeline
-- Task-board state, which `task-board` owns. A plan links to its task and does not create one.
-- Reconciling the context entries after the work lands, which `context-fold` owns, and marking the board, which `task-complete` owns
+- Executing the plan, which `auto-ship` owns
+- Creating a task for the plan, which `task-board` owns
+- Reconciling the context entries after the work lands, which `context-fold` owns
+- Marking the board, which `task-complete` owns

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

@@ -7,43 +7,27 @@ description: Why a question that has not been measured gets a disposable folder
 
 ## Gap
 
-Without this skill, a question nobody has measured is answered with a plan. The session commits to an approach before the current state is known, and the reasoning that produced it lives in a conversation that compacts away. A research pass that does run spreads its findings across chat, so the next session re-measures what this one already counted, or worse carries a figure from recall and states it as current.
+A question nobody has measured is answered with a plan. The session commits before the current state is known, and its reasoning compacts away with the conversation, so the next session re-measures what this one counted or states a figure from recall as current.
 
-Two failure modes cost more than the rest. A track that fans out to subagents returns findings without the reasoning that makes the folder worth keeping, which turns a conversation into a search result. And an experiment fixture written under the project root loads that project's own instruction files through the ancestor chain, so the arm measures the repository instead of the question, and the result reads as evidence either way.
-
-A track that closes with several separable findings writes only one task, and the rest have no stated route out of the folder. Without one, a finding sits until the operator asks whether filing it elsewhere is the next step, which is how a track that measured everything correctly still lost work between sessions.
+A track fanning out to subagents returns findings without their reasoning. Under the project root, a fixture loads its instruction files, so the arm measures the repository instead of the question. When a closing track holds several findings, one task is written and the rest have no route out.
 
 ## Must
 
-- Detect open, resume, and close from the folder itself, matching the topic against tracks already there before deriving a slug
-- Name a newly opened folder with a two-digit ordinal ahead of the slug, taken from the highest one already present across groundwork and intake
-- Apply the qualifying test in open mode alone, so a track already measured is not refused by the test that admitted it
-- Measure the current state now rather than carrying a figure from a previous session
-- Carry a lean and the finding that would overturn it on every open question, or admit that a measurement is missing
-- Confine writes to the track folder, with the close-time task file, the experiment fixture, and the intake routing below as the only exceptions
-- Route a closing-track finding the required task does not cover through `plan-intake`, rather than leaving it to be asked about. The route runs in the same session, so it is a write outside the folder rather than a handoff to a later one.
-- Place the closing task's row through `task-board` Step 4 rather than writing `priority.md` or `backlog.md` directly
-- Link every claim about a source outside the project, and list an unread source as a lead rather than citing it
-- Put a fixture a headless run is pointed at outside the repository
-- Write the next-session file self-contained, since backing the folder through `canon records push` and `canon records pull` holds only where a records remote is configured, protects only against the machine being lost even there, and never against a compaction dropping this session's reasoning before it has pushed
+- Detect open, resume, and close from the folder itself, matching the topic against existing tracks first, and number a new folder past the highest ordinal across groundwork and intake
+- Measure the current state now, carry a lean and the finding that would overturn it on every open question, link every outside claim, and end a pass with every question leaned on a plain retell
+- Confine writes to the track folder, plus the close-time task file, the experiment fixture, and the intake routing
+- Route a closing finding the task does not cover through `plan-intake` in the same session, and place the closing task's row through `task-board`
+- Put a fixture a headless run is pointed at outside the repository, and write the next-session file self-contained
 
 ## Must not
 
 - Write a feature plan, a source change, a standard, a rule, or a reference doc
-- Dispatch subagents. A search too large to run inline is a finding that the question is too broad.
-- Close while an open question quietly fails an outcome, rather than resolving it or recording it as knowingly accepted
-- Spawn more than three billed headless runs without asking
-- Match a topic against the shared scratch directory, which holds folders that were never tracks
-- Pause for approval between steps, which the write scope is what makes safe
-
-## Guards
-
-- No topic given: stop rather than inferring one
-- Fewer than two of the three qualifying conditions hold in open mode: stop and route to the planning skill, because the decision is already made
-- Resume and close are exempt from that test by definition
+- Dispatch subagents, since a search too large to run inline is a finding that the question is too broad
+- Close while an open question quietly fails an outcome, or spawn more than three billed headless runs without asking
+- Pause for approval between steps, or open a track with no topic or fewer than two of the three qualifying conditions
 
 ## Out of scope
 
 - Writing the plan the track concludes toward, which `plan-feature` owns
-- Implementing anything the track recommends
-- Persisting the folder. It is gitignored and disposable, which is what makes it the right container for an unanswered question.
+- Filing a breadth dump, which `plan-intake` owns
+- Placing a task row, which `task-board` owns

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

@@ -1,6 +1,6 @@
 ---
 name: plan-groundwork
-description: Opens and runs a numbered groundwork folder under `.canon/groundwork/<nn>-<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", or "open a groundwork folder". Do NOT use to write a feature plan or to implement. That is `plan-feature`.
+description: Opens and runs a numbered groundwork folder under `.canon/groundwork/<nn>-<slug>/` for a topic that has to be measured before it can be planned. Detects open, resume, and close from the folder itself. Use when asked to "research X", "dig into X", "work out what we should do about X", "measure this before we commit", "open a groundwork folder", or "retell the groundwork". Do NOT use to write a feature plan or to implement. That is `plan-feature`.
 metadata:
   family: decide
 ---
@@ -88,6 +88,7 @@ A matched folder routes on its own `<nn>-<slug>/`. Detect the mode from the fold
 
 - Present without `06-decision.md`: resume
 - Present and the user judges it ready: close
+- Present and the user asks for a retell: read the track and end on the retell, measuring and writing nothing
 
 ## Step 2: orient
 
@@ -135,4 +136,6 @@ Aside from an experiment fixture, Steps 4 and 5 are the only ways close mode rea
 
 ## Output
 
-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.
+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, the retell, and the close template. A run that stops on a guard skips it.
+
+End on the retell in place of the open and resume template once every open question carries a lean. A question marked `none, needs measuring` keeps the open and resume template, unless the operator asks for a retell, which answers whatever the state. The retell lists written files under `**Written:**`, and close keeps its one-line report.