@erclx/canon 4.55.0 → 4.57.0

package/src/commands/labels.ts

@@ -2,6 +2,7 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { type LabelAuditRefusal, auditLabels } from '@/labels/audit'
 import { resolveScanInput } from '@/labels/event'
+import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
 import { MAP_REL } from '@/labels/map'
 import { scanPhaseLabels } from '@/labels/phase'
 import { scanTitleSpelling } from '@/labels/spelling'
@@ -22,6 +23,15 @@ interface ScanOptions {
   readonly json?: boolean
 }
 
+/** What a reader does about each way `checkTitleFormat` graded a title as broken. */
+const TITLE_FORMAT_MESSAGES: Record<TitleFormatIssue, string> = {
+  structure: 'does not match <type>(<scope>): <subject>',
+  'casing-type': 'the type is not lowercase',
+  'casing-scope': 'the scope is not lowercase',
+  'casing-subject': 'the first word of the subject is not lowercase',
+  length: 'is over 72 characters',
+}
+
 /** What a reader does about each way the audit produced no reading. */
 const REFUSALS: Record<LabelAuditRefusal, string> = {
   // An answer rather than a fault. A project declaring no map is labelled
@@ -142,11 +152,19 @@ export function register(program: Command): void {
         'a target project carries none, rather than reaching the network or',
         'forcing a new dependency.',
         '',
+        "It also grades the title alone against standards/pr.md's ## Title",
+        'section: the `<type>(<scope>): <subject>` structure, lowercase casing',
+        'for the type, the scope, and the first subject word, and a 72-',
+        'character length cap. A review carries no title of its own, so this',
+        'check is skipped there rather than graded against the forced empty',
+        'string.',
+        '',
         'Exit codes:',
-        '  0  none of the four found',
+        '  0  none of the five found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
-        '     session link, or a title word no dictionary holds',
+        '     session link, a title word no dictionary holds, or a title',
+        "     breaking standards/pr.md's format, casing, or length",
         '',
         'Examples:',
         '  canon labels scan --event "$GITHUB_EVENT_PATH"',
@@ -269,6 +287,12 @@ async function runScan(opts: ScanOptions): Promise<number> {
 
   const result = scanPhaseLabels(resolved)
   const spelling = await scanTitleSpelling(resolved.title, process.cwd())
+  // A review carries no title of its own, so `resolved.title` is forced
+  // empty and grading it would fail as `structure` for the wrong reason.
+  const titleFormat =
+    resolved.source === 'pull-request'
+      ? checkTitleFormat(resolved.title)
+      : undefined
 
   logStep(resolved.source === 'review' ? 'Review comment' : 'Pull request')
   logInfo(
@@ -339,6 +363,28 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const word of unspelledWords) logWarn(word)
   }
 
+  const titleFormatIssues = titleFormat?.issues ?? []
+
+  logStep(
+    titleFormat === undefined
+      ? 'Title format not checked'
+      : titleFormat.conforms
+        ? 'Clean'
+        : 'Title format issue found',
+  )
+  if (titleFormat === undefined) {
+    logInfo('a review comment carries no title, so there is no format to grade')
+  } else if (titleFormat.conforms) {
+    logInfo(
+      'the title matches <type>(<scope>): <subject> and its casing and length rules',
+    )
+  } else {
+    logWarn(
+      `${plural(titleFormatIssues.length, 'title format issue')} against standards/pr.md's ## Title section.`,
+    )
+    for (const issue of titleFormatIssues) logWarn(TITLE_FORMAT_MESSAGES[issue])
+  }
+
   outro()
 
   if (emitJson) {
@@ -351,6 +397,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
         sessionLinks: result.sessionLinks,
         unspelledWords,
         spellingChecked,
+        titleFormatIssues,
       })}\n`,
     )
   }
@@ -358,7 +405,8 @@ async function runScan(opts: ScanOptions): Promise<number> {
   return result.phaseLabels.length === 0 &&
     result.boardReferences.length === 0 &&
     result.sessionLinks.length === 0 &&
-    unspelledWords.length === 0
+    unspelledWords.length === 0 &&
+    titleFormatIssues.length === 0
     ? 0
     : 2
 }

package/src/commands/tasks.ts

@@ -1,6 +1,7 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
 import { type AnswersOutcome, planAnswers } from '@/tasks/answers'
+import { type BranchOutcome, planBranch } from '@/tasks/branch'
 import {
   type ArchiveOutcome,
   archiveTask,
@@ -62,6 +63,11 @@ interface AnswersCommandOptions {
   readonly root?: string
 }
 
+interface BranchCommandOptions {
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface PullRequestCommandOptions {
   readonly json?: boolean
   readonly plan?: string
@@ -230,6 +236,42 @@ export function register(program: Command): void {
       process.exitCode = await runAnswers(plan, opts)
     })
 
+  tasks
+    .command('plan-branch')
+    .description('Derive the branch name a dispatch and a worker both take')
+    .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 branch is derived and conforms to standards/branch.md',
+        '  1  refused as no-plan, archived, or bad-input',
+        '  2  derived, and conforms is false because the slug breaks a cap',
+        '',
+        'It reports type, slug, branch, words, and conforms. The type is fixed',
+        'at feat, since a derivation two sides grade differently is the defect',
+        'this closes, and git-branch renames a wrong type later in the chain.',
+        'Branch on conforms rather than on the exit code, which a shell',
+        'function wrapping canon can flatten to zero.',
+        '',
+        'The dispatch collision check and the worker worktree entry both call',
+        'it, so the branch a gate clears is the branch a session takes.',
+        '',
+        'Examples:',
+        '  canon tasks plan-branch dispatch-answer-gate',
+        '  canon tasks plan-branch .canon/plans/feature-dispatch-answer-gate.md',
+        '  canon tasks plan-branch dispatch-answer-gate --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (plan: string, opts: BranchCommandOptions) => {
+      process.exitCode = await runBranch(plan, opts)
+    })
+
   tasks
     .command('pull-request')
     .description('Record a pull request number on the task a branch closes')
@@ -732,6 +774,61 @@ function reportAnswers(
   return EXIT_FINDINGS
 }
 
+async function runBranch(
+  plan: string,
+  opts: BranchCommandOptions,
+): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = planBranch(root, plan)
+
+  return reportBranch(outcome, opts.json ?? false, root)
+}
+
+function reportBranch(
+  outcome: BranchOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, message: outcome.message })}\n`,
+      )
+      return 1
+    }
+
+    intro('canon tasks plan-branch')
+    logStep('Refused')
+    logError(outcome.message)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ ...outcome, root })}\n`)
+    return outcome.conforms ? 0 : EXIT_FINDINGS
+  }
+
+  intro('canon tasks plan-branch')
+  logStep(outcome.branch)
+
+  if (outcome.conforms) {
+    logInfo(`derived from ${outcome.plan}, ${outcome.words} words.`)
+    outro()
+    return 0
+  }
+
+  logWarn(
+    `derived from ${outcome.plan}, ${outcome.words} words and ${outcome.branch.length} characters.`,
+  )
+  logError(
+    'The slug breaks a cap in standards/branch.md, so hand the row to a person rather than renaming it.',
+  )
+  outro()
+
+  return EXIT_FINDINGS
+}
+
 function reportValidation(
   outcome: ValidateOutcome,
   emitJson: boolean,

package/src/gate/measures.ts

@@ -15,6 +15,10 @@ import {
   SHIPPED_CORPORA,
   type ShippedReference,
 } from '@/shipped/references'
+import {
+  README_PARAPHRASE_MARKER,
+  readmeCitationsIn,
+} from '@/web/readme-citations'
 
 export interface CommandResult {
   readonly exitCode: number
@@ -496,6 +500,8 @@ function describeShippedReference(reference: ShippedReference): string {
       return 'a pull request number that resolves elsewhere for a reader in a target'
     case 'docs-path':
       return 'a path into this repository that a registry install never carries'
+    case 'standards-path':
+      return 'a bare standards/ path that has nothing to expand it in an installed plugin cache'
     case 'phase-label':
       return 'a phase label that names a board no target holds'
   }
@@ -554,8 +560,8 @@ export const shippedReferences: Measure = async (ctx) => {
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
   }
 }
 
@@ -622,6 +628,75 @@ export const clientCommandCitations = async (
   }
 }
 
+/**
+ * Every `README.md:` anchor in `web/src/content/copy.ts` whose quoted phrase no
+ * longer appears in the current `README.md`, plus any leftover bare
+ * `README.md:<n>` citation the retired line-number convention would leave
+ * behind.
+ *
+ * Scoped to the one file carrying the anchors rather than walked across the
+ * tree, since `web/src/content/copy.ts` is the only place this repository
+ * writes one. A quoted phrase is checked with a plain substring test against
+ * the whole `README.md` text rather than against the cited line, which is the
+ * property that lets the anchor survive `README.md` growing or shrinking
+ * above it: the phrase fails only when the content itself moved or changed,
+ * never when a line number did.
+ */
+export const readmeCitations: Measure = async (ctx) => {
+  const copyPath = 'web/src/content/copy.ts'
+  const readmePath = 'README.md'
+  const copyFile = join(ctx.root, copyPath)
+  const readmeFile = join(ctx.root, readmePath)
+
+  if (!existsSync(copyFile) || !existsSync(readmeFile)) {
+    return {
+      emissions: [],
+      unmeasured: `${copyPath} or ${readmePath} is absent, so no citation was checked.`,
+    }
+  }
+
+  const readmeText = readFileSync(readmeFile, 'utf8')
+  const citations = readmeCitationsIn(copyPath, readFileSync(copyFile, 'utf8'))
+
+  if (citations.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: `${copyPath} carries no README.md citation, so nothing was checked.`,
+    }
+  }
+
+  const bad = citations.filter(
+    (citation) =>
+      citation.kind === 'bare' ||
+      (citation.kind === 'quoted' &&
+        citation.phrases.some((phrase) => !readmeText.includes(phrase))),
+  )
+
+  if (bad.length === 0) {
+    return {
+      emissions: [
+        info(
+          `${citations.length} README.md citation(s) in ${copyPath} verified against the current text`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: bad.map((citation) =>
+      warn(
+        citation.kind === 'bare'
+          ? `${citation.file}:${citation.line} carries ${citation.text}, a bare line number that cannot detect a shifted line`
+          : `${citation.file}:${citation.line} carries ${citation.text}, whose quoted phrase no longer appears in README.md`,
+      ),
+    ),
+    failure:
+      bad.length === 1
+        ? `One README.md citation in ${copyPath} failed. Quote a verbatim phrase from the current README.md, or mark the line ${README_PARAPHRASE_MARKER}: <reason> where the string condenses rather than quotes.`
+        : `${bad.length} README.md citations in ${copyPath} failed. Quote a verbatim phrase from the current README.md, or mark each line ${README_PARAPHRASE_MARKER}: <reason> where the string condenses rather than quotes.`,
+  }
+}
+
 /**
  * `canon sandbox coverage` moves only when a person runs it, so a scenario added
  * with no expectation ships unnoticed.

package/src/gate/stages.ts

@@ -5,6 +5,7 @@ import {
   markdownBans,
   type Measure,
   pluginManifests,
+  readmeCitations,
   recordIdempotence,
   sandboxCoverage,
   seedStandards,
@@ -390,6 +391,16 @@ export const STAGES: readonly Stage[] = [
     skipped: 'No shipped corpus changed, so no reference was read',
     checks: [{ kind: 'measure', measure: shippedReferences }],
   },
+  {
+    // Scoped to the two files a citation can drift between, so an edit to
+    // either one runs the check. web/src/content/copy.ts carries the anchors
+    // and README.md is the text they quote from.
+    id: 'readme-citations',
+    label: 'README citations',
+    scope: /^(web\/src\/content\/copy\.ts|README\.md)$/,
+    skipped: 'Neither copy.ts nor README.md changed, so no citation was read',
+    checks: [{ kind: 'measure', measure: readmeCitations }],
+  },
   {
     id: 'seed-standards',
     label: 'Seed standards',

package/src/labels/format.ts

@@ -0,0 +1,58 @@
+/**
+ * Which rule in `standards/pr.md`'s `## Title` section a title breaks.
+ *
+ * `structure` stands alone rather than beside the other three, because a
+ * title failing the shape match has no parsed `<type>`, `<scope>`, or
+ * `<subject>` to grade for casing, and `length` is read off the raw string
+ * regardless of whether it parses.
+ */
+export type TitleFormatIssue =
+  | 'structure'
+  | 'casing-type'
+  | 'casing-scope'
+  | 'casing-subject'
+  | 'length'
+
+export interface TitleFormatCheck {
+  readonly conforms: boolean
+  readonly issues: readonly TitleFormatIssue[]
+}
+
+const TITLE_MAX_LENGTH = 72
+
+// Casing-agnostic on purpose. Casing is graded separately once the shape
+// matches, so `type` and `scope` accept either case here and `structure`
+// reports only a title with no `<type>(<scope>): <subject>` shape at all.
+const TITLE_SHAPE = /^([A-Za-z]+)\(([A-Za-z0-9][\w.-]*)\): (.+)$/
+const LEADING_LETTERS = /^[A-Za-z]+/
+
+/**
+ * Grades a pull request title, or a commit subject sharing the same form,
+ * against `standards/pr.md`'s structure, casing, and length rules.
+ *
+ * Does not check `<type>` against `standards/commit.md`'s fixed enum.
+ * `pr.md`'s own `## Title` section states format, casing, and length only,
+ * and names no type list of its own to check against.
+ */
+export function checkTitleFormat(title: string): TitleFormatCheck {
+  const match = TITLE_SHAPE.exec(title)
+
+  if (match === null) {
+    return { conforms: false, issues: ['structure'] }
+  }
+
+  const [, type, scope, subject] = match
+  const issues: TitleFormatIssue[] = []
+
+  if (type !== type.toLowerCase()) issues.push('casing-type')
+  if (scope !== scope.toLowerCase()) issues.push('casing-scope')
+
+  const leadingWord = LEADING_LETTERS.exec(subject)?.[0]
+  if (leadingWord !== undefined && leadingWord !== leadingWord.toLowerCase()) {
+    issues.push('casing-subject')
+  }
+
+  if (title.length > TITLE_MAX_LENGTH) issues.push('length')
+
+  return { conforms: issues.length === 0, issues }
+}

