@erclx/aitk 0.53.0 → 0.55.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.53.0",
+  "version": "0.55.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/claude-groundwork/SKILL.md

@@ -14,6 +14,7 @@ Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file i
 - If no topic is given, stop: `❌ No topic. Name what needs measuring.`
 - Apply the qualifying test in open mode alone, after Step 1 resolves the mode and before the folder is created. Two of these three must hold: the current state is not known, more than one approach is live, and committing wrong costs more than a day of measuring. When one or fewer holds, stop: `❌ Already decided enough to plan. Run /claude-feature instead.`
 - Resume and close are exempt from the test above. A track that has already been measured fails it by definition, since its current state is now known and its approaches have narrowed, so applying the test to either mode refuses the folder that same test admitted.
+- A refused topic that is a broad dump rather than one question routes to `claude-intake`, not to the planning skill the stop names. Intake dispositions many findings in breadth from what the repository already holds, and one folder holding dozens of unrelated threads is what forcing them past this guard produces.
 - Do not pause for approval between steps. The write scope below is what makes that safe.
 
 ## Write scope

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

@@ -0,0 +1,46 @@
+---
+name: claude-intake
+description: Why a brain dump gets a filed inventory rather than ten plans, and why an empty operator slot means unread
+---
+
+# Claude intake requirement
+
+## Gap
+
+Without this skill, a brain dump reaches a session that has nowhere to put it. `claude-feature` answers with one plan per independent concern, so forty findings produce ten plan files before anything has been measured. `claude-groundwork` refuses a breadth pass outright, since its qualifying test asks whether the current state is unknown and most items are knowable by grep. What gets filed instead is a list of opinions, because nothing forces a count against the tree and a complaint reads the same whether it covers three sites or three hundred.
+
+Two failure modes cost more than the rest. An operator's silence on an item reads as consent when the folder borrows the plan file's blank-means-accept contract, which ships changes nobody approved across a folder read over weeks. And a report naming only a path cannot distinguish three new items from one reworded sentence in a file that holds a dozen items, so every reader diffs it against memory to find out what moved.
+
+Four more are cheaper to name than to rediscover. A question filed without a pick comes back unresolved, measured across one folder's 19 open items, where every one carrying a suggestion resolved on a bare `ok` and the five carrying none did not. A session with no numbering convention re-decides the folder shape per dump, so no two intakes are readable the same way and the second one has to be learned from scratch. A question answerable both in the index and on its item resolves to whichever a reader opens first, with no rule saying which wins. And a pass with no write scope starts fixing what it files, which turns a triage into a branch nobody asked for and nobody reviewed.
+
+## Must
+
+- Route each item on whether the repository can answer it today, sending what needs an experiment or an outside source to the groundwork skill and what is already decided to the planning skill
+- Measure every problem line against the tree during this pass, carrying a number or a file path rather than a figure from recall
+- Close every item with a verdict, and pair every open question with a suggested pick
+- Treat an empty operator slot as unread rather than as agreement
+- Reserve the index number and carry the domain in every other filename, leaving the rest of the numbering as read order
+- Keep answers on items alone, with the index pointing at them
+- Name the heading and the act beside every path the pass wrote
+- Confine writes to the intake folder
+
+## Must not
+
+- Write a plan, a task file, a standard, a rule, or a source change
+- Fill an operator's answer slot, or infer a disposition from an empty one
+- Replace a verdict with an overlap line, which drops the call on exactly the items where a live board task might be the thing that is wrong
+- Reserve mid-range numbers, which would force every future intake into one dump's shape
+- Date every file, since the first edit to one leaves the rest stale
+- Open a folder for a single question, which is either a groundwork track or a plan
+
+## Guards
+
+- No dump given: stop rather than inferring one
+- One question rather than a set of findings: stop and route to the groundwork or planning skill
+
+## Out of scope
+
+- Measuring one question in depth, which `claude-groundwork` owns
+- Planning a promoted item, which `claude-feature` owns
+- Promoting an item onto the board, which `claude-tasks` owns
+- Enforcing any of this. The folder is gitignored, so no check reaches its contents and every rule holds only while a session reads it.

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

