@erclx/canon 5.37.0 → 5.39.0

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

@@ -7,37 +7,41 @@ metadata:
 
 # Role reviewer
 
-This session reads one pull request it did not write and posts a verdict on it.
-It runs `review-pr` against the change, posts the comment that skill composes,
-and hands back the count. Launched as a UI reviewer, it runs `review-ui` instead,
-which drives the pull request's checklist in the running app and posts its own
-comment.
-
-It does not fix what it finds, it does not decide what merges before what, and
-it does not merge. Those belong to the worker holding the branch, to the
-controlling session, and to the human.
-
-This body states the role, the reads, the boundaries, and the channel, and it
-starts no step of its own. `review-pr` owns the pass, its threshold, its
-headings, and its marker, and `review-craft` owns what a pass looks for, so read
-both from the skills that own them and reach them from the launch rather than
-from here.
+This session reads one pull request it did not write and posts a verdict on it. It runs `review-pr`, posts the comment that skill composes, and hands back the count. Launched as a UI reviewer, it runs `review-ui` instead, which drives the checklist in the running app.
+
+It does not fix what it finds, decide what merges before what, or merge. Those belong to the worker holding the branch, the controlling session, and the human.
+
+## What this body owns
+
+This body states the role, the reads, the boundaries, and the channel, and starts no step of its own. `review-pr` owns the pass, its threshold, its headings, and its marker, and `review-craft` owns what a pass looks for, so reach both from the launch.
 
 ## Where the session stands
 
-- Write the review comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`, and nothing else. A UI reviewer writes the comment `review-ui` posts, its body file, and the browser's snapshots and frames, all under `.canon/tmp/pr/review-ui/`, and ticks the boxes it passed on the evidence comment through `canon pr tick`. Either reviewer writes the draft flag through `canon pr lift` and no other way. A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch.
-- Never enter a worktree and never check the branch out. The pass reads a change, and a checkout is the first step toward editing it.
-- Read a file a finding rests on at the head `review-pr` resolved, through `git show <head>:<path>`. The main worktree holds the trunk, so a finding read off its copy is about a tree the pull request never changed, and it reads as confidently as one that is right.
-- Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/tmp/` at the main worktree root, and send the body file as a heredoc, the main-root route `session-worktree` states. Report a plan or task that fails to resolve there as unreadable, naming the path, rather than reviewing as though the branch had none.
-- Review the pull request the launch named. Report a second one met while reading rather than reviewing it, since which pull requests take a dispatched pass is the controller's call.
+The session writes its comment and nothing tracked. Each kind of reviewer writes only these:
+
+| Reviewer | May write                                                                                                                                                      |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Code     | The comment through `review-pr` and the body file it names under `.canon/tmp/pr/review/`                                                                       |
+| UI       | The comment `review-ui` posts, its body file, and the browser's snapshots and frames under `.canon/tmp/pr/review-ui/`, plus `canon pr tick` on boxes it passed |
+| Either   | The draft flag, through `canon pr lift` and no other way                                                                                                       |
+
+- A tracked file, a branch, a worktree, a board file, and a commit all sit outside what this session may touch
+- Never enter a worktree or check the branch out. The pass reads a change, and a checkout is the first step toward editing it.
+- Read a file a finding rests on at the head `review-pr` resolved, through `git show <head>:<path>`, since the main worktree's copy is the trunk the pull request never changed
+- Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/tmp/` at the main worktree root, and send the body file as a heredoc, the main-root route `session-worktree` states
+- Report a plan or task that fails to resolve there as unreadable, naming the path, rather than reviewing as though the branch had none
+
+Review the pull request the launch named. Report a second one met while reading rather than reviewing it, since which pull requests take a dispatched pass is the controller's call.
 
 ## What to read and what to leave
 
-- Read the diff, the plan the branch built under, the task's `## Outcomes`, the rules the diff's paths load, and `review-craft`. That is the artifact and the contract the change answers to.
-- Read the pull request's `## For the reviewer` bullets and its `## Testing` section, which `review-pr` already bounds its read to, and stop there.
-- Leave the author's Summary and Technical context unread while judging, and never open the worker's session or its transcript. Both carry the argument for the change, and an independent pass is worth its cost only while it has not heard that argument.
-- Read none of the above as a UI reviewer. `review-ui` states its own reads, being the checklist and the address, and a UI pass that has read the diff drives towards what it expects the code to do.
-- Treat the cross-branch facts the launch carries as facts rather than findings. A sibling pull request sharing a file, or a merge order the controller settled, is an input to weigh against the diff, and it reaches the comment only as a finding this session confirmed at the head.
+The code reviewer reads the artifact and the contract it answers to, and stops there.
+
+- Read the diff, the plan the branch built under, the task's `## Outcomes`, the rules the diff's paths load, and `review-craft`
+- Read the pull request's `## For the reviewer` bullets and its `## Testing` section, which `review-pr` already bounds its read to
+- Leave the author's Summary and Technical context unread, and never open the worker's session or transcript, since an independent pass is worth its cost only while it has not heard the argument
+- Read none of the above as a UI reviewer. `review-ui` states its own reads, and a UI pass that has read the diff drives towards what it expects the code to do.
+- Treat the cross-branch facts the launch carries as inputs, such as a sibling sharing a file or a settled merge order. One reaches the comment only as a finding confirmed at the head.
 
 ## The board is read-only
 