package/src/shipped/references.ts

@@ -148,6 +148,37 @@ const SAME_REPOSITORY =
  */
 const DOCS_PATH = /(?<![\w./-])docs\/[^\s`)\]]*\.md\b/g
 
+/**
+ * A bare `standards/<name>.md` citation from a body under `claude/skills/`,
+ * which `598-authoring-layout.md` fixes as the broken form there:
+ * `${CLAUDE_SKILL_DIR}` is what resolves off the `claude/standards` symlink
+ * in every plugin cache, and a raw path has nothing to expand it.
+ *
+ * Scoped to that one corpus rather than every `isShippedCorpus` reads,
+ * because `docs/agents/` and `docs/workflow/` carry the identical
+ * `standards/<name>.md` shape correctly: a docs page resolves from this
+ * checkout's own root rather than through a skill's `${CLAUDE_SKILL_DIR}`,
+ * so the same string is the fix in one corpus and the defect in the other.
+ * Widening the pattern to every corpus turns it into a mass false-positive
+ * over the dozens of correct citations those two folders carry.
+ *
+ * The same leading-boundary discipline as `DOCS_PATH` excludes the already
+ * correct form: a `/` sits ahead of `standards` in
+ * `${CLAUDE_SKILL_DIR}/../../standards/<name>.md`, which the negative
+ * lookbehind rejects, so a citation already rewritten to the resolving form
+ * does not fail this check a second time.
+ *
+ * Reported only where `isStandardsPathResolvable` confirms the match
+ * resolves against this checkout, the same gate `DOCS_PATH` runs. A body
+ * illustrating the shape a project's own `standards/<name>.md` takes writes
+ * the identical placeholder token this pattern matches, such as
+ * `standards/<slug>.md` in `create-standard/SKILL.md` or `standards/<name>.md`
+ * in `migration-standards-drop/SKILL.md`, and neither resolves to a real
+ * file. Four such placeholders surfaced across three files the first time
+ * this pattern ran unresolved, measured 2026-09-06.
+ */
+const STANDARDS_PATH = /(?<![\w./-])standards\/[^\s`)\]]*\.md\b/g
+
 /**
  * A phase-label-shaped token: exactly two numeric groups, with a negative
  * lookahead rejecting a third.
@@ -173,7 +204,12 @@ export interface ShippedReference {
   readonly file: string
   /** One-based, matching the `file:line` form a reader clicks. */
   readonly line: number
