@erclx/canon 4.54.0 → 4.56.0

package/src/claude/cases/authoring.ts

@@ -42,6 +42,16 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
     expect: 'docs-draft',
   },
+  {
+    prompt:
+      'Write a context entry for the payments domain, there is no .claude/context page for it yet.',
+    expect: 'context-draft',
+  },
+  {
+    prompt:
+      'Draft a wireframe for the settings panel, nothing under .claude/wireframes covers that surface yet.',
+    expect: 'wireframe-draft',
+  },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',
     expect: 'restate-plainly',

package/src/claude/cases/misc.ts

@@ -33,4 +33,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',
   },
+  {
+    prompt: 'Is there a page anywhere in this repo that covers retries?',
+    expect: 'index-lookup',
+  },
 ]

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
@@ -622,6 +626,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/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,
   }

package/src/tasks/branch.ts

@@ -0,0 +1,78 @@
+import { basename } from 'node:path'
+import { type AnswersRefused, resolvePlanReference } from '@/tasks/answers'
+
+const PLAN_PREFIX = 'feature-'
+const MARKDOWN = '.md'
+
+/**
+ * The type every plan-derived branch takes. It is a constant rather than a
+ * reading, because determinism is the whole property that makes the dispatch
+ * gate and the worker agree, and prose reading is the judgment that produced
+ * three strings for one plan. A wrong type is cheap because a branch type is
+ * cosmetic, since a commit's type and a pull request's title are both read off
+ * the diff. Nothing renames it later, whatever three shipped bodies used to say.
+ */
+export const PLAN_BRANCH_TYPE = 'feat'
+
+/** The description cap in `standards/branch.md`, in kebab-separated words. */
+export const DESCRIPTION_WORD_CAP = 4
+
+/** The branch length cap in `standards/branch.md`, in characters. */
+export const BRANCH_LENGTH_CAP = 50
+
+export interface PlanBranch {
+  readonly ok: true
+  readonly plan: string
+  readonly type: string
+  readonly slug: string
+  readonly branch: string
+  readonly words: number
+  readonly conforms: boolean
+}
+
+export type BranchOutcome = PlanBranch | AnswersRefused
+
+/**
+ * Takes the slug off a plan filename. The `feature-` prefix and the extension
+ * are the two things every plan filename carries and no branch name does, so
+ * both come off and whatever is left is the description.
+ */
+function slugOf(path: string): string {
+  const stem = basename(path, MARKDOWN)
+
+  return stem.startsWith(PLAN_PREFIX) ? stem.slice(PLAN_PREFIX.length) : stem
+}
+
+/**
+ * Derives the branch a dispatch checks and a worker takes, from the plan both
+ * of them name. It is the one derivation, so the collision check and the
+ * worktree entry it gates cannot hold two answers for one plan.
+ *
+ * Conformance covers both caps `standards/branch.md` states, being the word
+ * count of the description and the length of the whole branch. A slug is a
+ * plan's own filename rather than a name anyone chose for a branch, so a plan
+ * can name a branch this refuses to grade as conforming, and reporting that is
+ * the point: the caller hands the row to a person rather than shipping a
+ * rename that parts the branch slug from the plan slug.
+ */
+export function planBranch(root: string, reference: string): BranchOutcome {
+  const resolved = resolvePlanReference(root, reference)
+  if (!resolved.ok) return resolved
+
+  const slug = slugOf(resolved.path)
+  const branch = `${PLAN_BRANCH_TYPE}/${slug}`
+  const words = slug.split('-').filter((word) => word.length > 0).length
+
+  return {
+    ok: true,
+    plan: resolved.plan,
+    type: PLAN_BRANCH_TYPE,
+    slug,
+    branch,
+    words,
+    conforms:
+      words > 0 &&
+      words <= DESCRIPTION_WORD_CAP &&
+      branch.length <= BRANCH_LENGTH_CAP,
+  }
+}

package/src/web/readme-citations.ts

