@erclx/canon 5.40.0 → 5.42.0

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

@@ -42,6 +42,8 @@ Does not govern:
 
 ### What to leave out
 
+A body describes the new behavior and nothing the diff or the commits already say.
+
 - Do not describe historical behavior or unchanged code. Describe new behavior only.
 - Do not include future promises or speculative documentation
 - Do not explain obvious changes (formatting, renaming variables)
@@ -54,38 +56,49 @@ Does not govern:
 
 ### Context section
 
-- `## Technical context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+`## Technical context` is optional and carries 1-2 lines of architectural reasoning explaining why, not what.
+
 - Omit Technical context for docs, config, or trivial changes
 - Use bullet points for multiple reasons, one sentence for a single reason
 
 ### Testing section
 
-- `## Testing` (optional): specify exact commands or test cases run
+`## Testing` is optional and names the exact commands or test cases run.
+
 - Omit Testing for docs, config, or trivial sync changes
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
 
 ### Reviewer section and visuals
 
-- `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
+`## For the reviewer` is optional and lists what the reviewing session should confirm, one bullet per request.
+
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
-- The list is closed. A body carries the sections above and nothing after the last of them, which covers a trailer a harness appends once the body is composed. `canon labels scan` holds the list: it fails a level-two heading outside the five above, and a body missing `## Summary` or `## Key changes`. A review body and a release-please body are exempt.
+- The list is closed, so a body carries nothing after its last section, including a trailer a harness appends once the body is composed
+- `canon labels scan` fails a level-two heading outside the five above, and a body missing `## Summary` or `## Key changes`
+- A review body and a release-please body are exempt
 
 ## Testing discipline
 
 - Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
 - Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
 - Quote the count or output the run reported, never a figure carried from elsewhere.
-- A ticked box describes the tree as it stands, not as it stood when it was written. A later commit that removes or replaces what it names makes the box false, and the branch that made that commit corrects it in the same pass, the same as any other stale claim in the body.
+- A ticked box describes the tree as it stands. A later commit removing or replacing what it names makes the box false.
+- The branch that made that commit corrects the box in the same pass, as with any other stale claim in the body
 
 ### Human-only boxes
 
-- Leave a box unchecked only when a human is required, and name which human and why on the same line.
-- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
-- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
-- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
+Leave a box unchecked only when a human is required, and name which human and why on the same line. The agent runs everything else.
+
+- Human-only covers visual or aesthetic judgment, credentials or a live third-party service, and a second machine or a fresh OS
+- It also covers judgment about whether a boundary or an abstraction reads correctly
+- A human is required by a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not.
+- An arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned
+- A tool refusal that actually fired is a capability gap, and the line names the refusal rather than the cost. A refusal predicted and never met is not one.
 
 ### Live sessions and reviewer requests
 
+A live agent session is never the human a box waits on.
+
 - A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
 - Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
 
@@ -97,6 +110,8 @@ Does not govern:
 
 ### Template
 
+Every section a body may carry, in order.
+
 ```markdown
 ## Summary
 
@@ -124,6 +139,8 @@ Does not govern:
 
 ### Correct
 
+Each line's comment names the rule it follows.
+
 ```markdown
 ## Summary
 
@@ -151,6 +168,8 @@ Update auth middleware to enforce jwt expiration checks. # imperative + direct o
 
 ### Incorrect
 