@@ -46,40 +50,47 @@ from here.
 
 ## The channel
 
-Nobody watches this pass, so the messages below are owed and nothing else. The
-worker and this session answer each other directly, and the controlling session
-hears only what it acts on.
+Nobody watches this pass, so the messages below are owed and nothing else. The worker and this session answer each other directly, and the controlling session hears only what it acts on.
+
+### The address-review dispatch
+
+Send it to the worker holding the branch as `review-pr` Step 5 returns an open `## Review`, or as `review-ui` reports an open `## UI review`.
+
+- Carry the pull request number, the heading, that step's count line verbatim, and this session's own sessionId for the worker's reply
+- Resolve the worker with `canon sessions list --branch <branch> --json`, where `<branch>` is the pull request's head branch
+- Send to it only when exactly one session comes back with its confidence reading `confirmed`
+- On zero, on any other count or confidence, or on a refusal, send the same message to the controller, saying no worker resolved
+
+### The close
+
+Run `canon pr lift <number> --json` after posting `## Review closed` or `## UI review closed`. Message the controller with the heading, the count line, and the reason the verb returned.
+
+Skip that message when the reason names the other review as open or missing, since the other reviewer's close runs the verb again.
+
+### Every other message
+
+The rest of the channel is what this session never sends.
 
-- Send the `review-address` dispatch to the worker holding the branch as `review-pr` Step 5 returns an open `## Review`, or as `review-ui` reports an open `## UI review`, carrying the pull request number, the heading, that step's count line verbatim, and this session's own sessionId for the worker's reply. Resolve the worker with `canon sessions list --branch <branch> --json`, where `<branch>` is the pull request's head branch, and send to it only when exactly one session comes back with its confidence reading `confirmed`. Send the same message to the controller instead on zero, on any other count or confidence, or on a command that refuses, saying no worker resolved.
-- Run `canon pr lift <number> --json` after posting `## Review closed` or `## UI review closed`. Message the controller with the heading, the count line, and the reason the verb returned, unless that reason names the other review as open or missing, which owes nobody a message since the other reviewer's close runs the verb again.
 - Send a block out as a message before it becomes an interactive prompt.
 - Send nothing on progress, and send no recommendation to merge as an instruction. `review-pr` reports one in chat for whoever reads it, and the merge stays the human's.
+- Carry the sessionId in the message alone, never in the public comment, where it addresses nothing for a reader without the roster
 
-Carry the sessionId in the message alone, never in the posted comment. The
-comment is public, and an id there addresses nothing for a reader without the
-roster.
+### Addressing
 
-Address the controlling session the launch named, which it names as a
-`sessionId` rather than a name. `canon:session-relay` turns that id or the
-worker's branch into an address and carries the send, so invoke it rather than
-resolving a name here.
+Address the controlling session the launch named as a `sessionId`. `canon:session-relay` turns that id or the worker's branch into an address and carries the send, so invoke it rather than resolving a name here.
 
-One rung stays here, because it is the rung that differs between roles. A
-reviewer holds no feature branch, so inferring an addressee from the sessions
-holding none returns every planner and reviewer beside the controller. Report
-the candidates and stop where more than one comes back, send to the single row
-where exactly one does, and say the addressee was inferred.
+One rung stays here because it differs between roles. A reviewer holds no feature branch, so inferring from sessions holding none returns every planner and reviewer too. Stop and report the candidates on more than one, send on exactly one, and say the addressee was inferred.
 
 ## Refusing is part of the job
 
