@erclx/canon 4.45.1 → 4.47.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.45.1",
+  "version": "4.47.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-feature/SKILL.md

@@ -101,6 +101,8 @@ Run `canon records validate plans` after writing the file when the CLI is on PAT
 
 Run `canon markdown audit .canon/plans/feature-<slug>.md` beside it, naming the file. `.canon/plans/` is gitignored and the audit's default path set is what git lists, so no other gate ever opens a plan, and six ban hits landed across four plans written without this call. Rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.
 
+When Step 1 resolved an existing task for this feature, run `canon tasks plan-link <task> .canon/plans/feature-<slug>.md` right after the file lands, naming the stem Step 1 read. Skip the call when Step 1 found no task, since there is nothing to link yet. Report a refusal rather than stopping on it. The plan file is already written, and `canon tasks validate` still catches an unlinked task through `plan-uncited` if this call cannot run.
+
 Then output in chat:
 
 ```markdown

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/docs/agents/commands.md

@@ -32,6 +32,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon transcripts <url>`     | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                                                                              |
 | `canon tasks archive`         | Move a shipped task and its plan off the board, clear its ordering row, and regenerate the index                                                                                                                                   |
 | `canon tasks pull-request`    | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                                                                                           |
+| `canon tasks plan-link`       | Write or correct a task's `Plan:` line to point at a plan, by stem and plan path or slug (`--json`)                                                                                                                                |
 | `canon tasks outcome`         | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                                                                                                          |
 | `canon tasks validate`        | Report board rows whose shape, order, plan, task file, group, file set, or blocker does not hold (`--json`)                                                                                                                        |
 | `canon intake list`           | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                                                                                                              |

package/docs/agents/tasks.md

@@ -104,6 +104,28 @@ The orchestrator dispatch runbook calls this before it checks the branch or the
 canon tasks plan-answers dispatch-answer-gate --json | jq -r '.launchable'
 ```
 
+## Plan link
+
+`canon tasks plan-link <task> <plan>` writes or corrects a task's `Plan:` line, as `Plan: [<label>](<target>)` right after the H1. `claude-feature` calls it right after a plan file lands, when Step 1 resolved an existing task for the feature, so the line is a mechanical write rather than hand-edited markdown.
+
+Name the task by its filename stem, and the plan by its path or its slug, the same two forms `canon tasks plan-answers` accepts:
+
+```bash
+canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate # canon-allow-reference: illustrates the stem-selection form, not a citation of a real task
+canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-answer-gate.md --json
+```
+
+| Option          | Behavior                                    |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The plan resolves the same way `canon tasks plan-answers` resolves one, against the project root first and `.canon/tasks/` second, so a bare slug and a board-relative path both work. A reference resolving to no file refuses as `no-plan`, naming every base it looked under.
+
+The write mirrors `canon tasks pull-request`'s add/correct/unchanged shape, anchored on the H1 rather than on the last origin line, since `Plan:` is the first origin line a task carries rather than the last. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same plan safe.
+
+Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, `no-plan`, or `bad-input`.
+
 ## Pull request
 
 `canon tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.45.1",
+  "version": "4.47.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/commands/tasks.ts

@@ -11,7 +11,9 @@ import {
 import {
   type CloseOutcome,
   closeOutcomes,
+  type PlanOutcome,
   type PullRequestOutcome,
+  recordPlan,
   type RecordRefused,
   type RecordSelector,
   recordPullRequest,
@@ -66,6 +68,11 @@ interface PullRequestCommandOptions {
   readonly root?: string
 }
 
+interface PlanLinkCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface OutcomeCommandOptions {
   readonly close?: readonly string[]
   readonly json?: boolean
@@ -258,6 +265,40 @@ export function register(program: Command): void {
       },
     )
 
+  tasks
+    .command('plan-link')
+    .description("Write or correct a task's Plan: line to point at a plan")
+    .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
+    .argument('<plan>', 'Plan path or its slug, as in dispatch-answer-gate')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the line was added, corrected, or already correct',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes Plan: [<label>](<target>) right after the H1, the same',
+        'add/correct/unchanged shape canon tasks pull-request writes with, and',
+        'resolves both a bare slug and a board-relative path the way',
+        'canon tasks plan-answers does. Safe from a linked worktree, since it',
+        'resolves the board root in-process.',
+        '',
+        'Examples:',
+        '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',
+        '  canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-answer-gate.md --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (task: string, plan: string, opts: PlanLinkCommandOptions) => {
+        process.exitCode = await runPlanLink(task, plan, opts)
+      },
+    )
+
   tasks
     .command('outcome')
     .description('Mark outcomes closed on a task by their position')