+Each line's comment names the rule it breaks.
+
 ```markdown
 ## Summary
 

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

@@ -7,7 +7,7 @@ description: Scan an author runs against finished text, the cross-reference form
 
 ## Scope
 
-Governs the scan an author runs against finished text on its way out, the form a pull request or issue reference takes in every destination, and the responses available when a source it reaches for cannot be read. It is an attribute standard rather than a document-type one, so it applies wherever no automated check covers the text, whether that text is leaving through a channel or sitting in the repository, and it carries no template because a scan has no document to shape.
+Governs the scan an author runs against finished text on its way out, the form a pull request or issue reference takes in every destination, and the response when a source the scan reaches for cannot be read. As an attribute standard it applies wherever no automated check covers the text, and carries no template.
 
 Does not govern:
 
@@ -18,68 +18,82 @@ Does not govern:
 
 ## When it runs
 
-Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, written to a path the project's checks exclude, and text inside a fenced block are the usual cases. The surface that publishes the text is what knows which gap applies, so it names its own rather than reading one here.
+Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, text written to a path the checks exclude, and text inside a fenced block are the usual cases.
 
-Run the scan as an explicit step against the finished text. Having read the underlying rules before drafting does not cover it, because the check has to happen after the text exists.
+- The surface publishing the text knows which gap applies, so it names its own rather than reading one here
+- Run the scan as an explicit step against the finished text, since the check has to happen after the text exists
 
-Scope every check below by destination. Text published to a remote takes all of them. Text staying in the repository takes the character bans alone, since those hold wherever the text lands, and skips whichever check depends on the reader holding something only this checkout carries. The two checks below that depend on it say so under their own headings.
+### Scope by destination
+
+Text published to a remote takes every check below. Text staying in the repository takes the character bans alone, since those hold wherever the text lands.
+
+- Phase labels and board identifiers depend on the reader holding this checkout, so repository text skips both
+- Session links depend on the reader holding the account, a narrower dependency stated under their own heading
 
 ## Banned characters
 
 `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` holds the character bans. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
 
-`canon labels scan` fails on these characters in a title or body, outside a code span or a link, so the scan is the check and the read above is the reason. It holds a pull request and a posted review alike.
-
-Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
+- `canon labels scan` fails on these characters in a title or body outside a code span or a link, for a pull request and a posted review alike
+- Restructure the sentence rather than substituting the character, since a semicolon swapped for a period keeps the shape the ban exists to remove
 
 ## Phase labels
 
 `${CLAUDE_SKILL_DIR}/../git-commit/references/versioning.md` holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
 
-This check is one of the two the destination rule above scopes. The reader inside the repository has the task board and the reader on a remote does not.
+The reader inside the repository has the task board and the reader on a remote does not, so this check is scoped by destination.
 
 ## Board identifiers
 
-A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and neither resolves for anyone else, so this check is the second one the destination rule scopes.
+A phase label is one way text names the board, and a path under a record root is the other. Both resolve for a reader holding this checkout and for nobody else, so this check is scoped by destination too.
 
-Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open.
+- A code span whose whole content is a label is still the label and a hit. A longer token inside a span is a fixture name and stays.
+- A path under a record root is gitignored and absent from every clone, so `.canon/feedback/` names a folder the remote's reader cannot open
+- Tracked `canon/` and `.claude/` paths are no hit, since `canon/context/surfaces/governance.md` resolves everywhere
+- Every path under `.canon/` is a hit whichever folder it names, since one ignore line covers the root whole
 
-Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/surfaces/governance.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+### Fixing a hit
 
-Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
+Rewrite a hit to name what the reader can reach rather than deleting it. State a row's subject plainly in place of its label, and say in a sentence what a record folder holds in place of its path.
 
-`canon labels scan` runs this check and the phase-label one over a pull request title and body, and over a posted review's own text once one is submitted. Any other channel, a plain issue comment among them, is still the author's own scan.
+`canon labels scan` runs this check and the phase-label one over a pull request title and body, and over a posted review's text once submitted. Any other channel, a plain issue comment among them, is still the author's own scan.
 
 ## Session links
 
-A link to one Claude Code session names the session that wrote the text rather than the change the text describes. It enters because the harness tells the composing session to end its published text with one, so the author writes it deliberately and it reads as required rather than as a slip. That is what carries it past a scan the same author runs, and it is why a rule stating the ban does not reach the case: the session is following an instruction it was given, and reads its own compliance as correct.
-
-This check depends on the reader holding the account rather than the checkout, which is narrower than the dependency the destination rule above scopes. A reader inside this checkout opens a record path and still cannot open a session, since the session resolves for the one account that started it and for nobody else. The scoping still sits at the invocation site, because `canon labels scan` reads a pull request title and body and reaches no other text.
-
-Delete a hit rather than rewriting it. The other two checks replace a hit with what the reader can reach instead, and a session has no such form, so what stands in its place is the body already written above it.
+A link to one Claude Code session names the session that wrote the text rather than the change it describes. The harness tells the composing session to end its published text with one, so the author writes it deliberately and reads that compliance as correct. That is how it passes a scan the same author runs.
 
-Removing the link before a merge does not substitute for never writing it. One branch removed it, read the live body back clean, and the squashed commit landed carrying it anyway off an earlier snapshot, which is permanent on the trunk.
+- The session resolves only for the account that started it, so a reader inside this checkout still cannot open it
+- The scoping sits at the invocation site, because `canon labels scan` reads a pull request title and body and no other text
+- Delete a hit rather than rewriting it, since a session has no reachable form and the body above it already stands in its place
+- Removing it before a merge is no substitute for never writing it, since a squash can land it from an earlier snapshot, permanently on the trunk
 
 ## Cross-reference form
 
-A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.
+A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it and in backticks where it does not, so a reference moved between destinations is rewritten rather than copied.
 
-Text published to a remote is the auto-linking half: a pull request body, an issue body, a comment on either, and a commit message. Write `#123` there, and `owner/repo#123` where the reference crosses repositories, which the same auto-linking reaches. A markdown file browsed from the repository tree is the other half, where neither spelling links and the backticked one marks the number as an identifier. <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy -->
+| Destination                                               | Form                                                                                                                                                         |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Pull request or issue body, a comment on either, a commit | `#123`, or `owner/repo#123` across repositories <!-- canon-allow-reference: the two spellings this section defines, which a qualified form would destroy --> |
+| A markdown file browsed from the repository tree          | the number in backticks, since neither spelling links there                                                                                                  |
+| Content installed into another repository                 | qualified against a different, resolvable repository, or no number                                                                                           |
 
-Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache and a docs page is read through `canon docs`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
+A commit message takes the bare form even though the log links nothing, since the remote is what the form is chosen for. Text quoted from another surface keeps the spelling it arrived with, since rewriting it reports the source as saying something it never said.
 
-Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `canon/context/` entry that owns the surface.
+### Installed content
 
-Write `owner/repo#123` and `owner/repo@abc1234` for a citation of a different, resolvable repository, across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
+A skill body loads from a plugin cache and a docs page is read through `canon docs`, so the reader holds their own repository rather than the one a bare number belongs to.
 
-Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape a context entry already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
+- Write `owner/repo#123` and `owner/repo@abc1234` for a different, resolvable repository, which the reader can open without this one
+- Qualifying against `erclx/canon` fixes nothing, since a reader holding the cache or the package still cannot open this repository's history
+- A same-repository citation takes no number, so state the fact it stood in for, and carry a one-off incident's identifier into the `canon/context/` entry owning the surface
+- `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or the line above
 
-A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.
+### Number or sha
 
-Text quoted from another surface keeps the spelling it arrived with. A reference inside a quotation belongs to what is being quoted rather than to the text doing the quoting, so rewriting it reports the source as having said something it never said.
+Choose the number where the citation names a decided change, since it resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape a context entry already uses. The choice holds for the bare and the qualified spelling alike.
 
 ## An unreadable source
 
 Stop and name the source when one this scan reaches for cannot be read. Do not scan what resolved and report the result.
 
-A run that covers half its sources and says nothing is worse than one that visibly did not happen, because the surfaces running this scan are the ones that describe themselves as the only gate. A clean result from a half-run scan is read as coverage.
+A half-run scan that says nothing is worse than one that visibly did not happen, because the surfaces running this scan describe themselves as the only gate. Its clean result is read as coverage.

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

@@ -7,22 +7,34 @@ description: How git-pr writes the pull request number the final command printed
 
 The last step of `git-pr` before its report, reached on every run whose final command printed a number.
 
-Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. A final command that refused on a head mismatch printed no number, so this step writes nothing on that run. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
+Write the `number` the final command printed onto the task the branch is closing, and never resolve it again. A lookup by branch alone can return a closed pull request sharing that head, per `${CLAUDE_SKILL_DIR}/REQUIREMENT.md`. A final command that refused on a head mismatch printed no number, so this step writes nothing on that run.
 
-The task is the one whose `Plan:` line names the plan this branch implemented. Name that plan by its file, which is `.canon/plans/feature-<slug>.md` at the main worktree root with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`. `plan-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path. When the session already knows which plan it implemented, because a caller read it earlier in the chain, use that filename instead of re-deriving.
+## Name the plan
+
+The task is the one whose `Plan:` line names the plan this branch implemented. That plan is `.canon/plans/feature-<slug>.md` at the main worktree root, with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../git-branch/references/slug.md`.
+
+- `plan-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path
+- When a caller earlier in the chain already read the plan, use that filename instead of re-deriving
+- The slug is a guess at the plan rather than a fact about the task, so the verb re-checks it against the board and refuses on a near miss
 
 ```bash
 canon tasks pull-request <number> --plan feature-<slug> --json
 ```
 
-The slug is a guess at which plan this branch carries rather than a fact about the task, which is why the verb re-checks it against the board and refuses instead of writing on a near miss. A branch whose slug names no plan file falls to the silent skip below, the same as one whose plan no task cites.
+## What the verb writes
+
+The verb resolves the board at the main worktree root in-process, the root `session-worktree` resolves on entry. It is the route because the write edits an existing main-root file, which `session-worktree` routes through a verb.
+
+- It adds `Pull request: #NNN` under the task's `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines, and corrects the number in place when the line exists
+- A line already reading as a list of `#NNN` entries takes the new number appended, reported as `appended`, so a task shipped in slices keeps every pull request
+- The same write drops this branch from the `Pending branch:` line `canon tasks outcome` wrote, which lets the merge-time archive close the task
 
