@erclx/aitk 0.30.1 → 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.1",
+  "version": "0.31.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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.1",
+  "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