-  readonly kind: 'pull-request' | 'commit' | 'docs-path' | 'phase-label'
+  readonly kind:
+    | 'pull-request'
+    | 'commit'
+    | 'docs-path'
+    | 'standards-path'
+    | 'phase-label'
   /** The reference as written, so a report names the token to qualify. */
   readonly text: string
   /**
@@ -202,18 +238,37 @@ function isDocsPathResolvable(
   return existsSync(join(root, path))
 }
 
+/**
+ * Whether `file` sits in the one corpus `STANDARDS_PATH` gates.
+ *
+ * `REQUIREMENT.md` is excluded for the reason `598-authoring-layout.md`
+ * leaves it alone: a maintainer or an audit command reads that file rather
+ * than a session loading it, so the resolver rule this pattern enforces
+ * never applies there.
+ */
+function isStandardsPathScope(file: string): boolean {
+  return file.startsWith('claude/skills/') && !file.endsWith('/REQUIREMENT.md')
+}
+
+/** Whether a `STANDARDS_PATH` match names a real file in this checkout. */
+function isStandardsPathResolvable(path: string, root: string): boolean {
+  return existsSync(join(root, path))
+}
+
 /**
  * Every reference in one shipped file that no marker mutes.
  *
  * The corpus walk is deliberately absent, which lets most of the shape be
  * tested against a string rather than against a fixture. That is the seam
  * `headingCitationsIn` draws in `src/claude/skills-headings.ts` and `citationsIn`
- * draws in `skills-reach.ts`. `DOCS_PATH` is the one pattern that still needs
- * a filesystem, since resolving against this checkout is the only thing that
- * separates its two readings, so it takes `root` as the one caller-supplied
- * exception to that rule. `root` is required rather than defaulted, since a
- * caller that dropped it silently would report zero docs-path findings
- * rather than raising, which is the wrong failure direction for a gate.
+ * draws in `skills-reach.ts`. `DOCS_PATH` and `STANDARDS_PATH` are the two
+ * patterns that still need a filesystem, since resolving against this
+ * checkout is the only thing that separates a real citation from an
+ * illustration for either, so `referencesIn` takes `root` as the one
+ * caller-supplied exception to that rule. `root` is required rather than
+ * defaulted, since a caller that dropped it silently would report zero
+ * findings for both rather than raising, which is the wrong failure
+ * direction for a gate.
  *
  * The unit is the match rather than the line, unlike those two, because one
  * line here can carry three separate tokens each needing its own repair and a
@@ -272,6 +327,18 @@ export function referencesIn(
       })
     }
 
+    if (isStandardsPathScope(file)) {
+      for (const match of line.matchAll(STANDARDS_PATH)) {
+        if (!isStandardsPathResolvable(match[0], root)) continue
+        references.push({
+          file,
+          line: index + 1,
+          kind: 'standards-path',
+          text: match[0],
+        })
+      }
+    }
+
     for (const match of line.matchAll(PHASE_LABEL)) {
       references.push({
         file,

package/src/tasks/answers.ts

@@ -47,6 +47,18 @@ export interface PlanAnswers {
 
 export type AnswersOutcome = PlanAnswers | AnswersRefused
 
+/**
+ * A reference that named a live plan, carrying the absolute path a reader opens
+ * and the root-relative spelling a record reports.
+ */
+export interface PlanResolved {
+  readonly ok: true
+  readonly path: string
+  readonly plan: string
+}
+
+export type ResolveOutcome = PlanResolved | AnswersRefused
+
 /**
  * The spellings a caller reaches a plan by, in the order they are tried. A bare
  * slug names the live folder outright, and a path is resolved against the
@@ -146,19 +158,18 @@ function openQuestions(lines: readonly string[]): OpenQuestion[] {
 }
 
 /**
- * Answers whether a plan is launchable, which is whether it still waits on the
- * operator for a call only they can make. It reads the question block through
- * the same `readQuestions` the plan validator runs, so the gate and the
- * conformance check cannot drift into disagreeing about what a question is.
+ * Resolves a caller's reference to a live plan, refusing an empty reference, a
+ * reference that names no file, and one that lands in the plans archive.
  *
- * It reports and never writes. Holding the row, naming the slot, and reaching
- * the operator belong to the dispatcher, which is where the decision already
- * sits.
+ * Both `planAnswers` and `planBranch` answer the same reference, so the
+ * resolution and the three refusals sit here rather than in each of them. Two
+ * verbs reading one reference through two copies of this ladder is the defect
+ * the branch derivation was filed against, one layer down.
  */
