@erclx/aitk 3.38.1 → 3.40.0

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

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

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

@@ -89,7 +89,7 @@ Behavior paths carry two spellings, the one a surface authors at and the one it
 - `claude/skills/` and `.claude/skills/`
 - `governance/rules/` and `.claude/rules/`
 - `standards/`, which is the authoring root and reaches a reader by resolution rather than by an install, so it carries no `.claude/` spelling
-- `snippets/` and `.claude/snippets/`
+- `snippets/`, which reaches a session through the `claude/snippets` symlink rather than an install, so it carries no `.claude/` spelling either
 - `internal/` and `tooling/`, which hold the stack references and the seed documents a target is handed
 - `CLAUDE.md` at the repository root, named as a file because a path prefix reaches nothing that sits in no folder
 

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

@@ -35,6 +35,8 @@ Every one of them therefore has to ship inside the skill, the four covering the
 
 The dispatch's return leg is unplaced for the same reason. A reply reaches this session as a message and settles a finding, corrects which session holds which branch, or names a gate a worker's edits pass through, and reading it is the whole of what happens to it. Both sessions then end, so the half that belonged on the pull request never reaches it and the half that belonged on the board is rediscovered by whoever needs it next.
 
+Cost never enters the decision to widen a wave. The rule weighing how many tracks to open measures collision and review attention, and both describe what a worker writes rather than what the loop spends. Claude Code delivers a message from another session as a fresh turn carrying the whole accumulated context, and a recurring poll bills that same window on its own interval, so a wave's spend tracks this session's context rather than the work coming back. The one setting that bounds it reads as available to whoever finds it, and the two values that would bound it break the handback the loop runs on.
+
 The session also records nothing of what it learns. Both other callers of memory capture are ship-chain skills and this one never ships, so the session taking every operator correction is the session with no moment that writes one down. Hanging that moment on the merge sweep answers it and bills the operator a capture pass per batch of merges while nothing is being built, which is a cost paid on the days shipping is fastest.
 
 ## Must
@@ -43,6 +45,7 @@ The session also records nothing of what it learns. Both other callers of memory
 - Report the state of play so the human knows what to launch, what to review, and what to merge
 - Verify a plan against the tree before handing it over, counting the sites it claims and opening the files it describes
 - List a candidate's file set against every track in flight, and serialize when the sets are not disjoint
+- State what a wave costs in inbound turns beside the collision rule, and name the control that bounds it together with the reason it stays unset, since a lever recorded without its conclusion reads as available to set
 - Place every finding a merged pull request produced against the surface that owns it
 - Place what the return leg carries by what it changes, sending an answer that settles a finding onto the pull request and one that corrects this session's model of the world to the task owning that surface, since neither becomes a record by being read
 - Keep one planned, non-conflicting task in reserve beyond what is running

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

@@ -200,6 +200,21 @@ properly and stop when you cannot. An operator can also cap this session's
 workers by saying so, and a spoken cap binds for that session rather than
 standing as a number in a file.
 
+Inbound turns are the third input to that judgment. Claude Code delivers a
+message from another session as a new turn whenever this one sits idle, and the
+turn carries the whole accumulated context rather than the few lines the worker
+sent, so one handback from a wide wave costs more than the same handback from a
+narrow one. A recurring review poll bills that window again on every interval it
+fires. Weigh the spend before widening, since it lands on this session's context
+and never on the worker's.
+
+`crossSessionInbound` is the control, on an `accept`, `hold`, `refuse` ladder,
+and it is recorded here as deliberately not pulled. `hold` and `refuse` are the
+two values that bound the cost, and both break the handback this loop runs on,
+since a held message reaches nobody until a later `accept` applies and a refused
+one is dropped outright. `accept` bounds nothing. Read the ladder before turning
+concurrency up rather than after, and leave it unset.
+
 Serialize any track that touches a shared wiring seam with another in flight, and
 serialize one whose sets are disjoint when a stated reason still puts it behind
 another, since two tracks interact in ways no file-set comparison reads. One

package/docs/agents/commands.md