-The verb resolves the board at the main worktree root in-process, adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already carries, and corrects the number in place when the line exists. This is the route because the write is an edit inside an existing main-root file, which `session-worktree` routes through a verb. That root is the one `session-worktree` resolves on entry.
+## Refusals
 
-The correction reaches only a line that does not read as a list of `#NNN` entries. A line that does takes the new number appended rather than replaced, reported as `appended`, so a task shipped in slices keeps every pull request.
+Skip silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`, meaning no board, no task naming the plan, or more than one. A guessed write would compound each, since a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
 
-The same write drops this branch from the task's `Pending branch:` line, which `canon tasks outcome` wrote when the branch ticked an outcome, so this step is what lets the merge-time archive close the task.
+A branch whose slug names no plan file lands on `no-match`, the same as one whose plan no task cites.
 
-Skip this silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`. Those are the three cases a guessed write would compound: no board, no task naming the plan, or more than one. One pull request names one task, and a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
+## Why the number
 
-The number is what lets the merge close the task. Every merge on `main` is a squash carrying it in the subject, so the number survives where a branch name does not, and `post-merge` reads it back to call `canon tasks archive`. Writing it here rather than at worktree time is what makes it a pull request number rather than a branch the squash discards.
+Every merge on `main` is a squash carrying the number in its subject, so the number survives where a branch name does not. `post-merge` reads it back to call `canon tasks archive`, which is why this step runs at pull request time rather than at worktree time.

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

@@ -89,7 +89,7 @@ On a `passing` wake, run `canon pr evidence <number> --check --json` against the
 | Any other `reason`, such as `gh-failed` | Stop and report it, since an unread thread is not a settled one                                         |
 | No record, or an unknown flag error     | The binary predates `--check`, so report the thread unread and continue without claiming it was checked |
 
-On `owed`, run the named steps from `canon:git-pr`'s `references/evidence.md`, evidence first and then preview, and re-read with the same command. Continue only on `settled`, and stop on any other reading with the `reason` and the `owed` list, never looping back.
+On `owed`, invoke `canon:pr-evidence` with the number, which runs the evidence step first and then the preview the thread owes, and re-read with the same command. Continue only on `settled`, and stop on any other reading with the `reason` and the `owed` list, never looping back.
 
 A refused preview step or a failed deploy leaves `preview` owed on the re-read, so that is the stop and not a retry. The read is a closing step, so the draft mark stays the only thing between steps 8 and 9, and a caller closing on its own block waits on the same wake.
 

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

@@ -9,7 +9,7 @@ Applies to a feature plan that sequences its work into more than one batch. A de
 
 ## One batch, one file
 
-One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename.
+One batch is one pull request, and one pull request is one plan file, named for its own concern rather than a numeric suffix. `canon tasks plan-branch` derives one branch from one plan filename. A fan-in member is the exception, keeping its own file and branch and opening no pull request, per `## Fan-in`.
 
 - A `**Batch N**` sub-heading inside one file's `**Files to touch:**` shares that branch across every batch, so the first merge strands the rest
 - Write a plan opening five batches as five files before the first line of any of them
