@erclx/canon 4.29.0 → 4.29.1

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

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

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -249,8 +249,10 @@ over a plan nobody has written yet.
 
 What a planning dispatch owes instead is the reverse reading, because the plan
 it produces carries a constraint per track in flight and a row planned during a
-wave is planned against a tree that wave is changing. `claude-planner` states that read as a command over open pull
-requests, which is why the brief carries no branch list for it.
+wave is planned against a tree that wave is changing. `claude-planner` composes
+the session roster with the pull request list for that read rather than reading
+pull requests alone, which is why the brief carries no branch list for it: the
+planner takes this reading itself either way.
 
 One row per dispatch. A session reused across a batch pays the context load once
 and ages its picture of the tree while it works, which is what puts the in-flight

package/claude/skills/claude-planner/REQUIREMENT.md

@@ -50,7 +50,7 @@ four carried at least one, caught only because the planner ran
 ## Must
 
 - Assert what a planning session is, what it may not write, and how long the role lasts, since `claude-feature` carries the procedure and no body carries the role
-- State the in-flight read as a command over open pull requests, and say that a branch and a worktree are not evidence, since a count of either reported merged work as live
+- State the in-flight read as a command composing the session roster with open pull requests, and say that a branch and a worktree are not evidence, since a count of either reported merged work as live
 - Run that read once per task rather than once per batch, since a reused session ages its picture of the tree while it works
 - Name every read a plan needed and a launch string did not carry, the task file's findings and the source files among them, since a count quoted from a row was wrong or stale in ten places across four plans
 - Name the validate and audit calls the written plan passes through, since nothing else opens a plan and the audit caught ban hits in three of four trial plans
@@ -73,7 +73,7 @@ four carried at least one, caught only because the planner ran
 ## Guards
 
 - Task file does not resolve from where the session stands: report it unreadable and name the main-root path, rather than reporting the row as absent
-- A read of what is in flight returns nothing: report that no pull request is open rather than falling back to a branch or worktree count
+- A read of what is in flight returns nothing: report that no pull request is open and no live session holds another branch, rather than falling back to a raw branch or worktree count
 - Launch named no controlling session and an operator is present: ask which row to address rather than inferring
 - Launch named no controlling session and nobody is present: infer from the sessions holding no feature branch, never from a name prefix, and say the addressee was inferred
 

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

@@ -39,8 +39,8 @@ Each item below is something a plan needed and a launch string did not carry.
 
 ## Read what is in flight rather than inferring it
 
-- Run `gh pr list --json number,headRefName`, then `git diff --name-only main...<headRefName>` per open pull request, and take every in-flight file set from that pair.
-- A branch is not evidence and neither is a worktree. This repository squash-merges and leaves both behind, so a count of either reports merged work as live. One trial named four branches as in flight and all four had merged.
+- Run `canon sessions list --json`, take the `branch` field of every session whose `repository` matches this one and whose branch is neither null nor the trunk branch, union that with every `headRefName` from `gh pr list --json number,headRefName`, dedupe by branch name, then diff each with `git diff --name-only main...<branch>` for its file set. That resolves locally whether or not a pull request exists, since every track in this repository shares one git directory across its worktrees.
+- A bare branch or worktree with neither a live session nor a pull request behind it is still not evidence, since this repository squash-merges and leaves both behind. The roster read is already filtered to live sessions, so what changed is the second source composed with it rather than a raw count. It still misses a live session that reached its worktree through the direct-path fallback rather than `EnterWorktree`, since that session's registered branch never moves off the trunk.
 - Run the read once per task rather than once per batch. A session planning several rows ages its picture of the tree while it works, and this read is what dates it.
 - Name each in-flight set as a constraint, say which act it forbids, and stamp the block with the commit the tree was read at, per Constraints in the plan standard. A bare path list leaves the worker guessing.
 

package/docs/agents/key-changes.md

@@ -53,17 +53,17 @@ The cut used to decide whether a span was read at all, and the paths past the co
 
 A span anywhere in the bullet has to survive all of these:
 
