simt-dev 0.6.3 → 0.7.0

package/src/commands/rules.mjs

@@ -20,7 +20,9 @@ import { EXIT, emit, emitJson, 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 { byId, citations, loadDecisionsCached, redactEstate } from '../decisions/index.mjs';
+import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { decisionsDir } from '../decisions/dir.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { CLI } from '../name.mjs';
 
@@ -175,15 +177,36 @@ function rulesFailure(message, remedy, exitCode) {
   throw Object.assign(new Error(message), { remedy, exitCode });
 }
 
+/**
+ * The merged decision index: the package's shipped records underlay the
+ * repository's own, which win on an id collision (review 0003 Q34).
+ *
+ * Before this, a consumer with its own ADR-001/002 read `rules why core` as
+ * settled by *their* ADR-001 while the package's ADR-003…009 — the ones the
+ * shipped rules actually cite — reported MISSING. The overlay keeps both
+ * visible: every decision carries which layer it came from, so a same-number
+ * collision reads as two records, never as one answer wearing the wrong title.
+ *
+ * @returns {{ok: boolean, decisions: object[], errors: string[], origins: Record<string,'repo'|'package'>}}
+ */
 async function loadDecisionsFor(root, all) {
-  const localDir = root ? join(root, 'docs', 'decisions') : null;
-  const hasLocal = localDir
-    ? (await readdir(localDir).catch(() => [])).some((n) => /^ADR-\d{3,}-.*\.md$/i.test(n))
-    : false;
-  return loadDecisions({
-    all,
-    ...(hasLocal ? { dir: localDir } : {}),
-  });
+  // Q55: one resolution (manifest key, then detection) and the shared cache,
+  // so `rules why` answers from the repository's own records without re-parsing
+  // every record on every call. No root means the package's own records.
+  const pkg = await loadDecisionsCached({ root, dir: DECISIONS_DIR, all });
+  if (!root) return { ...pkg, origins: Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package'])) };
+  const relDir = await decisionsDir(root);
+  const absDir = join(root, relDir);
+  const hasLocal = (await readdir(absDir).catch(() => [])).some((n) => /^ADR-\d{3,}-.*\.md$/i.test(n));
+  if (!hasLocal) return { ...pkg, origins: Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package'])) };
+  const local = await loadDecisionsCached({ root, dir: absDir, all });
+  const merged = new Map(pkg.decisions.map((d) => [d.id, d]));
+  const origins = Object.fromEntries(pkg.decisions.map((d) => [d.id, 'package']));
+  for (const d of local.decisions) {
+    merged.set(d.id, d);
+    origins[d.id] = 'repo';
+  }
+  return { ok: pkg.ok && local.ok, decisions: [...merged.values()], errors: [...pkg.errors, ...local.errors], origins };
 }
 
 /** The catalogue both surfaces answer from: every rule, its decisions, and the selection. */
@@ -217,20 +240,22 @@ export async function rulesWhyFacts(root, what, { all = false } = {}) {
   const { rules } = await load(root);
   if (/^ADR-\d{3,}$/i.test(what)) {
     const id = what.toUpperCase();
-    const { ok, decisions, errors } = await loadDecisionsFor(root, all);
+    const { ok, decisions, errors, origins } = await loadDecisionsFor(root, all);
     if (!ok) {
       rulesFailure(errors[0], 'the decision records must be readable for provenance to work', EXIT.CONFIG);
     }
-    const record = decisions.find((x) => x.id === id);
+    const record = decisions.find((x) => x.id === id) ?? null;
     // Was 'list them with: ls docs/decisions/' - a path relative to simt-dev's own
     // tree, which resolves to nothing in the repo the reader is standing in. The
-    // remedy must be a command they can run.
-    if (!record) rulesFailure(`no decision record ${id}`, `list the known decisions with: ${CLI} rules list`, EXIT.USAGE);
+    // remedy must be a command they can run (Q34: the decisions list, not the
+    // rules list - the reader asked about a decision, not a rule).
+    if (!record) rulesFailure(`no decision record ${id}`, `list the known decisions with: ${CLI} rules decisions`, EXIT.USAGE);
     const replacement = record.supersededBy ? decisions.find((x) => x.id === record.supersededBy) : null;
     return {
       direction: 'decision',
       id,
-      adr: record,
+      adr: { ...record, origin: origins[id] ?? 'package' },
+      origins,
       supersededBy: replacement ? { id: replacement.id, title: replacement.title } : null,
       inForce: replacement
         ? { id: replacement.id, status: replacement.status, summary: replacement.summary }
@@ -247,7 +272,7 @@ export async function rulesWhyFacts(root, what, { all = false } = {}) {
       EXIT.USAGE,
     );
   }
-  const { ok, decisions, errors } = await loadDecisionsFor(root, all);
+  const { ok, decisions, errors, origins } = await loadDecisionsFor(root, all);
   if (!ok) {
     rulesFailure(errors[0], 'the decision records must be readable for provenance to work', EXIT.CONFIG);
   }
@@ -261,9 +286,10 @@ export async function rulesWhyFacts(root, what, { all = false } = {}) {
     title: rule.title ?? null,
     source: rule.source,
     origin: rule.origin,
-    adrs: cited.map((c) => index.get(c) ?? { id: c, missing: true }),
+    adrs: cited.map((c) => (index.has(c) ? { ...index.get(c), origin: origins[c] ?? 'package' } : { id: c, missing: true })),
     uncited: cited.length === 0,
     others: others.map((r) => r.id),
+    origins,
   };
 }
 
@@ -351,10 +377,11 @@ function ruleDirection(facts, flags) {
   lines.push('', `settled by ${facts.adrs.length} decision${facts.adrs.length === 1 ? '' : 's'}`);
   for (const d of facts.adrs) {
     if (d.missing) {
-      lines.push(`  ${d.id}  MISSING - the rule cites it, but this installation has no record of it`);
+      lines.push(`  ${d.id}  MISSING - the rule cites it, but neither this repo nor this installation has a record of it`);
+      lines.push(`          remedy: list the known decisions with: ${CLI} rules decisions`);
       continue;
     }
-    lines.push(`  ${d.id}  ${d.title}`);
+    lines.push(`  ${d.id}  [${d.origin ?? 'package'}]  ${d.title}`);
     lines.push(`          ${d.status}`);
     if (d.supersededBy) {
       // Never print a reversed ruling as if it were current.
@@ -379,6 +406,7 @@ function adrDirection(facts, flags) {
   const lines = [
     `${d.id} - ${d.title}`,
     '',
+    `origin    ${d.origin ?? 'package'}${d.origin === 'repo' ? ' (this repository overlays the shipped record of the same number)' : ''}`,
     `status    ${d.status}`,
     `restates  ${restates.length > 0 ? restates.join(', ') : '(no rule cites it)'}`,
   ];
@@ -462,4 +490,50 @@ function adrDirection(facts, flags) {
   // A superseded record is not a failure; it is the supersession rule working.
   // The caller asked a question and got a true answer.
   return EXIT.OK;
+}
+
+// --- decisions ------------------------------------------------------------------
+
+/**
+ * `simt rules decisions`: every known decision record, both layers.
+ *
+ * The shipped records underlay the repository's own, which win on a number
+ * collision (review 0003 Q34). The column that matters is `origin`: a reader in
+ * a consumer repository must be able to tell the package's ADR-001 from their
+ * own, because they are two records that happen to share a number.
+ */
+export async function decisionsCommand(args, flags) {
+  const root = flags.root ?? null;
+  const { ok, decisions, errors, origins } = await loadDecisionsFor(root, flags.all === true);
+  if (!ok) {
+    return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable to list them');
+  }
+  const rows = [...decisions]
+    .sort((a, b) => Number(a.id.replace(/^ADR-/i, '')) - Number(b.id.replace(/^ADR-/i, '')))
+    .map((d) => ({
+      id: d.id,
+      title: d.title,
+      status: d.status,
+      origin: origins[d.id] ?? 'package',
+      supersededBy: d.supersededBy ?? null,
+      file: d.file,
+    }));
+
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'rules decisions', root, decisions: rows });
+    return EXIT.OK;
+  }
+
+  const repo = rows.filter((r) => r.origin === 'repo').length;
+  const lines = [
+    `${rows.length} decisions${root && repo > 0 ? ` (${repo} from this repo overlay the shipped set)` : ''}`,
+    '',
+    'id       origin   title',
+  ];
+  for (const r of rows) {
+    const head = r.status.length > 80 ? `${r.status.slice(0, 80)}...` : r.status;
+    lines.push(`${r.id.padEnd(8)}  ${r.origin.padEnd(7)}  ${r.title} — ${head}`);
+  }
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
 }

package/src/commands/skills.mjs

@@ -9,7 +9,7 @@
 // token instead of guessing. Suppressing it is how a discovery tool becomes a
 // black box.
 
-import { readFile } from 'node:fs/promises';
+import { readFile, realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 
@@ -20,6 +20,7 @@ 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 { localSkillNodes } from '../resolve/local.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { CLI } from '../name.mjs';
 import { parsePathList } from '../argv.mjs';
@@ -75,18 +76,25 @@ async function skillsRegistry(args) {
   return registry;
 }
 
-function findSkill(registry, name, verb) {
+/**
+ * The named skill: the registry first, then the repo's own skills, because a skill
+ * the repo installed is addressable by the same name (plan 0005 S3). The local lookup
+ * costs a fingerprint plus a directory scan, so it runs only when the registry did
+ * not answer.
+ */
+async function findSkill(registry, root, name, verb) {
   if (!name) skillsFailure(`${verb} needs a skill name`, `usage: ${CLI} skills ${verb} <name>`, EXIT.USAGE);
   const skill = registry.skills.find((s) => s.name === name);
-  if (!skill) {
-    const near = nearMatches(name, registry.skills.map((s) => s.name));
-    skillsFailure(
-      `no skill named "${name}"${near.length ? ` (did you mean ${near.join(', ')}?)` : ''}`,
-      `run: ${CLI} skills find <query>`,
-      EXIT.USAGE,
-    );
-  }
-  return skill;
+  if (skill) return skill;
+  const repoStack = (await fingerprint(root)).signals;
+  const local = (await localSkillNodes(root, registry, repoStack)).find((s) => s.name === name);
+  if (local) return local;
+  const near = nearMatches(name, registry.skills.map((s) => s.name));
+  skillsFailure(
+    `no skill named "${name}"${near.length ? ` (did you mean ${near.join(', ')}?)` : ''}`,
+    `run: ${CLI} skills find <query>`,
+    EXIT.USAGE,
+  );
 }
 
 /** The JSON-safe skill facts both surfaces spread: absent lists read as empty, not missing. */
@@ -116,6 +124,10 @@ export async function skillsBriefFacts(root, args = {}) {
   const task = args.task ?? null;
   const repoFacts = { root, stack: repoStack, facts: repo.facts };
 
+  // The repo's own skills rank alongside the registry, so every command agrees on
+  // the names a reader in this repo can address (plan 0005 S3).
+  const pool = [...registry.skills, ...(await localSkillNodes(root, registry, repoStack))];
+
   // A brief with no task and no paths resolves on stack alone, which produces a
   // plausible-looking list the agent may act on. It warns rather than silently
   // answering; under `--json` the warning is a field, not prose on stdout.
@@ -125,7 +137,7 @@ export async function skillsBriefFacts(root, args = {}) {
       'pass --task "<what you are doing>" or stage files so the diff drives selection, ' +
       'or pass --all to take everything for this stack.';
     if (args.all) {
-      const usable = registry.skills.filter((s) => stackCompatible(s, repoStack));
+      const usable = pool.filter((s) => stackCompatible(s, repoStack));
       return {
         kind: 'all',
         repoStack,
@@ -153,12 +165,12 @@ export async function skillsBriefFacts(root, args = {}) {
   }
 
   const context = { repoStack, taskTokens, paths };
-  const { selected, excluded } = rankSkills(registry.skills, context, { forced });
+  const { selected, excluded } = rankSkills(pool, context, { forced });
 
   // Hard dependencies are pulled in even when they did not score, and even past
   // budget: a skill that is useless without its dependency is worse than a large
   // context, because it silently misleads.
-  const expanded = closure(selected, registry.skills);
+  const expanded = closure(selected, pool);
   const { picked, deferred, used: inlineBytes } = selectWithinBudget(expanded, {
     budget,
     all: args.all === true,
@@ -216,31 +228,53 @@ export async function skillsBriefFacts(root, args = {}) {
   };
 }
 
-/** Raw search across capability, keyword and summary. */
-export async function skillsFindFacts(query, args = {}) {
+/**
+ * Raw search across capability, keyword and summary.
+ *
+ * Local nodes are admitted on `score > 0`, not the `selectionVerdict` rule the
+ * registry nodes keep: that rule exists to compensate for find having no repo, and
+ * a local skill has one - its presence in the repo is the scoping signal the rule
+ * stands in for.
+ */
+export async function skillsFindFacts(root, query, args = {}) {
   const q = String(query ?? '').trim();
   if (!q) skillsFailure('find needs a query', `usage: ${CLI} skills find <query>`, EXIT.USAGE);
   const registry = await skillsRegistry(args);
   const tokens = tokenize(q);
-  const results = registry.skills
-    .map((skill) => ({ skill, ...scoreSkill(skill, { repoStack: [], taskTokens: tokens, paths: [] }) }))
-    .filter((r) => selectionVerdict(r.evidence, r.reasons) === null)
-    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+  const context = { repoStack: [], taskTokens: tokens, paths: [] };
+  const results = [
+    ...registry.skills
+      .map((skill) => ({ skill, ...scoreSkill(skill, context) }))
+      .filter((r) => selectionVerdict(r.evidence, r.reasons) === null),
+    ...(await localSkillNodes(root, registry, (await fingerprint(root)).signals))
+      .map((skill) => ({ skill, ...scoreSkill(skill, context) }))
+      .filter((r) => r.score > 0),
+  ].sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
   return {
     query: q,
-    results: results.map((r) => ({ name: r.skill.name, score: r.score, summary: r.skill.summary, reasons: r.reasons })),
+    results: results.map((r) => ({ name: r.skill.name, score: r.score, bytes: r.skill.bytes, summary: r.skill.summary, reasons: r.reasons })),
   };
 }
 
 /** Tier 2: one skill body and the metadata needed to judge it. */
 export async function skillsShowFacts(root, name, args = {}) {
   const registry = await skillsRegistry(args);
-  const skill = findSkill(registry, name, 'show');
+  const skill = await findSkill(registry, root, name, 'show');
   const { note: workspace, root: workspaceRoot } = await announceWorkspace(args);
   // The repo is a location for a declared source too, so `show` reads a body the
   // caller already has instead of reporting the body missing.
   const body = await sourcePath(skill, workspaceRoot, root);
-  const bodyFrom = body === null ? 'none' : body.startsWith(`${root}/`) ? 'repo' : 'workspace';
+  // A local file is canonicalized by realpath, while a declared repo source keeps the
+  // caller's spelling: on a symlinked prefix (macOS `/var`) the label must accept the
+  // canonical root too, or a repo body is mislabelled `workspace`.
+  let realRoot = root;
+  try {
+    realRoot = await realpath(root);
+  } catch {
+    /* root does not exist; the label falls back to the un-canonical comparison */
+  }
+  const bodyFrom =
+    body === null ? 'none' : body.startsWith(`${root}/`) || body.startsWith(`${realRoot}/`) ? 'repo' : 'workspace';
   return {
     skill: skillFacts(skill),
     workspace,
@@ -253,7 +287,7 @@ export async function skillsShowFacts(root, name, args = {}) {
 /** The signal chain for one skill in one repository. */
 export async function skillsWhyFacts(root, name, args = {}) {
   const registry = await skillsRegistry(args);
-  const skill = findSkill(registry, name, 'why');
+  const skill = await findSkill(registry, root, name, 'why');
   const repo = await fingerprint(root);
   const paths = args.paths ? parsePathList(args.paths) : await dirtyPaths(root);
   const tokens = tokenize(args.task ?? '');
@@ -402,9 +436,10 @@ async function emitAllFacts(facts, flags) {
 // --- find ---------------------------------------------------------------------
 
 export async function findCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
   let facts;
   try {
-    facts = await skillsFindFacts(args.join(' '), flags);
+    facts = await skillsFindFacts(root, args.join(' '), flags);
   } catch (error) {
     return fail(error.message, error.exitCode ?? EXIT.FAIL, error.remedy);
   }

package/src/commands/skillscompile.mjs

@@ -20,7 +20,8 @@ import { resolveVaultDir } from '../bench/mine.mjs';
 import { locateSource, sourceHeldLocally } from '../resolve/source.mjs';
 import { nearMatches } from '../resolve/near.mjs';
 import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
-import { CLI, STATE_DIR } from '../name.mjs';
+import { CLI } from '../name.mjs';
+import { LOCAL_DIR } from '../state.mjs';
 
 async function readSkillRawText(skill, workspaceRoot, root) {
   const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
@@ -44,7 +45,7 @@ async function readSkillRawText(skill, workspaceRoot, root) {
 
 async function loadGoldPathsByTask(root) {
   const map = new Map();
-  const tasksDir = join(root, STATE_DIR, 'bench', 'tasks');
+  const tasksDir = join(root, '.simt', 'bench', 'tasks');
   const vaultRoot = resolveVaultDir(root);
   const entries = (await readdir(tasksDir).catch(() => [])).filter((f) => f.endsWith('.json')).sort();
   for (const entry of entries) {
@@ -172,26 +173,26 @@ async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, fla
     triggerStats,
   });
 
-  const outDir = join(root, STATE_DIR, 'compiled', 'skills', skill.name);
-  const proposalPath = join(root, STATE_DIR, 'proposals', 'skills', `${skill.name}.json`);
+  const outDir = join(root, LOCAL_DIR, 'compiled', 'skills', skill.name);
+  const proposalPath = join(root, LOCAL_DIR, 'proposals', 'skills', `${skill.name}.json`);
   const writtenFiles = [];
 
   if (mode.apply) {
     await mkdir(outDir, { recursive: true });
     await writeFile(join(outDir, 'SKILL.md'), compiled.mainText, 'utf8');
-    writtenFiles.push(`${STATE_DIR}/compiled/skills/${skill.name}/SKILL.md`);
+    writtenFiles.push(`${LOCAL_DIR}/compiled/skills/${skill.name}/SKILL.md`);
 
     for (const ref of compiled.references) {
       if (!ref.content) continue;
       const refFull = join(outDir, ref.path);
       await mkdir(dirname(refFull), { recursive: true });
       await writeFile(refFull, ref.content, 'utf8');
-      writtenFiles.push(`${STATE_DIR}/compiled/skills/${skill.name}/${ref.path}`);
+      writtenFiles.push(`${LOCAL_DIR}/compiled/skills/${skill.name}/${ref.path}`);
     }
 
     await mkdir(dirname(proposalPath), { recursive: true });
     await writeFile(proposalPath, `${JSON.stringify(proposal, null, 2)}\n`, 'utf8');
-    writtenFiles.push(`${STATE_DIR}/proposals/skills/${skill.name}.json`);
+    writtenFiles.push(`${LOCAL_DIR}/proposals/skills/${skill.name}.json`);
   }
 
   if (isJson(flags)) {

package/src/commands/skillsinstall.mjs

@@ -89,6 +89,18 @@ export async function installCommand(args, flags) {
 
   const found = await locateSource(pick.source, { workspaceRoot: ws.root, root });
   if (!found.path) {
+    // A repo-side candidate with the wrong size is a third reason, and it needs
+    // its own wording: the file is on the reader's disk, so "this repo does not
+    // hold it" would send them looking for a file that is already there. The
+    // variant path calls the same failure an impostor (chooseSource).
+    const impostor = found.candidates.find((c) => c.how === 'repo');
+    if (impostor) {
+      return fail(
+        `${skill.name}: ${root}/${pick.source.path} exists but is not the declared body (${pick.source.bytes} bytes declared)`,
+        EXIT.USAGE,
+        `run: ${CLI} graph lint --workspace <path>  to see what the registry expects, or delete the local copy`,
+      );
+    }
     // Two reasons land here and they need different wording: no workspace at all,
     // or a workspace that should hold this body and does not. An install that
     // cannot read a body has failed, so this is never a degraded mode - the