@@ -49,8 +49,8 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                                       |
 | `aitk standards audit`     | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)                                |
 | `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)                            |
-| `aitk claude skills reach` | Report the shipped bodies citing a toolkit path no target project receives, exiting 2 on an unqualified one                                                          |
-| `aitk claude skills rank`  | Score the shipped catalog's descriptions against a hand-authored case corpus by TF-IDF cosine similarity, reporting rank-one and top-three                           |
+| `aitk claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                           |
+| `aitk claude skills rank`  | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                      |
 | `aitk claude routing`      | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                                       |
 | `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                              |
 | `aitk gov superseded`      | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)                                                   |

package/docs/agents/counts.md

@@ -37,7 +37,7 @@ The set is closed rather than derived, so widening it is a deliberate change to
 
 A sentence has to carry an assertion verb (`loads`, `ships`, `carries`, `holds`, `counts`, `totals`, `documents`, `declares`, `installs`, `lists`, `contains`, `comprises`, `authors`), the quantifier `all`, or an article (`the`, `a`, `an`) immediately ahead of the number, which is immediately ahead of the catalog noun, with one optional qualifying word between the number and the noun (`sixty-one shipped skills`). The number reads either as digits or as a spelled-out cardinal through ninety-nine, since this corpus states a catalog size in words as often as in digits.
 
-Nothing stands between the trigger and the number, which is the rule an author writing a new count has to know. It separates `the toolkit authors 69 rules` and `took all 69 rules`, both read, from `a domain of 55 skills` and `denominator of sixty-one shipped skills`, neither of them read. A figure meant as a past state takes a date in the same sentence instead, which reads the sentence past whatever its shape.
+Nothing stands between the trigger and the number, which is the rule an author writing a new count has to know. It separates `the toolkit authors 70 rules` and `took all 70 rules`, both read, from `a domain of 55 skills` and `denominator of sixty-one shipped skills`, neither of them read. A figure meant as a past state takes a date in the same sentence instead, which reads the sentence past whatever its shape.
 
 ## How the trigger set grew
 
@@ -45,7 +45,7 @@ The verb gate is not the first design tried. A bare number next to a catalog nou
 
 The article half was added after a first review of the shipped design found a live miss: `.claude/context/development/gates.md` stated a stale audit total while the tree held 20, and the verb gate never reached it, since that sentence puts its verb after the noun rather than ahead of the number. Widening the trigger set to admit an article ahead of the number closed that gap.
 
-The quantifier `all` and the verb `authors` joined on the same evidence, two more live misses failing only the trigger test. Allowing words to stand between the trigger and the number was the other candidate, measured and declined: at widths of one, two, and three it reached 77, 104, and 132 sentences against a baseline of 65, missed `took all 69 rules` at every width, and reached `the toolkit authors 69 rules` only at a width admitting the indirect-noun shape below. The two words reach both at 75 sentences and no false positive.
+The quantifier `all` and the verb `authors` joined on the same evidence, two more live misses failing only the trigger test. Allowing words to stand between the trigger and the number was the other candidate, measured and declined: at widths of one, two, and three it reached 77, 104, and 132 sentences against a baseline of 65, missed `took all 70 rules` at every width, and reached `the toolkit authors 70 rules` only at a width admitting the indirect-noun shape below. The two words reach both at 75 sentences and no false positive.
 
 ## The plausibility filter
 
@@ -59,7 +59,7 @@ The article gate is looser than the verb list and carries a real cost. Re-runnin
 
 A delta phrased as a transition (`from fourteen to fifteen`), a fraction (`thirteen of sixteen`), and a total reached through an indirect noun (`denominator of sixty-one shipped skills`) are all catalog-size claims this corpus carries, and none matches the trigger shape this reads. Each stays a known gap. The false-positive rate that gated closing them has a measurement behind it now, and what it showed is that the widening these three need is the one that costs a false positive rather than the one that does not.
 
-A second figure in a sentence whose first figure already matched is a fourth gap and a structural one, since one match is taken per catalog per sentence. `authors 69 rules under governance/rules/ and consumes 54 into .claude/rules/` is read for its 69 alone, which is correct here because the two figures name different populations, and a sentence stating one catalog twice would go unread the same way.
+A second figure in a sentence whose first figure already matched is a fourth gap and a structural one, since one match is taken per catalog per sentence. `authors 70 rules under governance/rules/ and consumes 55 into .claude/rules/` is read for its 70 alone, which is correct here because the two figures name different populations, and a sentence stating one catalog twice would go unread the same way.
 
 A calendar date (`2026-08-21`) or a backticked commit reference in the same sentence reads the whole sentence past, since that is how this corpus already marks a figure as a historical record rather than a live claim. `.claude/ARCHITECTURE.md` and the context entries carry a figure this way deliberately, and every one of them stays correct forever.
 

package/docs/agents/index.md

@@ -32,7 +32,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
-- [Citation reach](skills-reach.md): Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
+- [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 - [Standard success criteria](standards-audit.md): Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates

package/docs/agents/skills-reach.md

@@ -1,21 +1,26 @@
 ---
 title: Citation reach
-description: Reporting the shipped skill bodies that cite a path no target project receives, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
+description: Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
 ---
 
 # Citation reach
 
-`aitk claude skills reach [path]` reports every shipped skill body citing a path that exists in the toolkit and reaches no target project. It reads and reports. Repairing what it finds is separate work.
+`aitk claude skills reach [path]` reports every skill body citing a path that exists in the project and reaches no reader elsewhere. It reads and reports. Repairing what it finds is separate work.
 
 ```bash
 aitk claude skills reach
 aitk claude skills reach --json