-| Rule                                              | What it keeps out                                      |
-| ------------------------------------------------- | ------------------------------------------------------ |
-| No whitespace, `<`, `>`, `$`, `*`, `\|`, `?`, `^` | A backticked command, a placeholder, a glob, a pattern |
-| No `://` and no leading `/`, `~`, `@`, `#`, `!`   | A URL, an absolute path, a module alias                |
-| Contains `/`                                      | A bare filename with no folder around it               |
-| Not a dotted-decimal segment, or ends with `/`    | A dotted number such as an address                     |
-| Not a single top-level folder                     | `src/`, which nobody claims to have rewritten whole    |
-| A `file:line` span leads its bullet               | A citation into a file the bullet is describing        |
-| The region carries no no-change marker            | A bullet recording a file it deliberately left alone   |
-
-The last three rows earn their place from the corpus rather than from a rule. Every body that spelled a lone top-level folder was naming where something lives, and a line citation that follows another claim in the same bullet points into the file being described rather than naming a second one. A line citation leading its bullet stays a claim, which is how a body names the exact line it rewrote.
+| Rule                                                                                   | What it keeps out                                                                      |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| No whitespace, `<`, `>`, `$`, `*`, `\|`, `?`, `^`                                      | A backticked command, a placeholder, a glob, a pattern                                 |
+| No `://` and no leading `/`, `~`, `@`, `#`, `!`                                        | A URL, an absolute path, a module alias                                                |
+| Contains `/`                                                                           | A bare filename with no folder around it                                               |
+| Not a dotted-decimal segment, or ends with `/`                                         | A dotted number such as an address                                                     |
+| Not a single top-level folder                                                          | `src/`, which nobody claims to have rewritten whole                                    |
+| A `file:line` span leads its bullet, or the bullet carries no bare line-only companion | A citation into a file the bullet already named, such as `verify.sh:634` beside `:642` |
+| The region carries no no-change marker                                                 | A bullet recording a file it deliberately left alone                                   |
+
+The last three rows earn their place from the corpus rather than from a rule. Every body that spelled a lone top-level folder was naming where something lives, and a line citation that follows another claim in the same bullet points into the file being described only when a bare line-only span sits beside it, such as `:642` following `verify.sh:634`. With no such companion the citation names a second, genuinely distinct file and stays a claim. A line citation leading its bullet stays a claim either way, which is how a body names the exact line it rewrote.
 
 The no-change marker is the one rule the region cut cannot substitute for. A body writes "Leave `x` untouched, since the decision keeps it" to record a change it declined, and the path sits ahead of the first comma, so a stricter cut would not reach it and a looser one would find more. Since `keep` and `leave` each open a real claim often enough, the marker decides it rather than the leading verb. Three words carry the set: `untouched`, `unchanged`, and `as written`. `in place` was measured and dropped, because rewriting a file in place is an ordinary claim, and `no other line` was dropped because a correct bullet writes "as one insertion that touches no other line" about a change it did make. `alone` shipped in the set too, until review found every corpus occurrence sitting past the first comma, where the cut already excludes it, so the word voided no true claim there. Restrictive use is the more common one in this repository's own prose, and a comma-free bullet exposed it: "Move the threshold read into `src/gate/stages.ts` alone" asserts an edit, and the marker voided it while the word was still in the set. Over the 40-pull-request corpus the rule still voids no true claim.
 

package/docs/workflow/operating-model.md

@@ -77,7 +77,7 @@ start, and only a count of the defect's extent decides how big it is.
 
 One feature travels this path end to end.
 
-1. The next feature is planned with `claude-feature`, writing a plan to `.canon/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight from open pull requests rather than from branches and worktrees, which this repository leaves behind after a squash merge.
+1. The next feature is planned with `claude-feature`, writing a plan to `.canon/plans/`. The orchestrator runs it warm when the row turns on a contract other features consume or a shared wiring seam, and dispatches a planner under `claude-planner` otherwise. A cold planner measures the row against the tree rather than trusting what the row claims, and it reads what is in flight by composing the live session roster with open pull requests. A bare branch or worktree is not evidence on its own, since this repository leaves both behind after a squash merge.
 2. Orchestrator checks the plan waits on nobody, checks the branch is unclaimed, and checks the plan's file set is disjoint from every track in flight, then dispatches a background worker with `claude --bg` against the plan, naming the branch and the model on the launch rather than leaving the worker to derive either. No count caps how many run at once. The branch travels as the argument to the worker's own worktree call, which is the one place the name is read rather than inferred. It falls back to naming the invocation for a human to run through `claude-worktree` and `claude-autoship` when the plan still waits on an answer only the operator can give, the check refuses, the sets overlap, or a stated reason serializes the plan behind a track already in flight. Either way, the worker enters its own worktree, builds, self-checks, opens a PR, and stops at the PR boundary.
 3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
 4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `canon sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.

package/package.json

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

package/src/pr/paths.ts

@@ -54,9 +54,6 @@ export type KeyChangeRead =
 /** The longest bullet a claim carries forward, matching the citation sweep. */
 const PREVIEW_LIMIT = 200
 
