@erclx/canon 5.44.0 → 5.46.0

package/src/tooling/scan.ts

@@ -12,6 +12,7 @@ import {
 import {
   collectDeps,
   collectScripts,
+  declaresInstalls,
   type DepState,
   readPackage,
   type ScriptState,
@@ -48,6 +49,7 @@ export interface ScanResult {
   readonly deps: readonly DepState[]
   readonly gitignore: readonly EntryState[]
   readonly hasPackageJson: boolean
+  readonly newManifest: boolean
   readonly totalChanges: number
 }
 
@@ -128,8 +130,10 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
   const packagePath = join(target, 'package.json')
   const pkg = readPackage(packagePath)
-  const scripts = pkg ? collectScripts(chain, pkg) : []
-  const deps = pkg ? collectDeps(chain, pkg) : []
+  const newManifest = !existsSync(packagePath) && declaresInstalls(chain)
+  const basis = pkg ?? (newManifest ? {} : undefined)
+  const scripts = basis ? collectScripts(chain, basis) : []
+  const deps = basis ? collectDeps(chain, basis) : []
 
   const gitignorePath = join(target, '.gitignore')
   const gitignoreContent = existsSync(gitignorePath)
@@ -138,6 +142,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
   const gitignore = scanGitignore(chain, gitignoreContent)
 
   const totalChanges =
+    (newManifest ? 1 : 0) +
     configs.filter((entry) => entry.state !== 'matching').length +
     seeds.filter((entry) => entry.state === 'missing').length +
     scripts.filter((entry) => entry.state !== 'matching').length +
@@ -152,6 +157,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
     deps,
     gitignore,
     hasPackageJson: pkg !== undefined,
+    newManifest,
     totalChanges,
   }
 }

package/src/worktrees/reclaim.ts

@@ -37,7 +37,11 @@ export type Refusal =
   | 'held-by-session'
 
 /** Why the whole reading was refused, so no verdict was produced at all. */
-export type Unreadable = 'gh-missing' | 'gh-failed' | 'sessions-unreadable'
+export type Unreadable =
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'sessions-unreadable'
+  | 'sessions-unchecked'
 
 /**
  * Which removal shape applies. `session` removes the background session and its
@@ -395,6 +399,17 @@ export async function reclaimReport(
     }
   }
 
+  // A foreign-namespace record whose socket is gone reads dead, but a reader
+  // that cannot see the pid may also be unable to see the socket, so it may be
+  // a live holder. The roster drops it, and a removal on that reading is final.
+  if (sessions.foreignDead > 0) {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unchecked',
+      detail: `${sessions.foreignDead} session records come from another pid namespace and no socket answers for them, so nothing was read about whether they still hold a worktree.`,
+    }
+  }
+
   const byBranch = new Map(
     merged.merged.map((request) => [request.branch, request.number]),
   )

package/tooling/astro/reference.md

@@ -6,8 +6,6 @@
 
 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.
@@ -17,65 +15,90 @@ It ships golden configs for `astro.config.mjs`, `vitest.config.ts`, `playwright.
 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
 
-### Astro and test configs
+- `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`
+- Keep the port at the top level and the bind guarantee under `vite`, since Astro feeds `server.port` through as the preview port but merges the `vite` block into both servers
 
-The configs below wire Astro into the web layer's test setup.
+## TypeScript
 
-- `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.
+- `tsconfig.json` extends `astro/tsconfigs/strict` and adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, and `@/` paths
+- Typecheck with `astro check` in place of `tsc --noEmit`, since `tsc` cannot parse `.astro` files
+- `build` runs `astro check && astro build`
 
-### Playwright config
+## Vitest
 
-`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`.
+- `vitest.config.ts` uses `getViteConfig` from `astro/config`, not `mergeConfig`, with jsdom, globals, the setup file, `passWithNoTests: true`, and v8 coverage
+- Exclude `**/*.astro` from coverage, and unit-test React island components (`.tsx`) alone, since Playwright verifies page-level behavior against rendered output
+- Keep Vitest at `^5` from the web manifest, which supports the Vite 8 that Astro 7 bundles
 
-- 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.
+## Playwright
 
-### ESLint 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`
+- Test the built `dist/`, since Astro's dev and production gap is wide across MDX, island hydration, and asset optimization
+- Set `DIST_PREBUILT` to drop the `build` half, running `bun run preview` alone against a `dist/` a prior CI job produced
 
