@erclx/canon 4.55.0 → 4.56.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.55.0",
+  "version": "4.56.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -56,6 +56,13 @@ Run `canon tooling sync <stack> <target> --check` for the list resolved against
 - `commitlint.config.js`
 - `scripts/verify.sh`
 
+### nextjs
+
+- `eslint.config.js`
+- `next.config.ts`
+- `playwright.config.ts`
+- `vitest.config.ts`
+
 ### python
 
 - `.coveragerc`

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

@@ -35,12 +35,28 @@ Invoke `canon:claude-worker` first, whatever the worktree state. This session is
 
 Report it rather than proceeding silently when `canon:claude-worker` does not resolve. It ships with the plugin, so a session running this chain from a project holding the CLI alone builds with no role asserted.
 
-If `git rev-parse --git-dir` equals `git rev-parse --git-common-dir`, the session is in the main worktree. Invoke `canon:claude-worktree` before continuing. The wrapper handles name derivation and branch alignment. Do not call `EnterWorktree` directly.
+If `git rev-parse --git-dir` equals `git rev-parse --git-common-dir`, the session is in the main worktree. Invoke `canon:claude-worktree` before continuing, carrying the argument the subsection below derives. The wrapper handles branch alignment. Do not call `EnterWorktree` directly.
 
 If neither command resolves, stop: `❌ Not a git repository. Autoship needs git or a WorktreeCreate hook.`
 
 If the two commands differ, the session is already in a linked worktree. Continue.
 
+### Name the worktree from the plan rather than leaving it to be derived
+
+This step runs ahead of Step 1, so what it holds is the raw invocation argument rather than a resolved plan. When that argument is a plan path or a bare slug, run the verb on it and hand the result to `canon:claude-worktree` as its tier 0 argument:
+
+```bash
+canon tasks plan-branch <argument> --json
+```
+
+- `conforms: true`: pass the record's `branch`, which is already `<type>/<slug>`, and invoke nothing else to derive a name.
+- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. Pass `branch` anyway and say the cap it broke, since the alternative is a name this session shortened by hand, which is a second derivation and the thing this call exists to prevent. `git-branch` decides the rename at ship.
+- Anything else, including a refusal, a record carrying no `branch` key, and an installed binary carrying no `plan-branch` subcommand: invoke `canon:claude-worktree` bare and let its ladder derive the name. Say the verb did not answer, so a reader can tell a derived name from a fallback one.
+
+The dispatch runbook runs the same verb on the same plan to pick the branch its collision check clears, so calling it here is what makes the checked branch and the taken branch one string. Deriving a name from `<plan>` by reading it was the alternative, and it is what produced three strings for one plan across four dispatches on 2026-09-05.
+
+A caller that supplied a task path, or supplied nothing at all, has no plan to hand the verb here, since resolving either is Step 1's work and Step 1 has not run. Invoke `canon:claude-worktree` bare in both cases. That is the ladder unchanged rather than a regression, and it leaves the hole open: a dispatched worker reaching this step through a task path derives its name from a tier rather than from the plan the dispatcher checked.
+
 ## Step 1: read the plan
 
 Resolve `<plan>` in this order, stopping at the first match:

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -7,9 +7,18 @@ Run this at loop step 4, for a `## Run now` row whose plan is verified, in place
 
 ## Derive the candidate
 
-Resolve `<slug>` from `<plan>`, the row's plan file, the way `claude-worktree` Step 2 resolves a plan-matched name, per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. Resolve `<type>` off that plan's `## Summary` and `**Files to touch:**` lines, per `${CLAUDE_SKILL_DIR}/../../standards/branch.md`, defaulting to `feat` when the lines settle nothing. The candidate branch is `<type>/<slug>`.
+Run `canon tasks plan-branch <plan> --json` against the row's plan file and read `branch`, `type`, `slug`, and `conforms` off the record.
 
