@erclx/canon 5.7.0 → 5.8.0

package/README.md

@@ -11,7 +11,7 @@
 [![CI status](https://img.shields.io/github/actions/workflow/status/erclx/canon/verify.yml?branch=main)](https://github.com/erclx/canon/actions/workflows/verify.yml)
 [![License MIT](https://img.shields.io/npm/l/@erclx/canon)](LICENSE)
 
-canon is a CLI and Claude Code plugin that stops your AI conventions drifting apart across repositories. It keeps one authoritative copy and installs it into each project on demand.
+canon is a CLI and Claude Code plugin that runs your agent's work from plan to merge, holds it to the practices that make code worth keeping, and installs the same setup in every repository.
 
 **[See it run at canon.erclx.dev](https://canon.erclx.dev)**
 
@@ -21,7 +21,9 @@ That page is one real session the toolkit ran on itself, and every count on it i
 
 ## Why
 
-If you work across more than one repository and your AI setup has started to drift between them, this is for you. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
+If an agent writes code for you in more than one repository, this is for you. canon runs that work from plan to merge. A planner writes the plan, a worker builds it on its own branch, and a separate session reviews the pull request. It holds the work to a practice, with rules that load when a matching path is edited and checks that fail when a rule is ignored. Both run on one setup, installed the same way in every repository you keep.
+
+That shared setup is what the rest of this page describes, and it is the part that drifts without a source. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
 
 Three design choices shape the toolkit.
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
-  "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "5.7.0",
+  "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
+  "version": "5.8.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -143,6 +143,8 @@ Invoke `canon:git-ship`. That body owns the sequence, being the verify gate, mem
 
 One thing this chain adds. Mark the pull request as a draft as soon as `git-ship`'s pull request step returns, ahead of its CI watch, naming the number that step returned rather than one resolved by branch. Read `${CLAUDE_SKILL_DIR}/references/draft-mark.md` on reaching that point for the one command that proves the target, marks it, and reads the flag back. A `false` read stops the chain, and never re-issue the mark on it.
 
+Emit the Output block on the wake after `git-ship`'s background CI watch exits on `passing`, not when the turn ends on its watch line.
+
 `git-ship` verifies again at its own gate, repeating Step 3 on a clean run. Keep that repeat, since a resumed run enters at that gate.
 
 ## Output

package/claude/skills/draft-and-pick/REQUIREMENT.md

@@ -29,6 +29,7 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Judges a lower layer through a finished higher one, so an operator asked about composition looks at the palette instead and answers about that.
 - Hands over the combined page alone for a decision about layout, where every arm sits in a column while the media queries answer to the whole window, so no arm is ever seen at its own viewport and a fault that appears only narrower survives the pick.
 - Rebuilds a navigation harness by hand on a run with several rounds, since each round writes its own folder and nothing reaches all of them from one address. Two design tracks hand-wrote the same page picker and theme toggle.
+- Puts the pick question with no address in its output, after capturing the page and reading the image back. The operator then has to ask for a served page before they can look, so the question goes unanswered or gets answered blind.
 - Sets the theme on an arm that persists its own and reads it back on load, so the control reports one theme while the arm renders the other and the set is compared across two.
 
 ## Must
@@ -49,7 +50,7 @@ Without this skill, a session facing a decision nobody can settle from a diff:
 - Apply the winning arm in one change.
 - Capture every arm from the final round as an image before deleting the run's scratch folder, rather than discarding the losing arms with it.
 - Resolve the archival capture's destination against the main worktree root, never against a linked worktree the run happens to be building in.
-- Serve the candidates live where the decision is one the operator has to drive, since a still cannot answer how a gesture feels or how a pace reads.
+- Serve the candidates on every run, whatever the decision's layer, and emit the local link ahead of the first pick question, so the operator can open the page the question is about and a still is never the only address.
 
 ## Must not
 

package/claude/skills/draft-and-pick/SKILL.md

@@ -45,17 +45,19 @@ Write every arm side by side on one self-contained HTML page at `<dest>/candidat
 
 ## Step 3: render and hand off
 
-Render the page, then look at what came back:
+Serve the page first, then render it and look at what came back. Every run serves, whatever the decision's layer, since a pick asked about a page the operator cannot open is a question nobody can answer.
 
 ```bash
+canon serve <dest> --entry candidates.html --json
 canon capture <dest>/candidates.html --selector <element>
 ```
 
+- Start `canon serve` in the background and read the link off its record, never assuming a port, since the printed link opens `index.html` without `--entry` and `<dest>` holds no such file. Keep each server up through the loop and note its process, since Step 5 re-enters this step and Step 6 stops them all. Serving needs no browser, so the link exists the moment the page is written.
+- Where Step 2 wrote a frame, hand over the frame's link instead, served from the parent folder as Step 2 says, and let no earlier round's `<dest>`-only link stand as the address a later round cites.
 - `--selector` has no default and the command refuses without it. Name the element wrapping the arms rather than `body`, which crops to whatever the page's own margins leave.
-- `canon capture` and `canon drive` both need a browser binary the toolkit does not install. When either refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, then stop rather than describing an arm nobody has seen.
-- Serve the page instead of capturing it when the operator has to drive the decision, such as a hover response, a scroll-linked position, or a pace. Start `canon serve <dest> --entry candidates.html` in the background and read the link off its record, since the printed link opens `index.html` without that flag and `<dest>` holds no such file. A still answers how a thing looks and answers none of those.
+- `canon capture` and `canon drive` both need a browser binary the toolkit does not install. When either refuses for that reason, report the refusal and name `bunx playwright install chromium` as the repair, stop every server Step 3 started, then stop rather than describing an arm nobody has seen.
 - Write the render inside the record that cites it wherever one exists, by pointing `--out` at `<dest>/renders/` rather than at a session scratch path. A pick taken from an image the record does not hold is a judgment nobody but this session can check, and the archival capture in Step 6 covers the final round alone.
-- Hand over the address rather than a description. Emit the PNG path on its own line, and the link beside it where the page is served.
+- Hand over the address rather than a description. Emit the link first on its own line, then the PNG path on its own line. A still answers how a thing looks and answers none of a hover response, a scroll-linked position, or a pace, which the served page does.
 - Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
 - Look to judge rather than to confirm. Reading the image back to check it rendered satisfies the rule above and still hands over weak work, so name the weakest thing on the page in a sentence. Where that sentence would embarrass the work, fix it and hand over the second version. Say the remaining weakness out loud either way, so the operator is not hunting for what you already know.
 
@@ -63,6 +65,7 @@ canon capture <dest>/candidates.html --selector <element>
 
 Put the choice to the operator through the structured question surface, since a call the operator's preference decides always routes through it rather than through prose.
 
+- Emit the link in the response text ahead of the question call, and name it again in the question's own text, since some surfaces render the question card alone. A question that goes out with no address is one the operator cannot answer by looking.
 - One option per arm, labeled with the arm's id and carrying its cost as the description.
 - Rank the recommendation first and mark it `(Recommended)`.
 - Author the real arms only. The surface appends its own escapes for a free-text answer and for reopening the question, so writing either as an option ships a duplicate the tool rejects.
@@ -82,8 +85,8 @@ Put the choice to the operator through the structured question surface, since a
 2. Close out whatever document stated the decision as open, in the same change, naming the arm that won and the ones that stayed defensible. A pick that changes a surface and records nothing about why leaves the next reader to re-derive it from a diff. Skip this where nothing stated the decision.
 3. Batch-capture the final round's arm files, when `<dest>` is the scratch path: `canon capture <dest>/arms --selector <wrapper-class> --out <archive-dir>`, naming Step 2's chosen class. This is the directory-batch convention `draft-identity` Step 6 already uses.
 4. Resolve `<archive-dir>` as `.canon/picks/<slug>/` against the main worktree root, since shared session scratch resolves there rather than against a linked worktree this run happens to be building in. The capture is what keeps every arm past the pick, the losing ones included, as a durable revert record distinct from the live comparison page.
-5. Delete `<dest>` and every file inside it, when `<dest>` is the scratch path, now that every arm sits at the durable path above. A variant left behind there is a second design nobody maintains.
-6. Leave `<dest>` in place when it is a live track's `evidence/<slug>/`: `plan-groundwork`'s write scope treats evidence as durable rather than as scratch a session may delete, and the arms already sit at a durable path there.
+5. Stop every background server Step 3 started, one per round where the loop re-entered it, then delete `<dest>` and every file inside it, when `<dest>` is the scratch path, now that every arm sits at the durable path above. A variant left behind there is a second design nobody maintains, and a server left running would serve a folder that no longer exists.
+6. Leave `<dest>` in place when it is a live track's `evidence/<slug>/`: `plan-groundwork`'s write scope treats evidence as durable rather than as scratch a session may delete, and the arms already sit at a durable path there. Stop every server there too.
 7. Report `<dest>` as still standing when the scratch-path delete is refused, naming the path for the operator to remove, rather than closing on a report the tree contradicts. The pick is applied either way, so the run has done its work and the folder is what outlives it.
 8. Report every surface that changed, each on its own line, name the arm that won by its id and its cost, and report the archival path from Step 3 where it ran.
 

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

@@ -20,7 +20,7 @@ The sequence also reaches the remote on work nothing re-checked. This skill is t
 - Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
 - Name the one point a wrapping caller may act at, so a chain built on this one is not left to pick a gap of its own
 - Name the condition under which the closing block is not emitted, since a caller that closes on its own block leaves two instructions about the last line and nothing deciding between them
-- Watch continuous integration to a terminal state, and stop on a failure naming the check
+- Watch continuous integration to a terminal state in the background, so the session stays reachable while CI runs, and stop on a failure naming the check
 - Stop memory work at the Propose phase
 
 ## Must not
@@ -30,11 +30,12 @@ The sequence also reaches the remote on work nothing re-checked. This skill is t
 - Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
 - Attempt a fix for a failing verify. The user is already making one, which is what brought the run back here.
 - Implement or review. This chain starts from work already believed done.
+- Report the chain done before the CI watch exits. A turn ending on the watch line leaves a pull request still waiting on CI, and a `✅ Shipped` there claims a result nothing has read.
 
 ## Guards
 
 - A failing verify stops the run before the sync skills write, so the tree is left as the user left it
-- A failing check stops the sequence. This is the one place text is allowed between steps.
+- A failing check stops the sequence. A stop report and the line announcing the background watch are the two places text is allowed between steps.
 
 ## Out of scope
 

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

@@ -7,7 +7,7 @@ description: Runs the full post-feature workflow by syncing docs, staging commit
 
 Run the full post-feature workflow by invoking each skill in sequence using the Skill tool. After each skill returns, invoke the next step immediately in the same response.
 
-Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, unless a wrapping caller states it closes on its own block, which `auto-ship` does.
+Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, emitted on the wake after the step 9 watch exits on `passing` rather than when the turn ends on the watch line, unless a wrapping caller states it closes on its own block, which `auto-ship` does.
 
 ## Verify
 
@@ -31,10 +31,33 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 6. Invoke `canon:git-stage` to group staged changes and commit by concern
 7. Invoke `canon:git-branch` to rename branch to match conventional format
 8. Invoke `canon:git-pr` to push branch and open pull request
-9. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending` or the record carries `conflicted: true`, branching on those fields rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. On `conflicted`, stop the sequence and report that the branch conflicts with its base, since no run will start for it and polling on never ends. A rebase is the repair. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. After the PR opens, watch CI in the background, so the session stays reachable while CI runs. Read `### Watching CI` below for the commands and the wake.
 
 A caller wrapping this sequence may act between step 8 and step 9, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `auto-ship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
 
+### Watching CI
+
+Run `canon pr checks <number> --json` once in the foreground. When no record comes back at all, the target's CLI predates the verb, and the watch command is `gh pr checks <number> --watch`. The loop below would never exit on such a target, since an empty read never satisfies its test.
+
+Otherwise start this loop through the Bash tool with `run_in_background` and a 60-minute timeout:
+
+```bash
+until canon pr checks <number> --json | jq -e '.state != "pending" or .conflicted == true' >/dev/null; do sleep 30; done; canon pr checks <number> --json
+```
+
+Emit `⏳ Watching CI on #<number> in the background` and end the turn. Print nothing more while the watch runs. The session wakes when the command exits, and the wake resumes this step rather than restarting the sequence at step 1. A wake that lands while the session is inside another skill, such as a `review-address` pass a message started during the watch, goes to whichever step is waiting on CI.
+
+On the wake, branch on the final record's fields rather than on the exit:
+
+- `state: passing`: continue to After completion.
+- `state: failing`: stop the sequence and report the failing check with its URL.
+- `conflicted: true`: stop the sequence and report that the branch conflicts with its base, since no run will start for it. A rebase is the repair.
+- A `reason` and no `state`: the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`. A missing `state` is never a pass.
+- The command hit its timeout and printed no final record: report CI unsettled after 60 minutes, and emit no `✅ Shipped`.
+- The `gh pr checks --watch` fallback ran, which prints a check table rather than a record. Only a printed table carrying at least one check, every one passing, continues to After completion. Any failing check stops the sequence naming it with its URL. Empty or errored output stops the sequence and reports the message, since `no checks reported on the '<branch>' branch` is what a conflicted branch prints, and that fallback has no `conflicted` field to separate it from lag.
+
+Do not auto-fix any of these. The watch line and a stop report from any branch above are the two exceptions to the no-text-between-steps rule.
+
 ### Why the reach reads at step 5
 
 The branch is whole there and nowhere earlier. Steps 2 and 3 write past whatever the plan declared, so a reading taken ahead of them misses the chain's own additions, and no pull request exists until step 8 to carry the answer anywhere.

package/claude/skills/review-address/SKILL.md

@@ -170,10 +170,12 @@ echo "${comment_url##*issuecomment-}" > .canon/tmp/pr/reply/reply-<number>.id
 
 ## Step 7: confirm resolution
 
-After the follow-up push, watch CI on the PR. Poll
-`canon pr checks <number> --json` until the record's `state` leaves `pending`
-or it carries `conflicted: true`, then read it. On `conflicted`, stop and report
-that a rebase is the repair rather than polling on. When every finding is addressed and the state is `passing`, append
+After the push, read Watching CI in `${CLAUDE_SKILL_DIR}/../git-ship/SKILL.md`
+without invoking that skill, start its background watch, end the turn on its
+line, and run the rest of this step and Step 8 on the wake. Reuse a watch
+already running on this PR, since it reads the new tip. On the wake, stop on `conflicted` naming a rebase, on a `reason` naming it,
+and on a timeout reporting CI unsettled. When every finding is addressed and
+the state is `passing`, append
 the closing confirmation to the reply file Step 6 already posted, so the thread
 carries one terminal state rather than a second comment under no heading:
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.7.0",
-  "description": "Infrastructure and quality tooling for developer workflows",
+  "version": "5.8.0",
+  "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
     "canon": "./src/cli.ts"