-/** A backticked span, the only carrier this corpus writes a path in. */
-const BACKTICKED = /`([^`\n]+)`/g
-
 /** A list item at any indent, in either bullet spelling or as an ordinal. */
 const BULLET = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/
 
@@ -70,6 +67,15 @@ const HEADING = /^(#{1,6})\s+(.+?)\s*$/
  */
 const LINE_SUFFIX = /:\d+(?:-\d+)?$/
 
+/**
+ * A span that carries a line suffix and nothing else, such as `:642` beside
+ * an earlier `verify.sh:634`. Its presence is what tells the citation guard
+ * below the bullet is describing lines inside one already-claimed file rather
+ * than naming a second file, since a genuinely distinct file never gets cited
+ * by a bare line number with nothing in front of the colon.
+ */
+const BARE_LINE = /^:\d+(?:-\d+)?$/
+
 /**
  * A character that puts the span outside a path this comparison resolves.
  *
@@ -108,9 +114,73 @@ function isDottedNumber(span: string): boolean {
   return /^\d+(?:\.\d+)+$/.test(segment)
 }
 
+/** One code span, paired by matching backtick-run length rather than count. */
+interface BacktickSpan {
+  /** Index of the opening run's first backtick. */
+  readonly start: number
+  /** Index one past the closing run's last backtick. */
+  readonly end: number
+  /** The text between the two runs, delimiters excluded. */
+  readonly content: string
+}
+
+/**
+ * Every code span in a bullet, pairing a run of backticks only with the next
+ * run of the same length.
+ *
+ * A single-backtick regex reads a doubled delimiter, such as
+ * ``` ``git status`` ```, as two unrelated single backticks: it opens on the
+ * second backtick of the pair, closes on the first backtick of the closing
+ * pair, and leaves one backtick before and after the span unconsumed. Every
+ * scan after that treats a stray leftover backtick as an opener, which
+ * absorbs the next real span's opening delimiter as its closer and drops the
+ * path inside past it. Pairing by run length rather than by single backtick
+ * keeps a doubled delimiter closed by a doubled delimiter, so nothing after
+ * it loses its pairing.
+ *
+ * An opening run with no same-length run after it is not a delimiter, per
+ * CommonMark, so it is left as literal text and the scan resumes at the next
+ * run rather than backtracking into the unmatched one.
+ */
+function findBacktickSpans(text: string): BacktickSpan[] {
+  const runs = [...text.matchAll(/`+/g)].map((match) => ({
+    start: match.index ?? 0,
+    length: match[0].length,
+  }))
+
+  const spans: BacktickSpan[] = []
+  let i = 0
+  while (i < runs.length) {
+    const open = runs[i]
+    const closeIndex = runs.findIndex(
+      (run, index) => index > i && run.length === open.length,
+    )
+    if (closeIndex === -1) {
+      i += 1
+      continue
+    }
+    const close = runs[closeIndex]
+    spans.push({
+      start: open.start,
+      end: close.start + close.length,
+      content: text.slice(open.start + open.length, close.start),
+    })
+    i = closeIndex + 1
+  }
+
+  return spans
+}
+
 /** Blanks every backticked span so a cue search never fires inside one. */
 function maskSpans(text: string): string {
-  return text.replace(/`[^`\n]*`/g, (span) => ' '.repeat(span.length))
+  let out = text
+  for (const span of findBacktickSpans(text)) {
+    out =
+      out.slice(0, span.start) +
+      ' '.repeat(span.end - span.start) +
+      out.slice(span.end)
+  }
+  return out
 }
 
 /**
@@ -329,10 +399,20 @@ export function extractKeyChangePaths(
     if (disclaimsChange(trimmed)) continue
 
     const accusesBefore = claimRegion(trimmed).length
+    const spans = findBacktickSpans(trimmed)
+    // Whether a `file:line` span citing an already-claimed file is a second
+    // claim or a citation into the file just claimed turns on this: a bullet
+    // that also carries a bare `:642`-shaped span alongside it is describing
+    // two lines in one file, where a bullet with no such companion is naming
+    // a second, genuinely distinct file. Computed once, up front, so the
+    // guard below reads it rather than scanning again for every span.
+    const hasBareLineCompanion = spans.some((span) =>
+      BARE_LINE.test(span.content),
+    )
     let claimed = false
 
-    for (const match of trimmed.matchAll(BACKTICKED)) {
-      const span = match[1] ?? ''
+    for (const match of spans) {
+      const span = match.content
       const bare = span.replace(LINE_SUFFIX, '')
 
       // A `file:line` span following another claim in the same bullet is a
@@ -342,7 +422,7 @@ export function extractKeyChangePaths(
       // its bullet it is an ordinary claim, which is how a body names the exact
       // line it rewrote.
       const cited = bare !== span
-      if (cited && claimed) continue
+      if (cited && claimed && hasBareLineCompanion) continue
 
       const resolved = resolveSpan(bare)
       if (resolved === undefined) continue
@@ -357,7 +437,7 @@ export function extractKeyChangePaths(
         path: resolved.path,
         directory: resolved.directory,
         anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
-        leading: (match.index ?? 0) < accusesBefore,
+        leading: match.start < accusesBefore,
         span,
         bullet: index + 1,
         preview,