-This is the branch the worker takes, not a guess at one it will derive for itself. Carry the exact string into the launch below. Both halves of that derivation have already disagreed in production: one run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, and a later one checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`. A check against a branch nobody uses verifies nothing, and a slug mismatch no longer fails the run downstream on its own, since `claude-autoship` now takes `<plan>` directly rather than resolving it from the worker's own branch. The check above is what has to catch a wrong candidate now.
+- `conforms: true`: take `branch` as the candidate, and take `type` and `slug` from the same record for the check below.
+- `conforms: false`: the plan's own filename breaks a cap in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. Report which, and hand the row to the human-launch line below rather than shortening the slug here. A rename parts the branch from the plan filename that `claude-worktree` tier 1 and `git-pr`'s plan lookup both read back.
+- `reason: archived`, `no-plan`, or `bad-input`: the row does not cite a live plan. Repoint the row or fix the citation rather than dispatching, since `claude-autoship` Step 1 refuses the same file and the worker would meet that refusal after the launch spent.
+- Anything else, including a record carrying no `branch` key and an installed binary carrying no `plan-branch` subcommand: treat the candidate as unverified rather than clear, name which reading could not be taken, and fall back to the human-launch line below. Re-deriving by prose here rebuilds the defect the verb closes, and does it quietly.
+
+Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+The worker calls the same verb on the same plan at `claude-autoship` Step 0, so the branch this gate checks and the branch that session takes are one string by construction rather than two readings of one paragraph. They were two readings until 2026-09-06. One run checked `docs/remaining-skill-verdicts` against a worker that took `docs/skill-verdicts-decide`, another checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`, and four dispatches on 2026-09-05 produced three strings for one plan. A check against a branch nobody uses verifies nothing.
+
+The type the verb reports is fixed at `feat` whatever the row does, which is the half of the derivation that disagreed most. What makes that safe is that a branch type is cosmetic: `git-stage` reads a commit's type off the staged diff and `git-pr` reads a title off the diff, so nothing a release reads passes through the branch name. What it costs is a worktree listing where every dispatched branch reads `feat/`, which a person scanning one loses. Nothing renames it later, and this paragraph said `git-branch` did until 2026-09-06, when its conventions guard turned out to fire on a conforming `feat/` before reaching any type judgment.
 
 ## Check the plan waits on nobody
 
@@ -93,9 +102,9 @@ The worker resolves that id back to a name through `canon sessions list --json`,
 
 The template carries no worktree call. `claude-autoship` Step 0 invokes `canon:claude-worker` and then `canon:claude-worktree` itself, and neither carries the flag, so both are reachable through the `Skill` tool regardless of where a call to them would sit in a prompt. The autoship call carries `<plan>`, the same file this runbook already read to derive the branch, so its Step 1 takes it as the caller-supplied plan rather than re-deriving one from the slug the worker's branch happens to carry.
 
-Dropping the argument does not hand `claude-worktree` a formal one in its place. A worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there, so the ladder alone still closes nothing.
+The template names no branch, and it does not need to. `claude-autoship` Step 0 runs `canon tasks plan-branch <plan>` on the same file this runbook derived the candidate from, and hands the `<type>/<slug>` it reports to `claude-worktree` as its tier 0 argument, so the two sides agree by calling one derivation rather than by a string copied between them.
 
-What closes it is the same inference four workers already took before this template existed: the session already holds `<plan>` and derives `claude-worktree`'s name from it directly, rather than waiting on a tier to supply one. That is a judgment rather than a contract, and it is the same judgment both live disagreements came from, so read it as the residual risk this template still carries rather than as solved.
+That retires the inference four workers took before the verb existed, which was to derive the name from `<plan>` by their own reading of it. Nothing has to reach `claude-worktree`'s ladder now, which mattered because a worker launched onto `main` cannot match tier 1, a board carrying more than one plan puts tier 2 out of reach, and tier 3 tells it to ask a person who is not there. What still travels on judgment is the fallback: a worker whose installed binary carries no `plan-branch` derives by prose, which is where both live disagreements came from.
 
 ### Expansion needs position zero and a clean delimiter, not leading order alone
 

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

@@ -49,11 +49,17 @@ Tier 0 sits ahead of the inference because every tier below it answers from stat
 
 Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
 
-Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan whose lines settle nothing.
+Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name that came from a plan, through tier 1 or tier 2, takes its type from `canon tasks plan-branch <plan> --json`, read off the record's `type` field. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan the verb could not answer for.
 
-The caller's type wins because reading it off a plan is the half that has already disagreed in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently.
+The verb is the reading rather than this body, because a type read off a plan's `## Summary` and `**Files to touch:**` lines is a judgment, and it has disagreed with itself in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently. The verb answers `feat` for every plan, so two sides calling it cannot part.
 
-A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens.
+The caller's type still wins over the verb's, because tier 0 is the one source that knows something no file states. The ordinary caller is `claude-autoship` Step 0, which ran the verb itself and is handing over the answer it got, so nothing is overridden in that case either.
+
+Branch on the record rather than on the exit code, which a shell function wrapping `canon` can flatten to zero. Take `feat` and say the verb did not answer where it refuses, where the record carries no `type` key, or where the installed binary carries no `plan-branch` subcommand.
+
+A wrong type is cheap because the branch type is cosmetic rather than because anything corrects it. `git-stage` reads a commit's type off the staged diff and `git-pr` reads a title off the diff too, so the semantics a release reads never pass through the branch name at all. Nothing downstream is wrong when a `feat/` sits over a fix, and a person scanning a worktree listing loses a signal.
+
+`git-branch` does not correct it, which three surfaces used to say it did. Its second guard reads `If branch name already follows conventions, stop`, and `${CLAUDE_SKILL_DIR}/../../standards/branch.md` makes the type vocabulary an axis without making the choice within that vocabulary one, so `feat/` over a fix conforms and the guard fires ahead of the Analysis line that would have re-derived the type.
 
 Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename:
 