@@ -366,6 +407,18 @@ async function runPullRequest(
   return reportPullRequest(outcome, emitJson, root)
 }
 
+async function runPlanLink(
+  task: string,
+  plan: string,
+  opts: PlanLinkCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await recordPlan(root, task, plan)
+
+  return reportPlanLink(outcome, emitJson, root)
+}
+
 async function runOutcome(
   task: string | undefined,
   opts: OutcomeCommandOptions,
@@ -484,6 +537,38 @@ function reportPullRequest(
   return 0
 }
 
+function reportPlanLink(
+  outcome: PlanOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks plan-link', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        plan: outcome.plan,
+        action: outcome.action,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks plan-link')
+  logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
+  logInfo(`${outcome.stem} names plan ${outcome.plan}`)
+  if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}
+
 function reportOutcome(
   outcome: CloseOutcome,
   emitJson: boolean,

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/src/tasks/archive.ts

@@ -211,10 +211,23 @@ export function readPlanTarget(text: string): string | undefined {
 }
 
 /**
- * Points the task's `Plan:` line at the plan's new home, as a markdown link
- * whose text and target stay in step. The line is matched with the pattern the
- * read above uses, so the archive rewrites exactly the line it parsed and never
- * a second `Plan:` a task displays inside a fenced sample.
+ * Builds a `Plan:` line as a markdown link whose text and target stay in step,
+ * the label taken from the target's filename with its extension dropped.
+ * `record.ts` reuses this so a plan-link write and an archive retarget produce
+ * one line shape rather than two.
+ */
+export function planLine(target: string): string {
+  const name = basename(target)
+  const label = name.endsWith('.md') ? name.slice(0, -'.md'.length) : name
+
+  return `Plan: [${label}](${target})`
+}
+
+/**
+ * Points the task's `Plan:` line at the plan's new home. The line is matched
+ * with the pattern the read above uses, so the archive rewrites exactly the
+ * line it parsed and never a second `Plan:` a task displays inside a fenced
+ * sample.
  *
  * The replacement is built by a function rather than passed as a string,
  * because `$&` and its siblings are substitution sequences inside a replacement
@@ -222,10 +235,7 @@ export function readPlanTarget(text: string): string | undefined {
  * `.canon/plans/` is gitignored, so nothing recovers the pointer it replaced.
  */
 export function retargetPlanLine(text: string, target: string): string {
-  const name = basename(target)
-  const label = name.endsWith('.md') ? name.slice(0, -'.md'.length) : name
-
-  return text.replace(PLAN_PATTERN, () => `Plan: [${label}](${target})`)
+  return text.replace(PLAN_PATTERN, () => planLine(target))
 }
 
 /**
@@ -624,7 +634,7 @@ async function planToArchive(
  * deeper than the live pair, so the link is measured between the two
  * destinations rather than written as the `../plans/` the live task carried.
  */
-function linkTo(taskDir: string, plan: string): string {
+export function linkTo(taskDir: string, plan: string): string {
   return relative(taskDir, plan).split(sep).join('/')
 }
 

package/src/tasks/record.ts

@@ -1,10 +1,13 @@
 import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
+import { planCandidates } from '@/tasks/answers'
 import {
   fenceMask,
+  linkTo,
   listTaskStems,
   OUTCOME_PATTERN,
+  planLine,
   readPlanTarget,
   tasksDir,
 } from '@/tasks/archive'
@@ -28,6 +31,7 @@ export const RECORD_REFUSALS = [
   'ambiguous',
   'no-outcomes',
   'out-of-range',
+  'no-plan',
   'bad-input',
 ] as const
 
@@ -56,6 +60,16 @@ export interface PullRequestRecorded {
 
 export type PullRequestOutcome = PullRequestRecorded | RecordRefused
 
+export interface PlanRecorded {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+  readonly plan: string
+  readonly action: LineAction
+}
+
+export type PlanOutcome = PlanRecorded | RecordRefused
+
 export interface OutcomesClosed {
   readonly ok: true
   readonly stem: string
@@ -127,6 +141,33 @@ function lastOriginLine(lines: readonly string[]): number | undefined {
   return found
 }
 
+/**
+ * Places the `Plan:` line right after the H1, mirroring
+ * `writePullRequestLine`'s add/correct/unchanged shape. `Plan:` is the first
+ * origin line a task carries, so it anchors on the heading itself rather than
+ * on the last origin line above it.
+ */
+export function writePlanLine(
+  text: string,
+  target: string,
+): { readonly text: string; readonly action: LineAction } {
+  const line = planLine(target)
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith('Plan:'))
+
+  if (existing !== -1) {
+    if (lines[existing] === line) return { text, action: 'unchanged' }
+    lines[existing] = line
+    return { text: lines.join('\n'), action: 'corrected' }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, action: 'added' }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), action: 'added' }
+}
+
 /**
  * Marks outcomes closed by their 1-based position in the task's outcome list,
  * which is the order the board format writes them. A caller reads the file
@@ -267,6 +308,42 @@ export async function recordPullRequest(
   return { ok: true, stem, path, number, action }
 }
 
+/**
+ * Records a plan's path on the task it belongs to, as the task's `Plan:` line.
+ * `claude-feature` runs this right after the plan file lands, resolving the
+ * reference the same two ways `canon tasks plan-answers` does, through
+ * `planCandidates`, so a bare slug and a board-relative path both resolve.
+ *
+ * The task is named directly rather than through `RecordSelector`'s `plan`
+ * kind: every caller already holds the stem, since resolving the task is what
+ * put it in a position to write the plan's path in the first place.
+ */
+export async function recordPlan(
+  root: string,
+  stem: string,
+  reference: string,
+): Promise<PlanOutcome> {
+  const opened = await openTask(root, { kind: 'stem', stem })
+  if ('ok' in opened) return opened
+
+  const { path } = opened
+  const dir = tasksDir(root)
+  const candidates = planCandidates(root, reference)
+  const plan = candidates.find((candidate) => existsSync(candidate))
+
+  if (!plan) {
+    const looked = candidates.map((entry) => relative(root, entry)).join(' or ')
+    return refuse('no-plan', `No plan at ${looked}.`, [reference])
+  }
+
+  const target = linkTo(dir, plan)
+  const { text, action } = writePlanLine(await readFile(path, 'utf8'), target)
+
+  if (action !== 'unchanged') await writeFile(path, text)
+
+  return { ok: true, stem: opened.stem, path, plan: target, action }
+}
+
 /**
  * Marks the named outcomes `[x]` in place. `claude-docs` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions

package/standards/tasks.md

@@ -219,6 +219,8 @@ A project that archived plans before the folder nested under `.canon/plans/` hol
 
 One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
+`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, mirroring how `canon tasks pull-request` writes its own. `claude-feature` calls it right after the plan file lands, when an existing task names the feature, so the line is a mechanical write rather than hand-edited markdown.
+
 `Groundwork:` points at `../groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
 
 `Intake:` points at `../intake/<slug>/`, the folder an intake pass fills. Use it rather than `Groundwork:`, because a groundwork track measures one question in depth while an intake dispositions many across a tree, and one key covering both loses which kind of pass produced the task. The line names the folder rather than an item inside it. A task routinely promotes several items at once, so an anchored line would name one and drop the rest, and the item numbers belong in that task's `## Findings`.

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.