@erclx/canon 4.18.0 → 4.19.0

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.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "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/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.