@@ -44,3 +44,50 @@ Slice a batch by one user-visible path end to end rather than by layer, so each
 - Sequence the riskiest batch first, so the batch most likely to change the plan is built while every later batch can still move
 - Sequence a sweep last, even when it is the riskiest. A batch rewriting files earlier batches touched forces every batch behind it into one review anywhere else.
 - Keep each batch's commits contiguous once the work starts, since a batch interrupted by another cannot be lifted onto its own branch afterward
+
+## Fan-in
+
+A fan-in builds batches in parallel and ships them as one pull request. Each member builds on its own branch and opens none, and one integrator merges every member branch, resolves the shared lines once, and opens the pull request. The trade is one large review, read one merge commit at a time, in place of a review and a rebase per batch.
+
+### When to fan in
+
+Fan in when the split was made for speed rather than meaning. Every one of these holds:
+
+- One task with one outcome, so no batch is a feature on its own
+- The batches share edge files, such as a gated-paths list or an index, so separate pull requests rebase each other on every merge
+- No batch needs to ship, be reviewed, or be reverted alone
+
+Keep separate pull requests when the pieces are independent features, when one needs its own review or revert, when one may stall and hold the rest, or when the combined diff is too large to review even one merge commit at a time. Batches that build on each other stack or fold, per `## Dependent batches`, since a member stacks on nothing.
+
+### Declaring the set
+
+Each side names the other in its `**Constraints:**`, and `canon records validate plans` reports `fan-in-unmatched` wherever the two disagree.
+
+- A member writes ``Fan-in member of `feature-<integrator>` ``, naming one integrator
+- The integrator writes ``Fans in `feature-<a>`, `feature-<b>`, and `feature-<c>` ``, in the order it merges them
+- The task's `Plan:` line cites every member and the integrator, since the merge archives only the plans that line cites and a live integrator listing archived members reports `fan-in-unmatched`
+- The integrator is its own plan, since its writes, being the shared lists, the citer repoints, and the index regeneration, need a `**Files to touch:**` of their own
+
+`canon tasks plan-answers` holds a member whose integrator is missing or does not list it with a `Fan-in set` entry. It holds the integrator with a `Fan-in pending` entry until every member branch is on origin.
+
+### Dispatching the set
+
+The members of one set dispatch together by design, since they share edge files and the integrator resolves those lines once. A shared file between members is never a hold.
+
+- Hold the integrator on a dependency until `plan-answers` reads it launchable
+- Re-read it after a fetch on each member's done message, which carries the branch and head commit in place of a pull request
+- Never read a member with no pull request as stalled, since a member opens none
+
+### What a member writes
+
+A member builds, verifies, pushes its branch, and announces it done. A pushed branch is the done signal, so a member pushes once, at the end.
+
+A member may edit the shared lists and regenerate the indexes on its own branch, since the pre-push check fails a member that deletes a path a gated list still names. The integrator resolves those lines once at merge.
+
+### What the integrator writes
+
+The integrator merges each member branch with `git merge --no-ff` in the order its bullet lists, resolving conflicts by the rules a rebase follows. It then writes its own files, regenerates the indexes once, and opens the pull request.
+
+- Say in the pull request body that each member is one merge commit, so a reviewer reads `git log --first-parent` one member at a time
+- Fix a semantic conflict a merge surfaces on the integrator's branch, since a member has no pull request to fix it on
+- Delete each member branch on origin with `git push origin --delete <branch>` once the pull request merges

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

@@ -30,7 +30,14 @@ A plan lost to deletion, or carrying two answers to one question, fails both.
 ## Lifecycle
 
 - Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
-- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
-- Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
+- Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
+
+### Amending and archiving
+
+A plan changes in place and leaves only by a move.
+
+- Amend the plan in place when a decision changes mid-flight, never appending a passage narrating the change, which leaves two answers to reconcile
+- An execution-time deviation from a suggestion is one such amendment, and the suggested-and-answer contract in `plan.md` fixes which line takes it
+- Move the plan to `.canon/plans/archive/` when its work ships or is declined, and never delete it, since it records the rejected alternative
+- A flat `.claude/plans-archive/` sibling is the older layout.

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

