@erclx/canon 5.39.0 → 5.41.0

package/src/tasks/fan-in.ts

@@ -0,0 +1,176 @@
+import type { Finding } from '@/records/validate'
+import { PLAN_BRANCH_TYPE } from '@/tasks/branch'
+import { constraintBullets, type StackPlan } from '@/tasks/stack'
+
+const PLAN_PREFIX = 'feature-'
+
+const MEMBER_OF = /\bfan[- ]in member of\s+/gi
+
+const FANS_IN = /\bfans in\s+/gi
+
+/**
+ * A backticked slug may drop the `feature-` prefix, and a bare one must carry
+ * it. Without the prefix a bare word is indistinguishable from the prose that
+ * follows the list, so `Fans in feature-a and the rest` would read `the` as a
+ * member.
+ */
+const TICKED_SLUG = /^`((?:feature-)?[a-z0-9][a-z0-9-]*)`/i
+const BARE_SLUG = /^(feature-[a-z0-9][a-z0-9-]*)/i
+
+const LIST_SEPARATOR = /^\s*(?:,\s*(?:and\s+)?|and\s+)/i
+
+function stemOf(slug: string): string {
+  const lower = slug.toLowerCase()
+
+  return lower.startsWith(PLAN_PREFIX) ? lower : `${PLAN_PREFIX}${lower}`
+}
+
+function leadingSlug(text: string): { stem: string; rest: string } | null {
+  const match = TICKED_SLUG.exec(text) ?? BARE_SLUG.exec(text)
+  const slug = match?.[1]
+  if (match === null || slug === undefined) return null
+
+  return { stem: stemOf(slug), rest: text.slice(match[0].length) }
+}
+
+/** Every slug in the list standing after each match of `phrase`, in order. */
+function readList(text: string, phrase: RegExp, many: boolean): string[] {
+  const stems: string[] = []
+
+  for (const bullet of constraintBullets(text)) {
+    for (const match of bullet.matchAll(phrase)) {
+      let rest = bullet.slice((match.index ?? 0) + match[0].length)
+
+      for (;;) {
+        const slug = leadingSlug(rest)
+        if (slug === null) break
+        stems.push(slug.stem)
+        if (!many) break
+
+        const separator = LIST_SEPARATOR.exec(slug.rest)
+        if (separator === null) break
+        rest = slug.rest.slice(separator[0].length)
+      }
+    }
+  }
+
+  return [...new Set(stems)]
+}
+
+/** The integrators a member plan names, which a conforming member holds one of. */
+export function readFanInIntegrators(text: string): string[] {
+  return readList(text, MEMBER_OF, false)
+}
+
+/** The members an integrator plan fans in, in the order its merges run. */
+export function readFanInMembers(text: string): string[] {
+  return readList(text, FANS_IN, true)
+}
+
+/**
+ * The branch a member builds on, derived the way `planBranch` derives it, since
+ * the integrator merges and the dispatch gate reads the branch the worker took.
+ */
+export function fanInBranch(stem: string): string {
+  const slug = stem.startsWith(PLAN_PREFIX)
+    ? stem.slice(PLAN_PREFIX.length)
+    : stem
+
+  return `${PLAN_BRANCH_TYPE}/${slug}`
+}
+
+function unmatched(stem: string, subject: string, message: string): Finding {
+  return { kind: 'fan-in-unmatched', record: `${stem}.md`, subject, message }
+}
+
+/**
+ * Every place a fan-in set's two sides disagree across the live plans.
+ *
+ * An absent plan is reported rather than skipped, unlike `stackFindings`. The
+ * caller hands over the live folder only, so a member archived after it merged
+ * reads as absent, and an integrator still listing it would otherwise take its
+ * leftover branch on origin as a member that finished.
+ *
+ * A member two integrators list is reported on each of them rather than paired
+ * with whichever sorts first, since either merge would carry it.
+ */
+export function fanInFindings(plans: readonly StackPlan[]): Finding[] {
+  const integratorsOf = new Map(
+    plans.map((plan) => [plan.stem, readFanInIntegrators(plan.text)]),
+  )
+  const membersOf = new Map(
+    plans.map((plan) => [plan.stem, readFanInMembers(plan.text)]),
+  )
+  const listers = new Map<string, string[]>()
+  for (const [integrator, members] of membersOf) {
+    for (const member of members) {
+      listers.set(member, [...(listers.get(member) ?? []), integrator])
+    }
+  }
+
+  const findings: Finding[] = []
+
+  for (const { stem } of plans) {
+    const integrators = integratorsOf.get(stem) ?? []
+
+    for (const integrator of integrators) {
+      if (integrators.length > 1) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of ${integrators.map((name) => `\`${name}\``).join(' and ')}. A member fans in to one integrator.`,
+          ),
+        )
+      } else if (!membersOf.has(integrator)) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of \`${integrator}\`, which is not a live plan. Write the integrator's plan, or drop the member bullet.`,
+          ),
+        )
+      } else if (!(membersOf.get(integrator) ?? []).includes(stem)) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of \`${integrator}\`, whose \`Fans in\` bullet does not list it.`,
+          ),
+        )
+      }
+    }
+
+    for (const member of membersOf.get(stem) ?? []) {
+      const others = (listers.get(member) ?? []).filter((name) => name !== stem)
+
+      if (others.length > 0) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which ${others.map((name) => `\`${name}\``).join(' and ')} also fans in. A member fans in to one integrator.`,
+          ),
+        )
+      } else if (!integratorsOf.has(member)) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which is not a live plan. An archived member is not a finished one, so drop it from the list or restore its plan.`,
+          ),
+        )
+      } else if (!(integratorsOf.get(member) ?? []).includes(stem)) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which does not name it as its integrator.`,
+          ),
+        )
+      }
+    }
+  }
+
+  return findings
+}

package/src/tasks/stack.ts

@@ -41,7 +41,7 @@ export interface StackPair {
  * One string per `**Constraints:**` bullet, with a wrapped continuation line
  * joined to the bullet it belongs to.
  */
-function constraintBullets(text: string): string[] {
+export function constraintBullets(text: string): string[] {
   const bullets: string[] = []
 
   for (const line of splitPlanSections(text).get('Constraints') ?? []) {

package/tooling/astro/reference.md

@@ -4,25 +4,49 @@
 
 ## Overview
 
-The astro stack covers Astro + TypeScript projects: content sites, marketing sites, blogs, and docs. Interactive islands use React only. Output is static. It ships golden configs for `astro.config.mjs`, `vitest.config.ts` (using `getViteConfig` from `astro/config`), `playwright.config.ts` (preview-server backed), a `tsconfig.json` that extends `astro/tsconfigs/strict`, an `eslint.config.js` that keeps ESLint for this stack alone, and a `.prettierrc` that formats `.astro` files alone.
+The astro stack covers Astro + TypeScript projects, being content sites, marketing sites, blogs, and docs. Interactive islands use React only and output is static.
+
+It ships golden configs for `astro.config.mjs`, `vitest.config.ts`, `playwright.config.ts` (preview-server backed), and a `tsconfig.json` extending `astro/tsconfigs/strict`. An `eslint.config.js` keeps ESLint for this stack alone, and a `.prettierrc` formats `.astro` files alone.
 
 ## Scaffold checklist
 
 1. Scaffold with `bunx create-astro@latest`. Choose `TypeScript: Strict`. Skip git init and install.
-2. Add React integration: `bunx astro add react`. Do not use `astro add tailwind`. That command installs the v3 integration. Tailwind v4 arrives via the web manifest.
-3. Install web tooling: `canon tooling sync web . --write`
-4. Install astro adapter: `canon tooling sync astro . --write`
+2. Add React with `bunx astro add react`. Never use `astro add tailwind`, which installs the v3 integration. Tailwind v4 arrives via the web manifest.
+3. Install web tooling with `canon tooling sync web . --write`.
+4. Install the astro adapter with `canon tooling sync astro . --write`.
 5. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the astro rows below.
 6. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
 ## What ships as golden configs
 
-- `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
-- `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
-- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
-- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, `@/` paths.
-- `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
-- `eslint.config.js`: this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling/stacks.md` for the measurement.
+### Astro and test configs
+
+The configs below wire Astro into the web layer's test setup.
+
+- `astro.config.mjs` adds `@astrojs/react`, `@tailwindcss/vite` in `vite.plugins`, the `@/` alias via `vite.resolve.alias`, and `ASTRO_SITE` for the `site` field.
+- It serves port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`.
+- Astro feeds `server.port` through as the preview port but merges the `vite` block into the config backing both servers, so the port sits at the top level and the bind guarantee under `vite`.
+- `vitest.config.ts` uses `getViteConfig` from `astro/config`, not `mergeConfig`, with jsdom, globals, the setup file, `passWithNoTests: true`, v8 coverage, and `**/*.astro` in coverage excludes.
+- `tsconfig.json` adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, and `@/` paths.
+
+### Playwright config
+
+`playwright.config.ts` runs all browsers, with `webServer` running `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET` and `reuseExistingServer: false`.
+
+- Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
+- `DIST_PREBUILT` in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job produced.
+
+### ESLint config
+
+`eslint.config.js` is this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. It adds `eslint-plugin-astro` with `astro-eslint-parser`.
+
+- React hooks apply to `.jsx` and `.tsx` only, since `.astro` is not React.
+- `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's PascalCase on purpose, since markup names a component by its import binding.
+- `.js` and `.jsx` stay out of that rule, matching `web` and `nextjs`.
+- `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the `pages/` subtree, which has its own off-block for bracket-named dynamic routes and slug folders.
+- `canon/context/surfaces/tooling.md` carries the measurement behind both naming rules.
+
+The social card files also ship as golden configs, being `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`. See `## Social card route` below.
 
 ## Typecheck
 
