simt-dev 0.6.3 → 0.7.1

package/src/commands/skills.mjs

@@ -9,7 +9,8 @@
 // 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 { repoContext } from '../context.mjs';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 
@@ -20,9 +21,11 @@ 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';
+import { commandRoot } from '../repo-root.mjs';
 
 export { parsePathList };
 
@@ -75,18 +78,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, ctx) {
   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 ctx.fingerprint()).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. */
@@ -106,7 +116,10 @@ function skillFacts(skill) {
 /** Tier 1: the selection the task resolves to, with the text packet's display sets. */
 export async function skillsBriefFacts(root, args = {}) {
   const registry = await skillsRegistry(args);
-  const repo = await fingerprint(root);
+  // One context per call: a second question about the same repository inside this
+  // command costs nothing (review 0003 Q67).
+  const ctx = args.ctx ?? repoContext(root);
+  const repo = await ctx.fingerprint();
   const { note: workspace, root: workspaceRoot } = await announceWorkspace(args);
   const repoStack = repo.signals;
   const paths = args.paths ? parsePathList(args.paths) : await dirtyPaths(root);
@@ -116,6 +129,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 +142,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 +170,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 +233,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 (args.ctx ?? repoContext(root)).fingerprint()).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', args.ctx ?? repoContext(root));
   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,8 +292,9 @@ 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 repo = await fingerprint(root);
+  const ctx = args.ctx ?? repoContext(root);
+  const skill = await findSkill(registry, root, name, 'why', ctx);
+  const repo = await ctx.fingerprint();
   const paths = args.paths ? parsePathList(args.paths) : await dirtyPaths(root);
   const tokens = tokenize(args.task ?? '');
   const { score, reasons } = scoreSkill(skill, { repoStack: repo.signals, taskTokens: tokens, paths });
@@ -352,7 +392,6 @@ export async function indexCommand(args, flags) {
       '',
       `deferred entries return a pointer, not a body. Fetch one with: ${CLI} skills show <name>`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
@@ -395,16 +434,17 @@ async function emitAllFacts(facts, flags) {
   if (deferred.length > 0) {
     lines.push('', `DEFERRED ${deferred.length}: ${deferred.map((s) => s.name).join(', ')}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 // --- find ---------------------------------------------------------------------
 
 export async function findCommand(args, flags) {
+  const root = commandRoot(flags);
   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);
   }
@@ -414,7 +454,6 @@ export async function findCommand(args, flags) {
   if (isJson(flags)) {
     emitJson(
       { ok: true, query, workspace, results },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -434,17 +473,17 @@ export async function findCommand(args, flags) {
           `${r.name.padEnd(26)} ${kb(r.bytes).padStart(7)}  ${r.reasons.join(' ')}`,
       ),
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
 
 // --- brief: tier 1 ------------------------------------------------------------
 export async function briefCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
+  const ctx = repoContext(root);
   let facts;
   try {
-    facts = await skillsBriefFacts(root, flags);
+    facts = await skillsBriefFacts(root, { ...flags, ctx });
   } catch (error) {
     return fail(error.message, error.exitCode ?? EXIT.FAIL, error.remedy);
   }
@@ -463,21 +502,20 @@ export async function briefCommand(args, flags) {
   }
 
   if (facts.warning) {
-    const repo = await fingerprint(root);
+    const repo = await ctx.fingerprint();
     emit(
       [
         `repo ${root.split('/').pop()} (${repoLine(repo)})`,
         '',
         facts.warning,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
 
   const { shown, shownDeferred, shownUsed, pointerOnly, excludedEntries, workspace, workspaceRoot, budget } = facts;
   const lines = [];
-  const repo = await fingerprint(root);
+  const repo = await ctx.fingerprint();
 
   lines.push(
     `RESOLVED ${shown.length} skills, ${kb(shownUsed)}${flags.all || shownUsed <= budget ? '' : ' (budget capped)'} - repo ${root.split('/').pop()} (${repoLine(repo)})`,
@@ -498,7 +536,7 @@ export async function briefCommand(args, flags) {
       lines.push('', `NOT SELECTED ${hidden.length}`, '', `  notes: ${CLI} skills why <name> | ${CLI} skills show <name>`);
     }
     lines.push('', 'OVERRIDE  --skill <name> | --budget <bytes> | --all | --paths <globs>');
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -543,14 +581,14 @@ export async function briefCommand(args, flags) {
   }
 
   lines.push('', 'OVERRIDE  --skill <name> | --budget <bytes> | --all | --paths <globs>');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 // --- show: tier 2 -------------------------------------------------------------
 
 export async function showCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let facts;
   try {
     facts = await skillsShowFacts(root, args[0], flags);
@@ -560,7 +598,7 @@ export async function showCommand(args, flags) {
   const { skill, workspace, body, bodyFrom, bodyText } = facts;
   const source = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
   if (isJson(flags)) {
-    emitJson({ ok: true, ...skill, workspace, body, bodyFrom, bodyText }, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: true, ...skill, workspace, body, bodyFrom, bodyText });
     return EXIT.OK;
   }
   emit(
@@ -583,7 +621,6 @@ export async function showCommand(args, flags) {
     ]
       .filter((l) => l !== null)
       .join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return EXIT.OK;
 }
@@ -591,7 +628,7 @@ export async function showCommand(args, flags) {
 // --- why ----------------------------------------------------------------------
 
 export async function whyCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let facts;
   try {
     facts = await skillsWhyFacts(root, args[0], flags);
@@ -606,7 +643,7 @@ export async function whyCommand(args, flags) {
   // to scrape: a skill that can never be selected in this repo is a decision, not
   // a line of output.
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'skills why', ...facts }, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: true, command: 'skills why', ...facts });
     return EXIT.OK;
   }
 
@@ -632,7 +669,7 @@ export async function whyCommand(args, flags) {
   if (facts.variantOf) lines.push('', `variant-of      ${facts.variantOf} (sibling group, one body per stack)`);
   if (facts.requires?.length > 0) lines.push(`requires        ${facts.requires.join(', ')}`);
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -738,7 +775,7 @@ export async function evalCommand(positional, flags) {
   }
 
   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 });
+  emit(lines.join('\n'));
   return okRun ? EXIT.OK : EXIT.FAIL;
 }
 

package/src/commands/skillscompile.mjs

@@ -20,7 +20,9 @@ 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';
+import { commandRoot } from '../repo-root.mjs';
 
 async function readSkillRawText(skill, workspaceRoot, root) {
   const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
@@ -44,7 +46,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) {
@@ -67,7 +69,7 @@ export async function compileCommand(args, flags) {
   const { registry, errors, ok } = await loadRegistry(null, flags);
   if (!ok) return fail(errors[0], EXIT.REGISTRY, WORKSPACE_REMEDY);
 
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const ws = await resolveWorkspace(flags);
   const targetName = args[0] ?? null;
 
@@ -116,7 +118,6 @@ export async function compileCommand(args, flags) {
           splitPlan: s.splitPlan,
         })),
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -149,7 +150,7 @@ export async function compileCommand(args, flags) {
     }
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -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)) {
@@ -222,7 +223,6 @@ async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, fla
           : null,
         proposal,
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -245,7 +245,7 @@ async function runSingleSkillCompile(skill, registry, { root, workspaceRoot, fla
     }
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   if (!mode.apply) {
     note(`note    dry-run  nothing written; apply with: ${CLI} skills compile ${skill.name} --yes`);
   }

package/src/commands/skillsinstall.mjs

@@ -38,6 +38,7 @@ import { resolveWorkspace, WORKSPACE_REMEDY } from '../workspace.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { nameProblems } from '../graph/spec.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 /**
  * Where skills live in this repo. The estate already has a convention - a
@@ -82,13 +83,25 @@ export async function installCommand(args, flags) {
   const ws = await resolveWorkspace(flags);
   if (ws.error) return fail(`workspace config: ${ws.error}`, EXIT.CONFIG, 'fix the JSON, or remove the file');
 
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const repo = await fingerprint(root);
   const pick = await chooseSource(skill, repo.signals, flags, { root, workspaceRoot: ws.root });
   if (pick.error) return fail(pick.error, EXIT.USAGE, pick.remedy);
 
   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
@@ -198,7 +211,6 @@ export async function installCommand(args, flags) {
       ]
         .filter((l) => l !== null)
         .join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
   }