@erclx/canon 4.15.1 → 4.17.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.15.1",
+  "version": "4.17.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 carries a phase label, sorting a release pull request's tokens as semver rather than as a leak (`--event`, `--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 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.15.1",
+  "version": "4.17.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',
+      'Fail a pull request whose title or body carries a phase label or a board identifier',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option(
@@ -112,10 +112,16 @@ export function register(program: Command): void {
         'other pull request may carry neither, so any token found there is a',
         'leaked phase label.',
         '',
+        'It reports a board identifier beside that, being text naming the task',
+        'board rather than the change: a version token a code span quotes, and a',
+        'path under a record root, both of which a reader on the remote holds no',
+        'copy of. A path under a tracked folder is left alone, so a rule or a',
+        'skill any clone resolves is not reported.',
+        '',
         'Exit codes:',
-        '  0  no phase label found',
+        '  0  no phase label and no board identifier found',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  the title or body carries a phase label',
+        '  2  the title or body carries a phase label or a board identifier',
         '',
         'Examples:',
         '  canon labels scan --event "$GITHUB_EVENT_PATH"',
@@ -345,6 +351,18 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const label of result.phaseLabels) logWarn(label)
   }
 
+  logStep(
+    result.boardReferences.length === 0 ? 'Clean' : 'Board identifier found',
+  )
+  if (result.boardReferences.length === 0) {
+    logInfo('no quoted label or record path in the title or body')
+  } else {
+    logWarn(
+      `${plural(result.boardReferences.length, 'board identifier')} in the title or body. Name what a reader on the remote can open, since a record path is gitignored there and a quoted label reads as one only from the board.`,
+    )
+    for (const reference of result.boardReferences) logWarn(reference)
+  }
+
   outro()
 
   if (emitJson) {
@@ -353,9 +371,12 @@ async function runScan(opts: ScanOptions): Promise<number> {
         cutsRelease: result.cutsRelease,
         phaseLabels: result.phaseLabels,
         semverTags: result.semverTags,
+        boardReferences: result.boardReferences,
       })}\n`,
     )
   }
 
-  return result.phaseLabels.length === 0 ? 0 : 2
+  return result.phaseLabels.length === 0 && result.boardReferences.length === 0
+    ? 0
+    : 2
 }

package/src/gate/measures.ts

@@ -164,6 +164,94 @@ export const unreferencedRules: Measure = async (ctx) => {
   }
 }
 
+/**
+ * The files the sweep would rewrite, each with its own count, taken from the
+ * `paths` array the record carries beside the total.
+ *
+ * Every field is tested rather than trusted. The record reaches here as parsed
+ * JSON rather than as a type the compiler checked, so a shape that moved
+ * upstream drops the entries it can no longer read and leaves the count that
+ * was read from a field of its own standing.
+ */
+function citedPaths(record: { paths?: unknown } | undefined): string[] {
+  if (!Array.isArray(record?.paths)) return []
+
+  return record.paths.flatMap((entry) => {
+    const cited = entry as { path?: unknown; rewritten?: unknown }
+    if (typeof cited.path !== 'string') return []
+    return typeof cited.rewritten === 'number'
+      ? [`${cited.path} (${cited.rewritten})`]
+      : [cited.path]
+  })
+}
+
+/**
+ * A second run of the records move should rewrite nothing, and the count is
+ * only knowable once the folders themselves have landed.
+ *
+ * `moves` empty means every record folder already sits at `.canon/`, so any
+ * citation the sweep would still rewrite is one the move left stale, which is
+ * the defect this stage exists to catch. Where `moves` is nonempty the tree has
+ * not migrated at all and a nonzero rewrite count is the verb describing its
+ * own first pass, so the reading is reported and never failed on.
+ *
+ * Exit `0` is a tree with nothing to do and exit `2` is a plan drawn without
+ * `--write`, so both read a tree and both carry a record. Every other exit is a
+ * refusal that planned nothing, which is unmeasured for the reason the markdown
+ * stage treats its own refusal exit so.
+ */
+export const recordIdempotence: Measure = async (ctx) => {
+  const run = await ctx.cli(['migrate', 'records', '--json'])
+
+  if (run.exitCode !== 0 && run.exitCode !== 2) {
+    return {
+      emissions: [],
+      unmeasured: `The records sweep refused (exit ${run.exitCode}) and planned nothing.`,
+    }
+  }
+
+  const record = parseJson(run.stdout) as
+    | { moves?: unknown; rewritten?: unknown; paths?: unknown }
+    | undefined
+  const moves = record?.moves
+  const rewritten = record?.rewritten
+
+  if (!Array.isArray(moves) || typeof rewritten !== 'number') {
+    return {
+      emissions: [],
+      unmeasured:
+        'The records sweep carried no plan, so the stage read no count. Run bun src/cli.ts migrate records --json.',
+    }
+  }
+
+  if (moves.length > 0) {
+    return {
+      emissions: [
+        info(
+          `${moves.length} record folder(s) still at the old root, with ${rewritten} citation(s) that move with them`,
+        ),
+      ],
+    }
+  }
+
+  if (rewritten > 0) {
+    return {
+      // The payload already names every file, so listing them here is what
+      // separates a count a reader has to go and reproduce from a remedy they
+      // can act on. A malformed `paths` costs the list and not the finding,
+      // since the count above it was read from a field of its own.
+      emissions: citedPaths(record).map((path) => warn(path)),
+      failure: `The records are at .canon/ and ${rewritten} citation(s) still name the old root, so a second run of canon migrate records would rewrite them. Repoint each one, or mark it canon-keep-record-root where the sentence has to keep the old spelling.`,
+    }
+  }
+
+  return {
+    emissions: [
+      info('Records at .canon/, and a re-run of the move rewrites nothing'),
+    ],
+  }
+}
+
 /**
  * A banned character, word, or spelling is a fact rather than a threshold, so
  * it fails the push while bullet, paragraph, and depth weight stay advisory.

package/src/gate/stages.ts

@@ -4,6 +4,7 @@ import {
   markdownBans,
   type Measure,
   pluginManifests,
+  recordIdempotence,
   sandboxCoverage,
   seedStandards,
   standardCriteria,
@@ -337,6 +338,17 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Rule citations resolve',
   },
+  {
+    // A citation naming the old record root resolves to nothing once the
+    // folders have moved, and the sweep that would repoint it only runs when a
+    // person calls it. Reading its plan back is what turns a silent stale
+    // citation into a stopped push, and it sits with the two citation stages
+    // above rather than at the end of the file because it answers their
+    // question about a root rather than a path.
+    id: 'record-idempotence',
+    label: 'Record idempotence',
+    checks: [{ kind: 'measure', measure: recordIdempotence }],
+  },
   {
     id: 'markdown-bans',
     label: 'Markdown bans',

package/src/labels/phase.ts

@@ -1,4 +1,5 @@
 import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
+import { RECORD_ENTRIES, RECORD_ROOTS, spell } from '@/record-root'
 
 /**
  * The two version namespaces `standards/versioning.md` keeps apart, and why a
@@ -22,10 +23,81 @@ export interface PhaseScanResult {
   readonly cutsRelease: boolean
   readonly phaseLabels: readonly string[]
   readonly semverTags: readonly string[]
+  /**
+   * Text naming the board rather than the change: a version token a code span
+   * quotes, and a path under a record root.
+   *
+   * It sits beside the two namespaces rather than inside either, because a
+   * record path is version-shaped in neither and a quoted token is one the
+   * reading below has already declined to sort. Both are one defect at the
+   * destination, which is a reader on a remote holding neither the task board
+   * nor the gitignored folder a path names.
+   */
+  readonly boardReferences: readonly string[]
 }
 
 const VERSION_TOKEN = /\bv\d+(?:\.\d+){1,2}\b/g
 
+/**
+ * A code span holding a version token and nothing else.
+ *
+ * The closing delimiter refers back to the opening one, so a span opened on two
+ * backticks closes on two, which is the rule `maskCodeSpans` reads a span by.
+ * Content is the token alone rather than a token found inside longer content,
+ * which is the whole of what separates a quoted phase label from `#1208`.
+ */
+const VERSION_SPAN = /(`+)(v\d+(?:\.\d+){1,2})\1/g
+
+/** Sentence punctuation a path picks up at the end of a clause. */
+const TRAILING_PUNCTUATION = /[.,;]+$/
+
+/** Escapes a literal so it can sit inside a constructed pattern. */
+function escapeLiteral(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * What is ignored under a 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
+ * migration to relocate a folder the harness pins.
+ *
+ * It is also the entry a worker announcement names most often, which is what
+ * makes the gap a live class rather than a theoretical one.
+ */
+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.
+ *
+ * `.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.
+ *
+ * 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\`)\\]]*`,
+  'g',
+)
+
 /**
  * The head branch release-please opens every release pull request under.
  *
@@ -53,6 +125,15 @@ function isReleasePullRequest(input: PhaseScanInput): boolean {
   )
 }
 
+/** Replaces a version span's delimiters with spaces, holding the line's width. */
+function unquoteVersionSpans(line: string): string {
+  return line.replace(
+    VERSION_SPAN,
+    (_span, ticks: string, token: string) =>
+      `${' '.repeat(ticks.length)}${token}${' '.repeat(ticks.length)}`,
+  )
+}
+
 /**
  * Drops a fenced block outright and blanks a code span inside what remains,
  * so a token quoted rather than written is read the way a reader reads it:
@@ -69,9 +150,34 @@ function isReleasePullRequest(input: PhaseScanInput): boolean {
  * compare link's URL, and masking it would empty `semverTags` on the one
  * pull request this check exists to pass, trading the corpus's one code-span
  * leak for a hole in every release.
+ *
+ * `keepVersionSpans` widens that reading for the board-reference pass alone. A
+ * span whose whole content is a version token survives it, which is the shape
+ * the leak reached the remote through, and longer content stays blanked, which
+ * is what holds `#1208` closed. Two passes over one source rather than one pass
+ * sorting its own output, because a token is a board reference by virtue of the
+ * span it came out of and nothing downstream of the match can see that.
  */