@@ -30,73 +54,90 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 ## Vitest scope
 
-Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Page-level behavior is verified by Playwright against rendered output.
+Unit-test React island components (`.tsx`) only. Do not test `.astro` files, since Playwright verifies page-level behavior against rendered output.
 
-Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin avoided `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro now bundles Vite 8 itself, so that conflict no longer applies.
+Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin dodged `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro bundling Vite 8 itself ended that conflict.
 
 ## Formatting (extend)
 
-- Format `.astro` files with Prettier and every other file with oxfmt. oxfmt loads no Prettier plugin, so it cannot parse `.astro`.
-- Load `prettier-plugin-astro` first in `.prettierrc`'s plugins, then `prettier-plugin-tailwindcss` last (per its docs), with a parser override for `.astro` files.
+- Format `.astro` files with Prettier and every other file with oxfmt, which loads no Prettier plugin and cannot parse `.astro`.
+- Load `prettier-plugin-astro` first in `.prettierrc`'s plugins and `prettier-plugin-tailwindcss` last, with a parser override for `.astro` files.
 - Ignore `**/*.astro` in this stack's `.oxfmtrc.json`, so the two formatters never touch one file.
-- Copy every other option from base's `.oxfmtrc.json` into this one by hand. Scan takes the child config over the parent's whole file, so a change to base's options is lost here until it is copied.
+- Copy every other option from base's `.oxfmtrc.json` by hand. Scan takes the child config over the parent's whole file, so a change to base's options is lost here until copied.
 - Override `check:format` and `format` to run oxfmt, then Prettier over `**/*.astro`.
 
 ## ESLint
 
 - Override `lint` and `lint:fix` back to `eslint . --max-warnings 0`, since the web layer sets them to oxlint.
