@erclx/aitk 3.39.0 → 3.41.0

package/src/claude/cases/claude-workflow.ts

@@ -118,6 +118,11 @@ export const CLAUDE_WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Tell me the paint and layout cost of this page right now.',
     expect: 'claude-ux-measure',
   },
+  {
+    prompt:
+      'I am building this branch for another session. What am I on the hook for, and what is off limits?',
+    expect: 'claude-worker',
+  },
   {
     prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
     expect: 'claude-worktree',

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