-`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`.
+## ESLint
 
-- 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.
+- Lint with this stack's own flat `eslint.config.js`, since the web layer's oxlint parses no `.astro` file. It adds `eslint-plugin-astro` with `astro-eslint-parser`.
+- Expect `lint` and `lint:fix` overridden back to `eslint . --max-warnings 0`, and the web layer's `.oxlintrc.json` in the target with nothing running it
+- Install `eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, and `globals`, since the web layer ships none of them
+- Pin `eslint@^9`, because ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports
 
-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.
+## ESLint naming rules
 
-## Typecheck
+- Apply React hooks rules to `.jsx` and `.tsx` alone, since `.astro` is not React
+- Name `.ts`, `.tsx`, and `.astro` files in `KEBAB_CASE`, overriding Astro's PascalCase, since markup names a component by its import binding
+- Keep `.js` and `.jsx` out of that rule, matching `web` and `nextjs`
+- Name every `src/**` folder in kebab case except `__tests__` and the `pages/` subtree, whose own off-block allows bracket-named dynamic routes and slug folders
 
-`astro check` replaces `tsc --noEmit` because `tsc` cannot parse `.astro` files. `build` runs `astro check && astro build`.
+## Formatting (extend)
 
-## Vitest scope
+- 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
+- Expect this stack's `.oxfmtrc.json` to replace base's whole file, so a base option change reaches a target only once this stack copies it
+- Override `check:format` and `format` to run oxfmt, then Prettier over `**/*.astro`
 
-Unit-test React island components (`.tsx`) only. Do not test `.astro` files, since Playwright verifies page-level behavior against rendered output.
+## Social card route
 
-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.
+- Keep the social card as a route the project owns, so a re-render after a rename is one string edit and a re-capture rather than another `design-identity` pick loop
+- Expect `canon:design-identity` to write the picked composition into the route and capture it through the card server
+- `card.config.mjs` is a second Astro config whose `srcDir` points at `./card-src`, which the main page router never reads, so the published build excludes the card structurally
+- It serves on 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
+- `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
 
-## Formatting (extend)
+## Card exclusion and size
 
-- 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` 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`.
+- `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 the leak test reads
+- Keep the exclusion a check rather than a convention, since the card server and the capture read the route and the published build must not carry it
+- Declare `.card` at 600x315, half the 1200x630 target, since `canon capture` shoots at a fixed 2x device scale and 1200x630 would capture at 2400x1260
 
-## ESLint
+## Card stylesheet and tokens
+
+- `card-src/pages/og-card.astro` ships as a working placeholder, so it serves before any pick
+- It imports `@/styles/global.css` for real tokens and fonts, and a project keeping its stylesheet elsewhere retargets that one line
+- It uses `--color-background` and `--color-text` as `canon design css` emits them, and sets no `font-family`, so the card inherits the body font
+- Expect an unresolved stylesheet path to refuse the card server by name, rather than capture an unstyled card that reports success
+- Name only properties `canon design css` emits, since an undefined one silently takes its fallback, and check the names against a retargeted stylesheet
+
+## Card route scope
+
+- Expect no card route on another web stack, since Astro is the one whose config gives a route a structural build exclusion
+- Next's App Router has none and needs none, since `ImageResponse` is its 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 there is a second Rollup entry rather than a route
 
-- Override `lint` and `lint:fix` back to `eslint . --max-warnings 0`, since the web layer sets them to oxlint.
-- 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.
+## Scenario switcher
+
+- Expect `src/components/dev/scenarios.astro` overwritten on every 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
+- Rely on its `import.meta.env.DEV` guard, so it renders nothing and ships nothing in a production build
+- Expect it on Astro alone, since it uses `is:inline`, `define:vars`, and `set:html`, which only the `.astro` format parses
 
 ## Development docs (extend)
 
-Append these rows to the `## Scripts` table.
+- Append these rows to the `## Scripts` table
 
 | Command             | Purpose                                                         |
 | ------------------- | --------------------------------------------------------------- |
