@erclx/aitk 0.54.0 → 0.56.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -9,11 +9,14 @@ description: Scope boundary for pipeline structure against job contents, and the
 
 Without this skill, a session writes a pipeline whose jobs run in sequence because `needs` was used to express the order a person reads them in rather than a data dependency. The pipeline then costs the sum of its jobs where it could have cost the longest one, and the waste compounds on every push.
 
+The same session splits a gate that finishes in a minute into three parallel jobs, which fails in the other direction. Each job repays checkout, dependency install, and toolchain setup before it reaches a stage, so the gate gets slower while reporting no earlier, and the roster reads as a design decision rather than as a cost nobody measured.
+
 The rest are reproducibility failures that surface as flakes. An action pinned to a moving ref changes under the project, so a run that passed yesterday fails today with no commit behind it and the diff explains nothing. A cache keyed on a static string serves a stale browser or toolchain after a version bump, and the failure reads as a broken test rather than a stale cache. Artifacts upload on every run and never expire, so storage grows with the commit count while the ones worth reading are the failures. And a workflow with no manual trigger can only be reproduced by pushing a commit, which is the wrong instrument for a run that failed for an environmental reason.
 
 ## Must
 
 - Gate a job only on a data dependency or on a cost that justifies the wait, and leave every other job parallel
+- Start the checks that share setup in one job and split them only once a run log puts the gate past roughly two minutes
 - Pin every action to a tag that cannot cross a major version
 - Key a cache on the version string of the thing it caches
 - Give every workflow a manual trigger beside its primary one

package/claude/skills/ci-workflow/SKILL.md

@@ -20,14 +20,21 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Job naming
 
-- Name jobs with emoji + title: `🛡️ Static Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, `🚀 Deploy`, `🔍 Code Quality`, `🏷️ Release`, `🔒 Security`.
+- Name jobs with emoji + title: `🛡️ Checks`, `🛡️ Static Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, `🚀 Deploy`, `🔍 Code Quality`, `🏷️ Release`, `🔒 Security`.
+
+## Job granularity
+
+- Start a new pipeline with the checks that share setup in one job: static analysis, unit tests, and build. A project with no run history has nothing to measure, and one job is the shape that costs least to reverse.
+- Keep them in one job while the gate runs under roughly two minutes end to end. Each extra job repays checkout, dependency install, and toolchain setup before it reaches a stage, so a split at that duration costs more than the parallelism returns.
+- Split once a run log puts the gate past that, then apply the dependency rules below. The run log is the revision trigger rather than the entry condition, since repository size and stage count answer nothing.
+- Give E2E, release, and deploy their own jobs from the start. Each carries a data dependency or a gate, so this rule never folds them into the check job.
 
 ## Job dependencies
 
 - Run independent jobs in parallel.
 - Use `needs` only when there is a data dependency (a job requires an artifact) or the job is prohibitively expensive relative to its gate.
-- Run static, unit, and build jobs in parallel.
-- Gate E2E on build, since it requires the built artifact.
+- Run static, unit, and build jobs in parallel once the gate is split.
+- Gate E2E on whichever job uploads the build artifact, since it consumes that artifact. That job is the folded check job in a new pipeline and the separate build job once the gate is split.
 - Gate release and deploy on E2E.
 
 ## Artifacts
@@ -42,7 +49,7 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Template
 
-Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed while preserving the parallel and gated structure.
+Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
 
 ## Validation
 
@@ -50,8 +57,8 @@ Before responding, verify:
 
 - `workflow_dispatch` is present alongside the primary trigger.
 - All actions pinned to major version tags, no `@latest` or `@main`.
-- Static, unit, and build jobs have no `needs` and run in parallel.
-- E2E uses `needs: build`. Release and deploy use `needs: e2e`.
+- A new pipeline folds static, unit, and build into one job, and a gate a run log put past two minutes gives them no `needs` so they run in parallel.
+- Every name in a `needs` matches a job declared in the same file. E2E names the artifact producer, release and deploy name E2E.
 - Artifacts upload on `if: failure()` only with `retention-days: 7`.
 - Job names use emoji + title format.
 - Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.

package/claude/skills/ci-workflow/references/workflows.md

@@ -1,6 +1,6 @@
 # CI workflow template
 
-Copy this base template and adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed while preserving the parallel and gated structure.
+Copy this base template and adapt it to the project's stack, test commands, and build output. It carries the shape a new pipeline starts in, with the checks that share setup in one job, per the granularity rule in the skill body. `e2e` and anything gated on it stay separate jobs at either size.
 
 ```yaml
 name: CI
@@ -13,8 +13,8 @@ on:
   workflow_dispatch:
 
 jobs:
-  static:
-    name: '🛡️ Static Checks'
+  checks:
+    name: '🛡️ Checks'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -23,9 +23,16 @@ jobs:
           bun-version: latest
       - run: bun install --frozen-lockfile
       - run: bun run check
+      - run: bun run test
+      - run: bun run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
 
-  unit:
-    name: '🧪 Unit Tests'
+  e2e:
+    name: '🎭 E2E Tests'
+    needs: checks
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -33,10 +40,27 @@ jobs:
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
-      - run: bun run test
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+      - run: bun run test:e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-results
+          path: test-results/
+          retention-days: 7
+```
 
-  build:
-    name: '📦 Build Check'
+## Splitting the check job
+
+Apply this once a run log puts the gate past roughly two minutes, never before. Each job below repays checkout, dependency install, and toolchain setup before it reaches a stage, which is the cost the duration has to cover. Replace the `checks` job above with these three and point `e2e` at `needs: build`.
+
+```yaml
+jobs:
+  static:
+    name: '🛡️ Static Checks'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -44,15 +68,21 @@ jobs:
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
-      - run: bun run build
-      - uses: actions/upload-artifact@v4
+      - run: bun run check
+
+  unit:
+    name: '🧪 Unit Tests'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
         with:
-          name: build-output
-          path: dist/
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run test
 
-  e2e:
-    name: '🎭 E2E Tests'
-    needs: build
+  build:
+    name: '📦 Build Check'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -60,15 +90,9 @@ jobs:
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
-      - uses: actions/download-artifact@v4
+      - run: bun run build
+      - uses: actions/upload-artifact@v4
         with:
           name: build-output
           path: dist/
-      - run: bun run test:e2e
-      - uses: actions/upload-artifact@v4
-        if: failure()
-        with:
-          name: e2e-results
-          path: test-results/
-          retention-days: 7
 ```

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

