@erclx/canon 4.57.0 → 4.58.0

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.57.0",
+  "version": "4.58.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-autoship/SKILL.md

@@ -87,7 +87,7 @@ Check for a `**Files to touch:**` or `## Files to touch` marker per `${CLAUDE_SK
 
 Read `<plan>` at the main worktree root. This file is the scope for this run.
 
-Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop.
+Its sections and its answer contract are fixed by `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A blank `- Answer:` accepts the `- Suggested:` line above it, so an unanswered question is a decision this run executes rather than a reason to stop. When this run decides against that suggestion, rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement, leaving the `- Answer:` slot blank, and put the same deviation in one line under the open task's `## Findings`, per `${CLAUDE_SKILL_DIR}/../../standards/plan.md`.
 
 ## Step 2: implement
 

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

@@ -23,6 +23,7 @@ Read `${CLAUDE_SKILL_DIR}/../../standards/groundwork.md` before writing any file
 - One exception, at close only: write one task file recording what the track concluded.
 - A second exception, for what a spike reads: write an input under `.canon/tmp/groundwork-fixtures/<slug>/`. Keep it out of `.canon/groundwork/` so mode detection never matches a fixture as a track. A fixture a headless run is pointed at goes outside the repository instead, per the rule in `## Running a spike`.
 - What a spike produces stays inside the track rather than joining the two exceptions above: write evidence a spike file cites under `.canon/groundwork/<nn>-<slug>/evidence/`, which the first rule already permits. Mode detection matches entries at the top level of the tracks directory, so the sibling the fixtures rule guards against cannot be a folder nested inside a track, and the scratch path holds only what can be deleted without loss, which a recording a finding rests on is not.
+- A `draft-and-pick` run invoked from inside a live track follows its own branch for this, writing to `evidence/` here rather than `.canon/tmp/<slug>/`.
 - Reading is not restricted. External research is in scope, so read documentation, comparable projects, and papers whenever a live question needs them.
 - Every claim about a source outside the project carries a link to it. A source found and not read is listed as a lead and is never cited.
 - Treat the folder as gitignored and unbacked. It dies with the machine, so `07-next-session.md` repeats what it needs instead of pointing at its siblings.

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

@@ -26,6 +26,7 @@ running and re-invoking it would restart the build.
 - 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.
 - Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft and no step anywhere un-marks, so a flag reading ready afterwards was lifted by a person readying it to merge, which GitHub requires and is theirs to take. Re-drafting fights them, which four sessions did on 2026-08-31 on a belief no surface in the tree states.
+- 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}/../../standards/plan.md`.
 
 ## The board is read-only
 

package/claude/skills/claude-worktree/SKILL.md

@@ -118,14 +118,16 @@ A linked worktree is a second working directory over one repository, and every e
 
 Report the state on one line. Do not install. Entering a worktree to read is as common as entering one to run, and an install is slow, needs a network, and picks an ecosystem on the session's behalf.
 
-Read the worktree root and emit the first line that matches:
+Read the worktree root and evaluate node and python independently, each emitting its own line regardless of the other's state:
 
-- `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run <install> before any build, test, or server command.` Take `<install>` from the lockfile beside the manifest, and use `bun install` when no lockfile names one.
-- A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.`
-- A manifest present with its folder alongside it: `Dependencies are installed.`
-- No package manifest of either kind: `No package manifest, so there is nothing to install.`
+- Node. `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run <install> before any build, test, or server command.` Take `<install>` from the lockfile beside the manifest, and use `bun install` when no lockfile names one. `package.json` present with `node_modules/` alongside it: `Node dependencies are installed.`
+- Python. A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.` Either manifest present with `.venv/` alongside it: `Python dependencies are installed.`
 
-The last line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed.
+Name the ecosystem in both installed lines rather than leaving `Dependencies are installed.` unqualified. Both checks can fire on one project, so an unqualified line reported the same sentence twice for a dual-root project with both folders present, and a reader could not tell which half each line answered.
+
+Emit the closing line only when neither manifest is present, tested directly rather than reached by falling through the two checks above unmatched: `No package manifest, so there is nothing to install.` A dual-root project matches both checks above, and a fallthrough test would route it here by accident.
+
+The closing line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed.
 
 Then report the port this worktree derives, on a second line:
 

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

@@ -16,14 +16,14 @@ Some decisions are settled by looking rather than by reasoning, and no draft is
 ## Step 1: name the decision and the arms
 
 1. State the decision in one sentence, naming what changes between arms and what stays fixed.
-2. Derive a kebab slug from that sentence. Every file this run writes goes to `.canon/tmp/<slug>/`, per `.claude/rules/canon/core/055-scratch.md`.
+2. Derive a kebab slug from that sentence. Call the folder every file this run writes to `<dest>` below. `<dest>` is `.canon/tmp/<slug>/`, per `.claude/rules/canon/core/055-scratch.md`. Running inside a live `claude-groundwork` track is the one exception: `<dest>` is the track's own `evidence/<slug>/` instead, since a candidate render is evidence the track's decision file cites rather than spike input.
 3. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
 4. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
 5. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
 
 ## Step 2: author the candidate set as one page
 
-Write every arm side by side on one self-contained HTML page at `.canon/tmp/<slug>/candidates.html`.
+Write every arm side by side on one self-contained HTML page at `<dest>/candidates.html`.
 
 - One page, never one file per arm. The comparison is the artifact, and several images handed over separately ask the operator to hold the differences in memory.
 - Label each arm on the page with its id and its cost, so the render carries what the question will ask about.
@@ -36,12 +36,12 @@ Write every arm side by side on one self-contained HTML page at `.canon/tmp/<slu
 Render the page, then look at what came back:
 
 ```bash
-canon capture .canon/tmp/<slug>/candidates.html --selector <element>
+canon capture <dest>/candidates.html --selector <element>
 ```
 
 - `--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 .canon/tmp/<slug> --entry candidates.html` in the background and read the link off its record, since the printed link opens `index.html` without that flag and the scratch folder holds no such file. A still answers how a thing looks and answers none of those.