@@ -87,57 +110,5 @@ Append these rows to the `## Scripts` table.
 
 ## CI docs (extend)
 
-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. Re-rendering it after a rename is an edit to one string and a re-capture, not another pass through the `design-identity` pick loop.
-
-`canon:design-identity` writes the picked composition into the route and captures it through the server below.
-
-### What ships
-
-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.
-
-### Stylesheet and tokens
-
-`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.
-
-- 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.
-
-- 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.
-
-### 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, 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)
-
-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 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.
+- Assert `` `astro check` passes `` on the Typecheck row of `canon/context/development/ci.md` <!-- audit-ignore-citations: canon/context/development/ci.md -->
+- Assert `` `astro build` succeeds `` on its Build row

package/tooling/base/configs/.github/workflows/phase-label-gate.yml

@@ -19,7 +19,7 @@ jobs:
     name: 🏷️ Phase Label Gate
     runs-on: ubuntu-latest
     # Dependabot bodies carry upstream release notes that read as phase labels
-    if: github.event.pull_request.user.login != 'dependabot[bot]' && (github.event_name == 'workflow_dispatch' || github.event.pull_request.base.ref == 'main')
+    if: github.event.pull_request.user.login != 'dependabot[bot]' && github.event.pull_request.user.login != 'renovate[bot]' && (github.event_name == 'workflow_dispatch' || github.event.pull_request.base.ref == 'main')
     steps:
       - name: Checkout
         uses: actions/checkout@v7

package/tooling/base/configs/scripts/verify.ts

@@ -225,7 +225,7 @@ function readPhaseList(): PhaseList {
 
 function readDeclaredScripts(): Set<string> {
   if (!existsSync('package.json')) {
-    fail("No package.json here. Run 'bun init', then sync the stack again")
+    fail('No package.json here. Sync the stack to write one')
   }
   return new Set(
     Object.keys(asRecord(asRecord(readJson('package.json')).scripts)),
@@ -323,7 +323,7 @@ function checkMarkdownBans(): void {
     case 2:
       pipeOutput(output)
       fail(
-        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk',
+        'Markdown prose carries a banned character, a relative link resolves to nothing on disk, or a gated path breaks a density limit',
       )
       break
     case 3:

package/tooling/base/reference.md

@@ -18,7 +18,6 @@ Two configs fix how output looks and how commits read.
 - 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.
-- `.husky/` holds `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, and `post-rewrite`.
 
 ### Verify runner
 
@@ -39,7 +38,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.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.
+- `canon/context/development/` holds the `setup` and `ci` entries under a folder index. Extend them with project-specific commands and workflows, and keep canonical rationale here.
 
 ## Tool pairing
 
@@ -83,13 +82,6 @@ The seeded baseline globs.
 - 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
-
-- `# System`: `.DS_Store`
-- `# Dependencies`: `node_modules/`
-- `# Secrets`: `.env`, `.env.*`, `*.local`, `!.env.example`
-- `# VSCode`: `.vscode/`
-
 ## Anti-patterns
 
 Negative knowledge that costs a failed run to relearn.

package/tooling/base/seeds/canon/context/{ci.md → development/ci.md}

@@ -7,7 +7,7 @@ description: GitHub Actions workflow triggers and checks
 
 ## Overview
 
-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.
+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 setup entry's subject.
 
 ## Layout
 

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

@@ -0,0 +1,11 @@
+---
+title: Development
+subtitle: The local loop and CI
+---
+
+# Development
+
+The local loop and CI
+
+- [CI](ci.md): GitHub Actions workflow triggers and checks
+- [Setup](setup.md): Local dev workflow, scripts, and husky hooks

package/tooling/base/seeds/canon/context/{development.md → development/setup.md}

@@ -1,19 +1,24 @@
 ---
-title: Development
+title: Setup
 description: Local dev workflow, scripts, and husky hooks
 ---
 
