@erclx/canon 4.19.0 → 4.19.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.19.0",
+  "version": "4.19.1",
   "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.1",
   "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[]