@@ -16,7 +16,7 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 - Take the approved plan for the branch as the scope, and implement only what it describes
 - Give every step a stop condition, and leave the code on the branch and the receipts on disk at each one
 - Classify the changed-file list by path as well as by extension, so informational prose skips a code review with no signal on it and executable prose still reaches one
-- Stop on any critical or should-fix finding rather than acting on it
+- Split findings by origin, stopping on a critical or should-fix one the branch inherited and repairing one this run caused
 - Open the pull request as a draft, then watch continuous integration to a terminal state
 - Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
 
@@ -24,7 +24,9 @@ Review is the step that varies most. It gets skipped on a diff that needed one,
 
 - Expand past the plan, refactor a neighbor, or touch a file outside it without reason
 - Loop on a failed verify. One fix attempt against the reported errors, then stop.
-- Fix a review finding or a failing check. Both stops are deliberate, since a green pull request reached by auto-fix hides what broke.
+- Fix an inherited review finding or a failing check. Both stops are deliberate, since a green pull request reached by auto-fix hides what broke.
+- Loop on a self-introduced finding. One repair pass, then stop, which is the bound a failed verify already carries.
+- Read the plan's file list as the boundary on a repair. It scopes what the run builds, and a finding this run caused is in reach wherever it landed.
 - Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
 - Read an empty changed-file list as prose-only. It satisfies that test vacuously and would route the branch past review instead of through it.
 - Read a markdown extension as evidence the change only informs. A skill body, a governance rule, and a standard are behavior written in prose.

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

@@ -90,12 +90,15 @@ The list covers this toolkit's authoring layout and the layout it installs, whic
 
 ## Step 6: evaluate findings
 
-Skip this step when Step 5 skipped review. Otherwise read `.claude/review/review-<slug>.md` at the main worktree root. Parse the summary line (`X critical, Y should-fix, Z minor`):
+Skip this step when Step 5 skipped review. Otherwise read `.claude/review/review-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited rather than for one this run introduced.
 
-- Any critical or should-fix count greater than zero, stop: `❌ Review found non-minor issues. See .claude/review/review-<slug>.md. Fix and run /git-ship.`
-- Zero critical and zero should-fix, continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
+- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop and do not offer the fix as a choice, which is the same stop wearing a proposal.
+- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .claude/review/review-<slug>.md. Fix and run /git-ship.`
+- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
 
-Do not auto-fix findings. The stop here is deliberate.
+Read origin as causation rather than authorship. Staleness this run induced in a file it never opened is a finding it caused, and the plan's "Files to touch" list scopes what the run builds rather than what it may repair.
+
+Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .claude/review/review-<slug>.md. Fix and run /git-ship.`
 
 ## Step 7: ship
 
@@ -151,5 +154,6 @@ Every stop point leaves recoverable state. The user resumes manually from the ap
 | Branch collision on worktree entry | `claude-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship. |
 | Verify fails                       | Read logs, fix manually, run `/git-ship`                                                                                                       |
 | UI checklist                       | Verify visually, run `/git-ship`                                                                                                               |
-| Review findings                    | Fix findings, run `/git-ship`                                                                                                                  |
+| Inherited review findings          | Fix findings, run `/git-ship`                                                                                                                  |
+| Self-introduced finding survived   | Read the receipt for what the one repair pass left open, fix it, run `/git-ship`                                                               |
 | git-ship fails                     | Inspect hook or remote error, run again                                                                                                        |

package/claude/skills/migration-standards/REQUIREMENT.md

@@ -9,10 +9,16 @@ description: Why the root-to-.claude relocation ships as git mv commands the use
 
 Without this skill, a project whose rules cite `.claude/standards/` while the files sit at the root gets fixed by hand, and the hand fix loses what version control was holding. A plain `mv` breaks the rename chain, so every relocated standard reads as a delete beside an unrelated add and its history stops at the move.
 
+A fourth failure comes before those three, from deciding what is unmigrated by listing the folder. A root `standards/` can hold the project's own docs and nothing the toolkit ever installed, and a listing cannot tell the two apart, so the skill proposes moving project files under `.claude/` where a sync walks them. The drift report already answers this, counting only files whose basename the toolkit ships, and it is the same report `toolkit-operator` reads to route here.
+
+Taking detection from a command opens a failure the listing never had. A CLI predating the field exits zero with a well-formed report that never mentions it, so a skill treating an absent key as an empty answer tells a project whose every domain sits at the root that it has nothing to relocate. That is the population this skill exists for, and a silent false negative there costs more than the unfiltered count reading the folder would have produced.
+
 Three failures follow from acting without looking first. A move onto an existing `.claude/standards/` copy overwrites the files already installed there, which is the case the relocation was supposed to be unnecessary for. A `git mv` on a dirty tree lands the relocation in the same commit as unrelated work, so neither can be reviewed or reverted alone. And a session that rewrites every inbound reference spends its effort on toolkit-owned rules and skills, which the next sync overwrites, while the author-owned lines that actually break go unmentioned.
 
 ## Must
 
+- Take the set of domains to relocate from `aitk sync --check --json`, and report its filtered count rather than a folder listing
+- Keep the listing as the fallback for a target where `aitk` is absent, the command fails, or the report carries no `unmigrated` key, and say that its counts are unfiltered
 - Detect an existing copy under `.claude/` and skip that folder's move rather than merging into it
 - Read the working tree state and require it clean before the moves, since the relocation has to be revertible on its own
 - Propose `git mv` so history follows each file