@@ -0,0 +1,139 @@
+---
+name: claude-intake
+description: Files a raw brain dump into a numbered intake folder under `.claude/intake/<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `claude-groundwork`.
+---
+
+# Claude intake
+
+Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
+
+Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter, and the item template.
+
+## Routing
+
+The test is one question. Can the item be answered by reading the repository today?
+
+- Yes: intake owns it, and the cost is a session of grepping
+- No, because it needs an experiment or a source outside the project: route it to `claude-groundwork`, where the cost is measured in runs and days
+- Already decided, with only the work left: route it to `claude-feature`
+
+Apply the test per item rather than per dump. A dump of forty items typically yields one groundwork candidate, so routing the whole dump on its worst item buys a folder nobody can close.
+
+Using the wrong one fails in two shapes. Intake on a question that needs measuring yields a confident verdict with nothing behind it. Groundwork on a brain dump is refused by its own qualifying guard, and forcing past that refusal gives one folder holding dozens of unrelated threads and a decision file that can close one of them.
+
+## Guards
+
+- If no dump is given, stop: `❌ No dump to file. Paste the notes or name what to triage.`
+- If the dump is one question rather than a set of findings, stop: `❌ One question, not a dump. Run /claude-groundwork to measure it or /claude-feature to plan it.`
+- Do not pause for approval between steps. The write scope below is what makes that safe.
+
+## Write scope
+
+- Write only inside `.claude/intake/<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
+- There is no exception. Promoting an item onto the board runs through `claude-tasks` after the operator has answered, which is a separate invocation.
+- Reading is unrestricted inside the project. Measuring is the work.
+- Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
+
+Nothing outside this body carries the floor, and no path-scoped rule can. The item format and the answer contract are heading for a standard covering this folder and a groundwork track together, which is queued rather than written.
+
+## Step 1: detect open or resume
+
+List `.claude/intake/` from the project root and match the topic against the folders already there before deriving a slug. A second pass over the same subject rarely phrases the topic the way the folder was named, so a fresh slug would open a duplicate beside a live folder.
+
+Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
+
+With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
+
+## Step 2: orient
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules, conventions, commands
+- `.claude/REQUIREMENTS.md`: scope and non-goals
+- `.claude/ARCHITECTURE.md`: decisions already made
+- `.claude/tasks/index.md`: what is already tracked. Open a task file whose entry looks related to an item.
+
+Then read only what a live item needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
+
+## Step 3: measure against the tree
+
+Grep for each construct an item names and count the sites. Every problem line carries a number or a file path taken during this pass.
+
+Never carry a figure from an earlier session, a summary, or another document. The dump states the complaint and the tree states the size of it, and that measurement is the whole difference between an inventory and a list of opinions. Confirm that any work an item sequences behind is still open, so no item leads with something that already shipped.
+
+Name the commit the pass measured against in the overview body. It is the half a later reader can check.
+
+## Step 4: cluster
+
+Split items by domain, one file per cluster, and let the file count follow the number of separable domains rather than the size of the dump. An item belongs to the domain its fix touches, not the domain the complaint arrived from.
+
+Two heading levels is the right depth. A third means the cluster should have been split into its own file.
+
+## Step 5: disposition each item
+
+Write every item in the format below, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot.
+
+## Step 6: write the index
+
+Write `00-overview.md` last, once the clusters are filed and the counts are real. It carries the format block, the cluster table, the verdict counts, the ready list, and the open questions.
+
+Each open question in the index is a labeled markdown link to its owning item's heading anchor. The index points and the item owns, so no answer slot appears in the index. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
+
+Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
+
+## Item format
+
+```markdown
+### N. Short title stating the defect
+
+- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
+- **Fix:** the one change proposed
+- **Worth it:** yes, later, or no, with the reason
+- **Open:** only where the call is the operator's
+- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
+- **Overlaps:** the live board task that already owns this item
+- **You:**
+```
+
+- `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
+- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default. The toolkit's `decision-help` snippet writes the same four-line shape for chat use, and the four lines above are the whole spec.
+- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
+
+## The answer contract
+
+`You:` belongs to the operator and ships empty on every item.
+
+Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
+
+That inverts the plan file's contract, where a blank `- Answer:` means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in chat. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
+
+Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
+
+## Numbering
+
+Numbers are read order and nothing else. Reserve `00` for the index and carry the domain in every other filename, so `07-tooling.md` says what it holds before anyone opens it.
+
+Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. `claude-groundwork` reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
+
+## Output
+
+Emit the full relative path from the project root for every file written, and name the heading and the act beside it. A path alone cannot distinguish three new items from one reworded sentence in a file that holds a dozen items and lives for weeks, so a bare path sends the reader to diff it against memory. This overrides the paths-only reporting the project states generally, which stays right wherever the reader is about to see a diff.
+
+A file the pass only read gets no line, which is what keeps the block short.
+
+```plaintext
+📂 Opened .claude/intake/<slug>/
+
+**Filed:**
+
+- `.claude/intake/<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
+- `.claude/intake/<slug>/00-overview.md` cluster rows and verdict counts updated
+
+**Routing:** <N> plan-ready, <N> groundwork candidates, <N> already settled
+
+**Open questions:** <N> awaiting your call
+
+Next: answer the `You:` slots, then /claude-tasks to promote what is ready
+```
+
+Use `📂 Resumed` in place of `📂 Opened` on a resume pass.

