@erclx/canon 4.55.0 → 4.57.0

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/standards/wireframes.md

@@ -26,7 +26,7 @@ A wireframe works when someone can rebuild the surface from it without opening t
 
 - What is on screen, and where does it sit relative to everything else?
 - Which states can a visitor reach, and what does each one look like?
-- What does it say, word for word?
+- What does its structural copy say, word for word, and where does its long-form content come from?
 
 A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
 
@@ -60,7 +60,8 @@ Both fields feed `.claude/wireframes/index.md` when regenerated.
 
 ## Copy
 
-- Carry UI copy verbatim in the ASCII block or a short list below it. The wireframe is the source of truth for on-screen text.
+- Carry short structural text verbatim, in the ASCII block or a short list below it: labels, headings, empty-state strings, and nav or footer copy. The wireframe is the source of truth for this text.
+- Cite the source file for long-form or article-body content instead of duplicating it. A lede sentence or a body paragraph pulled into an ASCII figure drifts the moment its source changes, and nothing checks a fenced block against prose elsewhere. A citation elsewhere in the file does not excuse the block itself from still carrying the duplicate. Trim the block once the citation exists.
 - Mark copy that is dynamic or templated so a reader does not treat a placeholder as final text.
 
 ## Behavior
@@ -113,6 +114,7 @@ description: <when and where the surface appears>
 
 - <on-screen text, word for word>
 - <text the surface templates>: <marked so a reader does not read it as final>
+- <long-form content>: cited at <its source file>, not duplicated here
 
 ## Behavior
 

package/tooling/base/configs/commitlint.config.js

@@ -1,7 +1,33 @@
+const SUBJECT_STARTS_WITH_LETTER = /^[A-Za-z]/
+const SUBJECT_LEADING_LETTERS = /^[A-Za-z]+/
+
+// Checks the first word alone, unlike the built-in subject-case rule, which
+// tests the whole subject and would reject a legitimate capitalized proper
+// noun anywhere past the first word.
+const subjectFirstWordCase = (parsed) => {
+  const { subject } = parsed
+
+  if (
+    typeof subject !== 'string' ||
+    !SUBJECT_STARTS_WITH_LETTER.test(subject)
+  ) {
+    return [true]
+  }
+
+  const leadingWord = SUBJECT_LEADING_LETTERS.exec(subject)[0]
+
+  return [
+    leadingWord === leadingWord.toLowerCase(),
+    'subject must start with a lowercase word',
+  ]
+}
+
 const config = {
   extends: ['@commitlint/config-conventional'],
+  plugins: [{ rules: { 'subject-first-word-case': subjectFirstWordCase } }],
   rules: {
     'subject-case': [0],
+    'subject-first-word-case': [2, 'always'],
     'header-max-length': [2, 'always', 72],
     'scope-case': [2, 'always', 'lower-case'],
     'subject-full-stop': [2, 'never', '.'],

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

package/tooling/web/configs/scripts/screenshot.sh

@@ -11,7 +11,8 @@ fi
 bun run build
 bun run preview >/dev/null 2>&1 &
 PREVIEW_PID=$!
-trap 'kill "$PREVIEW_PID" 2>/dev/null || true; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+# shellcheck disable=SC2154 # pid is bound by the for loop inside the single-quoted trap body, which shellcheck does not track there
+trap 'kill "$PREVIEW_PID" 2>/dev/null || true; if command -v lsof >/dev/null 2>&1; then for pid in $(lsof -ti tcp:"$PREVIEW_PORT" 2>/dev/null); do kill "$pid" 2>/dev/null || true; done; else echo "lsof not found on PATH; cannot confirm the preview port is clear of a detached grandchild." >&2; fi; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
 
 for _ in $(seq 1 40); do
   if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then