@erclx/canon 4.19.0 → 4.19.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.19.0",
+  "version": "4.19.2",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -11,7 +11,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 ## Guards
 
 - All `.canon/plans/` and `.canon/review/` reads resolve at the main worktree root, not the current worktree. Resolve that root the way `claude-worktree` does.
-- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` Every later step keys its output on this slug, being the worktree, the review receipt, the branch, and the memory proposal, regardless of which plan Step 1 reads.
+- Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.` This slug is provisional. It is superseded once `claude-worktree` runs, whether at Step 0 or before this chain began. Every later step keys its output on the slug that run resolves, being the worktree, the review receipt, the branch, and the memory proposal, regardless of which plan Step 1 reads.
 - Resolve `<plan>` in Step 1, ahead of any other read.
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 

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

@@ -61,7 +61,7 @@ What it leaves unmeasured is a prefix reaching no path, so a row left behind by
 
 ## Matching
 
-- Take the changed set from `git diff --name-only <base> HEAD`, resolved against the same base as the diff the body is written from
+- Take the changed set from `git diff --name-only <base>...HEAD`, resolved against the same base as the diff the body is written from. The three dots hold whether `<base>` arrives already resolved to a merge base or as a bare ref name, where the two-dot form is correct only in the first case and hands the branch somebody else's merged paths in the second
 - A path earns a label when the path starts with one of that label's prefixes
 - Collect the distinct labels across the whole set, ordered as the map declares them, so two runs over one branch produce one string
 - Pass the result as a single comma-separated value. An empty result runs no labelling step.

package/docs/agents/key-changes.md

@@ -18,12 +18,14 @@ The positional is the pull request to read, defaulting to the one open on this b
 | Option          | Behavior                                                           |
 | --------------- | ------------------------------------------------------------------ |
 | `--body <path>` | Read the body from a file, taking the changed set from git instead |
-| `--base <ref>`  | Far side of the range when `--body` supplies the body              |
+| `--base <ref>`  | Ref the range runs back to when `--body` supplies the body         |
 | `--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.
 
+`--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`.
+
 Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
 
 That view caps its file list at 100 rows and says nothing about having done so, which was measured against `#1250`: the pull request carries 101 files and the view reports 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.

package/docs/agents/label-coverage.md

@@ -14,11 +14,13 @@ canon labels audit --base origin/main
 canon labels audit src/cli.ts docs/index.md --json
 ```
 
-| Option          | Behavior                                                          |
-| --------------- | ----------------------------------------------------------------- |
-| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
-| `--root <path>` | Repository to read, defaulting to the current directory           |
-| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--base <ref>`  | Ref the range runs back to, defaulting to the trunk        |
+| `--root <path>` | Repository to read, defaulting to the current directory    |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
+
+`--base` names the far side of the range rather than the commit the diff runs against. The audit resolves the merge base between `HEAD` and the ref before reading anything, so `--base origin/main` on a branch the trunk has moved past still earns labels for the paths that branch wrote. Reading the ref literally is what once handed a long-open branch the labels for somebody else's merge, and it named those paths as uncovered surfaces on top.
 
 Positional paths replace the range entirely. A caller holding a changed set already passes it rather than paying for a second git read, and the record then omits `base` to say the range was never resolved.
 

package/docs/agents/test-order.md

