simt-dev 0.3.1 → 0.5.0

package/src/projection/lock.mjs

@@ -8,9 +8,10 @@
 // rewritten.
 
 import { createHash } from 'node:crypto';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
+import { readLockedVariants } from '../kernel/variants.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
 import { readManifest } from './manifest.mjs';
@@ -29,11 +30,25 @@ const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
  *   body that was written and not a body for a different set of surfaces
  */
 export async function computeLock(root, flags = {}) {
-  const desired = await desiredRegion(root, flags);
-  return {
-    inputs: await inputDigest(root),
-    outputs: createHash('sha256').update(desired.body).digest('hex'),
-  };
+  const variants =
+    flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
+  const desired = await desiredRegion(root, { ...flags, variants });
+  const inputs = await inputDigest(root, variants);
+  const outputs = createHash('sha256').update(desired.body).digest('hex');
+  const hasVariants =
+    variants && typeof variants === 'object' && Object.keys(variants).length > 0;
+  return hasVariants ? { inputs, outputs, variants } : { inputs, outputs };
+}
+
+/**
+ * Record locked variant winners in `simt-dev.lock.json` alongside updated digests.
+ */
+export async function writeLockVariants(root, nextVariants, flags = {}) {
+  const existing = await readLockedVariants(root);
+  const merged = { ...existing, ...(nextVariants ?? {}) };
+  const lock = await computeLock(root, { ...flags, variants: merged });
+  await writeFile(join(root, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+  return lock;
 }
 
 /** Read a lock, or null when the file is not there. A file that does not parse is an
@@ -52,13 +67,19 @@ export async function readLock(root) {
     if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
       return { lock: null, error: 'must be an object with inputs and outputs' };
     }
+    if (
+      lock.variants !== undefined &&
+      (typeof lock.variants !== 'object' || lock.variants === null || Array.isArray(lock.variants))
+    ) {
+      return { lock: null, error: 'variants must be an object' };
+    }
     return { lock, error: null };
   } catch (error) {
     return { lock: null, error: error.message };
   }
 }
 
-async function inputDigest(root) {
+async function inputDigest(root, variants = {}) {
   const hash = createHash('sha256');
   hash.update(`provenance:${await provenanceDigest()}\n`);
   const { stack, facts } = await fingerprint(root);
@@ -89,5 +110,16 @@ async function inputDigest(root) {
   } catch (error) {
     if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
   }
+  const variantKeys =
+    variants && typeof variants === 'object' ? Object.keys(variants).sort() : [];
+  if (variantKeys.length > 0) {
+    const winners = {};
+    for (const key of variantKeys) {
+      const entry = variants[key];
+      winners[key] =
+        typeof entry === 'string' ? entry : (entry?.winner ?? entry?.variant ?? null);
+    }
+    hash.update(`variants:${JSON.stringify(winners)}\n`);
+  }
   return hash.digest('hex');
 }

package/src/projection/rules.mjs

@@ -35,6 +35,7 @@ import { commandCard, CARD_LIMIT_BYTES } from '../kernel/card.mjs';
 import { packToBudget } from '../kernel/budget.mjs';
 import { filterInferable, inferableDefect, inferableProofs } from '../kernel/inferability.mjs';
 import { checkDefect, foldChecks } from '../kernel/checks.mjs';
+import { foldVariants, readLockedVariants, variantsDefect } from '../kernel/variants.mjs';
 import { BASELINES } from './baselines.mjs';
 import { CLI } from '../name.mjs';
 import { installedSkills } from './disclosure.mjs';
@@ -403,12 +404,14 @@ async function ruleBodies(root, manifest, flags) {
     for (const p of renderProblems) problems.push(`${rule.file}: ${p}`);
     if (renderProblems.length > 0) continue;
 
+    const variantFolded = foldVariants(body, rule.id ?? '', flags?.variants ?? null);
+
     // One canonical body, one target per selected surface. The body is identical
     // everywhere; only the frontmatter the editor reads before any rule text
     // differs. Without this loop a repo in a Claude Code session receives
     // AGENTS.md and none of the always-on process rules, because those lived only
     // in a directory only Cursor reads.
-    bodies.push({ rule, body });
+    bodies.push({ rule, body: variantFolded.body });
   }
 
   return { resolved, bodies, problems, notes, skipped };
@@ -449,12 +452,14 @@ function toolRule(rule) {
 
 export async function desiredRegion(root, flags) {
   const { stack, facts, manifest } = await fingerprint(root);
+  const lockedVariants =
+    flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
   const all = await loadRules(root);
   const { selected, fallback, notes } = select(all, stack, facts);
   const { resolved, bodies, problems, notes: ruleNotes } = await ruleBodies(
     root,
     manifest,
-    flags ?? {},
+    { ...(flags ?? {}), variants: lockedVariants },
   );
   notes.push(...ruleNotes);
 
@@ -476,7 +481,8 @@ export async function desiredRegion(root, flags) {
     // selected surface cannot narrow, the file would be the only home for a rule that
     // reader cannot reach — so it stays, and says why.
     if (narrowing) {
-      scoped.push(r);
+      const vf = foldVariants(r.body, r.id ?? '', lockedVariants);
+      scoped.push(vf.changed ? { ...r, body: vf.body } : r);
       continue;
     }
     inRegion.push(r);
@@ -521,18 +527,27 @@ export async function desiredRegion(root, flags) {
   // which lines the reader already knows.
   const inferable = [];
   const shipped = [];
+  const variantsSelected = [];
   let enforced = 0;
   for (const r of packed) {
-    const filtered = filterInferable(r.body, proofs);
+    const variantFolded = foldVariants(r.body, r.id ?? '', lockedVariants);
+    const filtered = filterInferable(variantFolded.body, proofs);
     const folded = foldChecks(filtered.body);
     enforced += folded.enforced.length;
-    if (!filtered.changed && !folded.changed) {
+    variantsSelected.push(...variantFolded.selected);
+    if (!variantFolded.changed && !filtered.changed && !folded.changed) {
       shipped.push(r);
       continue;
     }
     for (const x of filtered.removed) inferable.push({ rule: r.id, text: x.text, expr: x.expr });
     shipped.push({ ...r, body: folded.body });
   }
+  const lockedNonDefault = variantsSelected.filter((v) => v.locked && v.winner !== v.baseline);
+  if (lockedNonDefault.length > 0) {
+    notes.push(
+      `variants: applied ${lockedNonDefault.length} locked variant(s) (${lockedNonDefault.map((v) => `${v.slotId}=${v.winner}`).join(', ')})`,
+    );
+  }
   if (enforced > 0) {
     notes.push(
       `enforced: ${enforced} line(s) left the region because a checker runs them`,
@@ -1046,7 +1061,11 @@ export async function loadRules(root = null) {
       // it travels the field that already reaches `check` and `rules list`. The
       // frontmatter defect wins, because a rule that cannot say what it applies to cannot
       // be reasoned about at all.
-      error: describeDefect(meta) ?? inferableDefect(body) ?? checkDefect(body),
+      error:
+        describeDefect(meta) ??
+        inferableDefect(body) ??
+        checkDefect(body) ??
+        variantsDefect(body, meta['simt-id'] ?? ''),
     });
   }
   return out;
@@ -1081,6 +1100,8 @@ export async function packageRegions(root, flags, rootProfiles = null) {
   if (packages.length === 0) return { regions: [], notes };
 
   const rules = await loadRules(root);
+  const lockedVariants =
+    flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
   const sha = await provenanceDigest();
   // The ROOT's proofs, not the package's. The rule set is the root's, so which lines it
   // already proves is a fact about the repository rather than about the directory a file
@@ -1094,9 +1115,12 @@ export async function packageRegions(root, flags, rootProfiles = null) {
     const delta = selected.filter((r) => !shared.includes(r.id));
     if (delta.length === 0) continue;
     const shipped = delta.map((r) => {
-      const filtered = filterInferable(r.body, proofs);
+      const variantFolded = foldVariants(r.body, r.id ?? '', lockedVariants);
+      const filtered = filterInferable(variantFolded.body, proofs);
       const folded = foldChecks(filtered.body);
-      return filtered.changed || folded.changed ? { ...r, body: folded.body } : r;
+      return variantFolded.changed || filtered.changed || folded.changed
+        ? { ...r, body: folded.body }
+        : r;
     });
     regions.push({
       path: pkg.path,

package/src/resolve/body.mjs

@@ -0,0 +1,46 @@
+// Where a skill's body lives, and how a path the registry names becomes a file.
+//
+// Extracted from src/commands/skills.mjs when the distiller (plan 0003 R38) became
+// the second real caller: two commands that resolve the same body differently would
+// print two answers to one question, and ADR-002 refuses the third copy rather than
+// the second use.
+//
+// Sources are declared as `repo/path`, so finding one needs the workspace that
+// CONTAINS the repos. That used to be `resolve(here, '..', '..', '..')`, which is
+// right in the checkout and wrong in `node_modules` - so every source resolved to a
+// path that could not exist and `skills` failed with 38 ENOENT lines. Now it comes
+// from configuration, and `null` is a legitimate answer meaning "this installation
+// has no workspace" (ADR-014).
+//
+// A second location exists and is not a fallback: the repo being read is itself a
+// 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.
+
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { locateSource, sourceHeldLocally } from './source.mjs';
+
+export async function sourcePath(skill, workspaceRoot, root) {
+  const canonical = skill.sources?.find((s) => s.role === 'canonical') ?? skill.sources?.[0];
+
+  if (canonical) {
+    const found = await locateSource(canonical, { workspaceRoot, root });
+    if (found.path) return found.path;
+  }
+
+  const held = await sourceHeldLocally(skill, root, { workspaceRoot });
+  if (held && !held.ambiguous) return held.path;
+
+  // A skill with no canonical source, or one whose bytes match nothing, has no
+  // body. Say so rather than printing an empty section.
+  return canonical && workspaceRoot ? join(workspaceRoot, canonical.repo, canonical.path) : null;
+}
+
+/**
+ * The file a source path points at. A path may be a directory that carries its
+ * body as SKILL.md, the Agent Skills layout; SKILL.md wins when both exist.
+ */
+export function bodyFile(full) {
+  return existsSync(join(full, 'SKILL.md')) ? join(full, 'SKILL.md') : full;
+}