+aitk claude skills reach ~/repos/my-project
 ```
 
 | Option   | Behavior                                                   |
 | -------- | ---------------------------------------------------------- |
 | `--json` | Add a machine-readable record on stdout, keeping the frame |
 
+## Which corpus it reads
+
+`claude/skills/` when the project holds it, and `.claude/skills/` otherwise. The shipped tree wins where both are present, so a toolkit reads what it ships and a project holding only its own skills is measured rather than refused. Every report names the corpus it read on its `Corpus` line and carries it as `corpus` in the `--json` record.
+
 ## The defect it reads for
 
 A plugin skill installs into a project and the toolkit's own tree is not there. A body naming `.claude/context/transcripts.md` resolves for a session running in this repository and sends every other reader to nothing, and no stage asked the question until this one. The shape is wider than one folder: a seed naming a standard with no route and a machine-readable field naming a toolkit-only path are the same claim, true here and false in a target.
@@ -38,6 +43,8 @@ A cited path counts when it sits under an authoring root no install channel deli
 
 `src/`, `scripts/`, and bare `docs/` are deliberately outside the list. A body naming one of those is describing the reader's own tree, so listing them reports a correct citation on every run and buries the finding under the pass.
 
+`.claude/context/` joins them when the corpus read is a project's own. A seed put those entries there and the project owns them afterward, so a body under `.claude/skills/` naming one points at a file its reader holds. The seed disowning below cannot answer that in a project, since it reads a `tooling/` tree only the toolkit carries.
+
 A path a seed installs is disowned twice, under its own name and under the folder spelling it takes once a project splits the entry. A domain that outgrows one file becomes `<domain>/`, which is still the entry the seed delivered, so reporting the split form would fail a project for growing.
 
 ## The qualifier
@@ -52,6 +59,6 @@ A line mentioning the toolkit for an unrelated reason exempts a citation on it.
 
 ## Exit codes
 
-Exit codes are `0` when every citation names its owner, `1` for a refusal, and `2` when at least one is unqualified. The refusal is a tree carrying no `claude/skills/`, which ships no plugin body to measure, and it reports the reason rather than a clean count over nothing.
+Exit codes are `0` when every citation names its owner, `1` for a refusal, and `2` when at least one is unqualified. The refusal is a tree carrying neither `claude/skills/` nor `.claude/skills/`, which holds no skill body to measure, and it reports the reason rather than a clean count over nothing.
 
 The verb reports rather than gates. A toolkit-scoped instruction is sometimes meant for a session in this repository, so failing a push on one would make the check something to route around. `aitk audits run` registers it with no gating exit for the same reason, and carries `unqualifiedCitations` as its retained count.

package/docs/ai-workflow.md

@@ -138,7 +138,7 @@ For features on a mature stack, chain the post-plan pipeline in one session. App
 
 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.
+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 and rules in both the authoring and the installed spelling, so the list matches whether a repository authors those surfaces or consumed them from the toolkit. Standards, snippets, `internal/`, and `tooling/` carry the authoring spelling alone, since none of the four reaches a session through a `.claude/` copy, and root `CLAUDE.md` is named as a file because a path prefix reaches nothing sitting in no folder.
 
 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.
 

package/docs/operating-model.md

@@ -154,6 +154,14 @@ above it, and stop adding once you can no longer review every output properly.
 Serialize a track sharing a wiring seam with another, and serialize one whose
 sets are disjoint when a stated reason still puts it behind another.
 
+Inbound turns cost the controlling session as well, so weigh the spend before
+widening. A message from one of your other sessions arrives as a new turn
+carrying the whole accumulated context, and a recurring poll bills that window
+again on its own interval, which means a wide wave spends against the
+orchestrator rather than against any worker. `crossSessionInbound` is the one
+control over that and stays unset here, since `hold` and `refuse` both break the
+worker handback and `accept` bounds nothing.
+
 Unit checks run freely in many worktrees at once.
 A dev server, an end-to-end run, and a screenshot run alongside each other on a
 web stack, since every worktree derives its own port. Singleton resources (one

package/governance/rules/claude/576-settings.md

@@ -0,0 +1,14 @@
+---
+description: State the autoContinueAtUsageLimit inversion and the autoCompactWindow cap for .claude/settings.json and its seeded copy
+paths:
+  - '.claude/settings.json'
+  - 'tooling/claude/seeds/.claude/settings.json'
+---
+
+# Settings standards
+
+## Session budget settings
+
+- Never set `autoContinueAtUsageLimit` in this file. Its scope is user or managed, and a repository file setting it while no user, `--settings`, or managed value does makes Claude Code read the setting as off, so writing `true` here turns the behavior off for every operator carrying no value of their own.
+- Treat `autoCompactWindow` as capped at the model's own context window. A value above that cap is inert on a session running a smaller window and bites only on one running the larger, so name the window a recorded value is meant for.
+- Record why a session budget setting is left unset in the project's own development notes rather than in this file. JSON carries no pointer, so a session reading the settings file alone concludes the setting is unconfigured and sets it again.

package/package.json

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

package/scripts/core/regen-claude-copies.sh

@@ -5,30 +5,6 @@ set -o pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
-mirror_dir() {
-  local src="$1"
-  local dest="$2"
-  local find_args=("${@:3}")
-
-  rm -rf "$dest"
-  while IFS= read -r file; do
-    local rel="${file#"$src"/}"
-    mkdir -p "$dest/$(dirname "$rel")"
-    cp "$file" "$dest/$rel"
-  done < <(find "$src" -type f "${find_args[@]}" | sort)
-}
-
-mirror_dir "$PROJECT_ROOT/snippets" "$PROJECT_ROOT/.claude/snippets" -name "*.md"
-
-# `internal/` is the surface the plugin does not symlink. Mirrored on its own so
-# toolkit sessions read it at a `.claude/` path like every other consumed copy.
-# `internal/rules/` is excluded because it lands in `.claude/rules/` below, and
-# mirroring it here too would publish each rule at a second inert path. The
-# exclusion is anchored to that one folder, since an unanchored `*/rules/*` would
-# also drop a later `internal/standards/rules/` and report nothing for it.
-mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md" -not -path "$PROJECT_ROOT/internal/rules/*"
-
 # `.claude/rules/` is a subset rather than a mirror, so it resolves through the
-# stack machinery instead of a fourth `mirror_dir` call. The record naming the
-# subset is `internal/governance.toml`.
+# stack machinery. The record naming the subset is `internal/governance.toml`.
 bun "$PROJECT_ROOT/src/cli.ts" gov regen --root "$PROJECT_ROOT"

package/scripts/core/verify.sh

@@ -261,7 +261,7 @@ main() {
 
   log_step "Consumed copies"
   run_check "bash $PROJECT_ROOT/scripts/core/regen-claude-copies.sh" "Consumed-copy regen failed"
-  assert_no_drift ".claude/snippets .claude/internal .claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/snippets, .claude/internal, and .claude/rules."
+  assert_no_drift ".claude/rules" "Consumed copies drifted. Run bun run check and commit .claude/rules."
   log_info "Consumed copies clean"
 
   # Only the HTML is asserted. The PNG beside it is a chromium render whose bytes

package/src/audits/catalog.ts

@@ -530,10 +530,11 @@ export const AUDITS: readonly AuditSpec[] = [
     // The one reason this verb refuses for, and it is an absence rather than a
     // break. A tracked corpus normally allows nothing, since a tree that ships
     // to targets and cannot be found is a broken checkout, and this is the
-    // second exception on the same test the secret scan takes: no target holds
-    // `claude/skills/`, so without the allowance every project installing this
-    // CLI reports the verb unmeasured on every run and never changes, which is
-    // the permanent signal the per-machine allowance exists against.
+    // second exception on the same test the secret scan takes: a project
+    // carrying neither `claude/skills/` nor `.claude/skills/` has adopted no
+    // skill convention, so without the allowance it reports the verb
+    // unmeasured on every run and never changes, which is the permanent signal
+    // the per-machine allowance exists against.
     absentReasons: ['no-skills'] satisfies ReachRefusal[],
     counts: reachCounts,
   },
@@ -547,9 +548,11 @@ export const AUDITS: readonly AuditSpec[] = [
     // moved rank would teach a contributor to route around the stage.
     gatingExits: [],
     corpus: 'tracked',
-    // The one reason this verb refuses for, and it is an absence for the same
-    // reason the reach check's is: a project carrying no `claude/skills/` has
-    // adopted no skill convention this audit reads.
+    // The one reason this run refuses for, and it is an absence for the same
+    // reason the reach check's is: a project carrying neither `claude/skills/`
+    // nor `.claude/skills/` has adopted no skill convention this audit reads.
+    // The two case-corpus refusals never reach here, since they need `--cases`
+    // and this argv passes none.
     absentReasons: ['no-skills'] satisfies RankRefusal[],
     counts: rankCounts,
   },

package/src/claude/skills-audit.ts

@@ -43,6 +43,12 @@ export interface SkillFinding {
 }
 
 export interface CorpusReport {
+  /**
+   * Left as `join` produced it, where `SkillsCorpus.rel` in `skills-list.ts`
+   * normalizes the same spelling to POSIX. This one is an existing JSON field
+   * a caller already reads, so the split holds until a branch reading this verb
+   * is the one to close it.
+   */
   readonly rel: string
   readonly skills: number
 }