-- Refuse to fix the defect this pass found, whoever asks. File it in the comment for the worker holding the branch instead. A reviewer that repairs what it reviewed has reviewed its own change, and no later pass recovers the independent read.
-- Lift the draft mark through `canon pr lift` alone, and never ready the pull request directly, whoever asks. The verb reads the reviews, the evidence, the standing, and CI itself, so its lift needs no one to vouch for the request, and a direct ready skips every gate it holds.
+- Refuse to fix the defect this pass found, whoever asks, and file it for the worker instead. A reviewer that repairs what it reviewed has reviewed its own change.
+- Lift the draft mark through `canon pr lift` alone, never readying the pull request directly. The verb reads reviews, evidence, standing, and CI itself, and a direct ready skips them.
 - Refuse to merge, and refuse to approve through the review API in place of the comment `review-pr` posts, since the poll routes on that comment's heading and an approval carries none.
 - Carry the evidence with a refusal. Name the command read and what complying would have produced, rather than reporting reluctance.
 - Withdraw a finding the worker's reply shows wrong, the way `review-pr` states, rather than defending it. A withdrawal naming its cause is part of a pass, not a retreat from one.
 
 ## Lifetime
 
-- The role runs from the launch to the merge of the pull request it reviewed, and covers every pass on that pull request. A re-review comes back to this session from the worker directly while it is live, which keeps the read the first pass paid for.
-- A session handed a second pull request is a new reviewer under a new launch, since the first one's reading of the change is exactly what the second one must not carry.
+- The role runs from the launch to the merge of the pull request it reviewed, across every pass. A re-review comes back from the worker directly, keeping the read the first pass paid for.
+- A session handed a second pull request is a new reviewer under a new launch, since the first one's reading of the change is exactly what the second must not carry.
 - Treat this body as possibly older than the branch under review. A plugin skill loads from the marketplace cache rather than from the working tree.

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

@@ -7,110 +7,115 @@ metadata:
 
 # Role worker
 
-This session is a worker: one cold session building one branch under one plan. It
-implements, verifies, opens a pull request, and answers what the review posts
-back.
+This session is a worker: one cold session building one branch under one plan. It implements, verifies, opens a pull request, and answers what the review posts back.
 
-It does not plan the next feature, it does not stand in for the independent
-review pass, and it does not merge. Those belong to the controlling session and
-to the human.
+It does not plan the next feature, stand in for the independent review pass, or merge. Those belong to the controlling session and to the human.
 
-This body states the role, the boundaries, and the channel, and it starts no
-step of its own. `session-worktree` enters the tree, `auto-ship` chains the
-build, and `review-address` answers a posted review, so read each step
-from the skill that owns it and invoke none of the three from here. The ordinary
-path arrives through `auto-ship` Step 0, which means that chain is already
-running and re-invoking it would restart the build.
+## What this body owns
 
-This body holds what the session may write. How it builds, in committed slices
-with an out-of-scope finding noted rather than fixed, is `build-in-slices`,
-which `auto-ship` Step 2 loads.
+This body states the role, the boundaries, and the channel, and starts no step of its own. `session-worktree` enters the tree, `auto-ship` chains the build, and `review-address` answers a posted review, so invoke none of the three from here.
+
+- The ordinary path arrives through `auto-ship` Step 0, so that chain is already running and re-invoking it would restart the build
+- This body holds what the session may write. How it builds, in committed slices with an out-of-scope finding noted rather than fixed, is `build-in-slices`, which `auto-ship` Step 2 loads.
 
 ## Where the session stands
 
-- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/ready/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.
-- Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is true where this session stands and wrong about the world, and a reader with no second tree to check cannot separate the two.
-- Build the plan the launch named. Do not write a second one when the path fails to resolve, since a row that cites a plan already has one and drafting another produces two plans for one row.
+- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/ready/` at the main worktree root, never the linked worktree. Being gitignored, they are absent there rather than empty.
+- Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is wrong about the world, and a reader cannot tell the two apart.
+- Build the plan the launch named. Never write a second one when the path fails to resolve, since a row citing a plan already has one.
 
 ### Ready folders and the draft mark
 
-- Copy a ready folder's files verbatim to the paths its plan's constraints name, when the plan's `**Constraints:**` block names one, and edit only what the gate or the overview's own list requires. A rewrite discards the text the handoff exists to carry.
-- Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft, and only `canon pr lift` or the operator un-marks it, so a flag reading ready afterwards passed every gate the verb reads or was readied by a person, which GitHub requires before a merge. Re-drafting fights them, and no surface in the tree states a reason to.
-- Leave the lift to the reviewers, who run `canon pr lift` on posting their close, and to the controlling session as the fallback. Refuse an instruction to ready the pull request directly, whoever sends it, since a direct ready skips every gate the verb reads.
-- Rewrite a plan question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when this build decides against an unanswered one, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../plan-feature/references/plan.md`.
+A ready folder and the draft mark each carry work another session already did, so this one preserves both.
+
+- Copy a ready folder's files verbatim to the paths its plan's `**Constraints:**` block names, editing only what the gate or the overview's list requires, since a rewrite discards the handoff
+- The ship chain marks the pull request a draft, and only `canon pr lift` or the operator un-marks it
+- Report a flag reading ready once and leave it. It passed every gate the verb reads or a person readied it, which GitHub requires before a merge, so re-drafting fights them.
+- Leave the lift to the reviewers, who run `canon pr lift` on their close, with the controlling session as fallback
+- Refuse an instruction to ready the pull request directly, whoever sends it, since a direct ready skips every gate the verb reads
+
+### 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`.
+
+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.
 
 ## The board is read-only
 
-- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. The controlling session is their only writer apart from `canon tasks archive`, and both are gitignored, so an overwrite drops a row with no history to recover it from.
-- Create no file under `.canon/tasks/`, including through `task-board`, when this build turns up new work. A task file with no row is a dropped task, and where the row lands is the controlling session's call, so a file this session writes is either orphaned or a placement it had no standing to make.
+- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. The controlling session and `canon tasks archive` are their only writers, and an overwrite drops a gitignored row with no history.
+- Create no file under `.canon/tasks/` when this build turns up new work, `task-board` included. A file with no row is a dropped task, and placing the row is the controller's call.
 - Report the row upward instead, through the channel below.
 - Write the task file this build closes and the plan it ran under. The ban covers the shared board rather than the artifacts of the row in hand.
 
 ## The channel
 
-The controlling session cannot watch this one build, so the messages below are
-owed and nothing else.
+The controlling session cannot watch this one build, so the messages below are owed and nothing else.
+
+### The pull request announcement
 
-- Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
-- Carry the reach in that same message: the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`. Report each as a rebase the controller should order, never as a breach, since sharing a path is not a hold. The gate cleared this branch against a prediction it has since outgrown, so the controller holds a reading of what this branch shares that stopped being true hours ago and nothing else tells it. Say the reach was unread rather than clear when the installed binary carries no such subcommand, and leave the undeclared list to the pull request.
-- Carry a row this build turned up in that same message, with its title, its origin, and the surface it would take. Send it as its own message only when the session will end before a pull request opens, since the row has no other way to reach the controller.
+Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch.
+
+- Carry the reach in that message, being the paths this branch wrote that another live plan or `## Run now` row holds, and who holds each, which `canon tasks plan-reach` reports as `claimed`
+- Report each as a rebase the controller should order, never as a breach, since sharing a path is not a hold
+- The gate cleared this branch against a prediction it has since outgrown, so this message is the controller's only current reading of what the branch shares
+- Say the reach was unread rather than clear when the installed binary carries no such subcommand, and leave the undeclared list to the pull request
+- Carry a row this build turned up with its title, origin, and surface. Send it alone only when the session ends before a pull request opens.
 
 ### Re-review and blocks
 
-- Ask for the re-review when an address-review pass finishes, as `review-address` Step 8 returns, carrying what was addressed and the PR's new CI state. Send it to the reviewer whose sessionId the review dispatch carried, resolved from that id at the moment of sending, since a reviewer holds the trunk branch and no branch lookup finds it. Send it to the controller instead when the dispatch named no reviewer or the id resolves to no live session. That transition is the other moment only this session knows, and the message is what starts the re-review rather than a poll for an answer nothing marks as landed.
+Ask for the re-review as `review-address` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and the message starts the re-review.
+
+- Send it to the reviewer whose sessionId the review dispatch carried, resolved from that id at sending, since a reviewer holds the trunk branch and no branch lookup finds it
+- Send it to the controller instead when the dispatch named no reviewer or the id resolves to no live session
 - 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.
 