package/claude/skills/setup-init/SKILL.md

@@ -45,7 +45,8 @@ Read these from the project root in parallel, skipping any that do not exist:
 ## Resolve arguments
 
 - **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base` and carry the fallback into the preview.
-- **Tooling stack:** pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
+- **Tooling stack:** pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`, `nextjs`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
+- **Next.js:** map `next` in `package.json` dependencies, or a root `next.config.ts`/`.js`/`.mjs` file, to the `nextjs` tooling stack. The dependency name does not match the stack name by itself.
 - **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Do not add a rule the stack already pulls in.
 - **Skip (`--skip`):** `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
 

package/docs/agents/index.md

@@ -43,7 +43,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
 - [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
-- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
+- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, deriving the branch a dispatch and a worker both take, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
 - [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/tasks.md

@@ -1,6 +1,6 @@
 ---
 title: Tasks
-description: Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
+description: Selecting a shipped task by stem or pull request, recording a number and closing an outcome, deriving the branch a dispatch and a worker both take, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 ---
 
 # Tasks
@@ -104,6 +104,32 @@ 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 branch
+
+`canon tasks plan-branch <plan>` derives the branch name from a plan file. It reports and never writes, and it names the plan the same two ways `canon tasks plan-answers` does, by path or by slug, against the same two bases.
+
+```bash
+canon tasks plan-branch dispatch-answer-gate
+canon tasks plan-branch .canon/plans/feature-dispatch-answer-gate.md --json
+```
+
+| Option          | Effect                                      |
+| --------------- | ------------------------------------------- |
+| `--json`        | Emit a machine-readable record on stdout    |
+| `--root <path>` | Board root, defaulting to the main worktree |
+
+The record carries `type`, `slug`, `branch`, `words`, and `conforms`. Exit codes: `0` derived and conforming, `1` refused with `no-plan`, `archived`, or `bad-input`, `2` derived with `conforms` false. Branch on `conforms` rather than on the exit code, which a shell function wrapping `canon` can flatten to zero.
+
+`slug` is the plan filename with its `feature-` prefix and its extension taken off, and `type` is the constant `feat`. Reading a type off the plan's prose was the alternative, and it is the half of the derivation that has already disagreed with itself: one dispatch checked `fix/path-form-hook` against a worker that took `feat/path-form-hook`, both sides reading one plan. What makes the constant safe is that a branch type is cosmetic. `git-stage` reads a commit's type off the staged diff and `git-pr` reads a title off the diff, so the semantics a release reads never pass through the branch name. What it costs is a worktree listing where every plan-derived branch reads `feat/`, and nothing renames it later.
+
+`conforms` reads both caps `standards/branch.md` states, being 4 words on the description and 50 characters on the whole branch. A false reading is a row for a person rather than a name to shorten here, since a rename parts the branch slug from the plan slug that `claude-worktree` tier 1 and `git-pr`'s plan lookup both read back.
+
+Both sides of a dispatch call it. The orchestrator's collision check derives its candidate here, and `claude-autoship` Step 0 derives the worktree it enters from the same plan, so the branch a gate clears and the branch a session takes are one string by construction. They were two readings of one paragraph until 2026-09-06, when four dispatches on one plan produced three different strings.
+
+```bash
+canon tasks plan-branch dispatch-answer-gate --json | jq -r '.branch'
+```
+
 ## 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.

package/docs/target-projects.md

@@ -83,7 +83,7 @@ Each diagram entry records the commit and date it was last verified against, and
 
 The default path is `base`. `canon init` on `base` installs base tooling configs, Claude seeds, and governance core rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
 
-Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
+Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`canon tooling list --json` names the current set) and the matching governance stack (`react`, `astro`, `node`).
 
 `node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so nothing there marks a project as a backend. Pass it deliberately with `canon init --stack node-server` or `canon gov install node-server <target>`.
 

package/package.json

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

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/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,
+  },
+})

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

@@ -0,0 +1,28 @@
+import path from 'node:path'
+
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src'),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['src/test/setup.ts'],
+    passWithNoTests: true,
+    exclude: [
+      '**/node_modules/**',
+      '**/.next/**',
+      '**/e2e/**',
+      '**/.{idea,git,cache,output,temp}/**',
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'src/test/setup.ts', 'e2e/'],
+    },
+  },
+})

