@erclx/canon 4.26.0 → 4.26.2

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

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

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

@@ -110,7 +110,7 @@ On success the record carries `from`, `to`, `priorityRowRemoved`, and `indexRege
 
 Each reason has one resolution and none of them is to archive around it:
 
-- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `claude-docs` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. Cut the outcomes first when the work is being abandoned, so the board records what was dropped.
+- `open-outcomes`: the named outcomes are unmarked or genuinely open. Run `claude-docs` when the work shipped and nothing marked it. Leave the task on the board when the outcome is real. When the work is being abandoned, cut it by striking the body, `- ~~<outcome>~~ <why>`, whatever the checkbox holds, so the board records what was dropped rather than meeting this refusal a second time.
 - `ambiguous`: two tasks name one pull request, which is the misfile `${CLAUDE_SKILL_DIR}/../../standards/tasks.md` rules out. Resolve the citation by hand, since no sweep repairs it.
 - `no-match`: the stem or number names nothing on the board. Check the name against the listed stems.
 - `bad-input`: the command line was wrong rather than the board. Read the message, fix the arguments, and run it again. Nothing on the board needs repair, which is what separates this from the two above.

package/docs/agents/key-changes.md

@@ -22,7 +22,7 @@ The positional is the pull request to read, defaulting to the one open on this b
 | `--root <path>` | Repository to read, defaulting to the cwd                          |
 | `--json`        | Add a machine-readable record on stdout, keeping the frame         |
 
-`--body` decides where both halves come from, so a number passed beside it is never read. The body comes off disk and the changed set from the local range, which is the shape a fixture and a body still being drafted both need.
+`--body` decides where both halves come from, so a number passed beside it is never read. The body comes off disk and the changed set from the local range, which is the shape a fixture and a body still being drafted both need. A relative `--body` path resolves against the working directory the command runs from, never against `--root`. `--base` and the changed-file read still resolve against `--root`.
 
 `--base` names the far side of that range and never the commit the comparison runs against directly. The reader resolves the merge base between `HEAD` and the ref, so `--base origin/main` measures what the branch wrote rather than what the trunk gained while the branch was open. Passing the trunk as it stands today is therefore safe on a branch of any age, and a ref sharing no history with `HEAD` refuses as `bad-base`.
 

package/docs/agents/pr-reads.md

@@ -38,7 +38,7 @@ Keying the query on a sha is necessary and not sufficient. The endpoint answered
 
 Both empty cases report `pending` instead: a tip carrying no run yet, and a listing whose rows all belong to some other commit. The record separates them, since `matched` counts the runs belonging to the tip and `foreign` counts the rest, and a caller that wants to tell "not started" from "still going" reads those two numbers rather than the state alone.
 
-`matched` counts runs and not distinct checks, which is where it parts company with the list `gh pr checks` prints. A workflow that fires twice on one commit lands two runs under one name, so a pull request whose body was edited after the push reads 3 against that command's 2. Measured on 2026-09-02 against a commit whose phase-label workflow ran on the push and again on a later body edit. Read a `matched` above the check count as that, rather than as the verb disagreeing with the command.
+The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
 
 A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
 

package/docs/agents/tasks.md

@@ -24,6 +24,8 @@ canon tasks archive --pull-request 673 --json
 
 Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `bad-input`.
 
+An outcome whose body is struck reads as cut rather than open or closed, whatever its checkbox holds: `- ~~<outcome>~~ <why>`. A task carrying only cut outcomes archives, since the gate refuses `no-outcomes` only when both the closed and the cut counts are zero. The success record carries `closed` and `cut` as counts, so a reader tells a shipped task from an abandoned one without opening the file.
+
 The task carries its plan with it. When the closing task is the last live one whose `Plan:` line resolves onto that file, the plan moves to `.canon/plans/archive/` under its own name and the archived task's line is rewritten as `Plan: [feature-<slug>](../../plans/archive/feature-<slug>.md)`, a folder deeper than the live task wrote it. The `plan` field on the success record carries that `from` and `to`, and is `null` when nothing moved.
 
 A plan several tasks share stays where it is, and the task archives anyway. Moving it on the first task to close strands every sibling's pointer at a path that has gone, and `.canon/plans/` is gitignored so no history recovers the target. A `Plan:` line resolving to no file leaves the plan alone too, since a pointer somebody typed wrong is not a plan to move and holding the whole archive over it would park the board behind a repair the merge cannot make.

package/package.json

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

package/src/commands/pr.ts

@@ -349,15 +349,21 @@ async function listFilesByPage(
 /**
  * Reads the body off disk and the changed set from git, which is the shape a
  * fixture and a body still being drafted both need.
+ *
+ * `cwd` and `root` diverge when a caller passes `--root` to read a pull
+ * request against a worktree other than the one they are standing in. The
+ * body path is resolved against `cwd`, since it is correct from where the
+ * caller stands regardless of which tree `--root` names.
  */
 async function readFromFile(
   root: string,
+  cwd: string,
   path: string,
   base: string | undefined,
 ): Promise<SourceRead> {
   let body: string
   try {
-    body = await readFile(resolve(root, path), 'utf8')
+    body = await readFile(resolve(cwd, path), 'utf8')
   } catch {
     return { kind: 'refused', reason: 'unreadable-body' }
   }
@@ -403,7 +409,7 @@ async function runKeyChanges(
   const source =
     opts.body === undefined
       ? await readFromApi(root, number)
-      : await readFromFile(root, opts.body, opts.base)
+      : await readFromFile(root, process.cwd(), opts.body, opts.base)
 
   if (source.kind === 'refused') return refuse(source.reason, emitJson, root)
 
@@ -721,6 +727,11 @@ async function runChecks(
       `${plural(reading.foreign, 'further run')} belonging to another commit, so this listing does not describe the tip alone.`,
     )
   }
+  if (reading.collapsed > 0) {
+    logInfo(
+      `${plural(reading.collapsed, 'run')} folded into a newer run of the same check, so the count above includes a superseded run the state did not use.`,
+    )
+  }
 
   logStep(
     reading.state === 'passing'

package/src/commands/tasks.ts

@@ -825,6 +825,7 @@ function report(
   }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
+  if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
   outro()
 
   return 0
@@ -856,5 +857,7 @@ function recordFor(
           to: relative(root, outcome.plan.to),
         }
       : null,
+    closed: outcome.closed,
+    cut: outcome.cut,
   }
 }

package/src/pr/checks.ts

@@ -5,6 +5,8 @@ export interface RawCheckRun {
   readonly head_sha?: string
   readonly status?: string
   readonly conclusion?: string | null
+  readonly name?: string
+  readonly id?: number
 }
 
 /** What that endpoint returns, count and rows apart. */
@@ -23,6 +25,8 @@ export interface ChecksReading {
   readonly foreign: number
   /** What the endpoint said it holds, which can exceed the rows it returned. */
   readonly reported: number
+  /** Runs `matched` carried for a check name this reading already kept a newer run for. */
+  readonly collapsed: number
 }
 
 /**
@@ -43,6 +47,37 @@ function adapt(run: RawCheckRun): RawCheck {
   }
 }
 
+/**
+ * Keeps the newest run per check name, so a re-triggered gate's stale run
+ * does not outvote its own rerun.
+ *
+ * A run with no name keys on its own position rather than joining an
+ * unnamed group, since nothing ties two nameless runs to the same check. A
+ * run carrying an `id` always outranks one without, and a tie on `id`,
+ * including a pair both missing one, keeps whichever run occurs later in
+ * the array.
+ */
+function newestPerCheck(runs: readonly RawCheckRun[]): {
+  readonly kept: readonly RawCheckRun[]
+  readonly collapsed: number
+} {
+  const bestByKey = new Map<string, RawCheckRun>()
+
+  runs.forEach((run, index) => {
+    const key = run.name !== undefined ? `name:${run.name}` : `pos:${index}`
+    const existing = bestByKey.get(key)
+    const keepCurrent =
+      existing === undefined ||
+      (existing.id === undefined && run.id === undefined) ||
+      (run.id !== undefined &&
+        (existing.id === undefined || run.id >= existing.id))
+    if (keepCurrent) bestByKey.set(key, run)
+  })
+
+  const kept = [...bestByKey.values()]
+  return { kept, collapsed: runs.length - kept.length }
+}
+
 /**
  * Collapses a check-run listing to one word about one commit.
  *
@@ -55,6 +90,12 @@ function adapt(run: RawCheckRun): RawCheck {
  * The foreign test runs ahead of the collapse rather than after it. A listing
  * that describes another commit says nothing about this one, so answering off
  * the matching half would report a verdict on a set known to be incomplete.
+ *
+ * The matched set can still repeat a check name, since a re-triggered gate
+ * creates a second run rather than replacing the first. The final state
+ * rolls up from `newestPerCheck`'s kept rows rather than from `matched`
+ * directly, so a stale failing run left behind by a rerun no longer outvotes
+ * the passing run beside it.
  */
 export function collapseChecks(
   tip: string,
@@ -62,11 +103,13 @@ export function collapseChecks(
 ): ChecksReading {
   const runs = listing.check_runs ?? []
   const matched = runs.filter((run) => run.head_sha === tip)
+  const { kept, collapsed } = newestPerCheck(matched)
   const reading = {
     tip,
     matched: matched.length,
     foreign: runs.length - matched.length,
     reported: listing.total_count ?? runs.length,
+    collapsed,
   }
 
   if (reading.foreign > 0) return { ...reading, state: 'pending' }
@@ -79,5 +122,5 @@ export function collapseChecks(
 
   if (matched.length === 0) return { ...reading, state: 'pending' }
 
-  return { ...reading, state: rollup(matched.map(adapt)) ?? 'pending' }
+  return { ...reading, state: rollup(kept.map(adapt)) ?? 'pending' }
 }

package/src/tasks/archive.ts

@@ -67,6 +67,8 @@ export interface ArchiveSuccess {
   readonly indexRegenerated: boolean
   /** Undefined when the task cited no live plan, or when another task still holds it. */
   readonly plan: PlanMove | undefined
+  readonly closed: number
+  readonly cut: number
 }
 
 export interface ArchiveRefused {
@@ -81,6 +83,7 @@ export type ArchiveOutcome = ArchiveSuccess | ArchiveRefused
 export interface TaskOutcomes {
   readonly open: readonly string[]
   readonly closed: readonly string[]
+  readonly cut: readonly string[]
 }
 
 export function tasksDir(root: string): string {
@@ -93,6 +96,28 @@ export function archiveDir(root: string): string {
 
 export const OUTCOME_PATTERN = /^- \[([ xX])\] ?(.*)$/
 
+/**
+ * A bullet with an optional checkbox, wider than `OUTCOME_PATTERN` so a cut
+ * line missing its checkbox still parses. `record.ts` positions outcomes off
+ * the narrower pattern and stays that way, so a cut line with no checkbox
+ * stays invisible to `canon tasks outcome` by design rather than by oversight.
+ *
+ * Unlike `OUTCOME_PATTERN`, this reaches a struck bullet under any heading,
+ * not only `## Outcomes`, since a checkbox is what confined the narrower
+ * pattern there and a cut line may carry none. No struck bullet sits outside
+ * `## Outcomes` across the live board or the archive as of this change, so
+ * the wider reach is not live, and a heading test is one to add if that stops
+ * holding.
+ */
+const BULLET_PATTERN = /^- (?:\[([ xX])\] ?)?(.*)$/
+
+/**
+ * A struck outcome body, whatever its checkbox holds. The test only checks
+ * the body's start, since the canonical form trails the struck text with why
+ * it was cut: `- ~~<outcome>~~ <why>` leaves `<why>` outside the `~~` pair.
+ */
+const STRUCK_BODY_PATTERN = /^~~.+~~/
+
 /**
  * Marks the lines sitting inside a fenced block, the fence delimiters included.
  * A checkbox in a sample a task displays is not an outcome the task claims, and
@@ -112,31 +137,49 @@ export function fenceMask(lines: readonly string[]): boolean[] {
 }
 
 /**
- * Splits a task's outcome list by checkbox state. The board format puts every
- * outcome at the top level of `## Outcomes`, so an anchored match is enough and
- * no heading tracking is needed.
+ * Splits a task's outcome list by checkbox state, cut outcomes pulled out
+ * ahead of it. The board format puts every outcome at the top level of
+ * `## Outcomes`, so an anchored match is enough and no heading tracking is
+ * needed.
+ *
+ * A struck body reads as cut whatever its checkbox holds, since a dropped box
+ * and a retained one both appear in the tree and neither is the abandoned
+ * work's fault: `- ~~a thing~~` carries no box and would otherwise vanish
+ * from both arrays, `- [ ] ~~a thing~~` would otherwise read as open, and
+ * `- [x] ~~a thing~~` would otherwise read as shipped. Testing the body
+ * before the checkbox is what catches all three under one rule.
  */
 export function readOutcomes(text: string): TaskOutcomes {
   const open: string[] = []
   const closed: string[] = []
+  const cut: string[] = []
   const lines = text.split('\n')
   const fenced = fenceMask(lines)
 
   for (const [index, line] of lines.entries()) {
     if (fenced[index]) continue
 
-    const match = OUTCOME_PATTERN.exec(line)
-    if (!match) continue
+    const bullet = BULLET_PATTERN.exec(line)
+    if (!bullet) continue
+
+    const [, box, rawBody] = bullet
+    const body = rawBody.trim()
+
+    if (STRUCK_BODY_PATTERN.test(body)) {
+      cut.push(body)
+      continue
+    }
+
+    if (box === undefined) continue
 
-    const [, box, body] = match
     if (box === ' ') {
-      open.push(body.trim())
+      open.push(body)
     } else {
-      closed.push(body.trim())
+      closed.push(body)
     }
   }
 
-  return { open, closed }
+  return { open, closed, cut }
 }
 
 /**
@@ -492,17 +535,17 @@ export async function archiveTask(
   const from = join(dir, `${stem}.md`)
   const text = await readFile(from, 'utf8')
 
-  const { open, closed } = readOutcomes(text)
+  const { open, closed, cut } = readOutcomes(text)
 
   if (open.length > 0) {
     return refuse(
       'open-outcomes',
-      `${stem} has ${open.length} open outcome(s). Close them or cut them from the task, then archive.`,
+      `${stem} has ${open.length} open outcome(s). Close them, or cut one with \`- ~~<outcome>~~ <why>\`, then archive.`,
       open,
     )
   }
 
-  if (closed.length === 0) {
+  if (closed.length === 0 && cut.length === 0) {
     return refuse(
       'no-outcomes',
       `${stem} carries no outcomes, so nothing marks it shipped.`,
@@ -538,6 +581,8 @@ export async function archiveTask(
     priorityRowRemoved,
     indexRegenerated: regen.action === 'written',
     plan,
+    closed: closed.length,
+    cut: cut.length,
   }
 }
 

package/standards/architecture.md

@@ -45,13 +45,10 @@ A decision's reasoning stays correct while the numbers it cites move. The anchor
 
 ## Length
 
-Every session pays for this file before any work starts, so it carries a budget. The budget counts decisions rather than lines, because a bare line total is satisfied by merging paragraph pairs and the merged paragraphs then fail the weight checkpoint in `markdown.md`. A file over budget is carrying too many decisions, not decisions written too long.
+Every session pays for this file before any work starts, so a heavy read is a real cost. Judge weight by reading the file rather than by counting it: a file that reads heavy is carrying too many decisions, not decisions written too long.
 
-- Budget six lines per decision entry, being the H3, two paragraphs, and the blank lines separating them.
-- Budget the frame outside `## Key technical decisions` separately, covering the H1, the overview, and the risks. State the number the project takes where it records the budget, since a frame carries no fixed structure to derive one from.
-- Read the ceiling as the frame plus six lines against the decision count, rather than as the total the two multiply out to.
-- Bring an over-budget file back by merging two decisions or retiring one, never by compressing a decision's prose.
-- Yield the budget to the paragraph weight checkpoint when the two disagree. A paragraph past the checkpoint is a defect no budget licenses.
+- Bring a heavy file back by merging two decisions or retiring one, never by compressing a decision's prose.
+- Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
 
 ## Template
 

package/standards/tasks.md

@@ -255,4 +255,4 @@ Archiving a task archives its plan alongside it, when the closing task is that p
 
 One act rather than two is what makes the pair safe. The merge is the event that settles a plan, and a `post-merge` hook reaching the archive with nobody watching cannot act on a warning, so a second call after it would be a second failure point leaving the task archived and the plan live.
 
-A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file.
+A task with an open outcome stays on the board, and so does its plan. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. Cutting means striking the outcome's body: `- ~~<outcome>~~ <why>`. `archiveTask` reads a struck body as cut whatever its checkbox holds, so a task carrying only cut outcomes still archives and a mixed task carries both counts on its success record.