simt-dev 0.6.3 → 0.7.0

package/src/projection/loaders.mjs

@@ -146,10 +146,16 @@ export const LOADERS = [
     nested: 'cumulative up to the project root at session start; files below the workspace load when that area is read',
     skills: ['.agents/skills', '.opencode/skills', '.claude/skills'],
     hooks: {
-      path: '.opencode/plugins/',
+      path: '.opencode/plugins/simt-dev.js',
       verified:
         'OpenCode v2 plugins docs: direct .ts and .js files and immediate plugin packages are loaded from every discovered .opencode/plugins/ directory, and the plugins array in opencode.json(c)',
     },
+    agents: {
+      dir: '.opencode/agents',
+      ext: '.md',
+      verified:
+        'OpenCode v2 agents docs (opencode.ai/v2/docs/agents, read 2026-10-30): subagents are markdown files with a description frontmatter under .opencode/agents/',
+    },
     mcp: {
       path: 'opencode.json',
       key: 'mcp.servers',
@@ -242,6 +248,12 @@ export const LOADERS = [
       verified:
         'Claude Code hooks docs, hook locations: project settings at .claude/settings.json and .claude/settings.local.json, user settings at ~/.claude/settings.json',
     },
+    agents: {
+      dir: '.claude/agents',
+      ext: '.md',
+      verified:
+        'Claude Code subagents docs (code.claude.com/docs/en/sub-agents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .claude/agents/',
+    },
     mcp: {
       path: '.mcp.json',
       key: null,
@@ -320,6 +332,12 @@ export const LOADERS = [
       verified:
         'Codex hooks docs: <repo>/.codex/hooks.json or ~/.codex/hooks.json, or inline [hooks] tables in config.toml',
     },
+    agents: {
+      dir: '.codex/agents',
+      ext: '.toml',
+      verified:
+        'Codex custom agents docs (developers.openai.com/codex/subagents, read 2026-10-30): standalone TOML files under .codex/agents/ defining name, description and developer_instructions',
+    },
     mcp: {
       path: '.codex/config.toml',
       key: 'mcp_servers',
@@ -386,6 +404,12 @@ export const LOADERS = [
       path: '.cursor/hooks.json',
       verified: 'Cursor agent hooks docs: <project-root>/.cursor/hooks.json and ~/.cursor/hooks.json',
     },
+    agents: {
+      dir: '.cursor/agents',
+      ext: '.md',
+      verified:
+        'Cursor subagents docs (cursor.com/docs/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .cursor/agents/',
+    },
     mcp: {
       path: '.cursor/mcp.json',
       key: null,
@@ -470,6 +494,12 @@ export const LOADERS = [
       path: '.agents/hooks.json',
       verified: 'Antigravity hooks docs: workspace level .agents/hooks.json, global ~/.gemini/config/hooks.json',
     },
+    agents: {
+      dir: '.agents/agents',
+      ext: '.md',
+      verified:
+        'Google Antigravity subagents docs (antigravity.google/docs/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .agents/agents/',
+    },
     mcp: {
       path: '.agents/mcp_config.json',
       key: null,
@@ -541,6 +571,12 @@ export const LOADERS = [
       verified:
         'Gemini CLI hooks reference (geminicli.com/docs/hooks/reference/, read 2026-10-26): a project .gemini/settings.json carries a top-level hooks object whose events are arrays of {matcher, hooks:[{type:"command",command,timeout? (milliseconds)}]} — the same shape Claude and Codex use; BeforeTool denies with {decision:"deny",reason}, BeforeAgent and AfterTool inject via hookSpecificOutput.additionalContext',
     },
+    agents: {
+      dir: '.gemini/agents',
+      ext: '.md',
+      verified:
+        'Gemini CLI subagents docs (geminicli.com/docs/core/subagents, read 2026-10-30): project subagents are markdown files with name and description frontmatter under .gemini/agents/',
+    },
     mcp: {
       path: '.gemini/settings.json',
       key: 'mcpServers',
@@ -603,6 +639,8 @@ export const LOADERS = [
     skillsNote: 'no project skill directory is documented for Copilot',
     hooks: null,
     hooksNote: 'no hooks file is documented for Copilot in any first-party page checked on 2026-10-14',
+    agents: null,
+    agentsNote: 'no file-based agents are documented for Copilot in any first-party page checked on 2026-10-30',
     mcp: {
       path: '.vscode/mcp.json',
       key: null,
@@ -707,6 +745,8 @@ export const LOADERS = [
     hooks: null,
     hooksNote:
       'DeepSeek harness hooks docs: the Claude Code and Codex bridges take an explicit configPath, and project-local hooks.json discovery is still marked TODO, so no repository path is loaded by default',
+    agents: null,
+    agentsNote: 'no file-based agents are documented for the DeepSeek harness in any first-party page checked on 2026-10-30',
     mcp: {
       path: null,
       key: '@deepseek-ai/dsh-mcp-client',

package/src/projection/lock.mjs

@@ -13,11 +13,10 @@ import { join } from 'node:path';
 
 import { readLockedVariants } from '../kernel/variants.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { LOCK_FILE, LOCK_LEGACY } from '../name.mjs';
 import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
 import { readManifest } from './manifest.mjs';
 
-export const LOCK_FILE = 'simt-dev.lock.json';
-
 /** Manifest keys that change what the region contains. Anything else in the file is
  *  the repository's own notes, and hashing it would make a comment fail the lock. */
 const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
@@ -28,12 +27,15 @@ const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
  * @param {string} root
  * @param {object} [flags] the same flags `sync` rendered with, so the output is the
  *   body that was written and not a body for a different set of surfaces
+ * @param {object} [manifest] the manifest to digest, in place of the one on disk. A
+ *   writer that is about to write a manifest (a fresh `init`) passes it here so the
+ *   lock records the state the repo will have, not the state it has (Q29).
  */
-export async function computeLock(root, flags = {}) {
+export async function computeLock(root, flags = {}, manifest = undefined) {
   const variants =
     flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
   const desired = await desiredRegion(root, { ...flags, variants });
-  const inputs = await inputDigest(root, variants);
+  const inputs = await inputDigest(root, variants, manifest);
   const outputs = createHash('sha256').update(desired.body).digest('hex');
   const hasVariants =
     variants && typeof variants === 'object' && Object.keys(variants).length > 0;
@@ -41,7 +43,7 @@ export async function computeLock(root, flags = {}) {
 }
 
 /**
- * Record locked variant winners in `simt-dev.lock.json` alongside updated digests.
+ * Record locked variant winners in `simt.lock.json` alongside updated digests.
  */
 export async function writeLockVariants(root, nextVariants, flags = {}) {
   const existing = await readLockedVariants(root);
@@ -53,15 +55,20 @@ export async function writeLockVariants(root, nextVariants, flags = {}) {
 
 /** Read a lock, or null when the file is not there. A file that does not parse is an
  *  error the caller reports, not a missing lock: absence and damage are different
- *  repairs. */
+ *  repairs. A lock under the legacy name is a lock (ADR-110): it is read until the
+ *  next write migrates it, and a permission failure on the new name is not an excuse
+ *  to fall back to an older file. */
 export async function readLock(root) {
-  let text;
-  try {
-    text = await readFile(join(root, LOCK_FILE), 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return { lock: null, error: null };
-    throw error;
+  let text = null;
+  for (const name of [LOCK_FILE, LOCK_LEGACY]) {
+    try {
+      text = await readFile(join(root, name), 'utf8');
+      break;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
   }
+  if (text === null) return { lock: null, error: null };
   try {
     const lock = JSON.parse(text);
     if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
@@ -79,13 +86,13 @@ export async function readLock(root) {
   }
 }
 
-async function inputDigest(root, variants = {}) {
+async function inputDigest(root, variants = {}, manifest = undefined) {
   const hash = createHash('sha256');
   hash.update(`provenance:${await provenanceDigest()}\n`);
   const { stack, facts } = await fingerprint(root);
   hash.update(`signals:${JSON.stringify({ stack, facts })}\n`);
-  const { manifest } = await readManifest(root);
   const owned = {};
+  if (manifest === undefined) manifest = (await readManifest(root)).manifest;
   if (manifest && typeof manifest === 'object') {
     for (const key of MANIFEST_KEYS) {
       if (manifest[key] !== undefined) owned[key] = manifest[key];

package/src/projection/manifest.mjs

@@ -24,6 +24,9 @@ import { journaledWriteFile } from '../journal.mjs';
 // answers to "can this repo run that gate", which is precisely the kind of drift this
 // file exists to prevent elsewhere.
 import { getGate } from '../hooks/gates.mjs';
+// Q31: the one Node runner table. This module and the card, capability,
+// dispatcher and CI workflow all spell `<manager> run <script>` from it.
+import { runScript } from '../ecosystem/node-runner.mjs';
 
 // Imported as well as re-exported: a bare `export { X as Y } from` binds nothing here,
 // and the manifest name is used a dozen times below in remedy strings that name this
@@ -201,7 +204,7 @@ export const ECOSYSTEMS = [
  * fail closed — the defect is declaring a gate this repo has no way to run.
  *
  * The check mirrors what the dispatcher actually attempts:
- *   - `script` gates  run `npm run <script>`, so the script must exist
+ *   - `script` gates  run `<manager> run <script>`, so the script must exist
  *   - `staged` gates  look for each named tool in `node_modules/.bin`, so it must be
  *     installed, not merely declared as a dependency
  *   - `command` gates run whatever the manifest's `gates.commands` declares, so a
@@ -237,13 +240,16 @@ export function gateRunnable(gate, capability = {}) {
   }
   if (gate.kind === 'script') {
     const script = gate.script ?? gate.name;
-    if (capability.scripts?.[script]) return { runnable: true, why: `runs: npm run ${script}` };
+    // Q31: the runnable sentence names the repo's own runner, never a bare npm
+    // assumption — the card, the dispatcher and this check read one resolver.
+    const spell = runScript(capability.runner ?? 'npm', script);
+    if (capability.scripts?.[script]) return { runnable: true, why: `runs: ${spell}` };
     // Saying "no script in package.json" about a repo with no package.json states a
     // fact about a file that does not exist and implies a fix that cannot be taken.
     return {
       runnable: false,
       why: foreign
-        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "npm run ${script}" cannot run here`
+        ? `this repo runs ${runnerName(capability.runner)}, not npm, so "${spell}" cannot run here`
         : `no "${script}" script in package.json`,
     };
   }
@@ -277,11 +283,17 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
   const name = gate?.name ?? 'the gate';
   const npmShaped = gate?.kind === 'staged' || gate?.kind === 'script';
   const foreign = isForeignRunner(runner);
+  // Q31: a missing tool in a Node repo names the repo's own installer —
+  // `pnpm add -D`, not `npm i -D` — and anything elsewhere keeps the honest
+  // undo: name the program under `gates.commands`.
+  const addDev = { npm: 'npm i -D', pnpm: 'pnpm add -D', yarn: 'yarn add -D', bun: 'bun add -d' }[runner] ?? null;
   const fix =
     npmShaped && foreign
       ? `this repo runs ${runnerName(runner)}, not npm; name the program under "gates.commands" in ${MANIFEST_FILE} instead of the npm equivalent`
       : gate?.kind === 'staged'
-        ? `install ${gate.tools.join(', ')} as a dev dependency`
+        ? addDev
+          ? `install ${gate.tools.join(', ')} as a dev dependency: ${addDev} ${gate.tools.join(' ')}   (the gate runs from the pinned dependency)`
+          : `install ${gate.tools.join(', ')} as a dev dependency`
         : gate?.kind === 'script'
           ? `add a "${gate.script ?? name}" script to package.json`
           : gate?.kind === 'command'
@@ -302,11 +314,14 @@ function gateRemedy(gate, { existing = false, runner = null } = {}) {
 /**
  * Is this runner one where `npm run` is not how a gate is spelled?
  *
- * `undefined` means "the caller did not report a runner", and `npm` means the npm
- * remedy applies. Only a positively identified other ecosystem changes the wording.
+ * `undefined` means "the caller did not report a runner", and every Node manager
+ * (`npm`, `pnpm`, `yarn`, `bun`) spells gates as `<manager> run <script>` with
+ * scripts living in the same `package.json`. Only a positively identified
+ * non-Node runner changes the wording. (Q31: pnpm is Node-shaped, not foreign.)
  */
 function isForeignRunner(runner) {
-  return runner != null && runner !== 'npm';
+  if (runner == null) return false;
+  return !['npm', 'pnpm', 'yarn', 'bun'].includes(runner);
 }
 
 /** How a reader would name the runner in a sentence. */
@@ -316,6 +331,9 @@ function runnerName(runner) {
       none: 'no recognised runner',
       gradle: 'Gradle',
       python: 'Python',
+      npm: 'npm',
+      pnpm: 'pnpm',
+      yarn: 'yarn',
       bun: 'bun',
       cargo: 'Cargo',
       go: 'Go',
@@ -383,14 +401,15 @@ export function planGates(stack = [], capability = null, facts = []) {
  */
 function ecosystemCommands(facts = [], capability = null) {
   if (!capability?.tools?.length) return {};
-  // An npm runner already answers "how do I test and format" with its own package.json
-  // scripts, and a seed only wins over those scripts when the repo has not declared a
-  // command of its own — which is exactly the mixed repos (package.json AND Cargo.toml)
-  // where the script is the deliberate answer. Seeding there would replace a choice with
-  // a default; the reader's escape hatch is declaring gates.commands by hand, which a
-  // seed would lose to anyway. Pure ecosystem repos have runner 'cargo'/'go'/... and
-  // seed normally.
-  if (capability.runner === 'npm') return {};
+  // A Node runner (npm/pnpm/yarn/bun) already answers "how do I test and format"
+  // with its own package.json scripts, and a seed only wins over those scripts when
+  // the repo has not declared a command of its own — which is exactly the mixed
+  // repos (package.json AND Cargo.toml) where the script is the deliberate answer.
+  // Seeding there would replace a choice with a default; the reader's escape hatch
+  // is declaring gates.commands by hand, which a seed would lose to anyway. Pure
+  // ecosystem repos have runner 'cargo'/'go'/... and seed normally.
+  // Q31: every Node manager skips seeding — pnpm is not "foreign", it is Node.
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(capability.runner)) return {};
   const present = new Set(facts);
   const commands = {};
   for (const eco of ECOSYSTEMS) {
@@ -728,6 +747,23 @@ export function declaredShared(manifest) {
 
 export const GENERATED_KEYS = new Set(['$comment', 'projection']);
 
+// The sub-keys of `projection` this tool writes. `projection` is a generated key, but
+// not wholesale: the repository owns sub-keys this writer does not emit (`place` is the
+// one that shipped), and a repair that replaces the object deletes them (review 0003 Q26).
+const PROJECTION_KEYS = new Set(['simtDevSha', 'version']);
+
+/** The `projection` object a manifest carries; anything that is not an object is nothing. */
+function projectionOf(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/** Only the generated sub-keys of a `projection` object, in the order this writer emits them. */
+function generatedProjection(value) {
+  const out = {};
+  for (const key of PROJECTION_KEYS) if (key in projectionOf(value)) out[key] = value[key];
+  return out;
+}
+
 /**
  * A manifest with this tool's own fields replaced by what this build writes, and
  * nothing else touched.
@@ -738,13 +774,22 @@ export const GENERATED_KEYS = new Set(['$comment', 'projection']);
  * repo chose is never compared" is a promise about the repair too, not only about
  * the report, and a repair is exactly where it would be broken.
  *
+ * `projection` merges the same way, one level down: the object the repository has
+ * keeps every sub-key it chose, and the generated sub-keys take this build's values.
+ *
  * @param {object} manifest the repository's manifest, as parsed
  * @param {object} expected `buildManifest`'s output, from the call `manifestDrift` made
  * @returns {object} a new manifest; the argument is not mutated
  */
 export function withGenerated(manifest, expected) {
   const patched = { ...manifest };
-  for (const key of GENERATED_KEYS) if (key in expected) patched[key] = expected[key];
+  for (const key of GENERATED_KEYS) {
+    if (!(key in expected)) continue;
+    patched[key] =
+      key === 'projection'
+        ? { ...projectionOf(manifest?.projection), ...expected.projection }
+        : expected[key];
+  }
   return patched;
 }
 
@@ -787,9 +832,14 @@ export async function manifestDrift(root, stack, sha) {
   // `[...GENERATED_KEYS]`, and not `Object.keys(expected)`: the question is which
   // fields are ours, and the answer is the set above. Iterating the expected object
   // asks the same question of a different list and can only agree by coincidence.
-  const stale = [...GENERATED_KEYS].filter(
-    (key) => key in expected && JSON.stringify(manifest[key]) !== JSON.stringify(expected[key]),
-  );
+  const stale = [...GENERATED_KEYS].filter((key) => {
+    if (!(key in expected)) return false;
+    // `projection` compares on the sub-keys this tool writes: a sub-key the repo
+    // chose (`place`) is not a stale field, and reporting it is what made `sync`
+    // delete the one setting that was not stale (review 0003 Q26).
+    const actual = key === 'projection' ? generatedProjection(manifest[key]) : manifest[key];
+    return JSON.stringify(actual) !== JSON.stringify(expected[key]);
+  });
   if (stale.length > 0) {
     return {
       file: MANIFEST,

package/src/projection/markers.mjs

@@ -165,6 +165,43 @@ export function parse(text, style) {
   };
 }
 
+/**
+ * The line spans of every generated region in `text`, across both marker styles.
+ *
+ * `parse` is the single reader: a malformed region is still a region (an edit
+ * anywhere in the file stays denied), so malformed counts as a span covering the
+ * whole file rather than as absent. Line numbers are 1-based and inclusive.
+ *
+ * @returns {{malformed: boolean, spans: Array<{start: number, end: number}>}}
+ */
+export function regionSpans(text) {
+  const spans = [];
+  let malformed = false;
+  for (const style of ['html', 'hash']) {
+    const state = parse(text, style);
+    if (state.status === 'malformed') {
+      malformed = true;
+      continue;
+    }
+    if (state.status !== 'ok') continue;
+    const start = state.before === '' ? 1 : state.before.split('\n').length + 1;
+    const bodyLines = state.body === '' ? 0 : state.body.split('\n').length;
+    spans.push({ start, end: start + bodyLines + 1 });
+  }
+  if (malformed) {
+    const total = text.split('\n').length;
+    return { malformed: true, spans: [{ start: 1, end: total }] };
+  }
+  return { malformed: false, spans };
+}
+
+/** Line range of `text.slice(index, index + length)`, 1-based and inclusive. */
+export function lineRangeOf(text, index, length) {
+  const start = text.slice(0, index).split('\n').length;
+  const end = text.slice(0, index + length).split('\n').length;
+  return { start, end };
+}
+
 function malformed(lines, from, at, reason) {
   return {
     status: 'malformed',
@@ -359,9 +396,12 @@ export function inject(text, body, meta, opts = {}) {
   // too. A body that matches with a seam that does not is red on `format:check`, and
   // reporting `unchanged` there means `check` finds no drift and `sync` never repairs
   // it - the repository stays red with no remedy the tool offers. Top placement is
-  // excluded because there the splice is a repair that legitimately moves bytes
-  // outside the markers, so the two files differ for a reason unrelated to the seam.
-  const settled = unchanged && (where === 'top' || spliced === text);
+  // excluded from the seam test because there the splice is a repair that
+  // legitimately moves bytes outside the markers, so the two files differ for a
+  // reason unrelated to the seam. Position is the test there instead: a region below
+  // the file's own settings has been moved, and the move is what `where: 'top'`
+  // exists to repair (review 0003 Q26).
+  const settled = unchanged && (where === 'top' ? state.before.trim() === '' : spliced === text);
   if (settled) return { ...seen, text, action: 'unchanged' };
 
   return { ...seen, text: spliced, action: 'updated' };

package/src/projection/mdc.mjs

@@ -28,6 +28,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse } from './markers.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
 
 // ROOT is computed here rather than imported: project.mjs is the caller of every
 // function below, so importing it back would create a cycle for the sake of one
@@ -148,9 +149,18 @@ function parseSubstitutions(text) {
     const scope = next ? tail.slice(0, next.index + 1) : tail;
     const def = /^\s*default:\s*(.*)$/m.exec(scope);
     const desc = /^\s*describe:\s*(.*)$/m.exec(scope);
+    // A per-signal default: `default-<signal>:` picks the value when the repository
+    // carries that signal (a stack tag or a detection fact). `default:` is the
+    // fallback. The two cannot collide: `default:` requires the colon immediately
+    // after the word, and a signal line has a `-` there.
+    const perSignal = {};
+    for (const pm of scope.matchAll(/^\s*default-([a-z0-9][a-z0-9-]*):\s*(.*)$/gm)) {
+      perSignal[pm[1]] = unquote(pm[2].trim());
+    }
     out.push({
       key: hit[1],
       default: def ? unquote(def[1].trim()) : '',
+      perSignal,
       describe: desc ? unquote(desc[1].trim()) : '',
     });
   }
@@ -197,6 +207,19 @@ function stripFrontmatter(text) {
     .trim();
 }
 
+/**
+ * The default a signal set selects: the first per-signal default whose signal is
+ * present, else the plain default. Signals carry detection facts as well as stack
+ * tags, because a Go repository is selected on a fact, not a stack (review 0003 Q32).
+ */
+function pickDefault(sub, signals) {
+  const perSignal = sub.perSignal ?? {};
+  for (const s of signals) {
+    if (Object.prototype.hasOwnProperty.call(perSignal, s)) return perSignal[s];
+  }
+  return sub.default;
+}
+
 /**
  * Substitute declared placeholders.
  *
@@ -209,9 +232,11 @@ function stripFrontmatter(text) {
  * rendered rule would ship a literal `{{key}}`, which reads as a finished rule
  * and is not one.
  */
-export function renderMdc(rule, declared = {}) {
+export function renderMdc(rule, declared = {}, signals = []) {
   const problems = [];
-  let body = rule.body;
+  // The rule text names the manifest with a token and the render substitutes it,
+  // so a rename of the file is a change in one place (MANIFEST_FILE).
+  let body = rule.body.replaceAll('{manifest}', MANIFEST_FILE);
 
   for (const sub of rule.substitutions) {
     const has = Object.prototype.hasOwnProperty.call(declared, sub.key);
@@ -226,17 +251,19 @@ export function renderMdc(rule, declared = {}) {
     }
 
     if (provided === undefined || provided === null || provided === '') {
-      // Fall back to the default. An empty DEFAULT is also a drop instruction,
-      // which is how the same file serves a repo that has nothing to add.
-      if (sub.default === '') {
+      // Fall back to the default the signals select. An empty chosen default is
+      // also a drop instruction, which is how the same file serves a repo that
+      // has nothing to add.
+      const chosen = pickDefault(sub, signals);
+      if (chosen === '') {
         body = dropOrReplace(body, sub.key, '');
         continue;
       }
-      if (sub.default === undefined) {
+      if (chosen === undefined) {
         problems.push(`substitution ${sub.key} has no default and none declared`);
         continue;
       }
-      body = dropOrReplace(body, sub.key, sub.default);
+      body = dropOrReplace(body, sub.key, chosen);
       continue;
     }