@erclx/canon 5.41.0 → 5.43.0

package/claude/skills/role-orchestrator/scripts/poll.ts

@@ -85,7 +85,8 @@ export const STALE_AFTER = 7200
 // so a heading added in one of them breaks a test here that no check reaches
 // across. The review family reaches this file through `canon pr review-state`,
 // so its two headings are pinned only for the fallback that answers a target
-// whose CLI predates that verb.
+// whose CLI predates that verb. The UI family reaches it through the same
+// record and is pinned nowhere here.
 const REVIEW_HEADINGS = ['## Review', '## Review closed']
 const REPLY_HEADINGS = [
   '## Review response',
@@ -95,8 +96,6 @@ const REPLY_HEADINGS = [
 // An evidence comment answers no review, so it stays out of the reply family
 // and is excluded from the unmatched filter on its own.
 const KNOWN_HEADINGS = [...REVIEW_HEADINGS, ...REPLY_HEADINGS, '## Evidence']
-const UI_HEADINGS = ['## UI review', '## UI review closed']
-const UI_MARKER = /^<!-- review-ui: head=([0-9a-f]{7,40}) -->$/
 
 const firstLine = (body: null | string | undefined): string =>
   (body ?? '').split('\n')[0].replace(/\r$/, '')
@@ -200,29 +199,22 @@ export const scopeFallback = (payload: Payload, now: number): Scope => {
 }
 
 /**
- * The UI family is posted as a pull request review, so it is read off
- * `reviews`. The newest UI heading decides the state, and the head it covered
- * comes from the marker on the body's last line, since the submission stamp
- * moves onto a commit pushed while the pass drove. A marker may name a short
- * sha, so coverage is a prefix match.
+ * Reads the UI family off the verb's record, so the poll and the lift agree on
+ * which head a close covers, a close carried across unpainted pushes included.
+ * A record carrying no `ui` object is a refusal or a CLI predating the field,
+ * and reads as unread, which leaves the baseline's value standing.
  */
-export const uiState = (payload: Payload, head: string): string => {
-  const last = (payload.reviews ?? [])
-    .filter((review) => UI_HEADINGS.includes(firstLine(review.body)))
-    .at(-1)
-  if (last === undefined) return 'none'
+export const uiFromVerb = (record: unknown): string => {
+  if (typeof record !== 'object' || record === null) return ''
+  const ui = (record as Record<string, unknown>).ui
+  if (typeof ui !== 'object' || ui === null) return ''
 
-  const heading = firstLine(last.body) === '## UI review' ? 'open' : 'closed'
-  const lastLine = (last.body ?? '')
-    .split('\n')
-    .map((line) => line.replace(/\r$/, ''))
-    .filter((line) => line !== '')
-    .at(-1)
-  const marked = lastLine === undefined ? null : UI_MARKER.exec(lastLine)
-  const commit = marked?.[1] ?? last.commit?.oid ?? 'none'
-  const covered = commit !== 'none' && head.startsWith(commit)
+  const fields = ui as Record<string, unknown>
+  if (fields.state !== 'open' && fields.state !== 'closed') return 'none'
+  const commit = typeof fields.commit === 'string' ? fields.commit : 'none'
+  const covered = fields.isCovered === true && commit !== 'none'
 
-  return `${heading}-${covered ? 'head' : 'behind'}-${commit.slice(0, 7)}`
+  return `${fields.state}-${covered ? 'head' : 'behind'}-${commit.slice(0, 7)}`
 }
 
 /** Takes the first ten fields and ignores the rest, so a short or padded line still reads. */
@@ -792,7 +784,7 @@ const buildRow = (
     resp: replies.count,
     stale: stale.stale,
     staleFiles: stale.files,
-    ui: uiState(payload, head),
+    ui: uiFromVerb(record),
     unmatchedCount: unmatched.count,
     unmatchedHeading: unmatched.heading,
   }

package/claude/skills/role-planner/REQUIREMENT.md

@@ -61,7 +61,7 @@ four carried at least one, caught only because the planner ran
 - Owe an announcement when the record lands, carrying the path and what the row got wrong, since the controller cannot watch the read happen
 - Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
 - Keep correcting the dispatcher a first-class move carrying its evidence, since a trial corrected a brief's premise, planned every row anyway, and carried the consequence into a plan question
-- Carry a talk clause for a launch whose operator is in the session, putting each open question to them, recording a settled pick in place, and owing a close message when they end the conversation, since a cold planner's halting rules contradict a brief that asks it to talk
+- Carry a talk clause for a launch whose operator is in the session, putting each open question to them, recording a settled pick in place, sending an ask about a row now building to the controller rather than the worker, and owing a close message when they end the conversation, since a cold planner's halting rules contradict a brief that asks it to talk
 - Point at each of the three skills for its record's shape and the steps that write it
 - Defer the addressee resolution to `session-relay` and keep only the last-rung inference, which discriminates differently here than it does for a worker because a session in this role holds no feature branch either
 

package/claude/skills/role-planner/SKILL.md

@@ -101,10 +101,10 @@ One rung stays here because it differs between roles. Inference takes the sessio
 
 A launch whose brief says it is a talk session puts the operator in this one. Everything above holds, and the clause below changes how questions are answered and when the role ends. A launch carrying no such sentence takes none of this.
 
-- Put each open question to the operator through the structured question surface before writing the record, and record a settled pick in place per the plan standard
-- Never fill an `- Answer:` slot the operator did not answer
+- Put each open question to the operator through the structured question surface before writing the record
+- Record each pick per `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`
 - Keep answering under `plan-feature`'s discussion rounds after the record lands, since the operator launched this session to keep talking.
-- Owe the landing announcement as usual, plus a close message when the operator ends the conversation.
+- Owe the landing announcement as usual, plus a close message when the operator ends the conversation. Send an ask about a building row to the controller, never the worker.
 - Skip the before-prompt block message for a question put to the operator in the session. Keep it for a block the operator cannot answer, since a controller learns of a stall only from a message.
 
 The operator being present is an assumption the launch carries. A talk planner whose operator has walked away waits silently on its first question, so say what the session is waiting on in the turn it stops.

package/claude/skills/role-worker/REQUIREMENT.md

@@ -29,11 +29,14 @@ The draft mark fails from both ends. On 2026-08-31 four sessions re-drafted a pu
 - Owe an announcement the moment the pull request opens, carrying the number, the branch, and the task, since that transition is the one interval only the worker can observe
 - Carry a row the build turned up in the pull request announcement, and send it alone only when the session ends before a pull request opens, since the worker files no task file of its own and the channel is the row's only route
 - Carry a fan-in member's branch and head commit in its done message in place of a pull request number, and end its role at the push, since a member opens no pull request and its integrator fixes what the merge surfaces
+- Send the controller the `canon pr review-state` record when a wait for the reviews times out, rather than waiting on, since a worker improvising that read stalled silently with both reviewers idle behind it
 - Owe a message before a block becomes an interactive prompt, since a session already waiting on input never reaches the tool round an inbound message drains at
 - Defer the addressee resolution to `session-relay` and keep only the operator ask and the last-rung inference, which discriminates here because a worker holds a feature branch and a controller does not, and which falls back to the roster and says so, since an operator's own launch names nobody
 - Keep refusing a dispatcher a first-class move carrying its evidence, since the halts measured so far were correct and the cost of each fell where it belonged
 - State that a held body may be older than the branch under it, since a plugin skill loads from the marketplace cache rather than from the working tree
 - Carry a talk clause for a launch whose operator is in the session, asking them at a judgment call and sending a close message when they end the conversation, since a cold worker's halt-toward-the-controller and merge-ends-the-role rules contradict a brief that asks it to talk
+- Freeze the plan's scope at dispatch, sorting a late ask into a defect to fix, a follow-up row to report, or an addition the operator's word admits with its re-review cost stated, since intake 155 measured about four UI review rounds on one pull request from late asks, each re-running both reviews
+- Own the local preview server for a painted diff, started as a tracked background command before the pull request opens, since a `no-server` read leaves the evidence comment and the UI reviewer without an address on the one path nobody watched being built (erclx/frameboard#1 and erclx/frameboard#4)
 - Point at `session-worktree`, `auto-ship`, and `review-address` for the steps each already owns
 
 ## Must not

package/claude/skills/role-worker/SKILL.md

@@ -36,9 +36,32 @@ A ready folder and the draft mark each carry work another session already did, s
 
 ### Overriding a plan question
 
-Rewrite an unanswered question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against it, leaving `- Answer:` blank, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+Follow `### Overrides and settled questions` in `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md` when this build decides against a suggestion.
 
-Put the same deviation in one line under the open task's `## Findings`, opening with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+Open the task's `## Findings` line for an override with the bold source-and-date label `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md` fixes.
+
+### The preview server
+
+A painted pull request needs a server in this worktree for `canon pr local` to find, and this session is the one with a lifetime to own it. `auto-ship` Step 5 decides whether the diff is painted, so this body restates no file test.
+
+- Run `canon pr local --json` first and start nothing when `reason` reads `ok`
+- Otherwise start the stack's `dev` script as a background command from the worktree root before the pull request step. `dev` follows the worktree, so a `review-address` fix shows on the same link.
+- Wait up to 60 seconds for the verb to read `ok`, then ship either way. A stack with no `dev` script gets no start, and `pr-evidence` reports `no-server`.
+- Never detach it with `nohup`, `setsid`, or `disown`, since the owning session is the stop. `canon worktrees reclaim` ends any listener left in a worktree it removes.
+
+A hand-run `git-ship` or `git-pr` starts no server, since only a worker has a lifetime to own one.
+
+## Scope after dispatch
+
+The plan is the scope from the dispatch on. A late ask restarts both reviews, and one pull request took about four UI review rounds from asks that arrived mid-build.
+
+Sort each ask that arrives after dispatch three ways:
+
+- A defect is a failed outcome or a regression in what the plan builds. Fix it in this build, and take every review finding on the pull request through `review-address` the same way.
+- Anything else is a follow-up row. Do not build it. Reply with the follow-up wording, and report the row to the controller with its title, origin, and surface.
+- Add it to this pull request only on the operator's word, never a bare controller or planner message without an amended plan. Before the commit, say that both reviews run again.
+
+When the operator approves an addition through the controller, the controller amends the plan in place and sends the pointer, so the added scope stays checkable against the diff. Fall back to `session-relay`'s copyable block when no controller is live, and never drop the row.
 
 ## The board is read-only
 
@@ -78,6 +101,14 @@ Ask for the re-review as `review-address` Step 8 returns, carrying what was addr
 - Send a block out as a message before it becomes an interactive prompt.
 - Send nothing on progress. A worker reporting progress rebuilds, on this side of the channel, the poll the announcement retired on the other.
 
+### Waiting on the reviews
+
+A worker that improvised this read polled issue comments, never saw a UI close posted as a review, and stalled with both reviewers idle. One verb reads it the way the lift does.
+
+- Read review state only through `canon pr review-state`, never off issue comments, where neither review family posts
+- Enter `canon pr review-state <number> --wait 1200 --json` again in the background after asking for the re-review, the same wait `auto-ship` Step 7 runs
+- Send the controller that record on `timeout` rather than waiting on, since a silent wait past the deadline is the stall the verb exists to end
+
 ### Addressing
 
 Address the session the launch named, and the reviewer by its dispatch's sessionId, each as a `sessionId` rather than a name. `canon:session-relay` turns that id into an address and carries the send, falling back to a copyable block where no send tool exists.
@@ -99,6 +130,7 @@ A launch whose brief says it is a talk session puts the operator in this one. Ev
 
 - Ask the operator in the session through the structured question surface at a judgment call, rather than halting toward the controller
 - Put a plan question written as needing the operator's call to them directly
+- Sort a late ask from the operator in place under the scope rule above, and send the controller the follow-up row rather than relaying the ask
 - Send the controller a close message when the operator ends the conversation, beside the announcements the channel above owes.
 - Keep the before-prompt block message for a block the operator cannot answer. A question put to the operator who is in the session needs none.
 

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

@@ -42,7 +42,7 @@ Access is a second gap a session cannot derive. Probed on 2026-10-02, Reddit ref
 ## Out of scope
 
 - The form a citation takes: the procedure or standard writing it
-- A Claude Code subject: the `claude-code-guide` agent, which `draft-doc`'s wiki sourcing step already routes to
+- A Claude Code subject: a direct fetch of `https://code.claude.com/docs/llms.txt` and the `.md` page it names, as `draft-doc`'s wiki sourcing step already does
 - Image generation, which makes a picture rather than finding a source
 - Loading on every web search rather than on a research-shaped request: a hook matching `WebSearch`, planned on its own
 - Whether a session already scopes searches without the skill, which only a run on a fresh research request without it would show

package/claude/skills/search-craft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: search-craft
-description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is the `claude-code-guide` agent, or to generate an image, which is not search.
+description: Carries the thinking step a session takes before it searches outside the project, naming the field, deriving who that field treats as authoritative, and running a search scoped to those sources beside an open one, plus a dated note on which sites refuse access. Use before any outside search for evidence, papers, documentation, statistics, or opinion, when a procedure loads it at its sourcing step, or when asked "find me the strongest evidence on X", "where should I look for this", "what does the research say", "find papers on", "look up the docs for", or "what are people saying about". Do NOT use to format a citation, which belongs to the surface writing it, to source a Claude Code subject, which is a direct fetch of Anthropic's docs index, or to generate an image, which is not search.
 metadata:
   family: build
 ---
@@ -87,6 +87,6 @@ These flags fire after the search has run.
 ## What this delegates
 
 - The form a citation takes: the surface writing it, such as the standard the procedure writes to
-- A Claude Code subject: the `claude-code-guide` agent, which `draft-doc`'s wiki sourcing step routes to
+- A Claude Code subject: a direct fetch of `https://code.claude.com/docs/llms.txt` and the `.md` page it names, as `draft-doc`'s wiki sourcing step does
 - Generating an image: whatever draws the surface, since making one is not search
 - Access code a session needs repeatedly: a `canon` verb, never a script in this skill

package/claude/skills/search-craft/references/adopted.md

@@ -9,19 +9,31 @@ Three third-party research skills were read before this one was written. None of
 
 ## Adopted
 
-**Recording each route's failure.** [aghori3004/claude-research-stack](https://github.com/aghori3004/claude-research-stack) keeps one `research-sources` skill that orders sources cheapest first and writes down how each one fails. Adopted as the access note, which records a refusal a session hit rather than leaving the next session to learn it by failing.
+### Recording each route's failure
 
-**Calling the tools directly.** The same skill ships no wrapper scripts, so it calls the command-line tools and servers it names. Adopted as the rule to reach a keyless API with a plain request rather than writing a wrapper for one search.
+[aghori3004/claude-research-stack](https://github.com/aghori3004/claude-research-stack) keeps one `research-sources` skill that orders sources cheapest first and writes down how each one fails. Adopted as the access note, which records a refusal a session hit rather than leaving the next session to learn it by failing.
 
-**Treating a paid route as the operator's call.** [rohunvora/x-research-skill](https://github.com/rohunvora/x-research-skill) reaches X through the official API at a cost per search page. Adopted as the stop before any route that pays or logs in, since that cost is one the operator decides rather than one a session discovers.
+### Calling the tools directly
+
+The same skill ships no wrapper scripts, so it calls the command-line tools and servers it names. Adopted as the rule to reach a keyless API with a plain request rather than writing a wrapper for one search.
+
+### Treating a paid route as the operator's call
+
+[rohunvora/x-research-skill](https://github.com/rohunvora/x-research-skill) reaches X through the official API at a cost per search page. Adopted as the stop before any route that pays or logs in, since that cost is one the operator decides rather than one a session discovers.
 
 ## Declined
 
-**A directory of sites per category.** None of the three is one, and each earns its keep on access and cost instead. A site list also rots with nobody noticing, so the body derives a field's authorities per question rather than reading them off a list.
+### A directory of sites per category
+
+None of the three is one, and each earns its keep on access and cost instead. A site list also rots with nobody noticing, so the body derives a field's authorities per question rather than reading them off a list.
+
+### Reaching walled sites through a logged-in browser
+
+`claude-research-stack` reaches Reddit and X through a desktop Chrome session holding the operator's login. Declined because the body never suggests working around a login.
 
-**Reaching walled sites through a logged-in browser.** `claude-research-stack` reaches Reddit and X through a desktop Chrome session holding the operator's login. Declined because the body never suggests working around a login.
+### A bundled engine
 
-**A bundled engine.** [mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) is a Python engine with its own test suite and paid aggregators behind it. Declined because a skill here ships no code, and access a session needs repeatedly becomes a `canon` verb.
+[mvanhorn/last30days-skill](https://github.com/mvanhorn/last30days-skill) is a Python engine with its own test suite and paid aggregators behind it. Declined because a skill here ships no code, and access a session needs repeatedly becomes a `canon` verb.
 
 ## Stated by no source
 

package/claude/skills/session-map/references/session.md

@@ -5,9 +5,11 @@ description: Filename and location, the sections a handoff carries, the write an
 
 # Session map reference
 
-Applies to `.canon/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them. It is rewritten whenever the session that owns it learns something the next session would otherwise re-derive, and it is optional: a project whose sessions never approach a compaction carries none.
+Applies to `.canon/tasks/session-<slug>.md`. A session writes one before a compaction, because a compaction keeps conclusions and drops the reasoning that produced them.
 
-Any session writes one. The role a session holds decides which sections it adds on top of the core, never whether it may write at all.
+- Rewrite it whenever its owner learns something the next session would otherwise re-derive
+- It is optional, and a project whose sessions never approach a compaction carries none
+- Any session writes one. The role a session holds decides which sections it adds over the core, never whether it may write.
 
 ## Contents
 
@@ -70,14 +72,31 @@ Add a section only for content that fits none of the three and would otherwise b
 
 The `session-map` skill is the invocable route onto this procedure and holds no role, so a session reaching for a handoff without knowing this document exists still lands here. A session that arrives at this document directly follows the steps below unchanged.
 
-1. Run `canon claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`. A skill body enters a session once and re-invoking the skill does not re-read the file, so the drift is worst at exactly this moment and a name here is a body the session has been following out of date. Recording a name is not acting on it, and the verb misses a body this session edited and has not committed. This step belongs to session length rather than to any role, so every writer runs it, and a refusal names the boundary of what the verb can read rather than a fault.
-2. Recover that commit from how long the session has been running with `git log -1 --format=%H --before='<duration> ago'`, rounding the duration up rather than down. Nothing on the machine records it. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is the safe one and a guess at the exact commit is not worth making. An empty result means no commit predates the window, so take the oldest commit the history holds and say which of the two the ref came from.
-3. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering and what each task waits on, a task file holds its own findings, and a measurement folder holds its track.
+1. Run `canon claude skills drift <the commit this session started from>` and record what it names under `## Standing cautions`.
+2. Recover that commit with `git log -1 --format=%H --before='<duration> ago'`, rounding the session's running time up rather than down.
+3. Write only what a compaction destroys and no other artifact already carries. The board holds the ordering, a task file its findings, and a measurement folder its track.
 4. Cite a commit, a task, or a file and line for every claim, so the next session can tell a read from a recall.
-5. Fill a section from reasoning the session actually holds. A session with no cross-feature picture that fills `## State` from what is already in git has written a summary of the tree, which the reader can produce faster than they can read it.
+5. Fill a section from reasoning the session actually holds.
 
 Do not restate the board, and do not summarize the work that shipped, since version control already carries it.
 
+### Why the drift step
+
+A skill body enters a session once, and re-invoking the skill does not re-read the file. Drift is worst at this moment, so a name here is a body the session followed out of date.
+
+- Recording a name is not acting on it, and the verb misses a body this session edited and has not committed
+- The step belongs to session length rather than any role, so every writer runs it. A refusal names the boundary of what the verb can read rather than a fault.
+
+### Recovering the start commit
+
+Nothing on the machine records the start commit. A ref older than the oldest load over-reports, and confirming a name costs one read of the body, so the generous end is safe and an exact guess is not worth making.
+
+An empty result means no commit predates the window. Take the oldest commit the history holds, and say which of the two the ref came from.
+
+### Filling from what the session holds
+
+A session with no cross-feature picture that fills `## State` from git has written a summary of the tree. The reader produces that faster than they can read it.
+
 ## Reading one back
 
 - Read the newest map in the folder, by modification time, and treat it as the previous session's scratch rather than as a source
@@ -90,7 +109,7 @@ Do not restate the board, and do not summarize the work that shipped, since vers
 - Let the adding surface fix where its own section sits, so a role can place one between core sections where that reads better. The core order holds among the core sections alone.
 - Keep a section out of the core when a session holding no such role would leave it unfilled. An unfilled section teaches a reader to skip the file.
 - Cite the route onto `## Writing one` rather than restating the procedure, so the extension is the only thing the adding surface carries and the two cannot fall out of step
-- Carry a resume instruction inside the map itself when the routing to that instruction is what a compaction takes. The map survives what the instruction was loaded from, so each reaches a reader the other cannot.
+- Carry a resume instruction inside the map when a compaction takes the routing to it. The map survives what the instruction was loaded from, so each reaches a reader the other cannot.
 
 ## Template
 

package/claude/skills/session-worktree/references/main-root-writes.md

@@ -8,17 +8,34 @@ Shared session scratch, being `.canon/plans/`, `.canon/review/`, and `.canon/tas
 ## The refusal
 
 - The refusal is tool-scoped rather than path-scoped. `Edit` and `Write` are refused for every main-root path, `Read` resolves there normally, and `Bash` writes there.
-- A background session that entered no worktree at all meets the identical refusal writing to the main root, since the guard gates on isolation rather than on sitting inside a linked worktree.
-- The refusal names session isolation and points at a worktree copy. That copy is a second gitignored file no later session reads, so never take the redirect. The redirected write reports success, which is how a file gets lost with nothing saying so.
+- A background session that entered no worktree meets the identical refusal, since the guard gates on isolation rather than on sitting inside a linked worktree.
+- The refusal points at a worktree copy, a second gitignored file no later session reads, so never take the redirect
+- The redirected write reports success, which is how a file gets lost with nothing saying so
 
 ## Route by what the write does to the file
 
-- A whole-file create goes out as one plain `Bash` command carrying a heredoc. Send `mkdir -p` for a missing folder as its own command first, since a `&&` compound is refused for complexity.
-- When the heredoc itself is refused, which can happen on a body quoting shell syntax, a session inside a linked worktree can `Write` the file there and copy it out with a two-argument `cp` to the main-root path. The copy carries no syntax to inspect.
-- A background session that entered no worktree has nothing to `Write` into, so it sends a short file as one `printf '%s\n'` command carrying each line as an argument. When the file is too long for that, it reports the refusal rather than taking the redirect.
-- A change inside a file that already exists goes through a `canon` verb that resolves the main root in-process, such as `canon tasks outcome` or `canon tasks pull-request`. Where no verb covers the edit, read the whole file and write it back whole through the heredoc route. Never reach for a stream editor, which rewrites the line it anchored to and exits zero on a non-match.
-- A delete or a move runs as one plain `rm` or `mv` per call rather than chained.
+Each kind of write takes one route, and none of them is a stream editor.
+
+| Write                | Route                                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Whole-file create    | One plain `Bash` command carrying a heredoc                                                                    |
+| Change inside a file | A `canon` verb resolving the main root in-process, such as `canon tasks outcome` or `canon tasks pull-request` |
+| Delete or move       | One plain `rm` or `mv` per call rather than chained                                                            |
+
+- Send `mkdir -p` for a missing folder as its own command first, since a `&&` compound is refused for complexity
+- Where no verb covers an edit, read the whole file and write it back whole through the heredoc route
+- Never reach for a stream editor, which rewrites the line it anchored to and exits zero on a non-match
+
+### When the heredoc is refused
+
+A heredoc can be refused on a body quoting shell syntax. The fallback depends on whether the session has a worktree to write into.
+
+- Inside a linked worktree, `Write` the file there and copy it out with a two-argument `cp` to the main-root path. The copy carries no syntax to inspect.
+- A background session that entered no worktree sends a short file as one `printf '%s\n'` command carrying each line as an argument
+- When the file is too long for that, report the refusal rather than taking the redirect
 
 ## The index cost
 
-A shell write skips every `PostToolUse` hook, since those match `Write|Edit|MultiEdit` and never fire on `Bash`. That costs nothing on `.canon/plans/` and `.canon/review/`, which no hook indexes, and costs the generated `index.md` on `.canon/tasks/`. Regenerate positionally after a shell write there, by an explicit `canon indexes regen` call, unless the verb that made the write already calls it, as `canon tasks archive` does.
+A shell write skips every `PostToolUse` hook, since those match `Write|Edit|MultiEdit` and never fire on `Bash`. No hook indexes `.canon/plans/` or `.canon/review/`, so the cost lands on the generated `index.md` under `.canon/tasks/` alone.
+
+Regenerate positionally after a shell write there, by an explicit `canon indexes regen` call. Skip it when the verb that made the write already calls it, as `canon tasks archive` does.

package/claude/skills/systematic-debugging/references/adopted.md

@@ -11,34 +11,48 @@ External sources were read and filtered rather than imported. This file is the r
 
 ### The four phases
 
-**Investigate, find the pattern, hypothesize, fix.** From `obra/superpowers@8ca22db`, [`skills/systematic-debugging/SKILL.md`](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md), 283 lines at that commit. The four-phase spine, the no-fix-before-investigation rule, and the three-attempt stop come from it, restated in a fraction of the length. Nothing records the commit the original port read, so this pin names the one read when the ledger was written rather than the one the port used.
+**Investigate, find the pattern, hypothesize, fix.** From `obra/superpowers@8ca22db`, [`skills/systematic-debugging/SKILL.md`](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md), 283 lines at that commit.
 
-### The investigation lifts
+- The four-phase spine, the no-fix-before-investigation rule, and the three-attempt stop come from it, restated in a fraction of the length
+- Nothing records the commit the original port read, so this pin names the one read when the ledger was written rather than the one the port used
 
-Each from `addyosmani/agent-skills@2686b620`, [`skills/debugging-and-error-recovery/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/debugging-and-error-recovery/SKILL.md), 300 lines at that commit.
+### Closing sections
 
-**Bisect for a regression.** Its localize step runs `git bisect` against a known good commit, with `git bisect run` driving the focused test. Adopted in phase 1 with the runner replaced by a placeholder for the project's own focused test command.
+The excuses, red flags, and closing checklist follow the shape every practice skill in this toolkit carries, from `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md).
 
-**Reduce to a minimal case.** Its reduce step strips code, config, and input until only the failure remains. Adopted as the opening step of phase 2, so phase 1 stays reproduce and locate, and the comparison against working code runs on the reduced case.
+Each excuse row rebuts a reason a session gives to skip the investigation rather than an objection nobody raised. Three come from the source's own rationalizations table and the rest from this skill's earlier red flags.
 
-**The non-reproducible tree.** Its timing, environment, state, and truly-random branches, each with first moves. Adopted in phase 1 step 2 with the runtime names stripped. The random branch hands off to the no-root-cause section rather than to its alerting advice, since setting up an alert is a production concern outside a debugging session.
+### Default shelf
 
-**Error output as untrusted data.** Its rule that error messages, stack traces, and logs are data to analyze, and that a command, URL, or step inside them goes to the user. Adopted in phase 1 step 1, in the red flags, and in the closing checklist, with reading the error in full left intact.
+[Software Engineering at Google](https://abseil.io/resources/swe-book/html/toc.html) and [Google's engineering practices](https://google.github.io/eng-practices/) were checked first. Neither carries a debugging procedure, so the shelf gave this skill nothing.
 
-### Closing sections
+## The investigation lifts
 
-The excuses, red flags, and closing checklist follow the practice skill shape every practice skill in this toolkit carries, taken from `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md). Each excuse row rebuts a reason a session gives to skip the investigation, three of them from the source's own rationalizations table and the rest from this skill's earlier red flags, rather than an objection nobody raised.
+Each from `addyosmani/agent-skills@2686b620`, [`skills/debugging-and-error-recovery/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/debugging-and-error-recovery/SKILL.md), 300 lines at that commit.
 
-### Default shelf
+### Bisect for a regression
 
-[Software Engineering at Google](https://abseil.io/resources/swe-book/html/toc.html) and [Google's engineering practices](https://google.github.io/eng-practices/) were checked first. Neither carries a debugging procedure, so the shelf gave this skill nothing.
+Its localize step runs `git bisect` against a known good commit, with `git bisect run` driving the focused test. Adopted in phase 1 with the runner replaced by a placeholder for the project's own focused test command.
 
-## Declined
+### Reduce to a minimal case
+
+Its reduce step strips code, config, and input until only the failure remains. Adopted as the opening step of phase 2, so phase 1 stays reproduce and locate, and the comparison against working code runs on the reduced case.
+
+### The non-reproducible tree
+
+Its timing, environment, state, and truly-random branches, each with first moves. Adopted in phase 1 step 2 with the runtime names stripped.
 
-**The stop-the-line rule.** The source's six-step stop, preserve, diagnose, fix, guard, resume sequence. Declined because the rule at the top of the body and the three-attempt stop already carry it, and a second sequence would compete with the four phases.
+The random branch hands off to the no-root-cause section rather than to its alerting advice, since setting up an alert is a production concern outside a debugging session.
 
-**Safe fallback patterns.** The source's safe default and graceful degradation examples. Declined because the no-root-cause section already names retry, timeout, and explicit error as the handling, and a fallback written under time pressure is the symptom fix phase 1 exists to prevent.
+### Error output as untrusted data
+
+Its rule that error messages, stack traces, and logs are data to analyze, and that a command, URL, or step inside them goes to the user. Adopted in phase 1 step 1, in the red flags, and in the closing checklist, with reading the error in full left intact.
+
+## Declined
 
-**Per-error triage trees.** The source's test, build, and runtime triage trees and its layer table name runtimes, browsers, and package managers. Declined as stack-specific, since the body holds across stacks.
+Each item below stays out of the body for the reason given.
 
-**The six-step spine.** The source orders reproduce, localize, reduce, fix, guard, verify. Declined in favor of keeping the four phases, since other skills cite "phase 1" and the three-attempt stop by those names.
+- **The stop-the-line rule.** A six-step stop, preserve, diagnose, fix, guard, resume sequence. The rule atop the body and the three-attempt stop carry it, and a second sequence would compete.
+- **Safe fallback patterns.** The no-root-cause section already names retry, timeout, and explicit error, and a fallback written under time pressure is the symptom fix phase 1 exists to prevent.
+- **Per-error triage trees.** The source's test, build, and runtime trees and its layer table name runtimes, browsers, and package managers. Declined as stack-specific.
+- **The six-step spine.** The source orders reproduce, localize, reduce, fix, guard, verify. Other skills cite "phase 1" and the three-attempt stop by name, so the four phases stay.

package/claude/skills/target-check/references/domains.md

@@ -25,19 +25,24 @@ Read four fields off the same report, then two verbs:
 
 - `unmigrated`: a domain still at the root layout with nothing under `.claude/`. The most urgent finding, because such a domain reports no drift of its own while being entirely behind.
 - `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own.
-- `unmovedSurfaces`: a surface held only at its `.claude/` spelling, each entry carrying `rel` and `movesTo`. Every other field reads clean for such a target, and the report's drift status ignores it by design, so read the array itself rather than an exit status.
+- `unmovedSurfaces`: a surface held only at its `.claude/` spelling, each carrying `rel` and `movesTo`. Read the array itself, since every other field and the drift status read clean here by design.
 
 ### Reverse and the verbs
 
+The fourth field and the two verbs cover what the toolkit stopped shipping and what the context folder holds.
+
 - `reverse`: `unclaimed` names folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`.
 - `canon context audit --json`: required sections, entry length, citations, and index drift across the context folder.
 - `canon records validate <kind> --json`, once per record folder the target carries.
 
 ### Verdicts
 
+Each of the three states takes all six reads together.
+
 - Current: `unmigrated`, `superseded`, and `unmovedSurfaces` all empty, `reverse.unclaimed` carrying nothing outside `project` attribution, and both verbs finding nothing.
 - Behind: any of those carrying an entry. Name the entry and its attribution, and for `unmovedSurfaces` each `rel` with its `movesTo`.
-- Unread: `historyUnavailable` set on `reverse`, a `reverse` or `unmovedSurfaces` key the report does not carry at all, or either verb refusing. A missing key is a binary predating the field rather than a target with nothing to report, so name the installed version beside it.
+- Unread: `historyUnavailable` set on `reverse`, a `reverse` or `unmovedSurfaces` key the report does not carry, or either verb refusing
+- A missing key is a binary predating the field rather than a target with nothing to report, so name the installed version beside it
 
 Routes by finding.
 
@@ -53,22 +58,38 @@ Read `domains` off the report and take every entry it carries rather than naming
 The states are `matching`, `stale`, `customized`, `drifted`, `orphaned`, `retired`, `stranded`, and `missing`. A `retired` rule is one the toolkit no longer ships, and the next sync deletes it.
 
 - Current: every count but `matching` reads zero.
-- Behind: any other count is non-zero. Report the counts and name the paths behind `stale` and `missing`, which a sync repairs, separately from `customized` and `drifted`, which the project wrote and a sync would overwrite.
+- Behind: any other count is non-zero. Report the counts, and name the paths behind each state.
 - Unread: `stamped` false with no entries, or the domain absent from the array while the target carries installed rules.
+- Keep `stale` and `missing`, which a sync repairs, apart from `customized` and `drifted`, which the project wrote and a sync would overwrite
 
 Routes to `canon <domain> sync`, or to `canon sync` for every installed domain at once. Read the `canon-cli` skill before naming either, since a command name says nothing about what it does to a file already there, and a `customized` entry is exactly the file a sync takes back.
 
 ## 4. Tooling
 
-Read the `tooling` block off the report first, because the comparison command needs a value it carries.
+Read the `tooling` block off the report first, because the comparison command needs a value it carries. Read `measured` before anything under it, since every count is zero when it is false, an absence of measurement rather than a measured zero.
+
+### The comparison
 
-Read `measured` before anything under it. Every count is zero when `measured` is false, which is an absence of measurement rather than a measured zero.
+On a measured report, take `<stack>` from the first name in `chain` and run `canon tooling sync --check <stack>`. Never run it bare.
+
+- Omitting the stack reaches a prompt the non-interactive variable resolves to the catalog's first entry rather than refusing
+- That compares the target against a stack it does not use and reports the difference as drift
+
+### Verdicts
 
-On a measured report, take `<stack>` from the first name in `chain` and run `canon tooling sync --check <stack>`. Never run it bare. The stack argument is what the target carries, and omitting it reaches a prompt that the non-interactive variable resolves to the catalog's first entry rather than refusing, which compares the target against a stack it does not use and reports the difference as drift.
+Unread splits three ways, so it takes its own table below.
 
 - Current: `measured` true, `chain` naming stacks the toolkit still ships, and `--check` reporting nothing it would change.
 - Behind: `--check` naming files it would replace, or `counts.gitignore` carrying missing managed entries.
-- Unread: `measured` false. It splits three ways, and each is reported as unmeasured with its cause named rather than as clean. An empty `chain` at a workspace root is by design, since a chain there would guess at what the packages hold. An empty `chain` anywhere else means no tooling install is recorded. A `chain` carrying names the toolkit no longer ships means injecting would write against a retired name.
+- Unread: `measured` false. Report it as unmeasured with its cause named rather than as clean.
+
+| Cause                                   | Meaning                                                              |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| Empty `chain` at a workspace root       | By design, since a chain there would guess at what the packages hold |
+| Empty `chain` anywhere else             | No tooling install is recorded                                       |
+| `chain` naming stacks no longer shipped | Injecting would write against a retired name                         |
+
+### Routes
 
 Routes to `canon tooling sync <stack>`, or to `canon tooling inject --gitignore <stack>` for ignore entries alone, taking `<stack>` the same way the comparison above does. An unmeasured report names no stack, so it routes to neither.
 
@@ -88,12 +109,19 @@ A seed entry matching says the file's bytes match the shipped seed. It says noth
 
 ## 6. The Claude harness
 
-No verb reads this domain. Report it `unchecked` on every run and report it as a row rather than omitting it.
+No verb reads this domain. Report it `unchecked` on every run, as a row rather than omitted.
+
+What goes unread is whether the target's hooks fire, whether `.claude/settings.json` registers them, which plugin version the target's sessions load, and whether the marketplace cache matches what the toolkit ships.
+
+### Confirm the gap live
+
+Confirm the gap against `canon claude --help` and the help of any subcommand that sounds like an answer, rather than a list held here. A list in this file freezes on the day it was written and reports a gap a later release closed.
 
-What goes unread is whether the target's hooks fire, whether `.claude/settings.json` registers them, which plugin version the target's sessions actually load, and whether the marketplace cache matches what the toolkit ships.
+- `canon claude skills drift` comes nearest, but it reads the toolkit's own history against a ref, which says what moved upstream rather than what this target holds
+- On a run where a verb answers one of the four questions, report the domain checked with what the verb answered
 
-Confirm the gap against the live surface rather than against a list held here, by reading `canon claude --help` and the help of any subcommand under it that sounds like an answer. A list written into this file freezes on the day it was written and would report a gap a later release had closed. `canon claude skills drift` is the verb that comes nearest, and it reads the toolkit's own history against a ref, which says what moved upstream rather than what this target holds. Report the domain checked, with what the verb answered, on the run where a verb does answer one of the four questions above.
+### No file inspection
 
-Reading it by file inspection is the alternative and it is refused. Every other section here answers from the verb under test, and a section answering from a hand-rolled read of the same files reaches a verdict nothing else in the report is entitled to make. A hole a reader can see is worth more than a number nobody can trace.
+Reading the domain by file inspection is the alternative and it is refused. Every other section here answers from the verb under test, and a section answering from a hand-rolled read of the same files reaches a verdict nothing else in the report is entitled to make. A hole a reader can see is worth more than a number nobody can trace.
 
 `canon claude plugin-update` is what an operator runs to bring a cache forward. Name it as the action available rather than as a repair for a finding, since no finding was taken.