@erclx/aitk 0.30.0 → 0.31.0

package/README.md

@@ -55,7 +55,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 - [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill and its two paths, render command
 - [Slides](.claude/context/slides.md): `SLIDES.md` source, layout catalog, render command, draft skill
 - [Transcripts](.claude/context/transcripts.md): fetch a YouTube transcript with metadata frontmatter via `aitk transcripts`
-- [Sandbox](.claude/context/sandbox.md): scenario-based scaffolds for verifying each domain flow
+- [Sandbox](.claude/context/sandbox/index.md): scenario-based scaffolds for verifying each domain flow
 
 ## Documentation
 

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

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

package/claude/skills/claude-memory-review/REQUIREMENT.md

@@ -16,6 +16,7 @@ Without this skill, the memory folder grows and never drains. Entries pile up re
 - Rewrite a rule into the destination's voice instead of moving it unchanged
 - Write the proposal to a receipt on disk and take no action until the user decides per item
 - Keep a promotion on its own commit, since a change to how the agent operates should not ride inside a feature a reviewer is vetting for something else
+- Confine the pass that runs after application to the one receipt it tested, so tidying up removes a file whose decisions are known to be resolved and leaves the pen and every untested receipt alone
 
 ## Must not
 
@@ -23,12 +24,14 @@ Without this skill, the memory folder grows and never drains. Entries pile up re
 - Author a governance rule inline. Coding-standards rules have an owner and a scaffolding path, and a rule written here bypasses both.
 - Mutate tracked files from the main worktree
 - Answer a question raised in a decision slot while applying. Discussion and application are separate passes so an approval is never inferred from a reply.
+- Delete a memory entry outside the approved-per-item pass. The folder is gitignored with no history behind it, so a removal any other phase makes has no undo and no record of what it took.
 
 ## Guards
 
 - No memory folder at the main root: stop
 - The folder holds only its index: stop with a pass, not an error
 - Apply invoked from the main worktree: stop and name the worktree command
+- Cleanup invoked with no receipt on disk: stop with a pass, not an error
 
 ## Out of scope
 

package/claude/skills/claude-memory-review/SKILL.md

@@ -7,21 +7,22 @@ description: Reviews `.claude/memory/` and proposes per-entry actions (promote t
 
 This skill drives the full memory review lifecycle in five phases. Pick the phase from what the user said and whether a review receipt already exists at `<main-root>/.claude/review/memory-review-*.md`.
 
-| User intent                                    | Phase     | Mutates                      |
-| ---------------------------------------------- | --------- | ---------------------------- |
-| "review memory", "promote memory" (no receipt) | Propose   | review file only             |
-| "challenge the promotes" (receipt exists)      | Challenge | review file only             |
-| "discuss", "respond to questions"              | Discuss   | review file only             |
-| "apply decisions", "commit", "ship the review" | Apply     | tracked files + memory files |
-| "cleanup", "sweep stale", "delete the receipt" | Cleanup   | memory files + review file   |
+| User intent                                                            | Phase     | Mutates                      |
+| ---------------------------------------------------------------------- | --------- | ---------------------------- |
+| "review memory", "promote memory", "sweep stale memories" (no receipt) | Propose   | review file only             |
+| "challenge the promotes" (receipt exists)                              | Challenge | review file only             |
+| "discuss", "respond to questions"                                      | Discuss   | review file only             |
+| "apply decisions", "commit", "ship the review"                         | Apply     | tracked files + memory files |
+| "cleanup", "delete the receipt"                                        | Cleanup   | one review file              |
 
-If the user just re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
+If the user re-pings the skill with no new phrase and a receipt exists, default to Discuss when any `Decision:` contains `?`, otherwise Apply.
 
 ## Guards
 
 - All `.claude/memory/` reads, edits, and deletes resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
 - If no `.claude/memory/` directory exists at the main worktree root, stop: `❌ No .claude/memory/ directory found.`
 - If `.claude/memory/` contains no `*.md` entries other than `MEMORY.md`, stop: `✅ No memory entries to review.`
+- Cleanup is exempt from the two stops above. It works on receipts in `.claude/review/`, and a drained pen is the normal state once Apply has run, so a pen-shaped stop would strand the receipt it exists to delete.
 - Resolve the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. All review and memory reads anchor here.
 
 ## Propose phase
@@ -186,14 +187,17 @@ End with: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Om
 
 ## Cleanup phase
 
-Trigger: user says "cleanup", "sweep stale memories", or "delete the receipt" after Apply has run.
+Trigger: user says "cleanup" or "delete the receipt" after Apply has run.
 
-1. Read the latest `.claude/review/memory-review-*.md` to see which entries were skipped.
-2. Treat a `Skip` decision as terminal. Do not delete a memory just because it would Skip again next review. Target only entries whose decision value is exhausted: already-applied promotions and stale receipts.
-3. Delete the review file itself.
-4. Leave applied promotions, governance handoffs, and user-type memories alone.
+Cleanup removes one receipt and nothing else. Apply is the only phase that deletes a memory entry, and it does so per approved item against a folder that is gitignored with no history behind it, so a deletion made anywhere else has no undo and leaves no record of what it took. A user asking to sweep stale memories wants Propose, which classifies entries and writes a decision slot per entry.
 
-Do not promote or rewrite. Cleanup only.
+If no `.claude/review/memory-review-*.md` exists at the main root, stop: `✅ No review receipt to clean up.` Every other refusal in this skill carries a message, and the phase reads a receipt before it does anything else.
+
+1. Read the latest `.claude/review/memory-review-*.md` at the main root and confirm Apply has run against it. If any item is still 📝 pending, stop and name the pending numbers.
+2. Delete that one file. Leave every other receipt beside it in place, because the pending test above covers the file it read and nothing has tested the rest.
+3. Leave every memory entry in place. A `Skip` decision is terminal, and applied promotions, governance handoffs, and user-type memories each stay as the review left them.
+
+Do not promote, rewrite, or delete a memory entry. Receipts only.
 
 ## After completion
 
@@ -202,5 +206,6 @@ Output one line per action taken in the most recent phase:
 - `✅ Promoted: .claude/memory/<memory-file> → <target>`
 - `✅ Handed off: .claude/memory/<memory-file> → governance`
 - `🗑  Deleted: .claude/memory/<memory-file>`
+- `🗑  Swept: .claude/review/<review-file>`
 
 If the user accepted nothing, output: `✅ No changes applied.`

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

@@ -0,0 +1,35 @@
+---
+name: migration-context
+description: Scope boundary for the docs audience split and its ordering against the other two migrations
+---
+
+# Migration context requirement
+
+## Gap
+
+Without this skill, a session judges a `docs/` file agent-facing, moves it, and rewrites the inbound links in the same pass, so a classification the user rejects is no longer one command to undo.
+
+Three more failures share a cause. The skill reads a folder two other surfaces also write, and a proposal blind to them destroys work. A seed-derived `development.md` moved out of `docs/` comes back on the next seed sync. A move onto an existing `.claude/context/` filename overwrites the entry sitting there. A proposal drafted while `migration-claude-md` is proposing entries into the same folder cannot see those targets, and running the two in the wrong order turns a legitimate move into a skipped conflict.
+
+## Must
+
+- Classify by audience signal in the file rather than by its name or its folder position
+- Propose and stop. The `git mv` commands and the link fixes stay the user's to run.
+- Report every inbound reference to a moved path as a TODO line, leaving the reference itself untouched
+- Defer a seed-derived file to the seed sync path rather than proposing a move for it
+- Skip a move whose destination already exists and report it as a conflict
+
+## Must not
+
+- Sort a file carrying both audiences into either bucket. Flag it for a manual split, since a whole-file move and a silent split are both wrong.
+- Descend into `docs/` subfolders. List them for manual review and leave them alone.
+
+## Guards
+
+- A missing `docs/` directory, or one holding no top-level markdown, stops before any classification runs
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections, which `migration-claude-md` proposes into this same `.claude/context/` folder. Run this skill first when both apply, so that skill's append-or-create check reads a folder the moves have already populated.
+- Relocating root `standards/` and `snippets/`: `migration-standards`
+- Regenerating `.claude/context/index.md`, which `aitk indexes regen` does once the user has applied the moves

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: setup-gov
+description: Scope boundary for governance rule install and the authoring it refuses to do in a target
+---
+
+# Setup gov requirement
+
+## Gap
+
+Without this skill, a session picks a stack name from memory and installs rules written for a framework the project does not use, passes an extra the catalog does not carry so the install warns on a file it cannot resolve, and adds a rule the picked stack already pulls in.
+
+The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
+
+## Must
+
+- Read the catalog at run time and resolve both the stack and every extra against it
+- Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
+- Dedupe extras against the rules the picked stack already resolves
+- Run the install non-interactively, since the CLI picker blocks where no terminal is attached
+
+## Must not
+
+- Author a rule inside the target project. Rules are authored in the toolkit and reach a project by install or sync.
+- Install a stack or extra whose name did not come from the catalog read
+
+## Guards
+
+- An unmatched technology stops and presents the options rather than resolving to a nearby rule. Authoring the missing rule in the toolkit, installing the matching layers without the technology-specific one, and aborting are the three, and this skill picks none of them.
+
+## Out of scope
+
+- The rest of the onboarding chain. This skill installs governance and nothing else, and `setup-init` is the one-shot path that installs governance beside tooling, standards, snippets, and the seeds.
+- Scaffolding the rule file an unmatched technology needs. `create-rule` writes one into a target project, and a rule the toolkit should ship is authored under `governance/rules/` against `.claude/standards/rule.md`.
+- Updating rules a project already has, which `aitk gov sync` owns

package/claude/skills/setup-init/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: setup-init
+description: Scope boundary for the one-shot onboarding chain and the setup steps it leaves to a caller
+---
+
+# Setup init requirement
+
+## Gap
+
+Without this skill, a session installs a stack whose name it recalled rather than read, hand-writes configs the tooling sync already ships as golden files, and re-runs the chain over a project that owns its configs already.
+
+Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
+
+## Must
+
+- Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
+- Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
+- Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
+- State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+
+## Must not
+
+- Generate a config that tooling sync ships as a golden file. Generating from prose duplicates the installed file and the two drift.
+- Author a rule, stack, or snippet inside the target project when detection finds no match. Authoring happens in the toolkit and reaches a project by install or sync.
+- Grow an existing-project branch, a mode switch, or a clobber guard. The chain runs once against a fresh scaffold and the per-domain paths cover everything after that.
+
+## Guards
+
+- An unmatched technology stops for a decision. Surface the gap and either defer to rule authoring or proceed on the matched layer with the gap named in the report, rather than resolving to the nearest rule.
+
+## Out of scope
+
+- Installing governance rules alone: `setup-gov`. This skill installs governance beside tooling, standards, snippets, and the seeds.
+- Bootstrapping the `index.md` system: `setup-indexes`. Neither `aitk init` nor this chain performs it.
+- Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
+- Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
+- Re-installing into a project that already has the files, which the per-domain `aitk <domain> install` and `aitk sync` commands own

package/docs/target-projects.md

@@ -127,7 +127,7 @@ Use a targeted entry point when only one surface moved upstream. Use the catch-a
 
 ## Verify a sync
 
-Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox.md) for the scenario catalog and routing patterns.
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox/index.md) for the scenario catalog and routing patterns.
 
 ## Scenarios
 
@@ -182,4 +182,4 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 - [agents](agents.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
-- [sandbox](../.claude/context/sandbox.md): scenario catalog for verifying domain flows
+- [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `.claude/context/sandbox.md` states, and it
+ * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
  * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two