package/claude/skills/claude-intake/references/folder-format.md

@@ -0,0 +1,97 @@
+---
+title: Intake folder reference
+description: Reserved index number, file map, frontmatter and dating, the item template, retrieval, and anti-patterns
+---
+
+# Intake folder reference
+
+Applies to an intake folder at `.claude/intake/<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem and a verdict.
+
+The folder is gitignored and unbacked. No check reaches its contents, so the shape below survives only by being read.
+
+## Files
+
+| File                 | Holds                                                        | Required |
+| -------------------- | ------------------------------------------------------------ | -------- |
+| `00-overview.md`     | Index: format block, cluster table, verdicts, open questions | Always   |
+| `NN-<domain>.md`     | One cluster of items, filed by the domain their fixes touch  | Always   |
+| `99-next-session.md` | What a compaction destroys that no cluster file carries      | Optional |
+
+`00` is the only reserved number. Everything else is read order, and the domain rides in the filename so a reader knows what `07-tooling.md` holds without opening it.
+
+Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. Groundwork reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
+
+Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
+
+## Frontmatter and dating
+
+Every file carries `title` and `description` per the project's prose standard. `00-overview.md` carries one field the others do not, a `date` holding the day the folder opened.
+
+Date the folder once rather than every file. Twelve dated files leave eleven stale the first time one cluster is edited, and the opening date never rots. The checkable half is the commit, which the overview body names as what the claims were measured against.
+
+## 00-overview.md
+
+The index. It points at items and answers nothing itself.
+
+- The item format block, copied so a returning session picks the shape up from the folder
+- The answer contract stated out loud, since it inverts the plan file's
+- A cluster table of file, what it holds, item count, and open count
+- The verdict counts across the folder
+- A ready list, grouped by what shipping one actually costs
+- The open questions, each a labeled markdown link to its owning item's heading anchor
+
+The index carries no answer slot. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
+
+Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
+
+## Item template
+
+```markdown
+### N. Short title stating the defect
+
+- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
+- **Fix:** the one change proposed
+- **Worth it:** yes, later, or no, with the reason
+- **Open:** only where the call is the operator's
+- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
+- **Overlaps:** the live board task that already owns this item
+- **You:**
+```
+
+`Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. `Open:` appears only where the call is the operator's, `Suggested:` is required whenever it does, and `Overlaps:` is optional and never replaces the verdict.
+
+Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file.
+
+An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything that fits the four bullets belongs in them.
+
+## Retrieval
+
+Answers live on items, so one pass over the folder reports every touched slot.
+
+```bash
+awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' *.md
+```
+
+Counting what is still unread runs against the empty slot instead.
+
+```bash
+grep -c '^- \*\*You:\*\*$' *.md
+```
+
+Both walk `###` headings, which is the mechanical reason an answer typed anywhere else is lost.
+
+## Conventions
+
+- State a number with what it settles. The strongest items are the ones where a measurement decides the verdict and says so.
+- File an item under the domain its fix touches, not the domain the complaint arrived from.
+- Name a live board task an item overlaps, and keep the verdict beside it.
+- Revise a verdict the tree has moved under rather than appending a second one narrating the change.
+- Report unread items by count on a resume pass. Never decide one.
+
+## Anti-patterns
+
+- **Silence read as consent.** An empty slot on a folder read over weeks means nobody reached the item, and treating it as acceptance ships a change nobody approved.
+- **A verdict with nothing behind it.** An item whose problem line carries no number is an opinion, and it reads exactly like the ones that were measured.
+- **The overlap that ate the verdict.** Replacing `Worth it:` with `Overlaps:` drops the call on the items most likely to change what a live task should do.
+- **A question in two places.** An open question answerable in the index and on the item resolves to whichever a reader happens to open.
+- **The dump filed as one concern.** Forty findings under one heading is a folder nobody can promote from, and the split by domain is what makes each item liftable on its own.