-# Development
+# Setup
 
 ## Overview
 
 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.
 
+Install [Bun](https://bun.sh) with `curl -fsSL https://bun.sh/install | bash` and run `bun install`, then use the package scripts below. They call the shell scripts in `scripts/`, which holds every one since none belongs outside it.
+
 ## Layout
 
 ### `scripts/`
 
-Holds every shell script, since none belongs outside this folder. The package scripts below call them.
+| 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.                                                               |
 
 ### `.husky/`
 
@@ -23,15 +28,6 @@ Holds the git hooks that run the checks before a commit or a push leaves.
 - `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.                                                               |
-
 ## Gotchas
 
 - A push fails on formatting drift until `bun run format` runs, since the `pre-push` hook writes nothing

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

@@ -7,5 +7,4 @@ subtitle: Per-domain narrative loaded on demand
 
 Per-domain narrative loaded on demand
 
-- [CI](ci.md): GitHub Actions workflow triggers and checks
-- [Development](development.md): Local dev workflow, scripts, and husky hooks
+- [Development](development/index.md): The local loop and CI

package/tooling/claude/manifest.toml

@@ -21,8 +21,4 @@ scaffold = ""
 # array no longer tells it to ignore them, so the first sign is a memory file or
 # a task board appearing in someone's commit.
 [gitignore]
-"# Claude" = [
-  ".canon/",
-  ".claude/worktrees/",
-  ".claude/.tmp/", # canon-keep-record-root
-]
+"# Claude" = [".canon/", ".claude/worktrees/"]

package/tooling/claude/reference.md

@@ -2,59 +2,49 @@
 
 ## Overview
 
-The claude stack installs the `.claude/` workflow directory into a project. Tooling writes state docs once and never overwrites them. `CLAUDE.md` is one of those seeds, and a project fills it in after init.
+The claude stack installs the Claude Code workflow into a project through `canon claude`. Every file it ships is a seed, written once and never overwritten, so a project fills `CLAUDE.md` in after init.
 
-## Structure
+## Seeded records
 
-```plaintext
-CLAUDE.md              ← seeded. Project context and rules, auto-loaded by Claude Code each session
+- `CLAUDE.md` holds project context and rules, auto-loaded by Claude Code each session
+- `canon/REQUIREMENTS.md` holds the project's problem, goals, and non-goals
+- `canon/DESIGN.md` holds the visual intent and the decisions behind it
+- `canon/context/` holds per-domain narrative, with `index.md` as the discovery anchor
+- `.claude/settings.json` holds project-level Claude Code config. User-level config installs separately through `canon claude setup`.
 
-canon/
-├── REQUIREMENTS.md    ← seeded. Project problem, goals, non-goals
-├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
-└── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
+## Record folders
 
-.claude/
-├── GOV.md             ← retired. Removed by `canon gov sync` if present from a prior install
-├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `canon claude setup`.
-└── worktrees/         ← gitignored. Where EnterWorktree creates a linked worktree, which is why it did not move.
+- `.canon/tasks/` holds one file per task plus a generated `index.md`, local scratch only, with `archive/` holding the tasks that shipped
+- `.canon/plans/` holds execution detail for multi-step tasks, and `canon tasks archive` moves a `feature-*.md` plan into `archive/` when the `post-merge` hook archives its task
+- `.canon/review/` holds one subfolder per producer, with `design/` for `canon design render`
+- `.canon/tmp/` is ephemeral scratch, safe to delete without loss
+- `.claude/worktrees/` is where `EnterWorktree` creates a linked worktree, which is why it stays under `.claude/`
 
-.canon/
-├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
-├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries moved into `archive/` by `canon tasks archive` when the `post-merge` hook archives their task.
-├── review/            ← one subfolder per producer. `branch/` no longer written, `design/` for canon design render.
-└── tmp/               ← ephemeral scratch space, safe to delete without loss
-```
+## Ignored roots
 
-One ignore entry covers `.canon/` whole, so nothing under it is named separately and nothing tracked may land there. A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root.
+The `# Claude` group ignores `.canon/` whole, so nothing tracked may land there and a record folder added later needs no new entry.
+
+- Keep `.claude/worktrees/` as its own entry, since the harness requires a worktree's target to sit under `.claude/`
+- Expect a project scaffolded before the move to keep its records under `.claude/`, since every command reads either root
+- Expect `canon gov sync` to remove a retired `.claude/GOV.md` left by a prior install
 
 ## Moving the records to `.canon/`
 
 A project installed before the split holds its records under `.claude/`. `canon migrate records` moves them and repoints every tracked file that cites one, reporting the plan until `--write` is passed.
 
 - Run `canon tooling sync claude . --write` first. The verb refuses until the project ignores `.canon/`, since a relocated folder under a tracked root commits the task board and plans.
-- Until the move runs, the records sit at a root the shipped ignore set no longer names, so a `git add -A` in that window picks them up.
-- An installed binary answers `unknown command` until a published release carries the verb. Meanwhile run `bun src/cli.ts migrate records --root <project> --write` from a canon checkout.
-- Read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten.
+- Move soon after the sync, since until then the records sit at a root the shipped ignore set no longer names and a `git add -A` picks them up
+- Run `bun src/cli.ts migrate records --root <project> --write` from a canon checkout while the installed binary answers `unknown command`
+- Read the `ok` field out of `--json` rather than the exit code, which a shell wrapper around `canon` can flatten
 
 ## Upgrading from a single-file board
 
-A project installed before the board became a folder still holds `.claude/TASKS.md`, and nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.
-
-Convert by hand, once per project.
+A project installed before the board became a folder still holds `.claude/TASKS.md`, and nothing migrates it. `canon claude init` seeds an empty `.canon/tasks/index.md` beside it, so every skill reads the empty catalog while the real board sits unreferenced.
 
 1. Split each `###` block into `.canon/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the `task-board` skill requires. Compare each new file against its source block.
 2. Run `canon indexes regen --no-stage --root . .canon/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.canon/tasks/`.
 
-## Gitignore
-
-The `# Claude` group holds three entries, being `.canon/`, `.claude/worktrees/`, and `.claude/.tmp/`. <!-- canon-keep-record-root -->
-
-- The first entry covers the whole record root, so a record folder added later needs no line here and no sync.
-- The second is the carve-out the harness owns, since it creates a worktree under `.claude/` and requires its target to sit there.
-- The third is the scratch rule's fallback spelling, carried for a project the record move has not reached and retired once none is left.
-
 ## CLI
 
 | Command              | What it does                                                                                                                                                                     |
@@ -65,37 +55,24 @@ The `# Claude` group holds three entries, being `.canon/`, `.claude/worktrees/`,
 
 ## CLAUDE.md
 
-- It ships as a seed with placeholder project name, description, and key paths, to fill in after init.
-- Its sections are `Context`, `Commands`, and `Key paths`. Each groups rules that share a surface, so skills can detect, extend, or skip by heading.
-- The `Context` section points at `.claude/` state docs in one line. `plan-feature` does the parallel read when invoked, so the seed does not re-list every file.
+- Fill in the seed's placeholder project name, description, and key paths after init
+- Keep its sections `Context`, `Commands`, and `Key paths`, since skills detect, extend, or skip by heading
+- Keep the `Context` section to one line pointing at the state docs, since `plan-feature` does the parallel read when invoked
 
 ## Seed docs
 
-Seed docs ship with a guidelines preamble above the first H2. Claude internalizes those instructions before filling in the sections below, and they are not sections to populate.
+- Read a seed doc's guidelines preamble above the first H2 as instructions for filling the sections below, never as a section to populate
 
 ## settings.json
 
-The project and user files split what is project-specific from what is personal.
-
-### Project seed
-
-The seed at `tooling/claude/seeds/.claude/settings.json` ships hooks that pair with scripts under `.claude/hooks/`.
-
-- Three PreToolUse hooks pair with `index-reminder.sh`, `search-reminder.sh`, and `scratch-guard.sh`.
-- A PostToolUse hook pairs with `standards-audit.sh`.
-- Project settings layer over user settings, so a project file carries only what is project-specific.
-
-### Session defaults
-
-The seed also sets two defaults every session in the target runs under.
-
-- `permissions.deny` holds `Agent` and `Task`, so no session spawns a subagent. Parallel work runs as separate background sessions instead.
-- `autoMemoryEnabled` is `false`. A person turns it back on for themselves in `settings.local.json`.
-- `canon migrate session-defaults` adds both to a target seeded before them, since sync never rewrites an existing settings file.
-
-### User template
+- Pair the seed's three PreToolUse hooks with `index-reminder.sh`, `search-reminder.sh`, and `scratch-guard.sh`, and its PostToolUse hook with `standards-audit.sh`, all under `.claude/hooks/`
+- Keep only what is project-specific in the project file, since project settings layer over user settings
+- Expect `permissions.deny` to hold `Agent` and `Task`, so no session spawns a subagent and parallel work runs as separate background sessions
+- Expect `autoMemoryEnabled` to be `false`. A person turns it back on for themselves in `settings.local.json`.
+- Run `canon migrate session-defaults` on a target seeded before those two defaults, since sync never rewrites an existing settings file
 
-The template at `tooling/claude/user/settings.template.json` is installed once per machine by `canon claude setup`.
+## User settings
 
-- It allows `Bash(bun run *)` under `permissions.allow`.
-- Its `permissions.deny` holds `Read(**/.env)` and `Read(**/.env.*)`, blocking accidental secret exposure across any project.
+- `canon claude setup` installs `tooling/claude/user/settings.template.json` once per machine
+- It allows `Bash(bun run *)` under `permissions.allow`
+- Its `permissions.deny` holds `Read(**/.env)` and `Read(**/.env.*)`, blocking accidental secret exposure across any project

package/tooling/claude/seeds/.claude/hooks/board-validate.sh

@@ -51,7 +51,7 @@ fi
 # Exit 2 carries findings, so the status is read off the record rather than
 # the exit code.
 record=$(canon tasks validate --json --root "$root" 2>/dev/null)
-ok=$(printf '%s' "$record" | jq -r '.ok // empty' 2>/dev/null)
+ok=$(printf '%s' "$record" | jq -r '.ok | tostring' 2>/dev/null)
 
 if [ "$ok" = false ]; then
   report "canon tasks validate refused the board after this edit: $(printf '%s' "$record" | jq -r '.message // .reason')"

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

@@ -40,14 +40,9 @@ done
 
 session=$(printf '%s' "$input" | jq -r '.session_id // "none"')
 key=$(printf '%s__%s' "$session" "$index" | tr -c 'A-Za-z0-9' '_')
-# The marker is scratch, so it follows the scratch folder to whichever record
-# root the project carries rather than creating a second one beside it.
+# The marker is scratch, so it lives under `.canon/tmp/`.
 project="${CLAUDE_PROJECT_DIR:-.}"
-if [ -d "$project/.canon" ]; then
-  marker_dir="$project/.canon/tmp/hooks/index-reminder"
-else
-  marker_dir="$project/.claude/.tmp/hooks/index-reminder"
-fi
+marker_dir="$project/.canon/tmp/hooks/index-reminder"
 marker="$marker_dir/$key"
 [ -f "$marker" ] && exit 0
 mkdir -p "$marker_dir"

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -46,13 +46,8 @@ root="${CLAUDE_PROJECT_DIR:-.}"
 case "$root" in
 */.claude/worktrees/*) root="${root%/.claude/worktrees/*}" ;;
 esac
-# The log is scratch, so it follows the scratch folder to whichever record root
-# the project carries rather than creating a second one beside it.
-if [ -d "$root/.canon" ]; then
-  log_dir="$root/.canon/tmp/pr/log"
-else
-  log_dir="$root/.claude/.tmp/pr/log"
-fi
+# The log is scratch, so it lives under `.canon/tmp/`.
+log_dir="$root/.canon/tmp/pr/log"
 mkdir -p "$log_dir"
 session=$(printf '%s' "$input" | jq -r '.session_id // "unknown"')
 printf -- '- %s session=%s pr=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session" "$url" >>"$log_dir/log.md"