+- 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.
 - 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.
 - Never report a visual result you have not looked at. A claim about appearance with no render behind it is a guess.
 
@@ -60,14 +60,14 @@ Put the choice to the operator through the structured question surface, per `.cl
 2. Write fresh arms off the pick and return to Step 2 where the correction opens a new question. Revise the one arm where it does not.
 3. Re-render, hand off again, and take the next answer.
 4. Repeat until the operator says it is right. The loop stops on their word and on nothing else, so a run stopping because the arms stopped differing has stopped early.
-5. Hold the real surface untouched across every iteration. Nothing outside `.canon/tmp/<slug>/` changes until the pick is final.
+5. Hold the real surface untouched across every iteration. Nothing outside `<dest>` changes until the pick is final.
 
 ## Step 6: close
 
 1. Apply the winning arm to the real surface, in one change.
-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, and the losing arms are gone by the next step. Skip this where nothing stated the decision.
-3. Delete `.canon/tmp/<slug>/` and every losing arm with it. A variant left behind is a second design nobody maintains.
-4. Report the scratch folder as still standing when that 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.
+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, and the losing arms are gone by the next step where `<dest>` is deleted. Skip this where nothing stated the decision.
+3. Delete `<dest>` and every losing arm with it, when `<dest>` is the scratch path. A variant left behind there is a second design nobody maintains. Leave `<dest>` in place when it is a live track's `evidence/<slug>/`: `claude-groundwork`'s write scope treats evidence as durable rather than as scratch a session may delete, and the render a decision file cites has to stay where that file points.
+4. 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.
 5. Report every surface that changed, each on its own line, and name the arm that won by its id and its cost.
 
 ## Reading a measurement

package/governance/rules/core/005-behavior.md

@@ -14,6 +14,7 @@ description: Handle judgment calls, scope discipline, and file-editing mechanics
 - Put a call the user's preference decides through the structured question surface, such as `AskUserQuestion` in Claude Code, and fall back to a numbered list in one message where none exists. Rank the recommendation first and mark it, order the rest behind it, and give each option its cost, since an option with no stated cost is picked blind.
 - Author the real choices only. A structured surface appends its own trailing escapes for a free-text answer and for reopening the question as conversation, so never write either as an option. On the numbered-list fallback, say that answering outside the list is fine.
 - Answer from the artifact when one already put the question in writing with a suggestion, rather than re-asking it. A blank `- Answer:` slot in a plan accepts the `- Suggested:` line above it, per the plan standard, which your toolkit resolves by name.
+- Rewrite the `- Suggested:` line rather than the blank `- Answer:` slot when execution decides against an unanswered plan question's suggestion, per the plan standard, which your toolkit resolves by name.
 
 ## Scope discipline
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.57.0",
+  "version": "4.58.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/tasks/validate.ts

@@ -134,14 +134,24 @@ export function backlogPath(root: string): string {
   return join(tasksDir(root), BACKLOG_FILE)
 }
 
+/**
+ * Every link target in a cell, in order. `linkTarget` reads only the first,
+ * which is what the single-link `Task` and `Plan` columns need; `citedStem`
+ * walks the rest to find a blocker cell's bare sibling pointer.
+ */
+function linkTargets(cell: string): string[] {
+  return [...cell.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) =>
+    match[1].trim(),
+  )
+}
+
 /**
  * Pulls the target out of a markdown link, which is how both the `Task` and the
  * `Plan` column spell their pointer. A cell carrying prose instead of a link
  * yields nothing, and that absence is the finding rather than a parse failure.
  */
 function linkTarget(cell: string): string | undefined {
-  const match = /\[[^\]]*\]\(([^)]+)\)/.exec(cell)
-  return match ? match[1].trim() : undefined
+  return linkTargets(cell)[0]
 }
 
 function linkText(cell: string): string {
@@ -874,11 +884,18 @@ function checkFolderClaims(
  * directory names something else and yields nothing. A row waiting on a plan
  * links that plan, and reading its stem as a task would report the row settled
  * against a folder the plan does not sit in.
+ *
+ * A cell can carry more than one link, such as a `Waiting on` cell naming the
+ * record answering the blocker before naming the sibling task it waits on, so
+ * this walks every target rather than reading only the first. It stops at the
+ * first bare one rather than trying a later link when that one fails to
+ * resolve to a stem.
  */
 function citedStem(cell: string): string | undefined {
-  const target = linkTarget(cell)?.split('#')[0]
-  if (!target || target.includes('/')) return undefined
-  return stemOf(target)
+  const target = linkTargets(cell)
+    .map((t) => t.split('#')[0])
+    .find((t) => t && !t.includes('/'))
+  return target ? stemOf(target) : undefined
 }
 
 /** What one blocker citation produced, since a row can be neither settled nor open. */

package/standards/skill.md

@@ -210,6 +210,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, or `teach/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `.claude/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.