@@ -13,11 +13,11 @@ canon gov test-order --base origin/main --json
 canon gov test-order --root ../my-app
 ```
 
-| Option          | Behavior                                                          |
-| --------------- | ----------------------------------------------------------------- |
-| `--base <ref>`  | Far side of the range, defaulting to the merge base against trunk |
-| `--root <path>` | Repository to read, defaulting to the current directory           |
-| `--json`        | Add a machine-readable record on stdout, keeping the frame        |
+| Option          | Behavior                                                   |
+| --------------- | ---------------------------------------------------------- |
+| `--base <ref>`  | Ref the range runs back to, defaulting to the trunk        |
+| `--root <path>` | Repository to read, defaulting to the current directory    |
+| `--json`        | Add a machine-readable record on stdout, keeping the frame |
 
 Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode. A consumer reading stdout sees pure data, and an operator reading the terminal sees why a run refused rather than a command that appeared to do nothing.
 
@@ -27,6 +27,8 @@ The default range is the branch against the trunk, resolved as the merge base ag
 
 Reading all history on every run measures work nobody is reviewing and buries the finding that matters under the ones already merged. `--base` widens or narrows it when a reader wants a different window.
 
+A ref passed there is resolved the same way, through its merge base with `HEAD`, so it names the far side of the range and not the commit the range starts from. `--base origin/main` therefore reports the same window whether the trunk has moved since the branch left or not. Naming a commit the branch already carries still measures from that commit, since the merge base of `HEAD` and an ancestor is the ancestor, and a ref sharing no history with `HEAD` refuses as `bad-base`.
+
 Only history is read. A file sitting in the working tree and in no commit is invisible here, which is the point: the verification run sees a tree at one moment, and the ordering exists nowhere but history.
 
 ## How a pair is decided

package/package.json

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

package/src/commands/pr.ts

@@ -66,7 +66,7 @@ const REFUSALS: Record<Refusal, string> = {
     'git could not list this repository, so no path could be judged whole rather than partial.',
   'no-base': 'No base resolves against the trunk. Fetch origin or pass --base.',
   'bad-base':
-    'The ref passed to --base resolves to no commit here. Pass one this tree carries.',
+    'The ref passed to --base shares no history with HEAD here, either because it resolves to no commit or because it sits on an unrelated root. Pass a ref this branch was taken from.',
   'unreadable-changes':
     'git could not list what this branch changed, so the set is unknown.',
   'no-section': `This body carries no ## ${KEY_CHANGES} section, so it claims nothing to compare.`,

package/src/git-files.ts