package/claude/skills/migration-standards/SKILL.md

@@ -10,21 +10,38 @@ description: Proposes `git mv` commands to relocate a target project's root `sta
 - If neither `standards/` nor `snippets/` exists at `pwd`, stop: `❌ No root standards/ or snippets/ to relocate.`
 - If `pwd` is not a git work tree, stop: `❌ Not a git repository. git mv needs version control.`
 
-## Step 1: discover
+## Step 1: read the report
 
-Run these in parallel from the project root:
+Run `aitk sync --check . --json` from the project root. Its `unmigrated` array is the detection. Each entry carries `domain`, `rootPath`, `installPath`, and `files`, and a domain appears only when the root folder holds a file the toolkit ships and nothing sits at the install path. Report `files` as the count, since it excludes files the project wrote into the same folder.
 
-- `ls standards/*.md 2>/dev/null`: root standards present
-- `ls snippets/ 2>/dev/null`: root snippets present
-- `ls .claude/standards/ 2>/dev/null`: detect an existing target copy
-- `ls .claude/snippets/ 2>/dev/null`: detect an existing target copy
+Run these beside it, in parallel. The report answers which domains to move and neither of these is derivable from it:
+
+- `ls .claude/standards/ 2>/dev/null`: separate a domain already relocated from one never installed, which the report cannot, since both are absent from `unmigrated`
+- `ls .claude/snippets/ 2>/dev/null`: the same, for the other domain
 - `git status --short 2>/dev/null`: confirm a clean tree before proposing moves
 
+Keep the two listings as separate commands. `ls` labels its output with a `dir:` header only when more than one operand succeeds, so a combined call with one directory present prints that directory's filenames bare while the redirect swallows the other's failure, and the result reads as whichever directory was expected.
+
+### When the report is unavailable
+
+Fall back to `ls standards/*.md` and `ls snippets/` on any of three conditions. Say in the output that the counts are unfiltered, because a root folder can hold project-authored files the report would have excluded and the fallback counts every one of them.
+
+- `aitk` is not on `PATH`
+- The command exits non-zero
+- The report parses and carries no `unmigrated` key at all
+
+The third is the one that decides whether this skill works for the projects it exists for. `unmigrated` reached a release in `0.46.0`, and a CLI older than that exits zero with a well-formed report that never mentions the field. Reading an absent key as an empty list sends the run down the nothing-to-relocate branch and reports a clean layout to a project whose every domain sits at the root, which is a silent false negative where the unfiltered count is a visible imprecision.
+
+An absent key and an empty array are different states, so test for the key rather than for emptiness. A current CLI reporting `"unmigrated": []` has looked and found nothing, and falling back there would trade a correct answer for a listing that proposes moving whatever the folder happens to hold.
+
+Do not fall back on `historyUnavailable`. That field reports failed attribution on a domain or on `seeds`, and `unmigrated` is a filesystem read carrying no attribution of its own, so a report that cannot date a file still detects the layout correctly.
+
 ## Step 2: check conflicts
 
 - If `.claude/standards/` already holds `.md` files, mark standards as "already relocated" and skip its move.
 - If `.claude/snippets/` already holds `.md` files, mark snippets as "already relocated" and skip its move.
 - If `git status` is not clean, add a TODO line telling the user to commit or stash first. `git mv` on a dirty tree mixes the move with unrelated changes.
+- If a root folder holds files and no domain names it in a report that carried the key, propose nothing for it. The content is the project's own, and moving it under `.claude/` puts project files where a sync walks. This reads a present key alone. A report with no `unmigrated` key never reaches here, since Step 1 sends it to the fallback.
 
 ## Step 3: find author-owned inbound references
 