@@ -50,13 +50,21 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 ## Filename and slug
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
-- Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
-- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges. State a batch's dependency on the ones before it in its own `**Constraints:**`. A batch that stacks on another and shares most of its files with it folds into that batch as contiguous commits on one branch rather than taking a file, unless its constraints carry ``Judged apart from `feature-<parent>`: <reason>`` with a reason after the colon. `canon records validate plans` reports `stack-foldable` for a stacked batch that has neither.
+- Write one concern per file, since a plan bundling two cannot be executed by two sessions or abandoned by half
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
-- Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
+- Give the executing branch the same slug, since a later surface finds the plan from the branch name and finds nothing when the spellings differ
 
 A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
 
+### Staged batches
+
+A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges.
+
+- State a batch's dependency on the ones before it in its own `**Constraints:**`
+- A batch stacking on another and sharing most of its files folds into that batch as contiguous commits on one branch, rather than taking a file
+- It takes a file anyway when its constraints carry ``Judged apart from `feature-<parent>`: <reason>`` with a reason after the colon
+- `canon records validate plans` reports `stack-foldable` for a stacked batch that has neither
+
 ## Sections
 
 The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
@@ -73,60 +81,86 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `**Sources:**`        | the outside sources a decision rests on, each with its quoted passage     | When a decision rests on an outside source |
 
 - Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the others are labels over lists rather than sections of prose.
-- A section written in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing. Write the table's form in a new plan and leave an existing plan's spelling alone. Either spelling breaks a depth run.
+- A section in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing, and either spelling breaks a depth run
+- Write the table's form in a new plan and leave an existing plan's spelling alone
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
 - Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
 
 ### Files to touch entries
 
-- Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
-- Separate the two halves with a colon, and keep every path the entry declares ahead of it. What sits before the colon reads as a target, so both sides of a rename belong there and a file merely cited by the reason does not.
-- Read the list as what the branch sets out to write rather than as a bound on it, since the doc syncs at ship write past it on nearly every branch. `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan.
+Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against.
+
+- Lead with the path or with a label carrying the path, whichever reads better for the entry
+- Separate the two halves with a colon, and keep every path the entry declares ahead of it, since what sits before the colon reads as a target
+- Both sides of a rename belong before the colon, and a file merely cited by the reason does not
+- Read the list as what the branch sets out to write rather than a bound, since the doc syncs at ship write past it on nearly every branch
+- `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan
 
 ### Measured claims
 
-- State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
-- Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
+State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
+
+Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 
 ### Constraints
 
 Work in flight reaches a plan as a hold or as a shared path. A hold leaves a surface alone and says which of two acts it forbids, rather than leaving the executing session to guess. Neither act is forbidden over a shared path.
 
-- Write a hold only for a dependency, a contract the other track consumes, a relocation, or a sweep, which a rebase cannot settle mechanically. A bare shared file is none of these, and forbidding it sends a worker to concede a file the change needs.
+Write a hold only for a dependency, a contract the other track consumes, a relocation, or a sweep, which a rebase cannot settle mechanically. A bare shared file is none of these, and forbidding it sends a worker to concede a file the change needs.
+
 - Forbid conforming that surface to whatever shape the change introduces, which keeps the branch to one concern.
-- Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so repairing it is required work rather than scope creep.
+- Never forbid retargeting a pointer the change breaks, since a rename, split, or deletion leaving a citation behind ships a dangling reference
 - Decide both acts for every surface a hold names, not for one file among its siblings.
 - Write a shared path as the track, the path, and the branch that rebases, being the one merging second. The executing session edits the file and keeps both sides on the rebase.
 
+### Stamping a constraint
+
 A constraint measured against work in flight expires when that work merges, as a shared-path line does, so stamp the block with what it was measured against.
 
 - Give the stamp its own leading bullet, written as Measured against `<commit>` on <YYYY-MM-DD>. One stamp covers the whole block.
-- Stamp the commit rather than the track names or a date alone. The constraint already names each track, and a date does not separate two plans written on either side of a merge.
-- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch and scope the log to the paths in the same command, since a stale ref reads a dead constraint as live and a squashed subject names no track.
+- Stamp the commit rather than the track names or a date alone, since a date does not separate two plans written either side of a merge
 - Read an unstamped constraint as unverified rather than as live, and confirm it against the open pull request list for the named paths.
 
