@erclx/canon 4.46.0 → 4.48.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.46.0",
+  "version": "4.48.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-address-review/REQUIREMENT.md

@@ -25,15 +25,15 @@ A declined finding fails on a third axis, which is where its reason ends up. A w
 - Push before replying, so the comment never runs ahead of the code it describes
 - Map every finding to what changed, or to a one-line reason when it is a question or a conscious accept
 - Carry the fact behind a declined finding into the posted reply rather than into the message that answered the dispatch, since both sessions end and the thread is what the next reader opens
-- Post the terminal comment only when the findings are addressed and every check passes
-- Say what the run actually did on a rebase-only pass, since a reply mapping findings and a terminal comment claiming they were addressed are both false on a pull request carrying none
+- Append the closing confirmation to the reply only when the findings are addressed and every check passes
+- Say what the run actually did on a rebase-only pass, since a reply mapping findings and a closing confirmation claiming they were addressed are both false on a pull request carrying none
 - Scan the reply for banned characters and internal phase labels before posting, since the comment leaves for the remote unchecked
 
 ## Must not
 
-- Merge, or read the closing comment as an approval. The author cannot approve their own pull request.
+- Merge, or read the closing confirmation as an approval. The author cannot approve their own pull request.
 - Write a review. This skill consumes findings and does not produce them.
-- Post the closing comment while a check is failing
+- Append the closing confirmation while a check is failing
 - Reimplement the follow-up push or the doc refresh. Both have owners, and a second copy here drifts from them.
 - Edit silently. A finding answered without a reply leaves the reviewer re-deriving the change from the diff.
 - Answer a finding in the channel alone. A reply that changes what the review concluded is the one the thread has to carry.

package/claude/skills/claude-address-review/SKILL.md

@@ -153,34 +153,57 @@ matches it.
 Before posting, run the scan in
 `${CLAUDE_SKILL_DIR}/../../standards/publish.md`
 against the reply. The hook skips `.canon/tmp/`, so this scan is the
-only gate on the published reply. Post it to the PR:
+only gate on the published reply. Post it to the PR and capture the posted
+comment's id, since Step 7 edits this exact comment rather than trusting
+whichever one `gh` considers last:
 
 ```bash
-gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md
+comment_url=$(gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md)
+echo "${comment_url##*issuecomment-}" > .canon/tmp/address-review/reply-<number>.id
 ```
 
 ## Step 7: confirm resolution
 
 After the follow-up push, watch CI on the PR. Poll
 `canon pr checks <number> --json` until the record's `state` leaves `pending`,
-then read it. When every finding is addressed and the state is `passing`, post
-one closing comment so the thread has a clear terminal state:
+then read it. When every finding is addressed and the state is `passing`, append
+the closing confirmation to the reply file Step 6 already posted, so the thread
+carries one terminal state rather than a second comment under no heading:
 
 ```bash
-gh pr comment <number> --body "✅ All review findings addressed, CI green."
+printf '\n✅ All review findings addressed, CI green.\n' >> .canon/tmp/address-review/reply-<number>.md
 ```
 
-A rebase-only run addressed no finding, so it takes its own terminal comment
-rather than that one. Claiming findings were addressed on a pull request that
+A rebase-only run addressed no finding, so it appends its own confirmation
+instead of that one. Claiming findings were addressed on a pull request that
 carries none is false on a surface nothing else checks:
 
 ```bash
-gh pr comment <number> --body "✅ Rebased onto origin/main, CI green. No review findings were open."
+printf '\n✅ Rebased onto origin/main, CI green. No review findings were open.\n' >> .canon/tmp/address-review/reply-<number>.md
+```
+
+Re-run the `${CLAUDE_SKILL_DIR}/../../standards/publish.md` scan against the
+updated file, since the appended line is new content the Step 6 scan never saw.
+Then edit the exact comment Step 6 posted, read back from the id it saved,
+rather than posting a second comment:
+
+```bash
+gh api -X PATCH "repos/{owner}/{repo}/issues/comments/$(cat .canon/tmp/address-review/reply-<number>.id)" \
+  -F body=@.canon/tmp/address-review/reply-<number>.md
 ```
 