@@ -70,6 +87,9 @@ aitk gov sync .
 Re-syncing reinstalls toolkit-owned rules and standards at the new path. Author-owned references above need a manual one-line fix.
 ```
 
-If both folders are already relocated, output: `✅ standards/ and snippets/ already live under .claude/. Nothing to relocate.`
+Two states produce no proposal at all, and each gets its own line rather than an empty block:
+
+- Both folders already live under `.claude/`: `✅ standards/ and snippets/ already live under .claude/. Nothing to relocate.`
+- A root folder exists and no domain names it in `unmigrated`: `✅ <folder>/ holds no file the toolkit installed. Nothing to relocate.` Name every such folder. The guard passed because the folder is there, so a session that printed nothing would leave the user reading silence as a failed run rather than as the answer.
 
 Do not run the `git mv` commands. Do not edit `CLAUDE.md`, rule files, or docs. The user runs the commands and fixes author-owned references after reviewing.

package/docs/agents/install-and-sync.md

@@ -164,6 +164,13 @@ to, with nothing at the path the current one reads. It carries `rootPath`,
 root reports zero entries for that domain and reads as clean, which is the most
 misleading state the report can produce. Route it to `migration-standards`.
 
+That skill reads this field rather than listing the folder itself, so the entry
+is the detection on both sides of the handoff and the two cannot disagree. The
+count is what makes the difference visible: it counts only files whose basename
+the toolkit ships, so a root folder holding the project's own documents beside
+the installed ones reports the installed subset, where a listing reports every
+file and proposes relocating the lot.
+
 `unmigrated` counts toward `--exit-code`, since running the relocation closes it.
 `superseded` and every seed state are excluded, for the reason `orphaned` already
 is: only the user can move content they wrote, so failing a job on it leaves the

package/docs/agents/output-shape.md

@@ -46,8 +46,10 @@ Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to
 
 ## Process exit
 
-A command action that writes to stdout sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before the write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.
+A command action sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before a stdout write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.
 
-A fail-fast path that has written to stderr alone may still call `process.exit()`, and several do. The truncation has nothing to cut there, so the ban is scoped to the stream it protects rather than applied to every exit.
+The rule reaches an error path that writes to stderr alone, where the truncation has nothing to cut. Scoping it to the stdout writers was the alternative and it makes the floor depend on a detail that moves, since an action grows a stdout write long after its error branches are written. An action always has a return path, so the requirement costs it a line.
+
+The exit belongs to a helper that has no caller to unwind through. A prompt inside a promise executor and a wrapper propagating a child process status both qualify, and neither can hand a value back to a caller expecting one. A validation helper called from an action does not: it throws from a `never` return, which keeps its caller exhaustive to the compiler while the action catches and owns the code.
 
 Diagnostics reach stderr in every mode, including `--json`. Name the file and the field that failed, because a JSON record carries an action and a reason and an operator reading stderr alone sees neither.

package/docs/ai-workflow.md

@@ -102,7 +102,8 @@ It announces and moves nothing, so `aitk:claude-tasks` stays the only writer. A
 For features on a mature stack, chain the post-plan pipeline in one session. Approve the plan, invoke `aitk:claude-autoship`, and the skill runs implement → verify → review → ship sequentially.
 
 - Use when the plan is tight and the stack has real verify commands and test coverage
-- Autoship stops on: verify failure after one fix attempt, UI manual checklist non-empty, any review finding above minor, no diff baseline resolving against `main`, an empty changed-file list, or hook failure
+- Autoship stops on: verify failure after one fix attempt, UI manual checklist non-empty, an inherited review finding above minor, no diff baseline resolving against `main`, an empty changed-file list, or hook failure
+- Review findings split by origin before severity is read. One the branch inherited stops the chain, and one the run itself caused is repaired in place at any severity, bounded at a single pass. Origin is causation rather than authorship, so staleness the run induced in a file it never opened counts as its own and the plan's file list bounds what it builds rather than what it may repair.
 - Review is skipped when the diff is prose that only informs: every changed file matches `*.md` or `*.txt`, and none sits under a behavior path. Behavior paths cover skills, rules, standards, snippets, and `tooling/` in both the authoring and the installed spelling, plus root `CLAUDE.md`, so the list matches whether a repository authors those surfaces or consumed them from the toolkit. Markdown under one states what an agent does, so a branch touching it reaches review while `docs/` and `wiki/` still skip and stay gated by `docs-sync`, `claude-standards-audit`, and pre-push hooks.
 - An empty changed-file list stops the chain rather than counting as prose-only. The filename test passes vacuously on an empty set, which routed a branch past review instead of through it.
 - Every stop leaves recoverable state. Fix and resume with `/git-ship`

package/package.json

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

package/scripts/core/verify.sh

@@ -13,6 +13,11 @@ WRITE="${VERIFY_WRITE:-true}"
 SCOPED=true
 CHANGED_FILES=""
 
+# Scenarios declaring no expectation, taken from `aitk sandbox coverage` against a
+# clean tree. Raising it is a deliberate edit that says which scenario shipped
+# unarmed and why.
+SANDBOX_UNDECLARED_CEILING=47
+
 check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
@@ -138,6 +143,13 @@ seed_entry_count() {
     awk '{ total += $1 } END { print total + 0 }'
 }
 
+# One numeric summary key out of a coverage report. The per-scenario objects carry
+# neither key this is called with, so the match reaches the top level alone and
+# the caller does not depend on the order the keys are emitted in.
+sandbox_summary_field() {
+  printf '%s' "$2" | grep -o "\"$1\":[0-9]\+" | grep -o '[0-9]\+'
+}
+
 assert_no_drift() {
   local paths=$1
   local err_msg=$2
@@ -274,8 +286,47 @@ main() {
   run_check "cd $PROJECT_ROOT && bun src/cli.ts claude skills audit --requirements-only" "A skill folder carries no REQUIREMENT.md. Run bun src/cli.ts claude skills audit."
   log_info "Skill requirements present"
 
+  # `aitk sandbox coverage` moves only when a person runs it, so a scenario added
+  # with no expectation ships unnoticed. The gate is an absolute count of
+  # undeclared scenarios rather than a ratio or a floor under the declared count.
+  # A floor under the declared count passes the case this exists to catch, since
+  # adding an unarmed scenario leaves that number where it was. A ratio moves
+  # when a scenario is legitimately deleted, and this ceiling does not: deleting
+  # an unarmed scenario lowers it and deleting an armed one leaves it alone.
+  log_step "Sandbox coverage"
+  local coverage_output coverage_status=0 total armed undeclared
+  coverage_output=$(cd "$PROJECT_ROOT" && bun src/cli.ts sandbox coverage --json 2>/dev/null) || coverage_status=$?
+  if [ "$coverage_status" -ne 0 ]; then
+    if [ "${CI:-false}" = true ]; then
+      log_error "bun src/cli.ts sandbox coverage --json exited $coverage_status. The scenario tree ships in the checkout, so a run that does not report is a broken command rather than an absent tree, and skipping would report the pass this stage exists to withhold."
+    fi
+    log_warn "Skipped, the scenario tree did not report"
+  else
+    # `|| x=""` on both, because a grep that matches nothing exits non-zero and
+    # errexit would take the script down at the assignment, before the guard
+    # below could name what went missing.
+    total=$(sandbox_summary_field totalScenarios "$coverage_output") || total=""
+    armed=$(sandbox_summary_field armedScenarios "$coverage_output") || armed=""
+    if [ -z "$total" ] || [ -z "$armed" ]; then
+      log_error "The coverage report carried no scenario totals, so the stage measured nothing. Run bun src/cli.ts sandbox coverage --json."
+    fi
+    undeclared=$((total - armed))
+    if [ "$undeclared" -gt "$SANDBOX_UNDECLARED_CEILING" ]; then
+      log_error "$undeclared of $total scenarios declare no expectation, over the ceiling of $SANDBOX_UNDECLARED_CEILING. Declare expectations on the new scenario, or raise SANDBOX_UNDECLARED_CEILING in this script and say which scenario shipped unarmed."
+    fi
+    log_info "$armed of $total scenarios declare expectations, $undeclared undeclared against a ceiling of $SANDBOX_UNDECLARED_CEILING"
+  fi
+
+  # The plugin is the second delivery path and this is the only stage gating it,
+  # so the skip below is for a contributor's machine rather than for the merge
+  # gate. A runner installs the CLI as a workflow step, which makes an absent
+  # binary there a broken workflow, and skipping would report a pass for every
+  # manifest on the way to a marketplace install.
   log_step "Plugin manifests"
   if ! command -v claude >/dev/null 2>&1; then
+    if [ "${CI:-false}" = true ]; then
+      log_error "claude is not installed. CI installs it before this stage, so read the Install Plugin CLI step in .github/workflows/verify.yml."
+    fi
     log_info "Skipped, claude is not installed"
   else
     local manifests manifest

package/scripts/lib/sandbox-fixtures.sh

@@ -78,6 +78,27 @@ append_from_fixtures() {
   done < <(list_fixture_files "$source_dir")
 }
 
+# Stages the first `count` markdown files the toolkit ships for a domain into
+# `dest`, flattening any source subfolder. Source rather than fixture tree,
+# because an arm modelling a real install wants the files a target actually
+# received and a copy under `fixtures/` would drift from them silently.
+#
+# The flattening is load-bearing rather than incidental. Both `detectUnmigrated`
+# and the sync engine match a target file to its source by basename against the
+# flat domain root, so a file lifted out of a source subfolder such as `bundled/`
+# has no flat sibling and reads as project-authored. An arm staging one claims a
+# drift or an unmigrated domain it did not stage.
+stage_toolkit_markdown() {
+  local src="$1"
+  local dest="$2"
+  local count="$3"
+
+  mkdir -p "$dest"
+  while IFS= read -r file; do
+    cp "$file" "$dest/$(basename "$file")"
+  done < <(find "$src" -maxdepth 1 -type f -name "*.md" ! -name "index.md" | sort | head -n "$count")
+}
+
 # Stages one step of a scenario arm into the sandbox working directory.
 # Scenarios call this once per step so their own git operations stay between
 # the steps, where they are visible.

package/src/commands/design.ts

@@ -26,7 +26,8 @@ export function register(program: Command): void {
         process.stderr.write(
           `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${opts.source} not found\n${GREY}└${NC}\n`,
         )
-        process.exit(1)
+        process.exitCode = 1
+        return
       }
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Render design tokens${NC}\n`,

