simt-dev 0.1.1 → 0.2.1

package/src/commands/init.mjs

@@ -11,7 +11,7 @@
 //   2. scan for conflicts  does it contradict a ruling
 //   3. block on conflicts  unless --accept-conflicts
 //   4. plan everything     manifest + region, dry
-//   5. branch and tag      a named escape hatch, before the first write
+//   5. branch and tag      an opt-in escape hatch (--backup), before the first write
 //   6. write               only with --yes
 // Never commits, never pushes (ADR-001).
 
@@ -29,12 +29,22 @@ import { readHooksState } from '../compare/hooksstate.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOWS_DIR } from '../ci/workflow.mjs';
 import { planDependabot, renderDependabot } from '../ci/dependabot.mjs';
 import { planTsconfigBase, renderTsconfigBase, TSCONFIG_BASE_FILE } from '../tsconfig.mjs';
+import {
+  IDENTITY_FILE,
+  INCLUDE_KEY,
+  ignoreIdentity,
+  includeOwnIdentity,
+  includesOwnIdentity,
+  renderIdentityFile,
+  resolveIdentity,
+} from '../identity.mjs';
 import { pointerState, pointerTargets } from '../projection/project.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { plan, provenanceDigest, PRIMARY_TARGET, LOCAL_PROFILE_DIR } from '../projection/project.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
+import { packageVersion, hasNpm } from '../package-version.mjs';
 
 const run = promisify(execFile);
 
@@ -50,6 +60,11 @@ export async function initCommand(positional, flags) {
   }
 
   const sha = await provenanceDigest();