-If any check fails, do not post the closing comment. Report the failing check
-so it can be fixed first. This is a resolution signal, not a formal approval,
-since the PR author cannot approve their own PR.
+`--edit-last` was the first shape and it targets the wrong object here.
+It edits the last comment posted by the authenticated user, not the last
+comment this run posted, and every session here authenticates as the one
+account the operator also comments from. A comment the operator leaves on
+their own pull request during the minutes Step 7 spends waiting on CI becomes
+that last comment, so `--edit-last` would overwrite it with the reply and the
+confirmation, silently. Targeting the id Step 6 captured closes that whether
+or not anyone commented in between.
+
+If any check fails, skip the edit. Report the failing check so it can be fixed
+first. This is a resolution signal, not a formal approval, since the PR author
+cannot approve their own PR.
 
 ## Step 8: output
 

package/claude/skills/claude-ux-audit/SKILL.md

@@ -16,7 +16,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 
 - `CLAUDE.md`: project type and conventions
 - `.claude/DESIGN.md`: visual intent, tokens, typography, spacing rules
-- `.claude/wireframes/index.md` + every `.claude/wireframes/<surface>.md`: intended UI layout, UI copy, interaction rules. Surfaces are loaded one file at a time during Step 3. Per `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`, these carry layout and intent, not implementation detail.
+- `.claude/wireframes/index.md` + every `.claude/wireframes/<surface>.md`, each a flat file or a grouped surface's own `.claude/wireframes/<surface>/index.md` and the siblings it lists: intended UI layout, UI copy, interaction rules. Surfaces are loaded one file at a time during Step 3. Per `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`, these carry layout and intent, not implementation detail.
 - `.claude/REQUIREMENTS.md`: feature scope and non-goals
 
 ## Step 2: identify surfaces
@@ -32,7 +32,7 @@ For each surface, look for:
 3. **Inconsistencies**: spacing, tone of voice, interaction patterns, icon use, keyboard affordances
 4. **Roughness in daily use**: friction, redundant steps, unclear affordances, ambiguous labels
 
-Use `.claude/DESIGN.md` and the per-surface `.claude/wireframes/<surface>.md` files as ground truth for intent. For each implementation surface, read the matching wireframe file before flagging drift. Observations only, no implementation suggestions or fixes.
+Use `.claude/DESIGN.md` and the per-surface `.claude/wireframes/<surface>.md` files, each a flat file or a grouped surface's own `.claude/wireframes/<surface>/index.md` and the siblings it lists, as ground truth for intent. For each implementation surface, read the matching wireframe file before flagging drift. Observations only, no implementation suggestions or fixes.
 
 ## Step 4: report and persist
 

package/package.json

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

package/src/commands/migrate.ts

@@ -295,6 +295,31 @@ function reportRecords(plan: RecordsPlan, records: number): void {
       }
     }
   }