@@ -18,24 +18,28 @@ async function git(
 }
 
 /**
- * The far side of a branch range: the ref a caller named, or the merge base
- * against the first trunk this repository carries.
+ * The far side of a branch range: the merge base against the ref a caller
+ * named, or against the first trunk this repository carries.
  *
- * A named ref that resolves to nothing refuses rather than falling back, since
- * measuring the trunk range instead would answer a question nobody asked.
+ * A named ref names the far side rather than the comparison point, so it
+ * resolves through the merge base exactly as the trunk below does. Reading it
+ * literally is what let a trunk moving under an open branch report every path
+ * merged in between as one the branch had written. A caller naming an ancestor
+ * still gets that commit back, since the merge base of `HEAD` and an ancestor
+ * is the ancestor.
+ *
+ * A named ref that produces no merge base refuses rather than falling back,
+ * since measuring the trunk range instead would answer a question nobody
+ * asked. That covers a ref resolving to nothing and a ref sharing no history
+ * with `HEAD` alike, which no caller can separate.
  */
 export async function resolveBaseRef(
   root: string,
   ref?: string,
 ): Promise<string | undefined> {
   if (ref !== undefined) {
-    const resolved = await git(root, [
-      'rev-parse',
-      '--verify',
-      '--quiet',
-      `${ref}^{commit}`,
-    ])
-    return resolved === undefined || resolved === '' ? undefined : resolved
+    const merged = await git(root, ['merge-base', 'HEAD', ref])
+    return merged === undefined || merged === '' ? undefined : merged
   }
 
   for (const trunk of TRUNK_REFS) {

package/src/gov/test-order.ts

@@ -335,11 +335,14 @@ export function readTestOrder(
 }
 
 /**
- * The far side of the range. A ref the caller named has to resolve, since
- * falling back to the trunk there would measure a range nobody asked for. With
- * no ref named, the merge base against the trunk scopes the run to the branch,
- * and a repository carrying no trunk falls back to the root commit rather than
- * refusing.
+ * The far side of the range. A ref the caller named resolves through the merge
+ * base against `head`, matching the no-ref branch below rather than taking the
+ * ref as the comparison point, so a trunk that has moved under the branch does
+ * not pull other people's merged commits into the range. A ref producing no
+ * merge base has to refuse, since falling back to the trunk there would measure
+ * a range nobody asked for. With no ref named, the merge base against the trunk
+ * scopes the run to the branch, and a repository carrying no trunk falls back
+ * to the root commit rather than refusing.
  */
 function resolveBase(
   root: string,
@@ -347,15 +350,15 @@ function resolveBase(
   head: string,
 ): string | { kind: 'unreadable'; reason: TestOrderRefusal; message: string } {
   if (ref !== undefined) {
-    const resolved = revParse(root, ref)
-    if (resolved === undefined) {
+    const merged = git(root, ['merge-base', head, ref])
+    if (merged === undefined || merged === '') {
       return {
         kind: 'unreadable',
         reason: 'bad-base',
-        message: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+        message: `Ref ${ref} shares no history with HEAD in ${root}. Pass a ref this branch was taken from.`,
       }
     }
-    return resolved
+    return merged
   }
 
   for (const trunk of TRUNK_REFS) {

package/src/labels/audit.ts

@@ -10,7 +10,7 @@ import { type MapRefusal, readLabelMap } from '@/labels/map'
  * could not get, which is a broken invocation rather than a project that
  * declared nothing.
  *
- * A named ref that will not resolve is its own reason. Folding it into
+ * A named ref producing no merge base is its own reason. Folding it into
  * `no-base` sends the caller who already passed `--base` a message telling
  * them to pass `--base`.
  */
@@ -31,7 +31,11 @@ export type LabelAudit =
   | { readonly kind: 'refused'; readonly reason: LabelAuditRefusal }
 
 export interface LabelAuditOptions {
-  /** Far side of the range, defaulting to the merge base against the trunk. */
+  /**
+   * Ref naming the far side of the range, which resolves through its merge
+   * base with `HEAD` rather than being compared against literally. Defaults to
+   * the trunk.
+   */
   readonly base?: string
   /** A changed set the caller already holds, which skips git entirely. */
   readonly paths?: readonly string[]

package/src/labels/phase.ts

@@ -1,5 +1,6 @@
 import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
-import { RECORD_ENTRIES, RECORD_ROOTS, spell } from '@/record-root'
+import { RECORD_ENTRIES, RECORD_ROOTS } from '@/record-root'
+import type { RecordRoot } from '@/record-root'
 
 /**
  * The two version namespaces `standards/versioning.md` keeps apart, and why a
@@ -70,13 +71,15 @@ function escapeLiteral(text: string): string {
 }
 
 /**
- * What is ignored under a root beyond the entries the record move relocated.
+ * What is ignored under the tracked root beyond the entries the record move
+ * relocated.
  *
  * `RECORD_ENTRIES` answers which folders that move carried across, and this
- * check asks which paths a reader on a remote cannot open. The two questions
- * differ by exactly one entry: the worktrees folder is ignored and stays out of
- * that list deliberately, since the harness creates a worktree there and
- * requires its target to sit there, so adding it upstream would tell the
+ * check asks which paths a reader on a remote cannot open under `.claude/`,
+ * the one root still read by entry name below. The two questions differ by
+ * exactly one entry: the worktrees folder is ignored and stays out of
+ * `RECORD_ENTRIES` deliberately, since the harness creates a worktree there
+ * and requires its target to sit there, so adding it upstream would tell the
  * migration to relocate a folder the harness pins.
  *
  * It is also the entry a worker announcement names most often, which is what
@@ -85,29 +88,61 @@ function escapeLiteral(text: string): string {
 const IGNORED_BEYOND_RECORDS: readonly string[] = ['worktrees']
 
 /**
- * A path a reader on a remote cannot open, which is a root plus one of the
- * entries that root ignores rather than the root alone.
+ * Which reading each record root takes: `whole` for a root one `.gitignore`
+ * line covers entirely, `entries` for a root kept narrow by name.
  *
- * `.claude/` is tracked and holds `rules`, `skills`, `hooks`, and `context`, so
- * a rule path resolves in any clone and is not a board reference. The scratch
- * folder goes through `spell` because it is the one entry whose name differs by
- * root. Reading the roots and the relocated entries from `src/record-root.ts`
- * is what makes a folder added there matched here without an edit, and the list
- * above is what covers the one thing that module deliberately does not carry.
+ * `.canon/` takes `whole`: the ignore file excludes the folder outright, and
+ * git does not descend into an excluded directory, so no entry list is ever
+ * wider than the root itself. `.claude/` takes `entries` because it is
+ * tracked. A `Record` over `RecordRoot` rather than a filtered list of the
+ * roots read one way, so a root added to `RECORD_ROOTS` fails to typecheck
+ * here until this map says which reading it takes, rather than falling
+ * through a filter into the entry-list branch unnoticed.
+ */
+const ROOT_READING: Record<RecordRoot, 'whole' | 'entries'> = {
+  '.canon': 'whole',
+  '.claude': 'entries',
+}
+
+/**
+ * A path a reader on a remote cannot open.
+ *
+ * The two roots differ by why they are unreadable rather than by which one
+ * they are. A root reading `whole` matches on the root alone, since one
+ * ignore line covers everything beneath it and no entry list can ever be
+ * narrower than that. A root reading `entries` keeps the entry-list reading:
+ * `.claude/` is tracked and holds `rules`, `skills`, `hooks`, and `context`,
+ * so a rule path resolves in any clone and is not a board reference, and only
+ * the entries the record move relocated are unreadable there. Reading the
+ * roots and the relocated entries from `src/record-root.ts` is what makes a
+ * folder added there matched here without an edit, and the list above is what
+ * covers the one thing that module deliberately does not carry.
+ *
+ * The root-alone branch requires at least one tail character ahead of the
+ * shared tail capture, so a root written bare, such as the ignore line naming
+ * it as a concept, reports nothing: there is no path there for an author to
+ * remove. The entry-list branch instead bounds the entry name on the right
+ * with a lookahead, so `plans` does not also match the prefix of a longer
+ * word; that lookahead has to sit inside the entry branch rather than after
+ * the whole alternation; the character right after a bare root is an ordinary
+ * word character, and the same lookahead there would reject every root-alone
+ * match.
  *
- * The tail runs to the first whitespace or closing delimiter, so a report names
- * the whole path an author has to remove rather than the prefix that matched.
+ * The tail runs to the first whitespace or closing delimiter, so a report
+ * names the whole path an author has to remove rather than the prefix that
+ * matched.
  */
 const RECORD_PATH = new RegExp(
-  `(?<![\\w./-])(?:${RECORD_ROOTS.map(
-    (root) =>
-      `${escapeLiteral(root)}/(?:${[
-        ...RECORD_ENTRIES,
-        ...IGNORED_BEYOND_RECORDS,
-      ]
-        .map((entry) => escapeLiteral(spell(root, entry)))
-        .join('|')})`,
-  ).join('|')})(?![\\w-])[^\\s\`)\\]]*`,
+  `(?<![\\w./-])(?:${RECORD_ROOTS.map((root) =>
+    ROOT_READING[root] === 'whole'
+      ? `${escapeLiteral(root)}/(?=[^\\s\`)\\]])`
+      : `${escapeLiteral(root)}/(?:${[
+          ...RECORD_ENTRIES,
+          ...IGNORED_BEYOND_RECORDS,
+        ]
+          .map((entry) => escapeLiteral(entry))
+          .join('|')})(?![\\w-])`,
+  ).join('|')})[^\\s\`)\\]]*`,
   'g',
 )
 

package/standards/publish.md

@@ -40,7 +40,7 @@ This check is one of the two the destination rule above scopes. The reader insid
 
 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.
 
-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/review/feedback/` names a folder the remote's reader cannot open. Under a tracked folder there is no hit, since `.claude/rules/core/005-behavior.md` resolves everywhere.
+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/review/feedback/` names a folder the remote's reader cannot open. Under `.claude/`'s own tracked folders there is no hit, since `.claude/rules/core/005-behavior.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.
 
 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.