+  // The release this adoption records, and the kind of repository it is adopting: the
+  // version goes into the manifest pin and the rendered gate, and the kind decides how
+  // a repository without node_modules obtains the binary in CI.
+  const version = packageVersion();
+  const npm = await hasNpm(root);
   const existing = await readManifest(root);
   const { manifest: current, exists, error } = existing;
   if (error) {
@@ -58,11 +73,15 @@ export async function initCommand(positional, flags) {
 
   // What this repo can demonstrably run, not what its stack suggests. Without this the
   // stack table proposes gates the repo has no way to execute — the adoption of
-  // simt-social-media declared five and could run two, which would have blocked every
+  // a repository declared five and could run two, which would have blocked every
   // commit once hooks were installed.
   const capability = await readCapability(root);
-  const { dropped } = planGates(detected.stack, capability);
-  const manifest = buildManifest({ root, stack: detected.stack, sha, existing: current, capability });
+  // `facts` carries the ecosystem rows (has-cargo-toml, ...) — the same signal set that
+  // selects this repo's profiles, so one marker file reaches both the region the reader
+  // gets and the gates its commits run. Without it the ecosystem rows never fire here
+  // and a fresh Rust repo is adopted with gates it cannot run.
+  const { dropped, commands } = planGates(detected.stack, capability, detected.facts);
+  const manifest = buildManifest({ root, stack: detected.stack, sha, version, existing: current, capability, facts: detected.facts });
   const findings = await scanRepo(root);
   const summary = summarise(findings);
   const projected = await plan(root, flags);
@@ -98,6 +117,26 @@ export async function initCommand(positional, flags) {
   const ci = await planWorkflow(root);
   const dependabot = await planDependabot(root);
   const tsconfigBase = await planTsconfigBase(root);
+  // Per-developer, and planned with the rest so the operator sees it in the same
+  // preview that lists everything else. `exists` short-circuits the write: a
+  // repository that already has one keeps it exactly as it is.
+  const identity = await resolveIdentity(root);
+  const identityPlan = {
+    file: IDENTITY_FILE,
+    action: identity.exists ? 'unchanged' : identity.from === null ? 'skip' : 'created',
+    from: identity.from,
+    name: identity.name,
+    email: identity.email,
+    reason: identity.exists
+      ? `${IDENTITY_FILE} already exists and is left exactly as it is`
+      : identity.from === null
+        ? 'no identity is configured anywhere, and this tool does not invent one'
+        : null,
+    // Only worth fixing when this repository is the one being routed: an include
+    // pointing at another repository's identity file works here and breaks for the
+    // next person who clones without that sibling checkout.
+    include: await includesOwnIdentity(root),
+  };
 
   const payload = {
     ok: summary.conflicts === 0 || flags.acceptConflicts === true,
@@ -112,11 +151,18 @@ export async function initCommand(positional, flags) {
     // adoption: an existing manifest keeps its gates on purpose, so its drops would
     // describe proposals that were never made.
     droppedGates: exists ? [] : dropped,
+    // Commands a FRESH manifest declares under gates.commands. The plan must show them:
+    // a command that lands in the manifest without appearing here is a silent write,
+    // and the reader would approve it by reading the diff afterwards — the review step
+    // this tool exists to make unnecessary. On an existing manifest nothing is seeded
+    // (the repo's declaration owns that field), so the empty list is deliberate.
+    seededCommands: exists ? [] : Object.entries(commands).map(([gate, command]) => ({ gate, command })),
     surfaces: projected.surfaces,
     surfaceSource: projected.surfaceSource,
     pointers: pointerPlan.map((p) => ({ file: p.file, to: p.to, readers: p.readers, state: p.state })),
     pointersBlocked: pointerBlocked,
     ci: { file: ci.file, action: ci.action, bytes: ci.bytes, own: ci.own, reason: ci.reason },
+    identity: identityPlan,
     dependabot: {
       file: dependabot.file,
       action: dependabot.action,
@@ -163,6 +209,24 @@ export async function initCommand(positional, flags) {
     git: null,
   };
 
+  // A surface this build does not know cannot be written to. Checked before the rule
+  // branch, and named for what it is: `init --surfaces` accepts a list, a reader
+  // mistypes one, and the misspelling used to be reported as an unprojectable rule with
+  // a remedy about substitution keys — the one problem on this path that had no
+  // substitution keys anywhere near it.
+  const surfaceProblems = projected.surfaceProblems ?? [];
+  if (surfaceProblems.length > 0) {
+    payload.ok = false;
+    payload.blockedBy = 'surface-problem';
+    for (const p of surfaceProblems) note(`PROBLEM  ${p}`);
+    if (isJson(flags)) emit(`${JSON.stringify(payload, null, 2)}\n`);
+    return fail(
+      `${surfaceProblems.length} surface(s) cannot be resolved (${surfaceProblems[0]})`,
+      EXIT.FAIL,
+      `pass a known surface id to --surfaces, or omit it to take the default`,
+    );
+  }
+
   // A `.mdc` rule that cannot render is a defect in this build. Adopting a repo
   // without it would leave the family half-retired, and the user would have no way
   // to tell which half from the diff.
@@ -187,7 +251,7 @@ export async function initCommand(positional, flags) {
     if (isJson(flags)) {
       emit(`${JSON.stringify(payload, null, 2)}\n`);
     } else {
-      emit(render(payload, manifest));
+      emit(render(payload, manifest, { npm, version }));
       note('');
       note(
         `blocked  ${summary.conflicts} conflict${summary.conflicts === 1 ? '' : 's'}; nothing written`,
@@ -208,7 +272,7 @@ export async function initCommand(positional, flags) {
     payload.ok = false;
     payload.blockedBy = 'malformed-region';
     if (isJson(flags)) emit(`${JSON.stringify(payload, null, 2)}\n`);
-    else emit(render(payload, manifest));
+    else emit(render(payload, manifest, { npm, version }));
     return fail(
       `${malformed.length} target(s) have a malformed generated region (${malformed[0].file}: ${malformed[0].reason})`,
       EXIT.FAIL,
@@ -220,7 +284,7 @@ export async function initCommand(positional, flags) {
   if (isJson(flags)) {
     if (!apply) emit(`${JSON.stringify(payload, null, 2)}\n`);
   } else {
-    emit(render(payload, manifest));
+    emit(render(payload, manifest, { npm, version }));
   }
   if (!apply) {
     note('');
@@ -232,13 +296,68 @@ export async function initCommand(positional, flags) {
     return EXIT.OK;
   }
 
-  const git = await establishEscapeHatch(root);
+  // The escape hatch is opt-in (ADR-063): plan 0002 §8.2 item 3 said "always", and the
+  // tool complied, but consumers kept reporting the branch switch as a surprise. The
+  // default now writes in place on the branch the reader already has — `git diff` still
+  // shows the full adoption, and nothing is tagged or branched. `--backup` restores the
+  // tag and the branch for readers who want the named undo path.
+  const git = flags.backup
+    ? await establishEscapeHatch(root)
+    : { branch: null, tag: null, from: null, notes: [] };
   payload.git = git;
   for (const message of git.notes) note(`note     ${message}`);
+  if (!flags.backup) {
+    note(
+      'in place   no backup tag or adopt branch created; the adoption is written on your current branch - git diff shows it and git checkout -- . discards it; re-run with --backup for the tag and the branch',
+    );
+  }
+  // The operations that succeeded, not just the ones that failed.
+  //
+  // With --backup, `init` moves the reader onto a different branch and writes a tag
+  // into their repository. Both were once reported only under `--json`, so the run —
+  // the one almost everybody reads — did not say that the branch under them had
+  // changed. A reader who ran the documented escape hatch and then committed would be
+  // committing to a branch they had not chosen, and nothing in the output told them
+  // that had happened.
+  //
+  // The plan's heading is "Nothing is silent", so whatever the run does to git state —
+  // or deliberately does not — the output names it and the command that undoes it.
+  // `notes` carried the failures because a failure is the kind of thing an operator
+  // notices; a success is not.
+  if (git.tag !== null) {
+    note(`tagged   ${git.tag} at the pre-adoption commit; \`git reset --hard ${git.tag}\` returns this repository to what it was`);
+  }
+  if (git.branch !== null && git.from !== null) {
+    note(`branch   switched to ${git.branch}; ${git.from} is untouched and \`git checkout ${git.from}\` returns to it`);
+  }
 
   await writeManifest(root, manifest);
   note(`wrote    ${MANIFEST_FILE} (${manifestAction})`);
 
+  // Identity last, and for the same reason the gate is written after the manifest:
+  // the things that change what this repository does come first, and the one that
+  // only records who is doing them comes once there is something to be committing.
+  //
+  // Three separate refusals, each of which is the correct answer rather than a
+  // failure to try harder. An existing file is not this tool's to rewrite. An
+  // unconfigured identity is not one to invent - a placeholder is an identity git
+  // would use. And the include is only repointed when it is missing or wrong,
+  // because replacing it when it is already right would be a no-op that reads as
+  // a change.
+  if (payload.identity.action === 'created') {
+    await writeFile(join(root, IDENTITY_FILE), renderIdentityFile(identity));
+    await ignoreIdentity(root);
+    note(`wrote    ${IDENTITY_FILE} (${identity.from === 'last-commit' ? 'from the last commit in this repository' : 'from the identity configured on this machine'}); gitignored, because it is yours and not the repository's`);
+  } else if (payload.identity.action === 'unchanged') {
+    note(`kept     ${IDENTITY_FILE} (${payload.identity.reason})`);
+  } else {
+    note(`skipped  ${IDENTITY_FILE}  ${payload.identity.reason}`);
+  }
+  if (!payload.identity.include) {
+    await includeOwnIdentity(root);
+    note(`set      ${INCLUDE_KEY} = ../${IDENTITY_FILE}  this repository's own identity file`);
+  }
+
   // Written after the manifest so the gate exists in the same adoption that declares
   // what the gates are. Skipped with its reason printed rather than silently: a repo
   // with no `.github/workflows` has no CI surface to attach to, and inventing one
@@ -250,7 +369,7 @@ export async function initCommand(positional, flags) {
   // guaranteed to be misled.
   if (payload.ci.action === 'create') {
     await mkdir(dirname(join(root, payload.ci.file)), { recursive: true });
-    await writeFile(join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own }));
+    await writeFile(join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, version }));
     note(`wrote    ${payload.ci.file} (create; yours to edit from here, simt-dev will not rewrite it)`);
   }
   if (payload.dependabot.action === 'create') {
@@ -369,13 +488,14 @@ async function scanRepo(root) {
 }
 
 /**
- * A named escape hatch before the first write, per plan 0001. Both operations are
- * best-effort: a repo that is not a git repo, or has no commits yet, must still be
+ * The opt-in escape hatch before the first write, taken when --backup is passed
+ * (ADR-063 amended plan 0002 §8.2 item 3 from "always" to on request). Both operations
+ * are best-effort: a repo that is not a git repo, or has no commits yet, must still be
  * adoptable. Failure is reported as a note rather than blocking, because refusing
  * to initialise an unborn repo would be worse than proceeding without a backup.
  */
 async function establishEscapeHatch(root) {
-  const result = { branch: null, tag: null, notes: [] };
+  const result = { branch: null, tag: null, from: null, notes: [] };
   const isRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
   if (!isRepo.ok) {
     result.notes.push('not a git work tree; no backup branch or tag created');
@@ -403,6 +523,10 @@ async function establishEscapeHatch(root) {
 
   const current = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
   if (current.ok && current.stdout.trim() !== ADOPT_BRANCH) {
+    // Recorded rather than re-read by the caller: only this function knows what the
+    // branch was before it moved it, and a second `rev-parse` would answer with the new
+    // value and make every "you were on X" line read as "you were on Y".
+    result.from = current.stdout.trim();
     const branch = await git(root, ['checkout', '-b', ADOPT_BRANCH]);
     if (branch.ok) result.branch = ADOPT_BRANCH;
     else result.notes.push(`could not create branch ${ADOPT_BRANCH}: ${branch.stderr.trim()}`);
@@ -423,7 +547,7 @@ async function git(cwd, args) {
 }
 
 /** Every line is a decision with a reason. Nothing is silent. */
-function render(payload, manifest) {
+function render(payload, manifest, { npm = true, version } = {}) {
   const lines = [
     `repo        ${payload.root}`,
     `stack       ${payload.stack.length > 0 ? payload.stack.join(', ') : '(undetected)'}`,
@@ -444,6 +568,18 @@ function render(payload, manifest) {
       `coverage=${manifest.limits.coverage ?? 'undeclared (ADR-006)'} ` +
       `fileLines=${manifest.limits.fileLines.warn}/${manifest.limits.fileLines.error} (ADR-005)`,
   );
+  // The identity line, with its source named. "Created" is a statement about somebody's
+  // name landing in a file, so where the name came from is not a detail of the line.
+  const id = payload.identity;
+  if (id) {
+    const verb = id.action === 'skip' ? 'skip' : id.action;
+    const detail = id.action === 'unchanged'
+      ? id.reason
+      : id.action === 'skip'
+        ? id.reason
+        : `${id.name} <${id.email}>  from ${id.from === 'last-commit' ? "this repository's last commit" : 'the identity configured on this machine'}`;
+    lines.push(`  ${verb.padEnd(9)} ${id.file}${detail ? `\n            ${detail}` : ''}`);
+  }
   // Every gate the stack suggested and this repo cannot run is named, with the reason.
   // A silently shorter gate list reads as "this repo needs no formatting check", when
   // the truth is "declaring one would block every commit". The remedy is stated because
@@ -452,6 +588,12 @@ function render(payload, manifest) {
     lines.push(`  ${'dropped'.padEnd(9)} gate ${d.gate}: ${d.why}`);
     lines.push(`            remedy: ${d.remedy}`);
   }
+  // A seed is a write, and the same rule as for dropped gates applies: the reader must
+  // see the line or they approve it from the diff afterwards. Naming the manifest field
+  // keeps the line actionable — this is where the reader edits it if the default is wrong.
+  for (const s of payload.seededCommands ?? []) {
+    lines.push(`  ${'seeded'.padEnd(9)} gates.commands["${s.gate}"] = ${s.command}`);
+  }
   lines.push(
     `  ${'profiles'.padEnd(9)} ${LOCAL_PROFILE_DIR}/*.md  ` +
       `repo-local profiles are selected by the same matcher (ADR-013)`,
@@ -494,7 +636,7 @@ function render(payload, manifest) {
   // a reader can tell "this repo does not use GitHub Actions" from "this repo was
   // not offered the gate".
   if (payload.ci.action === 'create') {
-    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own }).length} bytes`);
+    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own, npm, version }).length} bytes`);
     lines.push(
       payload.ci.own
         ? `            this repository is simt-dev's own; ${CLI} ci --yes refreshes this copy when the gate changes`

package/src/commands/rules.mjs

@@ -16,6 +16,7 @@
 
 import { EXIT, emit, fail, isJson } from '../output/index.mjs';
 import { loadRules, select } from '../projection/project.mjs';
+import { loadMdcRules } from '../projection/mdc.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { byId, citations, loadDecisions, redactEstate } from '../decisions/index.mjs';
 import { nearMatches } from '../resolve/near.mjs';
@@ -23,9 +24,18 @@ import { CLI } from '../name.mjs';
 
 const kb = (bytes) => `${(bytes / 1000).toFixed(1)}k`;
 
-/** `simt-applies` is the string "always" for core and an array for profiles. */
+/**
+ * `simt-applies` is the string "always" for core and an array for profiles.
+ *
+ * An opt-in rule has an EMPTY array, and `-` is a true reading of that which answers
+ * none of the questions a reader has. `simt-opt-in` is why it is empty — detection cannot
+ * distinguish a repository with the problem from one without it, so the repository
+ * declares it — and that is the fact worth printing. It only became visible when the
+ * per-surface rules entered this catalogue; before that the rule was not listed at all.
+ */
 function appliesLabel(rule) {
   if (rule.applies === 'always') return 'always';
+  if (rule.optIn === true) return 'opt-in (the repo declares it)';
   if (Array.isArray(rule.applies)) return rule.applies.join(',') || '-';
   return '-';
 }
@@ -38,7 +48,37 @@ function sorted(rules) {
 async function load(root) {
   const rules = await loadRules(root ?? null);
   const broken = rules.filter((r) => r.error);
-  return { rules, broken };
+  return { rules: [...rules, ...(await loadPerSurfaceRules())], broken };
+}
+
+/**
+ * The `.mdc` rules, in the shape this file's three commands print.
+ *
+ * `loadRules` reads `rules/*.md` and `rules/stacks/*.md`, which is every rule that is a
+ * *stack profile* — and the four per-surface rules are not that. They are projected by
+ * `ruleBodies` inside `desiredRegion` rather than by `select`, so they were invisible to
+ * `rules list`, `rules show` and `rules why`: a reader could be told by an agent to run
+ * `simt rules why test-gate` and be met with "no rule with that id", for a rule that was
+ * in their own `AGENTS.md` at the time.
+ *
+ * Deliberately NOT added to `loadRules`. That function's result is `select`ed and
+ * `render`ed into the region, so putting these there would project every one of them
+ * twice — once as a profile section and once as `## Process: <id>` — which is the
+ * duplication ADR-046 exists to prevent. The catalogue is the right layer for this: it is
+ * a view, and a view may be wider than what one projection writes.
+ */
+async function loadPerSurfaceRules() {
+  const mdc = await loadMdcRules();
+  return mdc.map((r) => ({
+    ...r,
+    // These have no `simt-title`; their `description` is what a reader sees in the
+    // generated file, so it is the title here rather than a column of blanks.
+    title: r.title ?? r.description ?? null,
+    // `mdc` rather than `central`: the column exists so a reader can tell where a rule
+    // came from, and "central" is true of all of them and useless for this distinction.
+    origin: 'per-surface',
+    fallback: false,
+  }));
 }
 
 // --- list ---------------------------------------------------------------------
@@ -182,7 +222,7 @@ export async function whyCommand(args, flags) {
   if (!what) return fail('rules why needs a rule id or an ADR id', EXIT.USAGE, `usage: ${CLI} rules why <rule-id|ADR-NNN>`);
 
   const { rules, broken } = await load(flags.root ?? null);
-  const { ok, decisions, errors } = await loadDecisions();
+  const { ok, decisions, errors } = await loadDecisions({ all: flags.all === true });
   if (!ok) return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable for provenance to work');
 
   return what.match(/^ADR-\d{3}$/i)
@@ -342,6 +382,17 @@ async function adrDirection(adr, rules, decisions, flags) {
   if (effective.summary.ruled.length > 0) {
     lines.push('', replacement ? 'ruled now' : 'ruled');
     for (const r of effective.summary.ruled) lines.push(`  - ${redactEstate(r)}`);
+    // The count, because the excerpt above is two rulings and a record may carry eight.
+    // Without it the header reads as a claim about everything the record settled, which
+    // is how a reader goes looking for a ruling that was never printed and concludes it
+    // does not exist.
+    const shown = effective.summary.ruled.length;
+    const total = effective.summary.rulingCount ?? shown;
+    if (total > shown) {
+      lines.push(
+        `  (${shown} of ${total} rulings shown; the rest: ${CLI} rules why ${effective.id} --all)`,
+      );
+    }
   }
   if (effective.summary.rejected.length > 0) {
     // The rejected alternatives are the part a reader cannot reconstruct. A ruling is

package/src/commands/skills.mjs

@@ -3,7 +3,7 @@
 // Implementation sequence steps 4 and 5.
 //
 // Output design (plan 0002 section 6): one fact per line, fixed field order, no
-// wrapping, no colour when piped, bounded by --max-bytes with an explicit
+// wrapping, no ANSI on any stream, bounded by --max-bytes with an explicit
 // TRUNCATED line. The NOT SELECTED block is as important as the resolved block -
 // the agent can see what exists and why it was excluded, and override in one
 // token instead of guessing. Suppressing it is how a discovery tool becomes a
@@ -14,9 +14,10 @@ import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 
 import { EXIT, emit, emitJson, fail, isJson, note as emitNote } from '../output/index.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
 import { locateSource, sourceHeldLocally } from '../resolve/source.mjs';
-import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
+import { unknownSkills, scoreCorpus } from '../resolve/eval.mjs';
+import { PACKAGE_ROOT, resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { tokenize, rankSkills, closure, selectWithinBudget, resolveAlias, scoreSkill, selectionVerdict, stackCompatible } from '../resolve/resolve.mjs';
 import { nearMatches } from '../resolve/near.mjs';
@@ -48,6 +49,22 @@ export function parsePathList(value) {
     .filter(Boolean);
 }
 
+/**
+ * Read a list flag in both the forms this tool ships.
+ *
+ * `--skill` accepts `--skill a --skill b` and `--skill a,b`, and arrives here as an
+ * array in the first case and a string in the second. `String(['a','b'])` happens to
+ * produce `'a,b'`, so the old one-line reader would have kept working by accident — and
+ * would have started throwing the moment a skill name contained the character the
+ * join inserts. Both shapes are handled rather than one being relied upon, because
+ * relying on it is the same class of bug as the one being fixed here.
+ */
+export function listFlag(value) {
+  return (Array.isArray(value) ? value : [value])
+    .flatMap((v) => parsePathList(v))
+    .filter(Boolean);
+}
+
 /** Compact stack label: the tags that actually discriminate, not all of them. */
 function stackLabel(tags = []) {
   const DISCRIMINATING = [
@@ -75,8 +92,8 @@ const kb = (bytes) => `${(bytes / 1000).toFixed(1)}k`;
 // --- tier 0: index ------------------------------------------------------------
 
 export async function indexCommand(args, flags) {
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
   const workspace = await workspaceLine(flags);
 
   if (isJson(flags)) {
@@ -189,8 +206,8 @@ export async function findCommand(args, flags) {
   const query = args.join(' ').trim();
   if (!query) return fail('find needs a query', EXIT.USAGE, `usage: ${CLI} skills find <query>`);
 
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
   const tokens = tokenize(query);
   const workspace = await workspaceLine(flags);
@@ -227,8 +244,8 @@ export async function findCommand(args, flags) {
 // --- brief: tier 1 ------------------------------------------------------------
 
 export async function briefCommand(args, flags) {
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
   const root = flags.root ?? process.cwd();
   const repo = await fingerprint(root);
@@ -237,7 +254,7 @@ export async function briefCommand(args, flags) {
   const repoStack = repo.signals;
   const paths = flags.paths ? parsePathList(flags.paths) : await dirtyPaths(root);
   const taskTokens = tokenize(flags.task ?? '');
-  const forced = parsePathList(flags.skill);
+  const forced = listFlag(flags.skill);
   const budget = flags.budget ?? DEFAULT_BUDGET;
 
   // A brief with no task and no paths resolves on stack alone, which produces a
@@ -432,8 +449,8 @@ export async function showCommand(args, flags) {
   const name = args[0];
   if (!name) return fail('show needs a skill name', EXIT.USAGE, `usage: ${CLI} skills show <name>`);
 
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
   const skill = registry.skills.find((s) => s.name === name);
   if (!skill) {
@@ -490,8 +507,8 @@ export async function whyCommand(args, flags) {
   const name = args[0];
   if (!name) return fail('why needs a skill name', EXIT.USAGE, `usage: ${CLI} skills why <name>`);
 
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
   const skill = registry.skills.find((s) => s.name === name);
   if (!skill) {
@@ -565,6 +582,117 @@ export async function whyCommand(args, flags) {
   return EXIT.OK;
 }
 
+// --- eval ---------------------------------------------------------------------
+
+/**
+ * The gold corpus when the reader names none. A checkout holds one at this fixed path;
+ * `test/` is not in the published files, so an installed copy does not. That absence is
+ * a fact about where this copy runs, reported as such (ADR-061's tiered resolution is
+ * the same shape: explicit path, then the package's own file, then an honest absence).
+ */
+const DEFAULT_CORPUS = join(PACKAGE_ROOT, 'test', 'fixtures', 'eval-corpus.json');
+
+/**
+ * `simt skills eval [corpus]` - measure the resolver against the gold corpus.
+ *
+ * Plan 0002 section 9: "Reports precision and recall and fails on regression." The
+ * corpus states, per case, which skills must come back (`select`) and which must not
+ * (`reject`); a case that names no selection is exhaustive, and anything it returns is
+ * a miss. The exit code rests on `clean`, because the two ratios can both read 1.0
+ * while an exhaustive case returns a skill neither list named (see src/resolve/eval.mjs).
+ */
+export async function evalCommand(positional, flags) {
+  const corpusPath = positional[0] ?? (existsSync(DEFAULT_CORPUS) ? DEFAULT_CORPUS : null);
+
+  if (corpusPath === null) {
+    return fail(
+      `no eval corpus: ${DEFAULT_CORPUS} is not on this machine (test data does not ship in the package)`,
+      EXIT.FAIL,
+      `run: ${CLI} skills eval <path-to-corpus>  (a file of cases with select and reject lists)`,
+    );
+  }
+
+  let corpus;
+  try {
+    corpus = JSON.parse(await readFile(corpusPath, 'utf8'));
+  } catch (error) {
+    return fail(
+      `${corpusPath}: unreadable or invalid JSON (${error.message})`,
+      EXIT.FAIL,
+      `run: ${CLI} skills eval <path-to-corpus>`,
+    );
+  }
+  if (!Array.isArray(corpus.cases) || corpus.cases.length === 0) {
+    return fail(
+      `${corpusPath}: no cases (a corpus is {"cases": [{"name", "repo", "task", "select", "reject"}]})`,
+      EXIT.FAIL,
+      `run: ${CLI} skills eval <path-to-corpus>`,
+    );
+  }
+
+  // The corpus is measured against the registry it cites, so it needs the same
+  // resolution and the same failure as every other skills command.
+  const { registry, errors, ok, path } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
+
+  const unknown = unknownSkills(registry, corpus);
+  const score = scoreCorpus(registry, corpus);
+  const okRun = unknown.length === 0 && score.clean;
+
+  if (isJson(flags)) {
+    emit(
+      `${JSON.stringify(
+        {
+          ok: okRun,
+          command: 'skills eval',
+          corpus: corpusPath,
+          registry: path,
+          cases: score.cases.map((c) => ({
+            name: c.name,
+            selected: c.selected,
+            missing: c.missing,
+            unexpected: c.unexpected,
+          })),
+          unknownSkills: unknown,
+          precision: score.precision,
+          recall: score.recall,
+        },
+        null,
+        2,
+      )}\n`,
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return okRun ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const failed = score.cases.filter((c) => c.missing.length > 0 || c.unexpected.length > 0);
+  const lines = [
+    `corpus    ${corpusPath} (${score.cases.length} cases)`,
+    `registry  ${path}`,
+    `${score.cases.length - failed.length} pass, ${failed.length} fail`,
+    `precision ${score.precision.toFixed(3)}  recall ${score.recall.toFixed(3)}`,
+    '',
+  ];
+
+  for (const c of score.cases) {
+    if (c.missing.length === 0 && c.unexpected.length === 0) {
+      lines.push(`PASS  ${c.name}`);
+      continue;
+    }
+    lines.push(`FAIL  ${c.name}`);
+    for (const name of c.missing) lines.push(`      missed     ${name}`);
+    for (const name of c.unexpected) lines.push(`      unexpected ${name}`);
+  }
+
+  if (unknown.length > 0) {
+    lines.push('', `FAIL  corpus cites skills the registry does not declare: ${unknown.join(', ')}`);
+  }
+
+  lines.push('', okRun ? 'OK the resolver meets the gold corpus' : 'REGRESSION: the resolver no longer meets the gold corpus');
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return okRun ? EXIT.OK : EXIT.FAIL;
+}
+
 // --- bodies -------------------------------------------------------------------
 
 /**
@@ -581,7 +709,7 @@ export async function whyCommand(args, flags) {
  * location for a declared source, matched on bytes rather than on hope (ADR-015).
  * The canonical source is still tried first, so a workspace body always wins.
  */
-export async function sourcePath(skill, workspaceRoot, root) {
+async function sourcePath(skill, workspaceRoot, root) {
   const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
 
   if (canonical) {

package/src/commands/skillsinstall.mjs

@@ -25,7 +25,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 import { EXIT, emit, fail, isJson, note, writeMode } from '../output/index.mjs';
-import { loadRegistry, REGISTRY_PATH, measureSkill } from '../graph/load.mjs';
+import { loadRegistry, measureSkill } from '../graph/load.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { MANIFEST, buildManifest, readManifest, writeManifest } from '../projection/manifest.mjs';
@@ -39,7 +39,7 @@ import { MANIFEST_FILE } from '../name.mjs';
 /**
  * Where skills live in this repo. The estate already has a convention - a
  * canonical directory plus symlink fan-out - and it is not the same directory in
- * every repo (`.agents/skills` in five, `.cursor/skills` in simt-app). So the
+ * every repo (`.agents/skills` in some, `.cursor/skills` in others). So the
  * existing layout is respected and only invented when there is none.
  */
 export function skillsDir(root, entries) {
@@ -59,8 +59,8 @@ export async function installCommand(args, flags) {
     );
   }
 
-  const { registry, errors, ok } = await loadRegistry(REGISTRY_PATH, flags);
-  if (!ok) return fail(errors[0], EXIT.REGISTRY);
+  const { registry, errors, ok } = await loadRegistry(null, flags);
+  if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
   const skill = registry.skills.find((s) => s.name === name);
   if (!skill) {