@erclx/canon 4.18.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.18.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/commands.md

@@ -68,7 +68,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon secrets scan`          | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                                                 |
 | `canon deps audit`            | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)                        |
 | `canon labels audit`          | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)                                                         |
-| `canon labels scan`           | Fail a pull request whose title or body names the board, by a phase label, a label a code span quotes, or a gitignored record path (`--event`, `--json`)              |
+| `canon labels scan`           | Fail a pull request whose title or body carries a phase label, a label a code span quotes, a gitignored record path, or a session link (`--event`, `--json`)          |
 | `canon autoship classify`     | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
 | `canon pr key-changes`        | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
 | `canon repo metadata propose` | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)      |

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.18.0",
+  "version": "4.19.1",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/labels.ts

@@ -90,7 +90,7 @@ export function register(program: Command): void {
   labels
     .command('scan')
     .description(
-      'Fail a pull request whose title or body carries a phase label or a board identifier',
+      'Fail a pull request whose title or body carries a phase label, a board identifier, or a session link',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option(
@@ -118,10 +118,16 @@ export function register(program: Command): void {
         'copy of. A path under a tracked folder is left alone, so a rule or a',
         'skill any clone resolves is not reported.',
         '',
+        'It reports a session link as the third category, being a link to one',
+        'Claude Code session, which the harness appends to text it tells a',
+        'session to publish. That link resolves for the one account holding the',
+        'session and for no other reader, which no clone repairs, so it is read',
+        'on a release pull request too, where the board identifier is not.',
+        '',
         'Exit codes:',
-        '  0  no phase label and no board identifier found',
+        '  0  no phase label, no board identifier, and no session link found',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  the title or body carries a phase label or a board identifier',
+        '  2  the title or body carries one of the three',
         '',
         'Examples:',
         '  canon labels scan --event "$GITHUB_EVENT_PATH"',
@@ -363,6 +369,16 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const reference of result.boardReferences) logWarn(reference)
   }
 
+  logStep(result.sessionLinks.length === 0 ? 'Clean' : 'Session link found')
+  if (result.sessionLinks.length === 0) {
+    logInfo('no session link in the title or body')
+  } else {
+    logWarn(
+      `${plural(result.sessionLinks.length, 'session link')} in the title or body. Delete every hit rather than rewriting it, since a session resolves for the one account that started it and for no other reader.`,
+    )
+    for (const link of result.sessionLinks) logWarn(link)
+  }
+
   outro()
 
   if (emitJson) {
@@ -372,11 +388,14 @@ async function runScan(opts: ScanOptions): Promise<number> {
         phaseLabels: result.phaseLabels,
         semverTags: result.semverTags,
         boardReferences: result.boardReferences,
+        sessionLinks: result.sessionLinks,
       })}\n`,
     )
   }
 
-  return result.phaseLabels.length === 0 && result.boardReferences.length === 0
+  return result.phaseLabels.length === 0 &&
+    result.boardReferences.length === 0 &&
+    result.sessionLinks.length === 0
     ? 0
     : 2
 }

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

@@ -34,6 +34,19 @@ export interface PhaseScanResult {
    * nor the gitignored folder a path names.
    */
   readonly boardReferences: readonly string[]
+  /**
+   * A link to one Claude Code session, which the harness appends to text it
+   * tells a session to publish.
+   *
+   * It sits beside the board references rather than inside them because the
+   * two are unresolvable for different reasons. A record path fails for a
+   * reader holding no copy of this checkout, and a session link fails for
+   * everyone outside the one account that holds the session, which no clone
+   * and no checkout repairs. The report line for a board reference names a
+   * record path and a quoted label, so a session link folded in would be
+   * reported under a sentence that does not describe it.
+   */
+  readonly sessionLinks: readonly string[]
 }
 
 const VERSION_TOKEN = /\bv\d+(?:\.\d+){1,2}\b/g
@@ -98,6 +111,26 @@ const RECORD_PATH = new RegExp(
   'g',
 )
 