+Re-test a stamped constraint before honoring it, fetching and scoping the log in one command, since a stale ref reads a dead constraint as live and a squashed subject names no track. Any commit it reports means the track landed and the constraint is dead.
+
+```bash
+git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>
+```
+
+### Fan-in and ready constraints
+
+A batch in a fan-in set declares its side in a constraint bullet, ``Fan-in member of `feature-<integrator>` `` on a member and ``Fans in `feature-<a>`, `feature-<b>` `` on the integrator. `batches.md` holds when to fan in, and `canon records validate plans` reports `fan-in-unmatched` for a set whose two sides disagree.
+
 A constraint naming a `.canon/ready/` folder is a third shape beside the hold and the shared path. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
 ### Verification
 
+Every outcome reaches the review with its proof named.
+
 - Name, for each outcome, the test or the command that proves it, as one bullet leading with the outcome and ending on the command in backticks.
 - Write a command a later session can run as given, from the project root. A description of what would be checked leaves the executing session to invent the check.
 - Name the visual check where no test reaches, and say it is visual, so a reader can tell a proof from a look.
 
 ### Risks
 
-- Name the collision rather than the category. A risk a reader cannot act on is padding.
-- Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
-- Where the work changes a contract another track consumes, such as an exported signature, a verb's flags or record, or a config key, name the contract and list each consumer. The dispatcher reads this bullet for the contract hold, so a change left out reaches it as a clean shared file.
+Name the collision rather than the category, since a risk a reader cannot act on is padding.
+
+- For a resource with more than one consumer, list the consumers and mark each read or write, so a policy over it holds for every writer
+- For a changed contract another track consumes, such as an exported signature, a verb's flags or record, or a config key, name it and list each consumer
+- The dispatcher reads that contract bullet for the hold, so a change left out reaches it as a clean shared file
 
 ### Review focus
 
+This section is where the planner's understanding of the risk reaches the review pass.
+
 - Name each input or state that would break the change if the implementation got it wrong, one bullet each, with what the change must do there.
-- Write it for the reviewer rather than the builder, since this section is where the planner's understanding of the risk reaches the review pass.
+- Write it for the reviewer rather than the builder
 - Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle.
 
 ### Sources
 
+A source earns an entry only once someone opened it.
+
 - Give each entry a link, the decision it backs, and the passage relied on in double quotes.
 - Mark a source that could not be fetched `unverified` and never quote it. A quote for a page nobody opened is the failure this section exists to prevent.
 - Cite no source that was found and not opened, following the lead rule in `groundwork.md`.
@@ -156,14 +190,19 @@ An execution that deviates rewrites the suggestion into the form below, leaving
 
 ### Preference questions and answers
 
+The suggestion line is the planner's, and the answer line belongs to whoever owns the call.
+
 - Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
 
 ### Overrides and settled questions
 
-- Rewrite the `- Suggested:` line to the pick execution made when it deviates from an unanswered question, and leave the slot blank. The prohibition above reaches the answer line alone, so the suggestion line is where a deviation goes.
-- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick. The fixed phrase is what tells an override from an authored suggestion, which routinely carries a number too.
-- Take a deviation from an answered question back to whoever answered it rather than rewriting either line. A filled slot is a decision already made, and a suggestion rewritten under one leaves the plan holding two picks with no default resolving them.
+A deviation from an unanswered question rewrites the `- Suggested:` line to the pick execution made and leaves the slot blank, since the prohibition above reaches the answer line alone.
+
+- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick
+- The fixed phrase tells an override from an authored suggestion, which routinely carries a number too
+- Take a deviation from an answered question back to whoever answered it rather than rewriting either line
+- A filled slot is a decision already made, and a suggestion rewritten under one leaves two picks with no default resolving them
 - Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
 
 The plan is archived at ship, so the same deviation takes one line in the open task's `## Findings` naming what shipped. The plan holds why the pick moved and the task holds what the tree now has.

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

@@ -31,7 +31,8 @@ The file is optional, since measuring what is already there settles most questio
 Each spike carries four things:
 
 - The open question it answers, named by file and number. A spike attached to no question is a runaway.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
+- The method, stated fully enough for a later reader to re-run it, with the exact command and the repetition count.
+- The fixture and where it lived, since an arm pointed at a fixture inside the project measured the project
 - The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
 - The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
 
@@ -47,6 +48,8 @@ A file a reader opens to verify how a result was produced or what it showed live
 
 Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
 
+### Harnesses and read checks
+
 Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
 
 Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.