-export async function planAnswers(
+export function resolvePlanReference(
   root: string,
   reference: string,
-): Promise<AnswersOutcome> {
+): ResolveOutcome {
   if (reference.trim().length === 0) {
     return refuse('bad-input', 'No plan named. Pass a plan path or its slug.')
   }
@@ -188,12 +199,32 @@ export async function planAnswers(
     )
   }
 
-  const sections = splitPlanSections(await readFile(path, 'utf8'))
+  return { ok: true, path, plan: relative(root, path) }
+}
+
+/**
+ * Answers whether a plan is launchable, which is whether it still waits on the
+ * operator for a call only they can make. It reads the question block through
+ * the same `readQuestions` the plan validator runs, so the gate and the
+ * conformance check cannot drift into disagreeing about what a question is.
+ *
+ * It reports and never writes. Holding the row, naming the slot, and reaching
+ * the operator belong to the dispatcher, which is where the decision already
+ * sits.
+ */
+export async function planAnswers(
+  root: string,
+  reference: string,
+): Promise<AnswersOutcome> {
+  const resolved = resolvePlanReference(root, reference)
+  if (!resolved.ok) return resolved
+
+  const sections = splitPlanSections(await readFile(resolved.path, 'utf8'))
   const open = openQuestions(sections.get('Questions') ?? [])
 
   return {
     ok: true,
-    plan: relative(root, path),
+    plan: resolved.plan,
     launchable: open.length === 0,
     open,
   }