+
+  // Named individually, same reasoning as the glob report above: an ownership
+  // boundary and a tense judgment stop being visible the moment either is
+  // rewritten, so the reader gets the file and line rather than a count.
+  if (plan.crossRepoCitations.length > 0) {
+    logInfo(
+      `${plural(plan.crossRepoCitations.length, 'file')} carry a citation into another repository, left alone:`,
+    )
+    for (const entry of plan.crossRepoCitations) {
+      for (const line of entry.lines) {
+        logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+      }
+    }
+  }
+
+  if (plan.datedCitations.length > 0) {
+    logInfo(
+      `${plural(plan.datedCitations.length, 'file')} carry a dated citation, left alone:`,
+    )
+    for (const entry of plan.datedCitations) {
+      for (const line of entry.lines) {
+        logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+      }
+    }
+  }
 }
 
 function toRecordsRecord(
@@ -313,7 +338,11 @@ function toRecordsRecord(
     excluded: plan.excluded.length,
     coupled: plan.coupled,
     frontmatterGlobs: plan.frontmatterGlobs,
+    crossRepoCitations: plan.crossRepoCitations,
+    datedCitations: plan.datedCitations,
     globs: plan.globs,
+    crossRepo: plan.crossRepo,
+    dated: plan.dated,
     records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,
@@ -575,6 +604,11 @@ export function register(program: Command): void {
         'alone rather than rewritten, since a rewritten glob stops matching',
         'silently. No marker is needed; the YAML shape is enough.',
         '',
+        'A citation shaped like a path into another repository, or one sitting',
+        'inside a dated paragraph, is reported and left alone rather than',
+        'rewritten. The first is an ownership judgment and the second a tense',
+        'one, neither of which a regular expression makes reliably.',
+        '',
         'The records themselves are never swept. Everything under .canon/ and',
         'every .claude/ record folder is left alone and reported as a count, so',
         'a run after the ignore entries collapse touches the same files as one',

package/src/migrate/records.ts

@@ -257,7 +257,60 @@ function isFrontmatterPathsLine(
   return lines[top]?.trim().startsWith('paths:') ?? false
 }
 
-type LineClass = 'live' | 'kept' | 'glob'
+/**
+ * A path segment immediately before a citation match, shaped like another
+ * repository's own name: it carries a dot (a domain-shaped token, matching
+ * the measured `erclx.dev`) or it is itself preceded by a further `/` (two
+ * path segments deep, also matching the measured `public/erclx.dev/...`).
+ *
+ * Bounded by `[\w.-]`, which is what keeps a shell-glob prefix such as
+ * `*` before the slash and a variable-substitution prefix such as
+ * `$project` out: neither `*` nor `$` is in the class, so a segment built
+ * from either never reaches the dot or the second slash this looks for.
+ */
+const CROSS_REPO_PREFIX = /(?:[\w.-]+\.[\w.-]+|[\w.-]+\/[\w.-]+)\/$/
+
+/**
+ * Whether the line's citation sits right after a prefix `CROSS_REPO_PREFIX`
+ * reads as another repository's own path. Per-line rather than per-match,
+ * matching `isKept`'s and `isFrontmatterPathsLine`'s granularity: a line
+ * carrying more than one citation is judged by the first.
+ */
+function isCrossRepoPrefix(lines: readonly string[], index: number): boolean {
+  const line = lines[index] ?? ''
+  const match = [...line.matchAll(CITATION)][0]
+  if (match === undefined) return false
+
+  return CROSS_REPO_PREFIX.test(line.slice(0, match.index ?? 0))
+}
+
+/** An ISO date, marking a paragraph as recording what was true on that day. */
+const ISO_DATE = /\b\d{4}-\d{2}-\d{2}\b/
+
+/**
+ * Whether the line's citation sits inside a blank-line-delimited paragraph
+ * that also carries an ISO date, read as dated prose rather than a live path.
+ *
+ * Walks both directions from `index` to the paragraph's edges, unlike
+ * `isKept`'s upward-only walk to a marker: the date can close a paragraph the
+ * citation opens, as `.claude/ARCHITECTURE.md`'s own `Measured at ... on
+ * <date>` sentences do.
+ */
+function isDatedParagraph(lines: readonly string[], index: number): boolean {
+  let start = index
+  while (start > 0 && lines[start - 1]?.trim() !== '') start -= 1
+
+  let end = index
+  while (end < lines.length - 1 && lines[end + 1]?.trim() !== '') end += 1
+
+  for (let cursor = start; cursor <= end; cursor += 1) {
+    if (ISO_DATE.test(lines[cursor] ?? '')) return true
+  }
+
+  return false
+}
+
+type LineClass = 'live' | 'kept' | 'glob' | 'crossRepo' | 'dated'
 
 function classifyLine(
   lines: readonly string[],
@@ -266,6 +319,8 @@ function classifyLine(
 ): LineClass {
   if (isFrontmatterPathsLine(lines, index, frontmatterEndIndex)) return 'glob'
   if (isKept(lines, index)) return 'kept'
+  if (isCrossRepoPrefix(lines, index)) return 'crossRepo'
+  if (isDatedParagraph(lines, index)) return 'dated'
   return 'live'
 }
 
@@ -287,8 +342,9 @@ export function rewriteText(text: string): string {
 
 /**
  * How many citations `rewriteText` would rewrite, how many marked lines it
- * left alone, and how many sat inside a frontmatter `paths:` glob. The second
- * and third numbers are what say the markers and the glob boundary fired at
+ * left alone, how many sat inside a frontmatter `paths:` glob, how many sat
+ * behind a cross-repository-shaped prefix, and how many sat inside a dated
+ * paragraph. Every number past the first is what says its boundary fired at
  * all, which a diff cannot show because a protected line does not appear in
  * one.
  */
@@ -296,12 +352,16 @@ export function scanText(text: string): {
   readonly rewritten: number
   readonly kept: number
   readonly globs: number
+  readonly crossRepo: number
+  readonly dated: number
 } {
   const lines = text.split('\n')
   const frontmatterEndIndex = frontmatterEnd(lines)
   let rewritten = 0
   let kept = 0
   let globs = 0
+  let crossRepo = 0
+  let dated = 0
 
   for (const [index, line] of lines.entries()) {
     const matches = [...line.matchAll(CITATION)].length
@@ -310,10 +370,12 @@ export function scanText(text: string): {
     const kind = classifyLine(lines, index, frontmatterEndIndex)
     if (kind === 'glob') globs += matches
     else if (kind === 'kept') kept += matches
+    else if (kind === 'crossRepo') crossRepo += matches
+    else if (kind === 'dated') dated += matches
     else rewritten += matches
   }
 
-  return { rewritten, kept, globs }
+  return { rewritten, kept, globs, crossRepo, dated }
 }
 
 /** Where a citation sits, so a reader can judge it before `--write` runs. */
@@ -338,6 +400,45 @@ function frontmatterGlobLines(text: string): CitationLine[] {
   return held
 }
 
+/**
+ * Every line in `text` whose citation `classifyLine` reads as `crossRepo`.
+ *
+ * Reads through `classifyLine` rather than `isCrossRepoPrefix` alone, so a
+ * line a glob or a keep marker already claims is not reported twice under a
+ * second boundary.
+ */
+function crossRepoLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+
+  for (const [index, line] of lines.entries()) {
+    if ([...line.matchAll(CITATION)].length === 0) continue
+    if (classifyLine(lines, index, frontmatterEndIndex) !== 'crossRepo')
+      continue
+
+    held.push({ line: index + 1, text: line.trim() })
+  }
+
+  return held
+}
+
+/** Every line in `text` whose citation `classifyLine` reads as `dated`. */
+function datedLines(text: string): CitationLine[] {
+  const lines = text.split('\n')
+  const frontmatterEndIndex = frontmatterEnd(lines)
+  const held: CitationLine[] = []
+
+  for (const [index, line] of lines.entries()) {
+    if ([...line.matchAll(CITATION)].length === 0) continue
+    if (classifyLine(lines, index, frontmatterEndIndex) !== 'dated') continue
+
+    held.push({ line: index + 1, text: line.trim() })
+  }
+
+  return held
+}
+
 export interface FolderMove {
   readonly from: string
   readonly to: string
@@ -402,6 +503,18 @@ export interface FrontmatterGlobEntry {
   readonly lines: readonly CitationLine[]
 }
 
+/** One file whose citation resolves outside this project, held rather than rewritten. */
+export interface CrossRepoCitationEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+
+/** One file whose citation sits inside a dated paragraph, held rather than rewritten. */
+export interface DatedCitationEntry {
+  readonly path: string
+  readonly lines: readonly CitationLine[]
+}
+
 export interface RecordsPlan {
   readonly moves: readonly FolderMove[]
   readonly collisions: readonly string[]
@@ -409,9 +522,13 @@ export interface RecordsPlan {
   readonly excluded: readonly string[]
   readonly coupled: readonly string[]
   readonly frontmatterGlobs: readonly FrontmatterGlobEntry[]
+  readonly crossRepoCitations: readonly CrossRepoCitationEntry[]
+  readonly datedCitations: readonly DatedCitationEntry[]
   readonly rewritten: number
   readonly kept: number
   readonly globs: number
+  readonly crossRepo: number
+  readonly dated: number
 }
 
 /**
@@ -431,8 +548,12 @@ export function planRecordsMove(
   const excluded: string[] = []
   const coupled: string[] = []
   const frontmatterGlobs: FrontmatterGlobEntry[] = []
+  const crossRepoCitations: CrossRepoCitationEntry[] = []
+  const datedCitations: DatedCitationEntry[] = []
   let kept = 0
   let globs = 0
+  let crossRepo = 0
+  let dated = 0
 
   for (const source of sources) {
     // Silently, and ahead of the exclusion test. The command boundary filters
@@ -452,13 +573,24 @@ export function planRecordsMove(
     const counts = scanText(source.text)
     kept += counts.kept
     globs += counts.globs
+    crossRepo += counts.crossRepo
+    dated += counts.dated
 
     // Ahead of the rewritten === 0 continue below: a file whose only citation
-    // sits in its paths: glob still needs to be reported.
+    // sits in its paths: glob, a cross-repo prefix, or a dated paragraph still
+    // needs to be reported.
     const held = frontmatterGlobLines(source.text)
     if (held.length > 0)
       frontmatterGlobs.push({ path: source.path, lines: held })
 
+    const foreign = crossRepoLines(source.text)
+    if (foreign.length > 0)
+      crossRepoCitations.push({ path: source.path, lines: foreign })
+
+    const dates = datedLines(source.text)
+    if (dates.length > 0)
+      datedCitations.push({ path: source.path, lines: dates })
+
     if (counts.rewritten === 0) continue
 
     if (referencesExcluded(source.text)) coupled.push(source.path)
@@ -478,8 +610,12 @@ export function planRecordsMove(
     excluded,
     coupled,
     frontmatterGlobs,
+    crossRepoCitations,
+    datedCitations,
     rewritten: entries.reduce((sum, entry) => sum + entry.rewritten, 0),
     kept,
     globs,
+    crossRepo,
+    dated,
   }
 }

package/standards/versioning.md

@@ -18,6 +18,7 @@ Does not govern:
 - Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
 - Voice, rhythm, and sentence construction in any text carrying a label: the `write-human` skill
 - Punctuation, formatting, and word choice in any text carrying a label: `markdown.md`
+- How a quoted-alone version-shaped token or a record path is caught as a board reference, which sits outside the phase-label/semver split this file owns: `publish.md`
 
 ## Phase labels
 
@@ -59,6 +60,10 @@ External release identity used in git tags and release notes. Independent of pha
 - Git tags use semver only. Phase labels never become tags.
 - A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
 - PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
+- A phase label written alone inside its own code span reads as shown rather than asserted. `canon labels scan` masks a code span before checking for a bare token, so a backticked label on its own does not count as an appearance for the phase-label check.
+- That masking clears one check and not the gate. A span whose whole content is the label still resolves as a board reference under `publish.md`'s own board-identifier check, run by the same scan, so a title or body quoting a label alone in a span still fails on that check and does not clear every surface the table above marks `no`.
+- The one shape neither check reaches is a version-shaped token folded into a longer quoted phrase, such as a fixture name or a file path. A backticked span quoting a test fixture's own version-shaped name is the corpus case that forced this carve-out, and a real phase label folded the same way inside a review comment is the counterexample where it read as clean on both checks.
+- The operator decided to keep the carve-out rather than narrow it to fenced blocks alone or drop it outright, leaving an author responsible for writing a live reference in plain text instead of folding it into a quoted phrase.
 - A phase label in a context entry is permitted only when its substance is restated inline beside it. A bare label carrying nothing beside it is forbidden, since a reader without the board has nothing to resolve it against.
 - A phase label carries no exception for a surface this repository authors and ships to a target it does not control: a standard, a skill body, and a governance rule are all forbidden outright, substance restated or not. The line is ownership rather than reachability. A shipped file is read by a project that never edits it, so the label names a board that reader can never reach. A context entry stays permitted above because it is this project's own tracked surface, never shipped.
 - The shipped-surface rule governs a reference to a real row, never a token shown to illustrate the label's own format. A phase label naming no decision, written only to show the pattern's shape, is not a citation, which is what lets a standard defining the format still show what one looks like.