+/**
+ * A link to one Claude Code session, matched on the host and the path segment
+ * rather than on the identifier alphabet.
+ *
+ * The two instances on the trunk carry a 24-character identifier after
+ * `session_`, and reading that shape into the pattern would empty this check
+ * the moment the harness changed it, with nothing left to report and no
+ * failure to notice. The host and the path segment are what the harness has to
+ * keep for the link to resolve at all. A host change still gets past this and
+ * nothing detects that.
+ *
+ * The scheme is optional because it is incidental to the two parts being
+ * matched, so a link written without it is the same unresolvable reference.
+ * The tail runs to the first whitespace or closing delimiter, which is how a
+ * record path is read, so a report names the whole link rather than the prefix
+ * that matched.
+ */
+const SESSION_LINK =
+  /(?<![\w./-])(?:https?:\/\/)?claude\.ai\/code\/session_[^\s`)\]]+/g
+
 /**
  * The head branch release-please opens every release pull request under.
  *
@@ -180,6 +213,16 @@ function recordPaths(text: string): string[] {
   ]
 }
 
+function sessionLinks(text: string): string[] {
+  return [
+    ...new Set(
+      (text.match(SESSION_LINK) ?? []).map((link) =>
+        link.replace(TRAILING_PUNCTUATION, ''),
+      ),
+    ),
+  ]
+}
+
 /**
  * Reads a title and a body for version-shaped tokens and sorts every one
  * found into the namespace this pull request is allowed to carry.
@@ -197,11 +240,22 @@ function recordPaths(text: string): string[] {
  * body without passing the gate on its own. That its author has nothing to
  * rewrite is true as well and is the weaker half, since it would leave the
  * reference standing and unresolvable.
+ *
+ * A session link is reported on both paths, the release one included. Nothing
+ * appends one to a release body, which release-please generates with no
+ * session in the loop, so populating the field there costs nothing on every
+ * run this repository has seen. What it buys is that the coverage argument
+ * above never has to hold for this category: that argument reasons from every
+ * commit in the generated history having passed this gate, and a link the gate
+ * did not yet scan for would reach a release body under it. Reading the whole
+ * body on both paths leaves no hole if the premise ever slips.
  */
 export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
   const source = `${input.title}\n${input.body}`
+  const outsideFences = linesOutsideFences(source).join('\n')
   const tokens = versionTokens(readable(source))
   const cutsRelease = isReleasePullRequest(input)
+  const links = sessionLinks(outsideFences)
 
   if (cutsRelease) {
     return {
@@ -209,6 +263,7 @@ export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
       phaseLabels: [],
       semverTags: tokens,
       boardReferences: [],
+      sessionLinks: links,
     }
   }
 
@@ -222,9 +277,7 @@ export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
     cutsRelease,
     phaseLabels: tokens,
     semverTags: [],
-    boardReferences: [
-      ...quoted,
-      ...recordPaths(linesOutsideFences(source).join('\n')),
-    ],
+    boardReferences: [...quoted, ...recordPaths(outsideFences)],
+    sessionLinks: links,
   }
 }

package/standards/pr.md

@@ -14,7 +14,7 @@ Does not govern:
 - Commit subject format, which shares the title form: `commit.md`
 - Branch naming: `branch.md`
 - Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
-- Whether a quoted label or a gitignored record path may appear in a title or body, which `canon labels scan` fails on: `publish.md`
+- Whether a quoted label, a gitignored record path, or a link to one Claude Code session may appear in a title or body, which `canon labels scan` fails on: `publish.md`
 - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
 - Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 
@@ -46,6 +46,7 @@ Does not govern:
 - Use checkboxes, never prose. See Testing discipline for which box gets ticked.
 - `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
 - Visuals: include only when they clarify architecture, UI, or complex logic flows
+- The list is closed. A body carries the sections above and nothing after the last of them, which covers a trailer a harness appends once the body is composed. `publish.md` states the rule, and `canon labels scan` fails on the one such trailer measured so far.
 
 ## Testing discipline
 

package/standards/publish.md

@@ -46,6 +46,16 @@ Rewrite a hit to name what the reader can reach rather than deleting it. A row's
 
 `canon labels scan` runs this check and the phase-label one over a pull request title and body. It reads that pair alone, so every other channel is the author's own scan.
 
+## Session links
+
+A link to one Claude Code session names the session that wrote the text rather than the change the text describes. It enters because the harness tells the composing session to end its published text with one, so the author writes it deliberately and it reads as required rather than as a slip. That is what carries it past a scan the same author runs, and it is why a rule stating the ban does not reach the case: the session is following an instruction it was given, and reads its own compliance as correct.
+
+This check depends on the reader holding the account rather than the checkout, which is narrower than the dependency the destination rule above scopes. A reader inside this checkout opens a record path and still cannot open a session, since the session resolves for the one account that started it and for nobody else. The scoping still sits at the invocation site, because `canon labels scan` reads a pull request title and body and reaches no other text.
+
+Delete a hit rather than rewriting it. The other two checks replace a hit with what the reader can reach instead, and a session has no such form, so what stands in its place is the body already written above it.
+
+Removing the link before a merge does not substitute for never writing it. One branch removed it, read the live body back clean, and the squashed commit landed carrying it anyway off an earlier snapshot, which is permanent on the trunk.
+
 ## Cross-reference form
 
 A number referring to a pull request or an issue takes the form its destination renders. Write it bare where the destination auto-links it, and in backticks where it does not. Both spellings are correct, each in one place, so a reference moved from one destination to the other is rewritten rather than copied.