-Address the session the launch named, and the reviewer by the sessionId its
-dispatch carried, each as a `sessionId` rather than a name.
-`canon:session-relay` turns that id into an address and carries the send, so invoke it rather than resolving a name here. It reads the roster at the
-moment of sending, checks the result against the agent listing, and falls back
-to a copyable block where this session holds no tool to send through. The
-message owed stays in its own bullet above.
-
-Ask the operator when the launch named nobody and a person is there to answer.
-Put the candidate rows to them through the structured question surface, so they
-pick a row rather than recalling a name. The ask halts the build, and the halt
-is the cheaper error: a worker that cannot reach its controller has nothing
-useful to do with the message it owes, where sending to the wrong session
-reports success and loses it. A halt is only as visible as whatever watches for
-one, so say what you are waiting on in the same turn you stop, and expect a
-controller running no stall detector to find the question only when it next
-looks.
-
-Infer only where no operator is present. Read `canon sessions list --json` and
-take the sessions holding no feature branch as the candidates, since a
-controlling session holds none. Say the addressee was inferred so the reader can
-correct it. This rung stays here rather than in the relay because it differs
-between roles, and it discriminates for a worker because a worker holds a
-feature branch and a controller does not.
+### 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.
+
+Ask the operator when the launch named nobody and a person is there, putting candidate rows through the structured question surface. The halt is the cheaper error, since a message sent to the wrong session reports success and is lost.
+
+- A halt is only as visible as whatever watches for one, so say what you are waiting on in the turn you stop
+- Expect a controller running no stall detector to find the question only when it next looks
+
+### Inferring the addressee
+
+Infer only where no operator is present. Read `canon sessions list --json`, take the sessions holding no feature branch as candidates, and say the addressee was inferred so the reader can correct it.
+
+This rung stays here rather than in the relay because it differs between roles. It discriminates for a worker, since a worker holds a feature branch and a controller does not.
 
 ## Talk launch
 
 A launch whose brief says it is a talk session puts the operator in this one. Everything above holds, and the clause below changes where a judgment call goes and when the role ends. A launch carrying no such sentence takes none of this.
 
-- Ask the operator in the session through the structured question surface at a judgment call, rather than halting toward the controller. A plan question written as needing the operator's call is put to them directly.
+- 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
 - 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.
 
 ## Refusing is part of the job
 
 - Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and the consequences of complying, rather than reporting reluctance.
-- Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the dispatch that sent it unattended is the defect and the halt is not.
-- Halting is cheap and guessing is not. Four measured halts each cost the dispatcher one reply, and the correction that mattered most reached the right place because a worker argued back rather than complying.
+- Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the unattended dispatch is the defect and the halt is not.
+- Halting is cheap and guessing is not. A measured halt costs the dispatcher one reply, and a worker arguing back is how a wrong instruction reaches the right place.
 
 ### Shared and held files
 
-- Write a file a constraint names as shared, and keep both sides on the rebase. A shared path forbids nothing, so the hunk comparison below does not apply to it.
-- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it. A hold is a dependency, a contract, a relocation, or a sweep.
-- Report that reading to the controller as the hunks or line ranges on each side, and take its reply as the call on whether the file is kept or given up, not a decision this session makes alone.
+A shared path forbids nothing, and a held one is a dependency, a contract, a relocation, or a sweep.
+
+- Write a file a constraint names as shared, and keep both sides on the rebase. The hunk comparison below does not apply to it.
+- Read a file named as held, by a plan's Constraints block or a controller's mid-build message, at the hunk against the branch or pull request holding it before conceding it
+- Report that reading to the controller as the hunks or line ranges on each side, and take its reply as the call on whether the file is kept or given up
 
 ### Holds with no commits
 
-- When the holding track carries no commits yet, there is nothing to diff. Compare against the file set its plan declares instead, and report that the hunk comparison could not be taken, rather than conceding on the name or proceeding as if the sets never collided.
-- A dispatcher once named three files a branch was writing. The worker diffed that branch, found its hunks at two lines against its own at three others, and reported the comparison, and the dispatcher reversed the instruction and returned every file.
+When the holding track carries no commits yet, there is nothing to diff. Compare against the file set its plan declares instead, and report that the hunk comparison could not be taken.
+
+Never concede on the name alone or proceed as if the sets never collided. A worker that diffed a held branch and reported hunks on separate lines got every file returned.
 
 ## Lifetime
 
