@erclx/canon 4.45.1 → 4.46.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.46.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/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.46.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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/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`.