-- Install the ESLint packages here (`eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, `globals`), since the web layer no longer ships them. Pin `eslint@^9`: ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports.
+- Install `eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, and `globals`, since the web layer no longer ships them.
+- Pin `eslint@^9`, because ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports.
 - Expect the web layer's `.oxlintrc.json` in the target. Nothing runs it here.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run dev` | Start the Astro dev server on port 4321, plus this worktree's port offset. |
-| `bun run build` | Run `astro check` then build the static output. |
-| `bun run preview` | Serve the built site locally. |
-| `bun run astro` | Expose the Astro CLI. |
-| `bun run typecheck` | Run `astro check`. |
+| Command             | Purpose                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| `bun run dev`       | Start the Astro dev server on 4321 plus this worktree's offset. |
+| `bun run build`     | Run `astro check` then build the static output.                 |
+| `bun run preview`   | Serve the built site locally.                                   |
+| `bun run astro`     | Expose the Astro CLI.                                           |
+| `bun run typecheck` | Run `astro check`.                                              |
 
 ## CI docs (extend)
 
-In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row asserts `` `astro check` passes `` and the Build row asserts `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
 
 ## Social card route
 
-The social card is a route the project keeps rather than a page a render writes and deletes, so re-rendering it after a rename is an edit to one string and a re-capture instead of another pass through `draft-identity`'s pick loop with an operator in it. `canon:draft-identity` writes the picked composition into the route and captures it through the server below.
+The social card is a route the project keeps rather than a page a render writes and deletes. Re-rendering it after a rename is an edit to one string and a re-capture, not another pass through the `draft-identity` pick loop.
+
+`canon:draft-identity` writes the picked composition into the route and captures it through the server below.
 
 ### What ships
 
-- `card.config.mjs`: a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That is what excludes the card from the published build structurally rather than by a filename convention, the same mechanism `scenarios.astro` reaches for with `import.meta.env.DEV`. Its base port is `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a card server and a dev server of one worktree never contend.
-- `card-src/pages/og-card.astro`: the route, shipped as a working placeholder so it serves before any pick has been taken. It imports the project's own global stylesheet, which is what lets the composition read real tokens and real fonts instead of typed copies. It reads `--color-background` and `--color-text`, the names `canon design css` emits, and sets no `font-family` at all so the card inherits the project's body font rather than reading a font token the design system does not emit.
-- `scripts/check-card-exclusion.sh`: fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and fails when the route dropped that tag, since the marker is what the leak test reads for.
-- `bun run card:dev` serves the route. `bun run card:check` runs the exclusion check, which base's verify runner, `scripts/verify.ts`, also runs after its build stage whenever the script is installed.
+The route is a second config, an exclusion check, and two scripts. The page itself is covered below.
+
+- `card.config.mjs` is a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That excludes the card from the published build structurally.
+- `card.config.mjs` uses base port `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a worktree's card and dev servers never contend.
+- `scripts/check-card-exclusion.sh` fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and when the route dropped the tag, since the leak test reads it.
+- `bun run card:dev` serves the route and `bun run card:check` runs the exclusion check, which base's `scripts/verify.ts` also runs after its build stage when the script is installed.
 
-### Why each piece is shaped that way
+### Stylesheet and tokens
 
-The stylesheet import points at `@/styles/global.css`. A project keeping its stylesheet elsewhere retargets that one line, and an unresolved path then refuses the card server by name, which is the loud direction rather than the convenient one. The quiet failure it replaces is a card captured against no stylesheet at all: it renders as an unstyled box and reports success.
+`card-src/pages/og-card.astro` ships as a working placeholder, so it serves before any pick. It imports the project's global stylesheet to read real tokens and fonts, uses `--color-background` and `--color-text` as `canon design css` emits them, and sets no `font-family`, so the card inherits the body font.
 
-A custom property the stylesheet does not define is the same silent failure in a second costume. It takes its fallback, captures cleanly and reports success, so the card ships on typed values while reading as though it read real ones. That is why the route names only properties `canon design css` emits, and why a project retargeting the stylesheet import checks the names against what its own stylesheet defines.
+- The import points at `@/styles/global.css`. A project keeping its stylesheet elsewhere retargets that one line.
+- An unresolved path refuses the card server by name. That is the loud direction, replacing a card captured against no stylesheet that renders unstyled and reports success.
 
-The exclusion is a check rather than a convention because the route has three consumers and only one of them can be enforced. The card server reads it, the capture reads it, and the published build must not carry it.
+- A custom property the stylesheet does not define fails the same silent way. It takes its fallback, captures cleanly, and ships typed values.
+- So the route names only properties `canon design css` emits, and a project retargeting the import checks the names against its own stylesheet.
 
-`.card` is declared at 600x315, half of the 1200x630 target. `canon capture` opens every page at a fixed 2x device scale factor with no flag to change it, so a half-size element is what lands the captured PNG on the literal size. Declaring it at 1200x630 captures at 2400x1260.
+### Exclusion and card size
+
+The exclusion is a check rather than a convention because the route has three consumers and only one can be enforced. The card server reads it, the capture reads it, and the published build must not carry it.
+
+`.card` is declared at 600x315, half of the 1200x630 target. `canon capture` opens every page at a fixed 2x device scale factor with no flag to change it, so a half-size element lands the PNG on the literal size. Declaring 1200x630 captures at 2400x1260.
 
 ### Why v1 is Astro-only
 
-Astro is the one web stack whose config gives a route a structural build exclusion. Next's App Router has no build-time route exclusion at all, and it needs none on the path it will take, since `ImageResponse` is that framework's own production mechanism and a card route there is meant to be served. `vite-react` builds a single-page app with no page router, so a card is a second Rollup entry rather than a route.
+Astro is the one web stack whose config gives a route a structural build exclusion.
+
+- Next's App Router has no build-time route exclusion, and needs none on its path, since `ImageResponse` is that framework's production mechanism and a card route there is meant to be served.
+- `vite-react` builds a single-page app with no page router, so a card is a second Rollup entry rather than a route.
 
 ## Gitignore (extend)
 
-`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+These `[gitignore]` groups mirror the manifest.
 
 - `"# Astro" = [".astro/"]`
 - `"# Social card" = ["card-dist/"]`
 
 ## Scenario switcher
 
-- `src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
-- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher for moving between them.
-- Guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
-- Astro-only. It uses `is:inline`, `define:vars`, and `set:html`, which only the `.astro` file format parses. `vite-react` gets no equivalent until a real decision drives one.
+`src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
+
+- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher between them.
+- It is guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
+- It is Astro-only, using `is:inline`, `define:vars`, and `set:html`, which only the `.astro` format parses. `vite-react` gets no equivalent until a real decision drives one.

package/tooling/base/reference.md

@@ -2,65 +2,86 @@
 
 ## Overview
 
-The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, conventional commits, git hooks, CI, and the verify runner. Every other stack extends it, so a decision made here is one every stack inherits. Shell formatting and linting live in the `shell` add-on stack, which a project syncs once it writes shell.
+The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, conventional commits, git hooks, CI, and the verify runner. Every other stack extends it, so a decision made here is one every stack inherits. Shell formatting and linting live in the `shell` add-on stack.
 
 A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `canon docs scenarios` carries the recipe.
 
 ## What ships as golden configs
 
-Golden config files live in `tooling/base/configs/` and are copied into the target on `canon tooling sync base . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
+Golden configs live in `tooling/base/configs/`. `canon tooling sync base . --write` copies them into the target and replaces whatever sits at those paths. They are the source of truth, so this reference covers rationale and the configs show the setup.
 
-- `.oxfmtrc.json`: `semi: false`, `singleQuote: true`, `printWidth: 80`, and `sortPackageJson: false`, which keep the output Prettier wrote. The `astro` stack repeats these options in its own copy, so copy a change here into it.
-- `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, `subject-case` disabled, and a local `no-claude-co-author` rule refusing a `Co-authored-by` trailer that names Claude or Anthropic.
-- `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
-- `scripts/verify.ts`: the one verify runner every stack shares, and the command behind `check`. It runs typecheck, lint, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out. Node modules only, since a target's own lint and typecheck read it.
-- `scripts/verify.json`: the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins. A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script. Base requires `check:format`, so a base-only target still fails on a missing one. The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first. These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
+### Formatting and commit configs
+
+Two configs fix how output looks and how commits read.
+
+- `.oxfmtrc.json` sets `semi: false`, `singleQuote: true`, `printWidth: 80`, and `sortPackageJson: false`, keeping the output Prettier wrote.
+- The `astro` stack repeats those options in its own copy, so copy a change here into it.
+- `commitlint.config.js` is an ESM default export extending `@commitlint/config-conventional`. It sets `header-max-length: 72`, `scope-case: lower-case`, and `subject-full-stop: never`.
+- Its `subject-case` rule is off, and a local `no-claude-co-author` rule refuses a `Co-authored-by` trailer that names Claude or Anthropic.
+- `.husky/` holds `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, and `post-rewrite`.
+
+### Verify runner
+
+`scripts/verify.ts` is the one verify runner every stack shares, and the command behind `check`. It uses Node modules only, since a target's own lint and typecheck read it.
+
+- It runs typecheck, lint, format check, shell, unit tests, build, markdown bans, then card exclusion, always in that order, and skips any phase the folder's `scripts/verify.json` leaves out.
+- `scripts/verify.json` lists the phases a stack requires, plus any tools and preconditions it probes first. The nearest stack's copy wins.
+- A required phase whose script `package.json` lacks fails the run. A base phase the list leaves out runs only where the folder declares its script.
+- Base requires `check:format`, so a base-only target still fails on a missing one.
+- The shell phase runs only where `package.json` declares `check:shell`, which the `shell` stack adds, and probes for `shfmt` and `shellcheck` first.
+
+These two files are base's `[sync] per_root` set, which a `--skip base` subfolder still receives.
 
 ## What ships as user-owned seeds
 
 Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and never overwrites it, so a project extends them freely.
 
-- `.lintstagedrc`: the glob map below.
-- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`. A project with more than one language root adds its own jobs here.
-- `.github/pull_request_template.md`: `## Summary`, `## Key changes`, `## Technical context`, `## Testing`. A project adds the checklist lines its own review needs.
-- `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
+- `.lintstagedrc` holds the glob map below.
+- `.github/workflows/verify.yml` runs on pull requests targeting `main` and on `workflow_dispatch`. A multi-root project adds its own jobs here.
+- `.github/pull_request_template.md` has `## Summary`, `## Key changes`, `## Technical context`, and `## Testing`. A project adds its own checklist lines.
+- `canon/context/` holds the `ci` and `development` entries. Extend them with project-specific commands, workflows, or deploy steps, and keep canonical rationale in this reference.
 
 ## Tool pairing
 
-- Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
-- Formatting: oxfmt for what it parses, pinned to an exact version so an upgrade arrives as a reviewed diff. oxfmt has no shell parser, so shell formatting is the `shell` stack's.
-- Commits: commitlint against conventional commits, wired through the husky `commit-msg` hook. Format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
-- Dev dependencies: `oxfmt`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
+- Runtime is `bun` as package manager and script runner, with `bunx` over `npx` for a one-off executable.
+- Formatting is oxfmt for what it parses, pinned to an exact version so an upgrade arrives as a reviewed diff. Shell formatting is the `shell` stack's, since oxfmt has no shell parser.
+- Commits go through commitlint against conventional commits, wired through the husky `commit-msg` hook. The format is `<type>(<scope>): <subject>` in imperative mood with no trailing period.
+- Dev dependencies are `oxfmt`, `husky`, `@commitlint/cli`, and `@commitlint/config-conventional`, installed via `bun add -D`.
 
 ## oxfmt
 
 - Add a project's own ignores to `.prettierignore`, which oxfmt reads beside `.gitignore` by default. Sync overwrites `.oxfmtrc.json`, so an entry in its `ignorePatterns` is lost on the next sync.
-- Delete a leftover `.prettierrc` and run `bun remove prettier` by hand after the first sync onto oxfmt. Sync deletes nothing a stack stopped shipping, and the script overrides already stop Prettier from running.
+- After the first sync onto oxfmt, delete a leftover `.prettierrc` and run `bun remove prettier`. Sync deletes nothing a stack stopped shipping.
 
 ## File layout
 
-- Hooks live in `.husky/`, seeded context docs in `canon/context/`.
-- The `canon/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md` and `canon/REQUIREMENTS.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `canon/context/`. Indexes stay opt-in.
+Hooks live in `.husky/` and seeded context docs in `canon/context/`. That location matches the three-tier context model.
+
+- Project-wide invariants sit in `CLAUDE.md` and `canon/REQUIREMENTS.md`.
+- Path-scoped rules sit in `.claude/rules/`.
+- On-demand domain narrative sits in `canon/context/`, with indexes opt-in.
 
 ## Hooks
 
 - `pre-commit` runs `bunx lint-staged`.
 - `commit-msg` runs `bunx commitlint --edit "$1"`.
 - `pre-push` runs `bun run check`.
-- `post-merge` runs `canon hooks post-merge`: archive the task a merged pull request closed, push the records, reclaim merged worktrees, reinstall the CLI, and update the plugin. It does nothing when the board is absent. `CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three steps that act on the machine. Read `canon docs hooks` for the contract.
 - `post-rewrite` delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check.
+- `post-merge` runs `canon hooks post-merge`, which archives the task a merged pull request closed, pushes the records, reclaims merged worktrees, reinstalls the CLI, and updates the plugin.
+
+The hook does nothing when the board is absent. `CANON_SKIP_RECLAIM`, `CANON_SKIP_UPGRADE`, and `CANON_SKIP_PLUGIN_UPDATE` turn off the three steps that act on the machine, and `canon hooks post-merge --help` states the contract.
 
 ## lint-staged
 
-Seeded baseline globs:
+The seeded baseline globs.
 
 - `**/*.{json,md}` runs `oxfmt --no-error-on-unmatched-pattern`. Without the flag, a staged file every pattern ignores, such as `CHANGELOG.md`, exits 2 and fails the commit.
-- `**/*.md` runs `canon indexes regen`
+- `**/*.md` runs `canon indexes regen`.
 
 ## CI
 
-- Steps: checkout, setup Bun at latest, `bun install --frozen-lockfile`, then `check:format`.
-- CI asserts and never writes. Format must be clean before push.
+- Steps are checkout, setup Bun at latest, `bun install --frozen-lockfile`, then `check:format`.
+- CI asserts and never writes, so format must be clean before push.
 
 ## Gitignore
 
@@ -71,22 +92,32 @@ Seeded baseline globs:
 
 ## Anti-patterns
 
-Sticky negative knowledge. Do not relearn.
+Negative knowledge that costs a failed run to relearn.
 
 - Do NOT pass `--ignore-path` to oxfmt. It replaces the default `.gitignore` and `.prettierignore` pair rather than adding to it.
 - Do NOT put logic in a husky hook and expect its shebang to hold. Husky runs hooks as `sh -e`, so a hook carrying logic is POSIX sh under errexit whatever the first line says.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                                               |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Gates a checkout through `scripts/verify.ts` and writes nothing. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
-| `bun run check:format` | Asserts oxfmt formatting without writing                                                                                                                   |
-| `bun run format`       | Writes oxfmt formatting in place                                                                                                                           |
-| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                                                |
+| Script                 | What it does                                                                                                                  |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `bun run check`        | Gates a checkout through `scripts/verify.ts`, writing nothing. `VERIFY_NESTED=true` suppresses timeline boundaries in a call. |
+| `bun run check:format` | Asserts oxfmt formatting without writing                                                                                      |
+| `bun run format`       | Writes oxfmt formatting in place                                                                                              |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                   |
+
+### The check script
 
 Base writes `check` as a `[scripts.override]`, so a sync replaces whatever `check` a target declared, including one that chained further checks after the runner. Re-add a chained check as its own script after a sync.
 
-`bun run check` gates a checkout and writes nothing. Formatting drift fails it at `check:format`, and the failure line names `bun run format`, the one command that writes. It once ran `format` first to auto-fix drift, which rewrote files in a checkout several sessions share on every push and left a gate that could not fail. That was rejected, so the writing pass stays in `bun run format` and a push fails until it runs. The pull request workflow calls `check:format` directly as well.
+- `bun run check` writes nothing. Formatting drift fails it at `check:format`, and the failure line names `bun run format`, the one command that writes.
+- Auto-fixing drift inside `check` rewrote files in a shared checkout on every push and left a gate that could not fail, so the writing pass stays in `bun run format`.
+- The pull request workflow calls `check:format` directly as well.
+
+### The markdown bans stage
+
+The `Markdown bans` stage of `scripts/verify.ts` runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set.
 
-`scripts/verify.ts`'s `Markdown bans` stage gates on banned characters. It runs `canon markdown audit` over every tracked markdown file except `CHANGELOG.md`, since a generated changelog carries commit subjects nobody wrote against the ban set, and exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it. A refusal to measure exits `1` and is logged as a skip rather than a failure, as does a corpus with no file left to check once `CHANGELOG.md` is set aside. The stage needs `canon` on PATH. `canon docs projects` names the install command. Without it, the stage is skipped and logged, and coverage falls back to the format check above.
+- It exits `2` on a finding or `3` on a shipped-empty ban set, failing `bun run check` and the `pre-push` hook that calls it.
+- A refusal to measure exits `1` and is logged as a skip, as does a corpus with no file left once `CHANGELOG.md` is set aside.
+- The stage needs `canon` on PATH, and `canon docs projects` names the install command. Without it the stage is skipped and logged.

package/tooling/base/seeds/canon/context/ci.md

@@ -7,25 +7,17 @@ description: GitHub Actions workflow triggers and checks
 
 ## Overview
 
-Owns the GitHub Actions workflow that gates a merge: which events start a run, and which checks have to pass before the branch can land. The checks call package scripts rather than defining commands of their own, so what each one runs is the development entry's subject.
+Owns the GitHub Actions workflow that gates a merge, being which events start a run and which checks have to pass before the branch can land. The checks call package scripts rather than defining commands of their own, so what each one runs is the development entry's subject.
 
 ## Layout
 
-- `.github/workflows/` owns the workflow definitions a trigger below starts
+### `.github/workflows/`
 
-### Triggers
+Holds `verify.yml`, the workflow that gates a merge. A pull request targeting `main` starts it, and so does a manual `workflow_dispatch` run from the Actions tab.
 
-- Pull requests targeting `main`
-- `workflow_dispatch` (manual run from the Actions tab)
+- Every job must pass before merge
+- The Format check runs `bun run check:format` and asserts oxfmt is clean
 
-### Checks
+## Gotchas
 
-Defined in `.github/workflows/verify.yml`. All jobs must pass before merge.
-
-| Check  | Command                | What it asserts |
-| ------ | ---------------------- | --------------- |
-| Format | `bun run check:format` | oxfmt is clean  |
-
-### Running CI locally
-
-`bun run check` runs the same assert and writes nothing. If CI fails on format, run `bun run format` locally and commit the diff.
+- `bun run check` runs the same assert as CI and writes nothing, so a CI format failure is fixed by running `bun run format` locally and committing the diff

package/tooling/base/seeds/canon/context/development.md

@@ -7,31 +7,31 @@ description: Local dev workflow, scripts, and husky hooks
 
 ## Overview
 
-Owns how the project runs on a developer machine: installing the toolchain, the scripts that verify a change, and the git hooks that run them before a commit or a push leaves. CI calls the same scripts from a workflow, which is the CI entry's subject.
+Owns how the project runs on a developer machine, being the toolchain install, the scripts that verify a change, and the git hooks that run them before a commit or a push leaves. CI calls the same scripts from a workflow, which is the CI entry's subject.
 
 ## Layout
 
-- `scripts/` owns the shell scripts the package scripts below call
-- `.husky/` owns the git hooks
+### `scripts/`
 
-### Setup
+Holds every shell script, since none belongs outside this folder. The package scripts below call them.
 
-- Install [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`
-- Install dependencies: `bun install`
+### `.husky/`
+
+Holds the git hooks that run the checks before a commit or a push leaves.
+
+- `pre-commit` runs `lint-staged` (oxfmt on staged files)
+- `commit-msg` runs `commitlint` against the conventional commit format
+- `pre-push` runs `bun run check`, and also gates on banned characters across every tracked markdown file except `CHANGELOG.md` when a markdown-bans audit tool is on PATH
 
 ### Scripts
 
+Install [Bun](https://bun.sh) with `curl -fsSL https://bun.sh/install | bash` and run `bun install`, then use these commands.
+
 | Command          | Purpose                                                                                  |
 | ---------------- | ---------------------------------------------------------------------------------------- |
 | `bun run check`  | Gates locally and writes nothing. Fails on formatting drift until `bun run format` runs. |
 | `bun run format` | Auto-fix oxfmt formatting.                                                               |
 
-### Shell scripts
-
-All `.sh` files live under `scripts/`. Do not place shell scripts outside `scripts/`.
-
-### Husky hooks
+## Gotchas
 
-- `pre-commit` runs `lint-staged` (oxfmt on staged files).
-- `commit-msg` runs `commitlint` against the conventional commit format.
-- `pre-push` runs `bun run check`. When a markdown-bans audit tool is on PATH, it also gates on banned characters across every tracked markdown file except `CHANGELOG.md`. A push fails on formatting drift until `bun run format` runs, since the hook writes nothing.
+- A push fails on formatting drift until `bun run format` runs, since the `pre-push` hook writes nothing