@erclx/aitk 3.39.0 → 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.39.0",
+  "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/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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.39.0",
+  "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