@@ -0,0 +1,90 @@
+import { isMarked } from '@/exempt-marker'
+
+export const README_PARAPHRASE_MARKER = 'canon-allow-readme-paraphrase'
+
+export type ReadmeCitationKind = 'quoted' | 'paraphrase' | 'bare'
+
+export interface ReadmeCitation {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly kind: ReadmeCitationKind
+  /** The citation comment as written, so a report names the line to fix. */
+  readonly text: string
+  /** Verbatim phrases to check against `README.md`, set only for `kind: 'quoted'`. */
+  readonly phrases: readonly string[]
+}
+
+const ANCHOR = /README\.md:\s*(.*)$/
+const QUOTED_PHRASE = /"([^"]+)"/g
+
+/**
+ * Every `README.md:` anchor comment in one file, classified by shape.
+ *
+ * `quoted` carries one or more verbatim phrases a caller checks against the
+ * current `README.md` text, which is what replaces a line number that drifts
+ * silently the moment the cited line moves. A quote is checked whether or not
+ * the line also carries `README_PARAPHRASE_MARKER`, since a marker documents
+ * that part of a string is synthesized and asserts nothing about a phrase the
+ * same line puts in quotes: quoting a borrow verbatim and then never checking
+ * it would let the exact drift this file exists to catch survive inside its
+ * own escape hatch. `paraphrase` is what a marked line falls to only once it
+ * carries no quote of its own, muted by `README_PARAPHRASE_MARKER` the way
+ * `isMarked` mutes every other exemption in this repository. `bare` is the
+ * retired `README.md:<n>` form, reported rather than accepted so the fragile
+ * convention this replaces cannot come back on a later edit.
+ *
+ * Modeled on `clientCommandCitationsIn` in `src/client-commands.ts`, including
+ * its use of `isMarked` for the exemption.
+ */
+export function readmeCitationsIn(
+  file: string,
+  text: string,
+): ReadmeCitation[] {
+  const lines = text.split('\n')
+  const citations: ReadmeCitation[] = []
+
+  for (const [index, line] of lines.entries()) {
+    const match = ANCHOR.exec(line)
+    if (match === null) continue
+
+    const rest = (match[1] ?? '').trim()
+
+    const phrases = [...rest.matchAll(QUOTED_PHRASE)].map(
+      (found) => found[1] ?? '',
+    )
+    if (phrases.length > 0) {
+      citations.push({
+        file,
+        line: index + 1,
+        kind: 'quoted',
+        text: line.trim(),
+        phrases,
+      })
+      continue
+    }
+
+    if (isMarked(lines, index, README_PARAPHRASE_MARKER)) {
+      citations.push({
+        file,
+        line: index + 1,
+        kind: 'paraphrase',
+        text: line.trim(),
+        phrases: [],
+      })
+      continue
+    }
+
+    if (/^\d/.test(rest)) {
+      citations.push({
+        file,
+        line: index + 1,
+        kind: 'bare',
+        text: line.trim(),
+        phrases: [],
+      })
+    }
+  }
+
+  return citations
+}

package/standards/branch.md

@@ -21,11 +21,13 @@ Does not govern:
 - Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
 - Length: 50 characters maximum
 - Casing: kebab-case only, no underscores or camelCase
-- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Description: 2 words maximum, up to 4 only when genuinely needed for specificity
 - Capture the core change, not the commit message verbatim
 - For branches with multiple commits, use the unifying concern as the description.
 - Do not duplicate type in description (e.g., `feat/feature-login`)
 
+The upper bound reads 4 rather than 3 for every branch, whoever named it. It was widened on 2026-09-06 so that a branch taking its description from a planning document's own filename stops being renamed at ship, since a rename there is a third derivation and parts the branch from the filename that later tooling reads back to find the document. Nothing can tell such a name from any other, so the wider bound holds for all of them and 2 words stays the target.
+
 ## Types
 
 - `feat`: new feature or capability

package/tooling/claude/seeds/.claude/hooks/index-reminder.sh

@@ -53,5 +53,5 @@ marker="$marker_dir/$key"
 mkdir -p "$marker_dir"
 : >"$marker"
 
-msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search.' "$index")
+msg=$(printf 'An index.md exists at %s. Read it before searching this folder, it catalogs the sibling files faster than a blind search. For a cross-folder answer, run canon indexes list --json or invoke the index-lookup skill.' "$index")
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$msg}}'

package/tooling/nextjs/configs/eslint.config.js

@@ -0,0 +1,90 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import prettier from 'eslint-config-prettier'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+import vitest from 'eslint-plugin-vitest'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  globalIgnores([
+    '.next',
+    'next-env.d.ts',
+    'dist',
+    'dist-ssr',
+    'coverage',
+    'release',
+    '.claude',
+    '.vscode',
+    '.husky',
+    'test-results',
+    'playwright-report',
+    'blob-report',
+    'playwright/.cache',
+  ]),
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+      'simple-import-sort': simpleImportSort,
+      'check-file': checkFile,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+      ],
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/*.{ts,tsx}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+      'check-file/folder-naming-convention': [
+        'error',
+        { 'src/**/!(__tests__)': 'KEBAB_CASE' },
+      ],
+    },
+  },
+  {
+    // App Router route and layout files export non-component values (metadata, route handlers), which this rule flags as violations.
+    files: ['src/app/**/*.{ts,tsx}'],
+    rules: {
+      'react-refresh/only-export-components': 'off',
+    },
+  },
+  {
+    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+    ...vitest.configs.recommended,
+  },
+  {
+    files: [
+      '*.config.{js,mjs,cjs,ts}',
+      'vitest.config.ts',
+      'playwright.config.ts',
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  prettier,
+])

package/tooling/nextjs/configs/next.config.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  agentRules: false,
+  turbopack: {
+    root: import.meta.dirname,
+  },
+}
+
+export default nextConfig

package/tooling/nextjs/configs/playwright.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const isCI = !!process.env.CI
+const baseURL = `http://localhost:${3000 + (Number(process.env.WORKTREE_PORT_OFFSET) || 0)}`
+
+export default defineConfig({
+  testDir: 'e2e',
+  forbidOnly: isCI,
+  retries: isCI ? 2 : 0,
+  reporter: isCI ? 'list' : 'html',
+  use: {
+    trace: 'on-first-retry',
+    baseURL,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+  ],
+  webServer: {
+    command: process.env.DIST_PREBUILT
+      ? 'bun run preview'
+      : 'bun run build && bun run preview',
+    url: baseURL,
+    reuseExistingServer: false,
+  },
+})