package/src/commands/feedback.ts

@@ -60,12 +60,14 @@ export function register(program: Command): void {
         frameError(
           'No feedback on stdin. Pipe a markdown block: pbpaste | aitk feedback',
         )
-        process.exit(1)
+        process.exitCode = 1
+        return
       }
       const body = (await readStdin()).trim()
       if (!body) {
         frameError('Empty feedback body. Provide a markdown block on stdin.')
-        process.exit(1)
+        process.exitCode = 1
+        return
       }
 
       if (opts.github) {
@@ -83,7 +85,8 @@ export function register(program: Command): void {
           frameError(
             'gh unavailable and no toolkit source to fall back to. Install gh, or file it at https://github.com/erclx/aitk/issues/new',
           )
-          process.exit(1)
+          process.exitCode = 1
+          return
         }
         process.stderr.write(
           `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
@@ -94,7 +97,8 @@ export function register(program: Command): void {
         frameError(
           'Local scratch needs the toolkit source. Re-run with --github to open an issue instead.',
         )
-        process.exit(1)
+        process.exitCode = 1
+        return
       }
 
       const filePath = writeLocal(body)

package/src/commands/slides.ts

@@ -36,35 +36,39 @@ export function register(program: Command): void {
         mirror?: string
         open?: boolean
       }) => {
-        const sourcePath = resolve(process.cwd(), opts.source)
-        const outDir = resolve(process.cwd(), opts.out)
-        if (!existsSync(sourcePath)) {
-          fail(`${opts.source} not found`)
-        }
-        const variant = parseVariant(opts.variant)
-        const mirror = resolveMirror(opts.mirror)
-        intro('Render slides')
-        const result = await renderSlidesDoc(sourcePath, outDir, {
-          variant,
-          mirror,
-        })
-        process.stderr.write(
-          `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
-        )
-        if (result.mirrorPath) {
+        try {
+          const sourcePath = resolve(process.cwd(), opts.source)
+          const outDir = resolve(process.cwd(), opts.out)
+          if (!existsSync(sourcePath)) {
+            fail(`${opts.source} not found`)
+          }
+          const variant = parseVariant(opts.variant)
+          const mirror = resolveMirror(opts.mirror)
+          intro('Render slides')
+          const result = await renderSlidesDoc(sourcePath, outDir, {
+            variant,
+            mirror,
+          })
           process.stderr.write(
-            `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
+            `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
           )
+          if (result.mirrorPath) {
+            process.stderr.write(
+              `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
+            )
+          }
+          if (opts.open) {
+            const target = result.mirrorPath ?? result.pptxPath
+            const opened = await openDeck(target)
+            const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
+            process.stderr.write(
+              `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
+            )
+          }
+          outro()
+        } catch (error) {
+          reportFailure(error)
         }
-        if (opts.open) {
-          const target = result.mirrorPath ?? result.pptxPath
-          const opened = await openDeck(target)
-          const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
-          process.stderr.write(
-            `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
-          )
-        }
-        outro()
       },
     )
 
@@ -98,9 +102,27 @@ function resolveMirror(value: string | undefined): string | undefined {
   return mirror ? resolve(process.cwd(), mirror) : undefined
 }
 
+/**
+ * Carries a fail-fast message from a validation helper to the action that
+ * called it. `fail` has to keep its `never` return, since that is what makes
+ * `parseVariant` exhaustive to the compiler, and a helper deep in the call
+ * stack cannot set `process.exitCode` and unwind on its own.
+ */
+class SlidesError extends Error {}
+
 function fail(message: string): never {
+  throw new SlidesError(message)
+}
+
+/**
+ * `src/cli.ts` calls `program.parse()` without awaiting it, so a rejected
+ * action promise reaches no handler and Bun prints a stack trace. Every action
+ * that calls `fail` catches at its own boundary.
+ */
+function reportFailure(error: unknown): void {
+  if (!(error instanceof SlidesError)) throw error
   process.stderr.write(
-    `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
+    `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${error.message}\n${GREY}└${NC}\n`,
   )
-  process.exit(1)
+  process.exitCode = 1
 }

package/src/commands/transcripts.ts

@@ -42,7 +42,7 @@ export function register(program: Command): void {
         process.stderr.write(
           `${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
         )
-        process.exit(1)
+        process.exitCode = 1
       }
     })
 }

package/standards/skill.md

@@ -22,6 +22,17 @@ Does not govern:
 - The transform from a branch name to a slug a skill carries in a filename: `slug.md`
 - The domain conventions a skill cites, each of which belongs to the standard that owns it
 
+## Changing a skill
+
+Answer all four before editing, and carry the answers into wherever the change is proposed.
+
+- What problem does this solve? Name the run that went wrong, rather than the improvement the change makes.
+- Which surface owns the rule today? A rule already stated in a standard, a governance rule, or a sibling skill is cited or moved, never restated in the body.
+- What deterministic check catches a regression? Name it, or say none exists and the step holds on a session reading it.
+- What does this collide with? Name the sibling skill, rule, or requirement it contradicts, or state that nothing does.
+
+The second question is the one that decides between a body and a rule, which the next section tests in two parts.
+
 ## Whether a rule belongs beside the skill
 
 A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads a file matching its glob, with no decision from the session at all. The two are layers rather than alternatives, so the rule is the floor and the skill is the depth.

package/standards/standard.md

@@ -82,6 +82,17 @@ A standard failing these questions is non-conforming even when it satisfies ever
 
 ## Changing a standard
 
+### The checkpoint
+
+Answer all four before editing, and carry the answers into wherever the change is proposed. This section governs itself, so the next edit to this file answers them too.
+
+- What problem does this solve? Name the artifact that went wrong, rather than the improvement the change makes.
+- Which surface owns the rule today? A rule already stated somewhere moves or is cited, never restated in a second place.
+- What deterministic check catches a regression? Name it, or say none exists and the rule holds on reading alone.
+- What does this collide with? Name the sibling standard, rule, or template it contradicts, or state that nothing does.
+
+### What justifies a change
+
 - Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
 - Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
 - Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.

package/tooling/base/reference.md

@@ -1,114 +1,96 @@
 # Tooling base reference
 
-## Runtime
-
-- Use `bun` as package manager and script runner.
-- Use `bunx` instead of `npx` for one-off executables.
-
-## Prettier
-
-- Config: `.prettierrc` (JSON) at root.
-- Rules: `semi: false`, `singleQuote: true`.
-- Add parser overrides for non-standard extensions (e.g., `.mdx` → `markdown`).
-- Ignore paths via `.gitignore` and `.prettierignore`. Pass both as `--ignore-path` on all prettier invocations.
-- `.prettierignore` is a user-owned seed. It is created empty on install. Projects add their own entries.
-- Use `--log-level warn` on all prettier invocations to suppress per-file `(unchanged)` output.
-
-## Dev Dependencies
-
-- `prettier`, `cspell`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`.
-- Install via `bun add -D`.
-- Ensure `.gitignore` contains `node_modules/`.
-
-## CSpell
-
-- `cspell.json` is a user-owned seed at root. Sync drops it once on first install and never overwrites it. Projects extend it with extra `import` and `dictionaryDefinitions` entries.
-- The seeded baseline includes `version: "0.2"`, `language: "en"`, `useGitignore: true`, `gitignoreRoot: ["."]`, dictionary definitions for `project-terms` and `tech-stack`, and `ignorePaths: [".cspell/**", ".git/**"]` to skip dictionary self-checks and git object files. Both dictionary definitions set `addWords: true`.
-- `gitignoreRoot: ["."]` pins the `.gitignore` search to the project root. Without it, cspell run from inside a linked worktree under `.claude/worktrees/` walks up into the parent repo's `.gitignore`, resolves every worktree file as living under the ignored worktree path, and checks zero files. New words then pass locally and fail in CI. `gitignoreRoot` stops the walk at the root while the worktree's own `.gitignore` still excludes `node_modules` and build output.
-- Dictionary files in `.cspell/`: `project-terms.txt`, `tech-stack.txt`.
-- Include dotfolders in the spell glob: `cspell '**' '.*/**' '.*' ...`. The default `**` skips dot-prefixed folders, so `.claude/`, `.github/`, and `.husky/` go unchecked without explicit globs.
-- Keep dictionary entries sorted alphabetically, one word per line.
-
-## Shell Tooling
-
-- Format: `shfmt --indent 2 scripts/`. shfmt supports directory args natively, no `find` needed.
-- Lint: `find scripts -name '*.sh' -exec shellcheck --severity=warning {} +`. shellcheck has no directory mode, `find` is required.
-- Config: `.shellcheckrc` with `external-sources=true`. Required for shellcheck to follow `source` directives. Keep even with EditorConfig present.
-- All shell scripts live in `scripts/`. Do not place `.sh` files outside `scripts/`.
-- EditorConfig: `.editorconfig` at root with `[*.sh]` block enforcing `indent_style = space`, `indent_size = 2`. Prevents editor/shfmt conflicts that produce spurious git diffs.
-
-## Commit Lint
-
-- Config: `commitlint.config.js` (ESM default export).
-- Extends: `@commitlint/config-conventional`.
-- Rules: `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, `subject-case: disabled`.
-- Format: `<type>(<scope>): <subject>` (imperative mood, no trailing period).
-
-## Husky + Lint-Staged
-
-- `.lintstagedrc` is a user-owned seed at root. Sync drops it once on first install and never overwrites it. Projects extend it with extra glob → command entries (e.g. `aitk indexes regen`).
-- Seeded baseline globs:
-  - `**/*.{json,md,mdc}` → `["prettier --write --ignore-path .gitignore --ignore-path .prettierignore", "cspell --no-must-find-files"]`
-  - `**/*.md` → `["aitk indexes regen"]`
-  - `**/*.sh` → `["shfmt --write --indent 2", "shellcheck --severity=warning"]`
-- Hooks in `.husky/`:
-  - `pre-commit` → `bunx lint-staged`
-  - `commit-msg` → `bunx commitlint --edit "$1"`
-  - `pre-push` → `bun run check`
-  - `post-merge` → names `.claude/tasks/` archive candidates, silent otherwise and when the board is absent
-  - `post-rewrite` → delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check
-- Husky runs hooks as `sh -e`, so a hook carrying logic is POSIX sh under errexit no matter what its shebang says.
-- Note: lint-staged handles its own glob expansion and passes matched files as arguments. `**/*.sh` is safe here, unlike in package.json scripts.
-
-## GitHub
-
-- PR template: `.github/pull_request_template.md`.
-- Sections: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
-- Visuals: HTML comment only, never a visible section header.
-- Imperative mood, no "This PR" opener, no buzzwords, name specific files and functions.
-- CI workflow: `.github/workflows/verify.yml`. Runs on pull requests targeting `main` and on `workflow_dispatch`.
-- Workflow steps: checkout, setup Bun (latest), `bun install --frozen-lockfile`, install `shfmt` and `shellcheck` via apt, then `check:format`, `check:spell`, `check:shell`.
-- Does not run `format` before asserting. CI asserts only. Format must be clean before push.
+## Overview
 
-## Gitignore
+The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and three maintenance scripts. Every other stack extends it, so a decision made here is one every stack inherits.
 
-- `# System`: `.DS_Store`
-- `# Dependencies`: `node_modules/`
-- `# Secrets`: `.env`, `.env.*`, `*.local`, `!.env.example`
+## What ships as golden configs
+
+Golden config files live in `tooling/base/configs/` and are copied into the target on `aitk tooling sync base .`. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
+
+- `.prettierrc`: `semi: false`, `singleQuote: true`, plus a parser override per non-standard extension (`.mdx` to `markdown`).
+- `.shellcheckrc`: `external-sources=true`. Required for shellcheck to follow `source` directives.
+- `.editorconfig`: `root = true`, with an `[*.sh]` block setting `indent_style = space` and `indent_size = 2`.
+- `commitlint.config.js`: ESM default export extending `@commitlint/config-conventional`. Rules are `header-max-length: 72`, `scope-case: lower-case`, `subject-full-stop: never`, and `subject-case` disabled.
+- `.husky/`: `pre-commit`, `commit-msg`, `pre-push`, `post-merge`, `post-rewrite`.
+- `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
+- `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
+- `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
+- `scripts/verify.sh`, `scripts/clean.sh`, `scripts/update.sh`: the maintenance entry points behind `check`, `clean`, and `update`.
+
+## 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.
+
+- `cspell.json`: `version: "0.2"`, `language: "en"`, `useGitignore: true`, `gitignoreRoot: ["."]`, dictionary definitions for `project-terms` and `tech-stack` with `addWords: true` on both, and `ignorePaths: [".cspell/**", ".git/**"]` to skip dictionary self-checks and git object files.
+- `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
+- `.lintstagedrc`: the glob map below.
+- `.prettierignore`: created empty. Projects add their own entries.
+- `.claude/context/ci.md` and `.claude/context/development.md`: extend with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
 
-## Scripts
+## Tool pairing
 
-- Entry: `scripts/` directory with `verify.sh`, `clean.sh`, `update.sh`.
-- All scripts use logging functions from the bash script reference.
-- `verify.sh`: self-healing: runs `format` first to auto-fix AI-generated or drifted code, then asserts with `check:format`. Supports `VERIFY_NESTED=true` to suppress timeline boundaries when called by other scripts.
-- `clean.sh`: removes `node_modules/`, clears bun cache, reinstalls dependencies fresh.
-- `update.sh`: runs `bun update --interactive` then calls `verify.sh` with `VERIFY_NESTED=true` to confirm project health after updates.
+- Runtime: `bun` as package manager and script runner, `bunx` over `npx` for a one-off executable.
+- Formatting: Prettier for what it parses, shfmt for shell. Two formatters because Prettier has no shell parser.
+- Spelling: cspell over the whole tree, with project vocabulary split into a project-terms dictionary and a tech-stack one.
+- Shell: shfmt formats and shellcheck lints at warning severity. shfmt takes a directory argument, shellcheck has no directory mode and needs `find`.
+- 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: `prettier`, `cspell`, `husky`, `@commitlint/cli`, `@commitlint/config-conventional`. Install via `bun add -D`.
 
-## EditorConfig
+## File layout
 
-- Config: `.editorconfig` at root, `root = true`.
-- `[*.sh]`: `indent_style = space`, `indent_size = 2`.
-- Ensures consistent shell script indentation across editors, preventing shfmt vs editor conflicts that produce spurious git diffs.
+- All shell scripts live in `scripts/`. Do not place a `.sh` file outside it.
+- Dictionaries live in `.cspell/`, hooks in `.husky/`, seeded context docs in `.claude/context/`.
+- The `.claude/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md`, `.claude/REQUIREMENTS.md`, and `.claude/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `.claude/context/`. Indexes stay opt-in.
 
-## VS Code
+## Hooks
 
-- Extensions: `esbenp.prettier-vscode`, `streetsidesoftware.code-spell-checker`, `mkhl.shfmt`, `timonwong.shellcheck`, `mads-hartmann.bash-ide-vscode`.
-- Settings: `shellcheck.customArgs: ["--severity=warning"]`.
+- `pre-commit` runs `bunx lint-staged`.
+- `commit-msg` runs `bunx commitlint --edit "$1"`.
+- `pre-push` runs `bun run check`.
+- `post-merge` names `.claude/tasks/` archive candidates, staying silent otherwise and when the board is absent.
+- `post-rewrite` delegates to `post-merge` on `rebase`, so a `pull.rebase=true` machine still gets the check.
 
-## Context
+## lint-staged
 
-- Seeded at `.claude/context/development.md` and `.claude/context/ci.md` on install. User-owned, never overwritten by sync.
-- Each carries `title` and `description` frontmatter so the files slot into `.claude/context/index.md` if the project adopts the `indexes` system. Indexes stay opt-in.
-- Extend freely with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
-- The `.claude/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md` and `.claude/REQUIREMENTS.md`/`.claude/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `.claude/context/`.
+Seeded baseline globs:
 
-## Package Scripts
+- `**/*.{json,md,mdc}` runs `prettier --write --ignore-path .gitignore --ignore-path .prettierignore` then `cspell --no-must-find-files`
+- `**/*.md` runs `aitk indexes regen`
+- `**/*.sh` runs `shfmt --write --indent 2` then `shellcheck --severity=warning`
+
+## CI
+
+- Steps: checkout, setup Bun at latest, `bun install --frozen-lockfile`, install `shfmt` and `shellcheck` via apt, then `check:format`, `check:spell`, and `check:shell`.
+- CI asserts and never writes. Format must be clean before push.
+
+## Gitignore
+
+- `# System`: `.DS_Store`
+- `# Dependencies`: `node_modules/`
+- `# Secrets`: `.env`, `.env.*`, `*.local`, `!.env.example`
 
-- `check:spell`: runs cspell across all files, shows context on failures.
-- `check:format`: checks prettier and shfmt formatting without writing. shfmt targets `scripts/` directory directly. Uses `--log-level warn` and both `--ignore-path .gitignore --ignore-path .prettierignore`.
-- `check:shell`: runs shellcheck at warning severity via `find scripts -name '*.sh'` (shellcheck has no directory mode).
-- `format`: writes prettier and shfmt formatting in place. shfmt targets `scripts/` directory directly. Uses `--log-level warn` and both `--ignore-path .gitignore --ignore-path .prettierignore`.
-- `prepare`: initializes husky hooks (runs automatically on `bun install`).
-- `check`: runs `scripts/verify.sh`, the full verification suite. Auto-formats before asserting.
-- `clean`: runs `scripts/clean.sh`, wipes and reinstalls dependencies.
-- `update`: runs `scripts/update.sh`, interactive dependency update with verification.
+## Anti-patterns
+
+Sticky negative knowledge. Do not relearn.
+
+- Do NOT drop `gitignoreRoot: ["."]` from `cspell.json`. Without it, cspell run from inside a linked worktree under `.claude/worktrees/` walks up into the parent repo's `.gitignore`, resolves every worktree file as living under the ignored worktree path, and checks zero files. New words then pass locally and fail in CI.
+- Do NOT rely on the default `**` glob for spelling. It skips dot-prefixed folders, leaving `.claude/`, `.github/`, and `.husky/` unchecked. Pass `'**' '.*/**' '.*'` explicitly.
+- Do NOT invoke prettier without both `--ignore-path .gitignore --ignore-path .prettierignore`. Passing one drops the other, since the flag replaces the default rather than adding to it.
+- Do NOT omit `--log-level warn` from a prettier invocation. The default prints a line per unchanged file.
+- 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.
+- Do NOT drop the `[*.sh]` block from `.editorconfig` because shfmt already sets indentation. The editor and shfmt then disagree and produce spurious git diffs.
+- Do NOT copy lint-staged's `**/*.sh` glob into a package.json script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
+
+## CLI
+
+| Script                 | What it does                                                                                                                                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bun run check`        | Full verification suite via `scripts/verify.sh`. Runs `format` first to auto-fix drifted code, then asserts. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                                                                                  |
+| `bun run check:spell`  | Runs cspell across every file, with context on failures                                                                                                                                                |
+| `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                                                                                    |
+| `bun run format`       | Writes prettier and shfmt formatting in place                                                                                                                                                          |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                                                                                            |
+| `bun run clean`        | Removes `node_modules/`, clears the bun cache, reinstalls fresh                                                                                                                                        |
+| `bun run update`       | Runs `bun update --interactive`, then `verify.sh` with `VERIFY_NESTED=true`                                                                                                                            |

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

@@ -1,6 +1,13 @@
 #!/usr/bin/env bash
 
-input=$(cat)
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
 
 tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
 case "$tool" in

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

@@ -3,10 +3,18 @@
 # Regenerates .claude/memory/index.md after a memory file changes.
 #
 # The memory folder is gitignored, so the whole-repo walk in `bun run check`
-# drops it and never regenerates this index. A positional path bypasses that
-# filter, which makes this hook the only trigger that reaches the folder.
+# drops it and never regenerates this index. Naming the file as a positional
+# argument to `aitk indexes regen` below bypasses that filter, which makes this
+# hook the only trigger that reaches the folder.
 
-input=$(cat)
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
 
 tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
 case "$tool" in

package/tooling/claude/seeds/.claude/hooks/scratch-guard.sh

@@ -1,6 +1,13 @@
 #!/usr/bin/env bash
 
-input=$(cat)
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
 
 tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
 case "$tool" in

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 
-input=$(cat)
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
 file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_response.filePath // empty')
 
 file="${file//\\//}"

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

@@ -3,10 +3,18 @@
 # Regenerates .claude/tasks/index.md after a task file changes.
 #
 # The task folder is gitignored, so the whole-repo walk in `bun run check`
-# drops it and never regenerates this index. A positional path bypasses that
-# filter, which makes this hook the only trigger that reaches the folder.
+# drops it and never regenerates this index. Naming the file as a positional
+# argument to `aitk indexes regen` below bypasses that filter, which makes this
+# hook the only trigger that reaches the folder.
 
-input=$(cat)
+# Claude Code sends a payload and closes stdin. A bare read with nothing feeding
+# it blocks forever and holds the session open, so the read is bounded. `read`
+# rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
 
 tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
 case "$tool" in