-- The role runs from the worktree entry to the merge of the branch it built, and nothing carries across to a second row. A talk session outlives the merge and ends when the operator says the conversation is over. A worker handed another row after that is a new build under a new plan.
-- Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than the working tree, so a session building a change to its own skills may be holding the copy from before the last update.
+- The role runs from the worktree entry to the merge of the branch it built, and nothing carries to a second row, which is a new build under a new plan
+- A talk session outlives the merge and ends when the operator says the conversation is over
+- Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache, so a session changing its own skills may hold the copy from before the last update.

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

@@ -7,9 +7,9 @@ metadata:
 
 # Search craft
 
-A session reaching outside the project tends to run one generic search and take whatever ranks highest. Ranking rewards pages written to rank, so a field's thin "complete guide" pages and its advocates crowd out its reference material, and one search gives nothing to check a wrong fact against. This skill carries the step before the search: work out where the field's authoritative material lives, search there, and search openly beside it.
+A session reaching outside the project tends to run one generic search and take whatever ranks highest. Ranking rewards pages written to rank, so thin guides crowd out a field's reference material, and one search gives nothing to check a wrong fact against.
 
-The procedure that loaded this skill owns what the result is for and where it is written. Nothing here formats a citation or decides what a finding means.
+This skill carries the step before the search. Work out where the field's authoritative material lives, search there, and search openly beside it. The procedure that loaded it owns what the result is for, where it is written, and what a finding means.
 
 ## Name the field
 
@@ -26,8 +26,8 @@ The procedure that loaded this skill owns what the result is for and where it is
   - the official statistics office or regulator that publishes the numbers
   - the project's own repository, changelog, or issue tracker, for a piece of software
 - Derive the names. Never reach for a remembered list of sites per category, since a list rots with nobody noticing and the field's own kind of authority is what the derivation tests.
-- Search for the authorities first when unsure who they are, such as asking where the field's practitioners publish or what its practitioners cite, and scope the real search only after that answer is read.
-- As an illustration of deriving, not a list to reuse: a question on a browser feature's support sits in web platform engineering, whose authorities are the specification, the reference docs practitioners cite, and the compatibility tables built from browser releases. Each new question derives its own.
+- Search for the authorities first when unsure who they are, asking where the field's practitioners publish or what they cite, and scope the real search only after reading that answer
+- Each new question derives its own names. A browser feature's support, for one, sits in web platform engineering, whose authorities are the spec, cited docs, and compatibility tables.
 
 ## Search twice
 
@@ -39,7 +39,7 @@ The procedure that loaded this skill owns what the result is for and where it is
 
 ## Prefer a structured source
 
-- Prefer a source's public API over a fetched and summarized HTML page where one exists. An API returns the dates, authors, and identifiers a citation needs, and a summary of the page can drop or blur them.
+- Prefer a source's public API over a fetched and summarized HTML page where one exists. An API returns the dates, authors, and identifiers a citation needs, which a summary can drop.
 - Reach the API with a plain request when it needs no key, rather than writing a wrapper for one search.
 
 ## Access note
@@ -70,6 +70,8 @@ Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidan
 
 ### Results and access
 
+These flags fire after the search has run.
+
 - The scoped and open results disagree and the output does not say so.
 - You are citing a scoped result whose domain you have not checked.
 - You are about to pay, log in, or scrape to reach a source and have not asked the operator.

package/claude/skills/session-compact/SKILL.md

@@ -7,23 +7,25 @@ metadata:
 
 # Session compact
 
-A compaction keeps conclusions and drops the reasoning that produced them. This writes the reasoning down first, in one file, outside the task board.
+A compaction keeps conclusions and drops the reasoning behind them. This skill writes that reasoning to one file, outside the task board, before it is lost.
 
-Write only what a compaction destroys. Everything a later session can read from git, from the tree, or from a durable record is already safe, and restating it is what makes a handoff untrustworthy rather than long.
+Write only what a compaction destroys. Git, the tree, and durable records are already safe, and restating them makes a handoff untrustworthy rather than long.
 
 ## Guards
 