package/docs/agents/index.md

@@ -16,7 +16,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
-- [Output shape](output-shape.md): The two framed shapes every command renders into, and how JSON and --names modes keep stdout clean
+- [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain

package/docs/agents/output-shape.md

@@ -1,6 +1,6 @@
 ---
 title: Output shape
-description: The two framed shapes every command renders into, and how JSON and --names modes keep stdout clean
+description: Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 ---
 
 # Output shape
@@ -43,3 +43,13 @@ Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to
 ## JSON and `--names` modes
 
 `--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
+
+## Process exit
+
+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.
+
+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/agents/overview.md

@@ -15,7 +15,7 @@ See `CLAUDE.md` design principles. They apply to every command in this folder.
 
 ## Where to start
 
-- `output-shape.md`: the stream contract every command renders into, which is what a caller parsing stdout depends on
+- `output-shape.md`: the stream contract every command renders into and the exit discipline behind it, which is what a caller parsing stdout depends on
 - `commands.md`: the full command catalog, project-level and per-domain
 - `scripting.md`: the runtime catalogs that replace hardcoded names, plus headless invocation examples
 

package/docs/ai-workflow.md

@@ -44,6 +44,7 @@ One session works for most features. Prefer splitting across two sessions only w
 
 Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
 
+- When the input is a pile of findings rather than one feature, invoke `aitk:claude-intake` first. It files the dump into `.claude/intake/<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled. The routing test is whether the repository can answer an item today, so a session grepping handles the yes and the next bullet handles the no.
 - When the current state is unmeasured and more than one approach is live, invoke `aitk:claude-groundwork` first. It opens a track folder under `.claude/groundwork/<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled. A track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
 - Invoke `aitk:claude-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
 - Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
@@ -101,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`
@@ -131,6 +133,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 
 | Skill                        | When to use                                                                                                          |
 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `aitk:claude-intake`         | File a brain dump into an inventory under `.claude/intake/`, one item per finding with a verdict                     |
 | `aitk:claude-groundwork`     | Before a plan is warranted, measure an unknown in a track folder under `.claude/groundwork/`                         |
 | `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                            |
 | `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                     |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.53.0",
+  "version": "0.55.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/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/rule.md

@@ -19,6 +19,14 @@ Does not govern:
 - Skill folders and skill frontmatter: `skill.md`
 - Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
 
+## Whether a skill belongs behind the rule
+
+A rule fires on a path match with no decision from the session, which is what makes it a floor. Every bullet is one directive and nothing else, so an invariant needing procedure, worked cases, or a branch on project state has no room in the body.
+
+Run the two-part test in reverse before calling the rule finished. The rule already holds what fires on a path edit and ships silently when violated. Ask what a session still needs past the directive, and give that to a skill the rule points at, because a rule that grows a procedure has become a skill body wearing rule frontmatter.
+
+Write both when both apply. A rule stating the directive and a skill stating how to carry it out are one invariant at two depths rather than two copies of it, and `skill.md` carries the same checkpoint for a session arriving from the other side. Nothing checks either one.
+
 ## Location
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`

package/standards/skill.md

@@ -22,6 +22,25 @@ 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.
+
+Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, because a session that never invoked the skill still edits that path and needs the floor under it. An invariant failing either half stays here, which is most of a body, since procedure and orientation are what a rule cannot carry.
+
+Write that rule to the shape `rule.md` sets and leave the procedure here, since the two carry one invariant at two depths rather than two copies of it. Nothing checks the split. The checkpoint is a judgment prompt rather than an invariant, so it ships as prose with no gate behind it, and a skill that skips it fails silently in the same way the invariants it is meant to catch do.
+
 ## Skill types
 
 Pick the type before writing. It decides the body shape.

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