package/tooling/nextjs/manifest.toml

@@ -0,0 +1,19 @@
+[stack]
+name = "nextjs"
+extends = "web"
+runtime = "bun"
+scaffold = "bunx create-next-app@latest {{name}} --typescript --tailwind --eslint --app --src-dir --import-alias \"@/*\" --use-bun --skip-install --disable-git --no-agents-md --yes"
+
+[dependencies.dev]
+packages = [
+  "next",
+  "@tailwindcss/postcss",
+]
+
+[scripts]
+"preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && next start --port $((3000 + WORKTREE_PORT_OFFSET))"
+"typecheck" = "next typegen && tsc --noEmit"
+
+[scripts.override]
+"dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && next dev --port $((3000 + WORKTREE_PORT_OFFSET))"
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 3000) && export PREVIEW_PORT && bash scripts/screenshot.sh"

package/tooling/nextjs/reference.md

@@ -0,0 +1,47 @@
+# Tooling nextjs reference
+
+> Extends: `web`. Apply web stack first.
+
+## Overview
+
+The nextjs stack covers Next.js + TypeScript projects using the App Router. It ships golden configs for `next.config.ts`, `vitest.config.ts` (plain `defineConfig`, no bundler merge), `playwright.config.ts` (build-then-preview), and an `eslint.config.js` that extends the web layer's config with `.next` ignores and an App Router override. Shared web tooling (ESLint base, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+
+## Scaffold checklist
+
+1. Scaffold with `bunx create-next-app@latest <name> --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-bun --skip-install --disable-git --no-agents-md --yes`. `--no-agents-md` skips the scaffold-time `AGENTS.md`/`CLAUDE.md` write, which otherwise duplicates the root `CLAUDE.md`.
+2. Install web tooling: `canon tooling sync web . --write`
+3. Install nextjs configs: `canon tooling sync nextjs . --write`
+4. Extend the `ci` and `development` context entries under `.claude/context/` per the web reference's extend sections plus the nextjs rows below.
+5. Run `bun run lint:fix` then `bun run check`.
+
+## What ships as golden configs
+
+- `next.config.ts`: `agentRules: false` stops Next from regenerating `AGENTS.md`/`CLAUDE.md` on every run, which would otherwise compete with the root `CLAUDE.md`. `turbopack.root: import.meta.dirname` pins the workspace root, silencing Next's multi-lockfile inference warning in any checkout carrying more than one lockfile above the project, a worktree included.
+- `vitest.config.ts`: plain `defineConfig`, no `mergeConfig` or `getViteConfig` since Next has no Vite config to merge from. jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `.next/**` in test excludes.
+- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `3000` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. `DIST_PREBUILT` drops the `build` half, matching the astro stack's flag.
+- `eslint.config.js`: overrides the web layer with `.next` and `next-env.d.ts` added to `globalIgnores`, keeping `react-hooks`/`react-refresh` since this stack still ships React components. `react-refresh/only-export-components` is `off` for `src/app/**`, since route and layout files export non-component values the rule would otherwise flag.
+
+## Port
+
+Next has no config-file port hook, unlike `astro.config.mjs`'s `server.port` or `vite.config.ts`'s `server.port`. The `${base} + WORKTREE_PORT_OFFSET` formula is computed twice instead of once: in `playwright.config.ts` as a JS expression, and in `[scripts.override]` for `dev` and `preview` as shell arithmetic passed to `next`'s own `--port` flag. Default port is `3000`, Next's own default.
+
+## Typecheck
+
+`typecheck` runs `next typegen && tsc --noEmit`. The App Router's route-level types (`LayoutProps`, `PageProps`) are generated into `.next/types/`, gitignored and absent from a fresh checkout, and `tsc` fails on them unresolved without the typegen step first.
+
+## No golden `tsconfig.json`
+
+`create-next-app`'s own default `tsconfig.json` needs no changes beyond project-specific path aliases, so a golden copy here would ship nothing the scaffold does not already write.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run dev` | Start the Next dev server on port 3000, plus this worktree's port offset. |
+| `bun run build` | Build the production bundle. |
+| `bun run preview` | Serve the built bundle locally, on port 3000 plus the worktree offset. |
+| `bun run typecheck` | Run `next typegen` then `tsc --noEmit`. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `next typegen && tsc --noEmit` passes ``.

package/tooling/nextjs/seeds/.cspell/tech-stack.txt

@@ -0,0 +1,3 @@
+logomark
+turbopack
+vercel