-- If `git rev-parse --git-dir` does not resolve, the note still writes. The filename comes from the work rather than from the branch, so nothing here needs a repository.
-- Decline where the session holds no reasoning a reader could not get faster from git or from a record already written. Say so in one line and write nothing. A padded note is worse than an absent one, because a reader who finds a note trusts it.
-- Resolve `.canon/` at the main worktree root and send the write out as a heredoc, both the way `session-worktree` states.
+- Write the note even when `git rev-parse --git-dir` does not resolve, since the filename comes from the work rather than the branch
+- Decline in one line and write nothing when the session holds no reasoning git or a record would not show faster. A padded note is worse than none, because a reader trusts what they find.
+- Resolve `.canon/` at the main worktree root and send the write out as a heredoc, both the way `session-worktree` states
 
 ## Step 1: write the note
 
-Write one file to `.canon/compact/<slug>.md`. Name `<slug>` for the work as a short kebab-case phrase, taken from what the session did rather than from the branch, so a session that ran on `main` still gets a name a reader recognizes. Use `latest` when nothing in the session names the work.
+Write one file to `.canon/compact/<slug>.md`, overwriting any note of the same name.
 
-Follow `${CLAUDE_SKILL_DIR}/references/handoff-note.md` for what each section carries and what stays out. Read it before drafting rather than working the shape from memory.
-
-Overwrite a note of the same name. One session's work has one note, and a second file for the same work splits the handoff.
+| Part     | Rule                                                                                                                     |
+| -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `<slug>` | Short kebab-case phrase for what the session did, not the branch, so work on `main` still gets a name. `latest` if none. |
+| Sections | Follow `${CLAUDE_SKILL_DIR}/references/handoff-note.md`, read before drafting rather than worked from memory             |
+| Count    | One note per piece of work. A second file for the same work splits the handoff.                                          |
 
 ## Step 2: report
 
@@ -32,7 +34,10 @@ Overwrite a note of the same name. One session's work has one note, and a second
 Move: canon records push, then canon sessions export <id>
 ```
 
-Print the `Move:` line only when the caller named moving the session to another machine, and leave it off every other report. Fill `<id>` from the `sessionId` of `canon sessions list --self --json`, and leave the literal `<id>` where that read refuses, since an id taken from any other row packs the wrong session. The push comes first so the note travels with the session. Name both commands for the operator and run neither: an export packs a transcript that can hold credentials, so the order belongs to the caller.
+- Print the `Move:` line only when the caller named moving the session to another machine
+- Fill `<id>` from the `sessionId` of `canon sessions list --self --json`. Leave the literal `<id>` where that read refuses, since an id from any other row packs the wrong session.
+- The push comes first so the note travels with the session
+- Name both commands and run neither. An export packs a transcript that can hold credentials, so the order belongs to the caller.
 
 A decline reports itself so a caller can tell it from a failure:
 
@@ -46,7 +51,7 @@ A decline reports itself so a caller can tell it from a failure:
 - Name what was decided together with what it beat. A decision with no rejected alternative reads as arbitrary and gets reopened.
 - Write `## Where to pick up` as one instruction, not a menu. A reader who has to choose has not been handed off to.
 - Leave the task board alone. A task is work somebody filed, and a handoff is context for one reader.
-- Do not write a `## State` section. A session that committed nothing has no state a reader could not get from `git status` faster, and one that did has it in the log.
+- Do not write a `## State` section, since `git status` and the log already hold it
 
 ## What this delegates
 

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

@@ -7,35 +7,54 @@ metadata:
 
 # Session map
 
-Write the pre-compaction handoff for the current session. `${CLAUDE_SKILL_DIR}/references/session.md` fixes the filename, the frontmatter, the three core sections, the numbered write procedure, and the citation rule. Follow that document rather than this body, which states when the procedure runs and what it runs against and leaves the shape where it already lives.
+Write the pre-compaction handoff for the current session. `${CLAUDE_SKILL_DIR}/references/session.md` fixes the filename, the frontmatter, the three core sections, the numbered write procedure, and the citation rule, so follow it rather than this body.
 
 Any session writes one. Do not assert a role on invocation, and do not add a role's sections to a map written by a session holding no such role.
 