package/src/claude/skills-list.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { CORPORA } from '@/claude/skills-audit'
 
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/
 
@@ -9,6 +10,38 @@ export interface SkillListing {
   readonly requirement: boolean
 }
 
+export interface SkillsCorpus {
+  /**
+   * The corpus spelling in POSIX form, so a report reads the same on Windows.
+   * `CorpusReport.rel` in `skills-audit.ts` is the same spelling left as `join`
+   * produced it, so the two verbs disagree there. Normalizing it is a contract
+   * change on an existing JSON field and belongs to a branch reading the audit.
+   */
+  readonly rel: string
+  /** The folder a listing reads, absolute against the root it was resolved at. */
+  readonly dir: string
+}
+
+/**
+ * The skill corpus a measure reads at a given root: the shipped tree in this
+ * repository and a target's own `.claude/skills/` in a project that consumes
+ * it. `CORPORA` order settles a tree carrying both, so every reading taken
+ * here still comes from `claude/skills/`.
+ *
+ * Kept apart from `listSkills` deliberately. `src/counts/catalogs.ts` counts
+ * the shipped catalog through that function, so teaching it to read both
+ * corpora would move the reported total off the tree that installs and
+ * falsify every sentence in the corpus stating it.
+ */
+export function resolveSkillsCorpus(root: string): SkillsCorpus | undefined {
+  for (const rel of CORPORA) {
+    const dir = join(root, rel)
+    if (existsSync(dir)) return { rel: rel.replaceAll('\\', '/'), dir }
+  }
+
+  return undefined
+}
+
 /**
  * Enumerates the plugin skill catalog, which is the corpus under `claude/`
  * rather than the internal skills under `.claude/`. Only the former installs
@@ -22,7 +55,14 @@ export interface SkillListing {
  * `aitk claude skills audit` is what fails on it, across both corpora.
  */
 export function listSkills(root: string): SkillListing[] {
-  const skillsRoot = join(root, 'claude', 'skills')
+  return listSkillsAt(join(root, 'claude', 'skills'))
+}
+
+/**
+ * The same enumeration against a corpus folder the caller already resolved,
+ * which is what `resolveSkillsCorpus` hands a measure that reaches a target.
+ */
+export function listSkillsAt(skillsRoot: string): SkillListing[] {
   if (!existsSync(skillsRoot)) return []
 
   const paths = [

package/src/claude/skills-rank.ts

@@ -1,6 +1,5 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { listSkills } from '@/claude/skills-list'
+import { existsSync, readFileSync } from 'node:fs'
+import { listSkillsAt, resolveSkillsCorpus } from '@/claude/skills-list'
 
 /**
  * Whether a prompt reaches the right skill, measured by TF-IDF cosine
@@ -14,8 +13,6 @@ import { listSkills } from '@/claude/skills-list'
  * tracks on a cadence.
  */
 
-const SKILLS_DIR = join('claude', 'skills')
-
 const STOP = new Set(
   'a about after again all also and any are as at be before but by can do does for from has have help how in into is it its just make not of on or our so that the then there these this to use used uses using want was what when where which who why with you your run'.split(
     ' ',
@@ -44,11 +41,25 @@ export interface Miss {
 }
 
 /** Why a measure produced no reading, which is never the same as a clean one. */
-export type RankRefusal = 'no-skills'
+export type RankRefusal = 'no-skills' | 'no-cases' | 'bad-cases'
+
+/** The refusals a case corpus read produces, which the scan itself cannot raise. */
+export type CaseCorpusRefusal = Extract<RankRefusal, 'no-cases' | 'bad-cases'>
+
+export type CaseCorpusReport =
+  | { readonly kind: 'cases'; readonly cases: readonly SkillCase[] }
+  | {
+      readonly kind: 'refused'
+      readonly reason: CaseCorpusRefusal
+      /** What the caller has to change, which the reason alone never says. */
+      readonly detail: string
+    }
 
 export type RankReport =
   | {
       readonly kind: 'measured'
+      /** The corpus spelling measured, since a root can carry either one. */
+      readonly corpus: string
       readonly skills: number
       readonly cases: number
       readonly rank1: number
@@ -59,6 +70,67 @@ export type RankReport =
     }
   | { readonly kind: 'refused'; readonly reason: RankRefusal }
 
+/**
+ * Reads a project's own case corpus, which is JSON in the shape `SKILL_CASES`
+ * already holds. A target authors its own skills and its own vocabulary, so
+ * the toolkit corpus answers a question no other project asked.
+ *
+ * No standard stands behind the shape until a third project needs one, so
+ * every way the file fails is reported with what to change rather than
+ * measured against a spec. An empty array refuses for the reason a missing
+ * file does: a corpus of nothing scores 0 of 0 and reads as a clean pass.
+ */
+export function loadCaseCorpus(path: string): CaseCorpusReport {
+  if (!existsSync(path)) {
+    return { kind: 'refused', reason: 'no-cases', detail: path }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return { kind: 'refused', reason: 'bad-cases', detail }
+  }
+
+  if (!Array.isArray(parsed)) {
+    return {
+      kind: 'refused',
+      reason: 'bad-cases',
+      detail: 'the file holds something other than an array of cases',
+    }
+  }
+
+  const cases: SkillCase[] = []
+  for (const [index, entry] of parsed.entries()) {
+    const record = entry as Record<string, unknown> | null
+    if (
+      typeof record !== 'object' ||
+      record === null ||
+      typeof record.prompt !== 'string' ||
+      typeof record.expect !== 'string'
+    ) {
+      return {
+        kind: 'refused',
+        reason: 'bad-cases',
+        detail: `case ${index} carries no string prompt or expect`,
+      }
+    }
+
+    cases.push({ prompt: record.prompt, expect: record.expect })
+  }
+
+  if (cases.length === 0) {
+    return {
+      kind: 'refused',
+      reason: 'bad-cases',
+      detail: 'the file holds no cases at all',
+    }
+  }
+
+  return { kind: 'cases', cases }
+}
+
 /**
  * Every shipped skill's frontmatter description, read the way a prompt is
  * matched against it: whole, including the quoted trigger phrases it states.
@@ -66,7 +138,13 @@ export type RankReport =
  * and never wins a rank, so it is dropped rather than scored on nothing.
  */
 export function loadCatalog(root: string): RankedSkill[] {
-  return listSkills(root)
+  const corpus = resolveSkillsCorpus(root)
+  return corpus === undefined ? [] : loadCatalogAt(corpus.dir)
+}
+
+/** The same read against a corpus folder the caller already resolved. */
+export function loadCatalogAt(skillsRoot: string): RankedSkill[] {
+  return listSkillsAt(skillsRoot)
     .filter((skill) => skill.description !== '')
     .map((skill) => ({ name: skill.name, description: skill.description }))
 }
@@ -214,22 +292,24 @@ export function measureCases(
 }
 
 /**
- * Reads the shipped catalog off disk and scores it against the given case
- * corpus. Measures the cwd's catalog rather than the toolkit root, matching
- * the reach and audit verbs, so a linked worktree reads its own branch.
+ * Reads whichever skill corpus the root carries and scores it against the
+ * given cases. Measures the cwd's catalog rather than the toolkit root,
+ * matching the reach and audit verbs, so a linked worktree reads its own
+ * branch and a target reads the skills it wrote itself.
  */
 export function scanRank(
   root: string,
   cases: readonly SkillCase[],
 ): RankReport {
-  const skillsRoot = join(root, SKILLS_DIR)
-  if (!existsSync(skillsRoot)) return { kind: 'refused', reason: 'no-skills' }
+  const corpus = resolveSkillsCorpus(root)
+  if (corpus === undefined) return { kind: 'refused', reason: 'no-skills' }
 
-  const catalog = loadCatalog(root)
+  const catalog = loadCatalogAt(corpus.dir)
   const { rank1, top3, misses, unmeasurable } = measureCases(catalog, cases)
 
   return {
     kind: 'measured',
+    corpus: corpus.rel,
     skills: catalog.length,
     cases: cases.length,
     rank1,

package/src/claude/skills-reach.ts

@@ -1,12 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-
-/**
- * The tree that installs into a target. The internal skills under `.claude/`
- * never leave this repository, so a citation there is read by a session that
- * already has the file and cannot be a reach defect.
- */
-const SHIPPED_SKILLS = join('claude', 'skills')
+import { resolveSkillsCorpus } from '@/claude/skills-list'
 
 /**
  * The authoring roots this repository owns and no install channel delivers.
@@ -71,6 +65,8 @@ export type ReachRefusal = 'no-skills'
 export type ReachReport =
   | {
       readonly kind: 'measured'
+      /** The corpus spelling read, since a root can carry either one. */
+      readonly corpus: string
       /** Files opened, so a report can state what the verdict covers. */
       readonly bodies: number
       readonly qualified: readonly Citation[]
@@ -82,6 +78,25 @@ export function isQualified(line: string): boolean {
   return QUALIFIER.test(line)
 }
 
+/**
+ * The roots that belong to the toolkit rather than to the reader, read
+ * against the corpus being measured.
+ *
+ * A target's `.claude/context/` is the reader's own tree. A seed put the
+ * entries there and the project owns them afterward, so a body under
+ * `.claude/skills/` citing one names a file its reader holds. Measuring it
+ * would report a correct citation on every run, which is exactly why `src/`
+ * and `scripts/` are absent from the list above. In this repository the seed
+ * tree settles the same question through `readReceivedPaths`, which a target
+ * carrying no `tooling/` folder cannot answer at all, so the root comes out
+ * by corpus instead.
+ */
+export function authoringRootsFor(corpus: string): readonly string[] {
+  if (!corpus.startsWith('.claude/')) return AUTHORING_ROOTS
+
+  return AUTHORING_ROOTS.filter((root) => !root.startsWith('.claude/'))
+}
+
 /**
  * Every path a seed lands on in a target, spelled the way a body would cite it.
  *
@@ -113,7 +128,11 @@ export function readReceivedPaths(root: string): Set<string> {
  * outgrows one file becomes `<domain>/`, which is still the entry the seed
  * delivered, so reporting the split form would fail a target for growing.
  */
-export function isToolkitOwned(path: string, received: Set<string>): boolean {
+export function isToolkitOwned(
+  path: string,
+  received: Set<string>,
+  roots: readonly string[] = AUTHORING_ROOTS,
+): boolean {
   if (received.has(path)) return false
 
   for (const seeded of received) {
@@ -121,7 +140,7 @@ export function isToolkitOwned(path: string, received: Set<string>): boolean {
     if (stem !== seeded && path.startsWith(`${stem}/`)) return false
   }
 
-  return AUTHORING_ROOTS.some((prefix) => path.startsWith(prefix))
+  return roots.some((prefix) => path.startsWith(prefix))
 }
 
 /**
@@ -135,6 +154,7 @@ export function citationsIn(
   file: string,
   text: string,
   received: Set<string>,
+  roots: readonly string[] = AUTHORING_ROOTS,
 ): Citation[] {
   const citations: Citation[] = []
 
@@ -144,7 +164,7 @@ export function citationsIn(
     for (const match of line.matchAll(TOKEN)) {
       const path = match[1]
       if (!CONCRETE.test(path) || !path.includes('/')) continue
-      if (!isToolkitOwned(path, received)) continue
+      if (!isToolkitOwned(path, received, roots)) continue
 
       citations.push({ file, line: index + 1, path, qualified })
     }
@@ -154,20 +174,27 @@ export function citationsIn(
 }
 
 /**
- * Reads every shipped body for a path its reader cannot open.
+ * Reads every body in the root's skill corpus for a path its reader cannot
+ * open.
  *
  * A citation of a path this repository does not hold is dropped rather than
  * reported. The measure asks whether a claim true here is false in a target,
  * and a path true in neither is a different defect that `aitk context audit`
  * already reports against its own corpus.
+ *
+ * `resolveSkillsCorpus` prefers `claude/skills/`, which is the tree that
+ * installs into a target, so this repository's own reading is the one it
+ * always was. A project carrying `.claude/skills/` alone has no shipped tree
+ * and its own skills are the whole corpus a reader there opens.
  */
 export function scanReach(root: string): ReachReport {
-  const skillsRoot = join(root, SHIPPED_SKILLS)
-  if (!existsSync(skillsRoot)) return { kind: 'refused', reason: 'no-skills' }
+  const corpus = resolveSkillsCorpus(root)
+  if (corpus === undefined) return { kind: 'refused', reason: 'no-skills' }
 
   const received = readReceivedPaths(root)
+  const roots = authoringRootsFor(corpus.rel)
   const files = [
-    ...new Bun.Glob('**/*.md').scanSync({ cwd: skillsRoot, onlyFiles: true }),
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: corpus.dir, onlyFiles: true }),
   ].sort()
 
   const qualified: Citation[] = []
@@ -175,12 +202,13 @@ export function scanReach(root: string): ReachReport {
 
   for (const file of files) {
     const posix = file.replaceAll('\\', '/')
-    const text = readFileSync(join(skillsRoot, file), 'utf8')
+    const text = readFileSync(join(corpus.dir, file), 'utf8')
 
     for (const citation of citationsIn(
-      `${SHIPPED_SKILLS.replaceAll('\\', '/')}/${posix}`,
+      `${corpus.rel}/${posix}`,
       text,
       received,
+      roots,
     )) {
       if (!existsSync(join(root, citation.path))) continue
 
@@ -189,5 +217,11 @@ export function scanReach(root: string): ReachReport {
     }
   }
 
-  return { kind: 'measured', bodies: files.length, qualified, unqualified }
+  return {
+    kind: 'measured',
+    corpus: corpus.rel,
+    bodies: files.length,
+    qualified,
+    unqualified,
+  }
 }

package/src/commands/claude.ts

@@ -36,9 +36,11 @@ import {
 } from '@/claude/skills-reach'
 import { SKILL_CASES } from '@/claude/cases/all'
 import {
+  loadCaseCorpus,
   type RankRefusal,
   type RankReport,
   scanRank,
+  type SkillCase,
 } from '@/claude/skills-rank'
 import {
   planSettings,
@@ -93,6 +95,7 @@ interface SkillsReachOptions {
 
 interface SkillsRankOptions {
   readonly json?: boolean
+  readonly cases?: string
 }
 
 interface RoutingOptions {
@@ -331,8 +334,8 @@ export function register(program: Command): void {
 
   skills
     .command('reach')
-    .description('Report shipped bodies citing a path no target receives')
-    .argument('[path]', 'Repository root, defaulting to the current directory')
+    .description('Report skill bodies citing a path no target receives')
+    .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
@@ -341,10 +344,12 @@ export function register(program: Command): void {
         '',
         'Scope:',
         '  Every markdown file under claude/skills/, which is the tree that',
-        '  installs into a target. A cited path counts when it sits under an',
-        '  authoring root no install channel delivers and this repository',
+        '  installs into a target, or under .claude/skills/ in a project',
+        '  carrying that corpus alone. A cited path counts when it sits under',
+        '  an authoring root no install channel delivers and the project',
         '  holds it. A path under src/, scripts/, or bare docs/ names the',
-        "  reader's own tree and is not measured.",
+        "  reader's own tree and is not measured, and .claude/context/ joins",
+        "  them when the corpus read is a project's own.",
         '',
         'Exit codes:',
         '  0  every citation names the toolkit as the owner',
@@ -358,6 +363,7 @@ export function register(program: Command): void {
         'Examples:',
         '  aitk claude skills reach',
         '  aitk claude skills reach --json',
+        '  aitk claude skills reach ~/repos/my-project',
         '',
       ].join('\n'),
     )
@@ -367,21 +373,33 @@ export function register(program: Command): void {
 
   skills
     .command('rank')
-    .description('Score the shipped catalog against the routing case corpus')
-    .argument('[path]', 'Repository root, defaulting to the current directory')
+    .description('Score a skill catalog against a routing case corpus')
+    .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--cases <path>',
+      "A project's own case corpus as JSON, replacing the toolkit's",
+    )
     .addHelpText(
       'after',
       [
         '',
         'Scope:',
-        '  TF-IDF cosine similarity over every claude/skills/*/SKILL.md',
-        '  frontmatter description, scored against the hand-authored corpus',
-        '  at src/claude/cases/. A necessary condition rather than a report of',
-        '  real routing behavior: it asks whether the descriptions are',
-        '  separable by the words they use, and Claude Code does not route',
-        '  this way.',
+        '  TF-IDF cosine similarity over every SKILL.md frontmatter',
+        '  description under claude/skills/, or under .claude/skills/ in a',
+        '  project carrying that corpus alone, scored against the',
+        '  hand-authored corpus at src/claude/cases/. A necessary condition',
+        '  rather than a report of real routing behavior: it asks whether the',
+        '  descriptions are separable by the words they use, and Claude Code',
+        '  does not route this way.',
+        '',
+        'The case corpus:',
+        '  --cases takes a JSON array of { "prompt", "expect" } objects, the',
+        '  shape src/claude/cases/ already holds, where expect is a skill',
+        "  folder name. A project's own skills need its own prompts, so the",
+        '  toolkit corpus is not a default anything else can measure against.',
+        '  No standard stands behind the file until a third project needs one.',
         '',
         'Exit codes:',
         '  0  the catalog was read, whether or not a case missed rank one',
@@ -394,6 +412,7 @@ export function register(program: Command): void {
         'Examples:',
         '  aitk claude skills rank',
         '  aitk claude skills rank --json',
+        '  aitk claude skills rank ~/repos/my-project --cases cases.json',
         '',
       ].join('\n'),
     )
@@ -794,12 +813,14 @@ function reportRouting(
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':
-    'No claude/skills/ here, so this tree ships no plugin body to measure.',
+    'Neither claude/skills/ nor .claude/skills/ here, so this project carries no skill body to measure.',
 }
 
 /**
  * Measures the cwd rather than the toolkit root, matching the audit and drift
- * verbs, so a linked worktree reads its own branch instead of `main`.
+ * verbs, so a linked worktree reads its own branch instead of `main`, and a
+ * target carrying `.claude/skills/` alone is in scope the way the audit
+ * already has it.
  */
 function runSkillsReach(
   path: string | undefined,
@@ -830,6 +851,7 @@ function runSkillsReach(
     process.stdout.write(
       `${JSON.stringify({
         root,
+        corpus: report.corpus,
         bodies: report.bodies,
         qualified: report.qualified,
         unqualified: report.unqualified,
@@ -848,7 +870,7 @@ function runSkillsReach(
 function reportReach(report: Extract<ReachReport, { kind: 'measured' }>): void {
   logStep('Corpus')
   logInfo(
-    `${plural(report.bodies, 'shipped file')} read, ${plural(report.qualified.length, 'citation')} already naming the toolkit as owner`,
+    `${report.corpus}: ${plural(report.bodies, 'file')} read, ${plural(report.qualified.length, 'citation')} already naming the toolkit as owner`,
   )
 
   logStep('Unqualified citations')
@@ -865,37 +887,44 @@ function reportReach(report: Extract<ReachReport, { kind: 'measured' }>): void {
   )
 }
 
-/** What a reader does about the one way the measure fails to build. */
+/** What a reader does about each way the measure fails to build. */
 const RANK_REFUSALS: Record<RankRefusal, string> = {
   'no-skills':
-    'No claude/skills/ here, so this tree ships no plugin body to measure.',
+    'Neither claude/skills/ nor .claude/skills/ here, so this project carries no skill body to measure.',
+  'no-cases': 'No case corpus at the path given to --cases.',
+  'bad-cases':
+    'The case corpus is not a JSON array of { "prompt", "expect" } objects.',
 }
 
 /**
  * Measures the cwd rather than the toolkit root, matching the reach and audit
- * verbs, so a linked worktree reads its own branch instead of `main`. The
- * case corpus is the toolkit's own, since a target project ships no cases of
- * its own for a catalog it did not author.
+ * verbs, so a linked worktree reads its own branch instead of `main`, and a
+ * target carrying `.claude/skills/` alone is in scope.
+ *
+ * The toolkit's own cases are the default and answer for this catalog alone.
+ * A project measuring its own skills supplies its own prompts through
+ * `--cases`, since a corpus written against skills it did not author scores
+ * vocabulary it never uses.
  */
 function runSkillsRank(
   path: string | undefined,
   opts: SkillsRankOptions,
 ): number {
   const root = resolve(path ?? process.cwd())
-  const report = scanRank(root, SKILL_CASES)
 
-  if (report.kind === 'refused') {
-    frameError(RANK_REFUSALS[report.reason])
-    if (opts.json) {
-      process.stdout.write(
-        `${JSON.stringify({
-          root,
-          reason: report.reason,
-          message: RANK_REFUSALS[report.reason],
-        })}\n`,
-      )
+  let cases: readonly SkillCase[] = SKILL_CASES
+  if (opts.cases !== undefined) {
+    const corpus = loadCaseCorpus(resolve(opts.cases))
+    if (corpus.kind === 'refused') {
+      return refuseRank(root, corpus.reason, corpus.detail, opts)
     }
-    return 1
+    cases = corpus.cases
+  }
+
+  const report = scanRank(root, cases)
+
+  if (report.kind === 'refused') {
+    return refuseRank(root, report.reason, '', opts)
   }
 
   intro('aitk claude skills rank')
@@ -906,6 +935,7 @@ function runSkillsRank(
     process.stdout.write(
       `${JSON.stringify({
         root,
+        corpus: report.corpus,
         skills: report.skills,
         cases: report.cases,
         rank1: report.rank1,
@@ -919,6 +949,28 @@ function runSkillsRank(
   return 0
 }
 
+/**
+ * Carries the detail beside the reason, since three refusals share one verb
+ * and only one of them names a path the caller can correct without it.
+ */
+function refuseRank(
+  root: string,
+  reason: RankRefusal,
+  detail: string,
+  opts: SkillsRankOptions,
+): number {
+  const message = RANK_REFUSALS[reason]
+  frameError(detail === '' ? message : `${message} ${detail}`)
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason, message, detail })}\n`,
+    )
+  }
+
+  return 1
+}
+
 /**
  * States the corpus and both counts on every run, including a clean one. A
  * miss list alone reads as a verdict on the catalog unless the run also says
@@ -927,7 +979,7 @@ function runSkillsRank(
 function reportRank(report: Extract<RankReport, { kind: 'measured' }>): void {
   logStep('Corpus')
   logInfo(
-    `${plural(report.skills, 'skill')} scored against ${plural(report.cases, 'case')}`,
+    `${report.corpus}: ${plural(report.skills, 'skill')} scored against ${plural(report.cases, 'case')}`,
   )
 
   logStep('Score')

package/src/commands/gov.ts

@@ -774,9 +774,9 @@ function runList(opts: ListOptions): number {
 }
 
 /**
- * Silent on success so the consumed-copy stage that calls it stays as quiet as
- * the three `mirror_dir` lines it sits beside. The installed set is readable on
- * disk, so printing it would only add noise to every `bun run check`.
+ * Silent on success so the consumed-copy stage that calls it stays quiet. It is
+ * the only work that stage does now. The installed set is readable on disk, so
+ * printing it would only add noise to every `bun run check`.
  */
 async function runRegen(opts: RegenOptions): Promise<number> {
   const result = await regenConsumedRules(resolve(opts.root ?? PROJECT_ROOT))

package/standards/skill.md

@@ -91,7 +91,7 @@ allowed-tools: <tools required>
 
 - Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `EVAL.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
 - Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
-- `EVAL.md` holds prompts and a judging rubric a person runs by hand, so a skill carrying one needs no runner beside it
+- `EVAL.md` holds prompts and a judging rubric a person runs by hand, which is the path open to everyone. `claude plugin eval` is the automated one and it is gated in early access, refusing before it parses a target, so write the hand-run rubric and know that the runner exists rather than that it does not
 - `SKILL.md` must start with YAML frontmatter between `---` delimiters
 - No `README.md` inside the skill folder
 - No spaces, capitals, or underscores in folder or skill name

package/standards/snippets.md

@@ -33,8 +33,7 @@ Overlapping a skill that does the same job is not disqualifying on its own. A sn
 ## Invocation channels
 
 - Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
-- Claude Code terminal: prefix the install path with `@` (e.g. `@.claude/snippets/claude/feature`)
-- Snippets install preserving the source folder structure. A snippet at `claude/edit.md` installs as `.claude/snippets/claude/edit.md` and is invoked as `@.claude/snippets/claude/edit`
+- Claude Code terminal: prefix the plugin path with `@` (e.g. `@claude/snippets/claude/feature-recap`). `claude/snippets` is a symlink to the authoring root, so the folder a snippet is written in is the folder it is invoked from
 
 ## Use patterns