-function readable(text: string): string {
-  return linesOutsideFences(text).map(maskCodeSpans).join('\n')
+function readable(text: string, keepVersionSpans = false): string {
+  return linesOutsideFences(text)
+    .map((line) =>
+      maskCodeSpans(keepVersionSpans ? unquoteVersionSpans(line) : line),
+    )
+    .join('\n')
+}
+
+function versionTokens(text: string): string[] {
+  return [...new Set(text.match(VERSION_TOKEN) ?? [])]
+}
+
+function recordPaths(text: string): string[] {
+  return [
+    ...new Set(
+      (text.match(RECORD_PATH) ?? []).map((path) =>
+        path.replace(TRAILING_PUNCTUATION, ''),
+      ),
+    ),
+  ]
 }
 
 /**
@@ -83,13 +189,42 @@ function readable(text: string): string {
  * legitimately carries, and every other pull request's tokens are read as
  * leaked phase labels, which is what `standards/versioning.md` names the
  * defect this exists to catch.
+ *
+ * A release pull request reports no board reference either, and the ground is
+ * coverage rather than exemption. Release-please generates that body from
+ * merged history, and every commit in that history came through a pull request
+ * this same check already scanned, so a board reference cannot reach a release
+ * 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.
  */
 export function scanPhaseLabels(input: PhaseScanInput): PhaseScanResult {
-  const text = readable(`${input.title}\n${input.body}`)
-  const tokens = [...new Set(text.match(VERSION_TOKEN) ?? [])]
+  const source = `${input.title}\n${input.body}`
+  const tokens = versionTokens(readable(source))
   const cutsRelease = isReleasePullRequest(input)
 
-  return cutsRelease
-    ? { cutsRelease, phaseLabels: [], semverTags: tokens }
-    : { cutsRelease, phaseLabels: tokens, semverTags: [] }
+  if (cutsRelease) {
+    return {
+      cutsRelease,
+      phaseLabels: [],
+      semverTags: tokens,
+      boardReferences: [],
+    }
+  }
+
+  // Dropped where the same token is also written bare, since the phase-label
+  // half already names it and reporting it twice asks for one removal twice.
+  const quoted = versionTokens(readable(source, true)).filter(
+    (token) => !tokens.includes(token),
+  )
+
+  return {
+    cutsRelease,
+    phaseLabels: tokens,
+    semverTags: [],
+    boardReferences: [
+      ...quoted,
+      ...recordPaths(linesOutsideFences(source).join('\n')),
+    ],
+  }
 }

package/standards/pr.md

@@ -14,6 +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`
 - Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
 - Punctuation, formatting, and banned words in pull request prose: `markdown.md`
 

package/standards/publish.md

@@ -22,6 +22,8 @@ Wherever text leaves through a channel no automated check covers, the author is
 
 Run the scan as an explicit step against the finished text. Having read the underlying rules before drafting does not cover it, because the check has to happen after the text exists.
 
+Scope every check below by destination. Text published to a remote takes all of them. Text staying in the repository takes the character bans alone, since those hold wherever the text lands, and skips whichever check depends on the reader holding something only this checkout carries. The two checks below that depend on it say so under their own headings.
+
 ## Banned characters
 
 `markdown.md` holds the character bans and the banned words alike. Read it at scan time rather than working the sets from memory, then scan the drafted text and rewrite each occurrence.
@@ -32,7 +34,17 @@ Restructure the sentence rather than substituting the character. A semicolon swa
 
 `versioning.md` holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
 
-Scope this check by destination. Text published to a remote takes it. Text scanned on its way into the repository, where the reader has the task board, skips it.
+This check is one of the two the destination rule above scopes. The reader inside the repository has the task board and the reader on a remote does not.
+
+## Board identifiers
+
+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.
+
+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.
+
+`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.
 
 ## Cross-reference form