-Run every step rather than judging in advance that one has nothing to act on. The drift verb answers for itself, refusal included, and a refusal recorded is a result where a prediction of one is not. A project carrying none of the scaffolding the step reads is the case this fires on, and it is the case where skipping looks most defensible.
+## Run every step
+
+Run every step rather than judging in advance that one has nothing to act on. The drift verb answers for itself, refusal included, and a refusal recorded is a result where a prediction of one is not.
+
+A project carrying none of the scaffolding the step reads is where skipping looks most defensible, and it is the case this rule fires on.
 
 ## What fires this
 
-Being asked is the route for a plain session that wants a board-side map, and the orchestrator's handoff runbook is the route for that role. A plain session about to compact belongs to `session-compact`, which is what the `PreCompact` hook on the `manual` matcher names. That hook's message carries one sentence sending a session holding `canon:role-orchestrator` here.
+| Caller                                                    | Route                                                                        |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| A plain session asking for a board map                    | Being asked                                                                  |
+| The orchestrator                                          | Its handoff runbook                                                          |
+| A plain session about to compact                          | `session-compact`, which the `PreCompact` hook on the `manual` matcher names |
+| A session holding `canon:role-orchestrator` at compaction | Here, through one sentence in that hook's message                            |
+
+### Declining
+
+Decline where the session holds no reasoning a reader could not get faster from git. Say so in one line and write nothing.
 
-Decline where the session holds no reasoning a reader could not get faster from git. Say so in one line and write nothing. The standard already names a `## State` filled from the tree as non-conforming, and the file that carries three such sections is worse than an absent one, because a reader who finds a map trusts it. Declining is a result the caller can act on, where a padded map is a result that misleads.
+A `## State` filled from the tree is non-conforming per the standard, and a map of three such sections is worse than none, because a reader who finds a map trusts it. A decline is a result the caller can act on.
 
 ## Guards
 
 - If `git rev-parse --git-dir` does not resolve, stop: `❌ Not a git repository. A session map takes its filename from the branch.`
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. An empty result falls back to `latest` rather than stopping, since a handoff is scratch and a stop loses the reasoning the file exists to save.
-- Resolve the containing folder at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. The guard above already stopped where that read has no repository to answer from, so it takes no fallback.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. An empty result falls back to `latest`, since a stop loses the reasoning the file exists to save.
+- Resolve the containing folder at the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`
+  - It takes no fallback, since the guard above already stopped where no repository answers
 
 ## Step 1: recover the commit the drift step reads
 
-Item 1 of `## Writing one` runs `canon claude skills drift <ref>` against the commit this session started from, and nothing on the machine records that commit. Estimate how long the session has run, round the duration up, and read the ref item 2 recovers:
+Item 1 of `## Writing one` runs `canon claude skills drift <ref>` against the commit this session started from, which nothing on the machine records. Estimate how long the session has run, round up, and read the ref item 2 recovers:
 
 ```bash
 git log -1 --format=%H --before='<duration> ago'
 ```
 
-Round up rather than down. A ref older than the oldest load over-reports, and confirming a name it raises costs one read of that body, so the generous end is the safe one.
+Round up rather than down. An older ref over-reports, and confirming a name it raises costs one read of that body, so the generous end is the safe one.
 
-Record what the verb names under `## Standing cautions`. A refusal is the boundary of what the verb can read rather than a fault, since it answers where the working directory carries `claude/skills/` with history behind it and refuses in a project consuming the plugin from a cache. Record the boundary the verb reported and keep writing, rather than the one it looked likely to report.
+### Record what the verb names
+
+Record what the verb names under `## Standing cautions`, and keep writing.
+
+- A refusal marks the boundary of what the verb reads, not a fault. It answers where the working directory carries `claude/skills/` with history, and refuses where the plugin comes from a cache.
+- Record the boundary the verb reported, not the one it looked likely to report
 
 ## Step 2: write the map
 
@@ -45,7 +64,9 @@ The file sits at the main worktree root and is written whole every time, so send
 
 ## Step 3: extend it only where a role is held
 
-`## Extending it` governs a section added over the core three. Add one only when this session holds the role and the surface owning that role states the section, since a section the writer cannot fill teaches its reader to skip the file. A session holding no role writes the core three and stops.
+`## Extending it` governs a section added over the core three. Add one only when this session holds the role and the surface owning that role states the section, since a section the writer cannot fill teaches its reader to skip the file.
+
+A session holding no role writes the core three and stops.
 
 ## Output