simt-dev 0.6.3 → 0.7.0

package/skills/simt-commands/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: simt-commands
+description: Command reference for simt-dev: which commands are mutating vs read-only, and a scenario-to-command mapping for the agent.
+---
+
+## Dry run
+
+Most simt-dev commands that write to the repository default to **dry-run**:
+they print what they would change and exit without writing. Add `--yes` to
+apply. Read the dry-run output first — it is the plan — then re-run with
+`--yes`. A dry-run that shows an unexpected file is a reason to stop, not to
+add `--yes` and hope.
+
+### Mutating commands (need `--yes` to write)
+
+`init`, `sync`, `plan done`, `slice start`, `slice finish`, `slice abandon`,
+`agents install`, `agent-hooks install`, `hooks install`, `doctor --fix`,
+`ignore`, `ci`, `shared install`, `lessons review`, `decide`, `undo`,
+`skills install`, `bench mine|run|ablate|probes|variants`, `pack new|publish`,
+`lease`
+
+### Read-only commands (no flag needed)
+
+`brief`, `why`, `tests`, `gate`, `impact`, `map`, `check`, `status`,
+`plan status|next`, `rules *`, `agents status`, `agent-hooks status`,
+`hooks status`, `evidence`, `pr-body`, `explain`, `graph lint`,
+`skills index|brief|show|why|find`, `index`, `review`, `tokens`,
+`harness *`, `compare`, `distill`, `bench report|critic`, `pack lint`,
+`mcp`, `completions`, `lessons list|capture`
+
+## Command reference
+
+Pick the command by what you need, not by what you remember:
+
+| You need to… | Command | Notes |
+|---|---|---|
+| Understand a task before exploring | `simt brief "<task>"` | Kind, commands, files, tests, decisions |
+| Know what governs a file | `simt why <file>` | Decisions, rules, skills, gates, lessons |
+| Find tests for a file | `simt tests [path]` | Import, conventional, or coverage |
+| Find tests a change reaches | `simt gate [path...]` | `--changed` reads the diff |
+| See who a change affects | `simt impact <file\|symbol>` | Importers, tests, contracts |
+| Find files a task touches | `simt map --task "<text>"` | `--level outline\|names\|signatures` |
+| Read tracker state | `simt plan status` | Counts per tracker file |
+| Get the next slice | `simt plan next [<id>]` | Smallest ready slice, ~1 KB |
+| Mark a slice done | `simt plan done <id> <sha> --test "<cmd>" --yes` | Dry-run without `--yes` |
+| Start a slice in a worktree | `simt slice start <id> --yes` | Branch `slice/<id>`, brief beside it |
+| Finish a slice | `simt slice finish <id> --yes` | Gates, commit, record SHA |
+| Abandon a slice | `simt slice abandon <id> --yes` | Removes worktree, returns row |
+| Check the gate | `simt check` | Projection drift, manifest, policy |
+| Regenerate projection | `simt sync --yes` | Idempotent; `--check` for drift only |
+| Explain a finding | `simt explain <CODE>` | Decision, fix, trigger |
+| Read a rule | `simt rules show <id>` | One rule body |
+| Read a decision | `simt rules why <ADR-NNN>` | `--all` for every ruling |
+| Scaffold an ADR | `simt decide [<title>] --yes` | Next number, skeleton, frontmatter |
+| Adopt a repo | `simt init [path] --yes` | `--backup` tags the pre-adoption commit |
+| Install the agent | `simt agents install --yes` | `--harness <id>` for one |
+| Check agent status | `simt agents status` | Present, absent, drift, no-file |
+| Install hooks | `simt hooks install --yes` | Shared dispatcher |
+| Run a hook event | `simt hooks run <event>` | As git would |
+| Install agent hooks | `simt agent-hooks install --yes` | Per-harness policies |
+| Diagnose config | `simt doctor [--fix]` | `--fix` applies safe remedies |
+| Pin a skill | `simt skills install <name> --yes` | `--variant` for multi-variant |
+| Search skills | `simt skills find <query>` | Capability and keyword |
+| Rebuild the index | `simt index` | From git blob hashes |
+| Get PR body | `simt pr-body [--base <ref>]` | Evidence, decisions, gate state |
+| Check evidence | `simt evidence` | Runs recorded against the tree |
+| Review the staged diff | `simt review` | ADR-008 verdict skeleton |
+| Undo last writes | `simt undo --yes` | Only if every file is untouched |
+| Claim files for a session | `simt lease [<paths>...] --yes` | TTL; pre-edit hook refuses |
+| Measure token cost | `simt tokens` | Bytes a reader loads at session start |

package/src/advice/advice.mjs

@@ -98,7 +98,7 @@ export async function loadHistory(root) {
       task: record.task,
       model: record.model,
       resolved: isRunResolved(record),
-      cost: computeRunCost(record, prices),
+      cost: computeRunCost(record, prices).usd,
       tokens: tokensOf(record.usage),
       toolCalls: Number(record?.usage?.toolCalls ?? record?.usage?.tool_calls ?? 0),
       files: Number(descriptor?.gold?.files ?? record?.diff?.files ?? 0),
@@ -159,8 +159,10 @@ export function advise(features, history) {
   // the pick is allowed to stand on it.
   const ladderValues = new Map();
   for (const run of runs) {
+    const v = measure === 'cost' ? run.cost : run.tokens;
+    if (v === null) continue; // an un-costed run cannot ground a cost floor
     const values = ladderValues.get(run.model) ?? [];
-    values.push(measure === 'cost' ? run.cost : run.tokens);
+    values.push(v);
     ladderValues.set(run.model, values);
   }
   const ladderNames = [...ladderValues.keys()].sort(
@@ -170,8 +172,10 @@ export function advise(features, history) {
   const resolvedByModel = new Map();
   for (const run of pool) {
     if (!run.resolved) continue;
+    const v = measure === 'cost' ? run.cost : run.tokens;
+    if (v === null) continue;
     const values = resolvedByModel.get(run.model) ?? [];
-    values.push(measure === 'cost' ? run.cost : run.tokens);
+    values.push(v);
     resolvedByModel.set(run.model, values);
   }
 

package/src/agenthooks/decide.mjs

@@ -23,8 +23,9 @@ import { spawnSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
 
-import { parse } from '../projection/markers.mjs';
-import { activeLeases, leasePathFor, readLeases } from '../lease.mjs';
+import { lineRangeOf, parse, regionSpans } from '../projection/markers.mjs';
+import { activeLeases, canonicalLeasePath, readLeases } from '../lease.mjs';
+import { coreIgnoreCase } from '../repo-root.mjs';
 import { ALLOW_ENV, EVENTS, POLICY_IDS, SESSION_ENV, policiesFor } from './policy.mjs';
 import { applyAliases, commandFacts, GIT_BUILTINS } from './shell.mjs';
 
@@ -69,7 +70,13 @@ function applies(row, facts, env) {
     return row.regex !== null && row.regex.test(facts.command);
   }
   if (row.inspects === 'write') {
-    return (facts.writes ?? []).some((w) => w.generated !== null && w.generated !== undefined);
+    // A file carrying a region denies only an edit that touches it: an Edit outside
+    // the markers, a Write that keeps the region bytes, or a patch whose hunks miss
+    // the span is the author's own text (review 0003 Q17). No edit detail means the
+    // location is unknown, which still denies.
+    return (facts.writes ?? []).some(
+      (w) => w.generated !== null && w.generated !== undefined && w.touches !== false,
+    );
   }
   if (row.inspects === 'lease') {
     const writes = facts.writes ?? [];
@@ -138,15 +145,116 @@ async function submodules(root) {
  * editing its source, a submodule by committing in the other repository.
  */
 export async function generatedBytes(root, file) {
+  const fact = await generatedFact(root, file, null);
+  return fact.generated;
+}
+
+/** Split an `old_string` into its occurrences, each as a line range. */
+function occurrences(text, needle) {
+  if (typeof needle !== 'string' || needle === '') return [];
+  const ranges = [];
+  let from = 0;
+  for (;;) {
+    const index = text.indexOf(needle, from);
+    if (index === -1) return ranges;
+    ranges.push(lineRangeOf(text, index, needle.length));
+    from = index + Math.max(1, needle.length);
+    if (ranges.length > 64) return ranges;
+  }
+}
+
+function rangesOverlap(a, b) {
+  return a.start <= b.end && a.end >= b.start;
+}
+
+/** Line ranges an apply_patch body rewrites, per `@@ -a,b +c,d @@` headers. */
+function patchRanges(patch) {
+  const ranges = [];
+  let numbered = false;
+  let unnumbered = false;
+  for (const line of String(patch ?? '').split('\n')) {
+    const m = /^@@\s*(?:-(\d+)(?:,(\d+))?\s*\+(\d+)(?:,(\d+))?)?\s*@@/.exec(line.trim());
+    if (m === null) continue;
+    if (m[1] === undefined) {
+      unnumbered = true;
+      continue;
+    }
+    numbered = true;
+    const start = Number(m[1]);
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    ranges.push({ start, end: start + Math.max(count, 1) - 1 });
+  }
+  return { ranges, numbered, unnumbered };
+}
+
+/**
+ * Whether an edit touches the generated region in `current`.
+ *
+ * `edit` is what a renderer extracted beside the path: `old_string`/`edits` for an
+ * in-place replacement, `content` for a whole-file Write, `patch` for an
+ * apply_patch body. Unknown shapes deny: without a location the check cannot prove
+ * the edit is outside. A malformed region also denies, because its span is unknown.
+ */
+function touchesRegion(current, edit = {}) {
+  const { malformed, spans } = regionSpans(current);
+  if (spans.length === 0) return false;
+  if (malformed) return true;
+  const needles = [];
+  if (typeof edit?.old_string === 'string') needles.push(edit.old_string);
+  for (const e of edit?.edits ?? []) {
+    if (e && typeof e.old_string === 'string') needles.push(e.old_string);
+  }
+  if (needles.length > 0) {
+    // An `old_string` the file does not contain is an edit that changes nothing:
+    // no overlap, so no denial. Every occurrence is checked because the tool
+    // replaces all of them or the first, depending on the harness, and either way
+    // one overlap is enough to touch the region.
+    return needles.some((needle) => {
+      const found = occurrences(current, needle);
+      if (found.length === 0) return false;
+      return found.some((range) => spans.some((span) => rangesOverlap(range, span)));
+    });
+  }
+  if (typeof edit?.content === 'string') {
+    // A Write replaces the whole file: it touches the region only when the region
+    // bytes change. Each style present before must still be present with the same
+    // body afterwards.
+    for (const style of ['html', 'hash']) {
+      const before = parse(current, style);
+      if (before.status !== 'ok') continue;
+      const after = parse(edit.content, style);
+      if (after.status !== 'ok' || after.body !== before.body) return true;
+    }
+    return false;
+  }
+  if (typeof edit?.patch === 'string') {
+    const { ranges, numbered } = patchRanges(edit.patch);
+    if (!numbered) return true;
+    return ranges.some((range) => spans.some((span) => rangesOverlap(range, span)));
+  }
+  return true;
+}
+
+/**
+ * Why this path is not the author's to write, with whether the edit touches it.
+ *
+ * `edit` is the renderer's detail beside the path (possibly empty). Submodule
+ * writes always touch: another repository owns every byte under its directory.
+ */
+async function generatedFact(root, file, edit = null) {
   const abs = resolve(root, file);
   const text = await readFile(abs, 'utf8').catch(() => null);
-  if (text !== null && holdsRegion(text)) return 'region';
+  if (text !== null && holdsRegion(text)) {
+    return { path: file, generated: 'region', touches: touchesRegion(text, edit ?? {}) };
+  }
   const rel = relative(resolve(root), abs);
   if (!rel.startsWith('..')) {
     const inside = await submodules(root);
-    if (inside.some((dir) => rel === dir || rel.startsWith(`${dir}/`))) return 'submodule';
+    if (inside.some((dir) => rel === dir || rel.startsWith(`${dir}/`))) {
+      return { path: file, generated: 'submodule', touches: true };
+    }
   }
-  return null;
+  return { path: file, generated: null, touches: false };
 }
 
 /**
@@ -189,10 +297,25 @@ async function normalizeCommand(root, command) {
   return parsed;
 }
 
+/** A write entry is a path string or a `{path, ...edit}` row from a renderer. */
+function splitWrite(entry) {
+  if (typeof entry === 'string') return { path: entry, edit: {} };
+  if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+    const { path, ...edit } = entry;
+    return { path, edit };
+  }
+  return null;
+}
+
 /** Turn a renderer's extraction into the facts the table asks about. */
 export async function factsFor(root, { command = null, writes = [] } = {}) {
   const resolved = await Promise.all(
-    writes.filter(Boolean).map(async (path) => ({ path, generated: await generatedBytes(root, path) })),
+    writes.filter(Boolean).map(async (entry) => {
+      const split = splitWrite(entry);
+      if (split === null) return { path: String(entry), generated: null, touches: false };
+      const fact = await generatedFact(root, split.path, split.edit);
+      return { ...fact, edit: split.edit };
+    }),
   );
   // Shell facts, read only when the payload carried a command: the same "pay for what
   // you use" rule as the lease facts below, which a payload with no command cannot touch.
@@ -205,9 +328,18 @@ export async function factsFor(root, { command = null, writes = [] } = {}) {
   if (resolved.length === 0) return { command, writes: resolved, leaseError: null, shell };
   const read = await readLeases(root);
   if (read.error !== null) return { command, writes: resolved, leaseError: read.error, shell };
-  const live = new Map(activeLeases(read).map((l) => [l.path, l]));
+  // Both sides of the comparison in the one spelling a claim and an edit can
+  // both reach: symlinks resolved, case folded when the repository's git
+  // compares case-insensitively. A claim made for `src/keep.mjs` must meet an
+  // edit that spells the same file `src/Keep.mjs` on a volume where those are
+  // one file, and an edit that reaches it through a symlinked directory.
+  const ignoreCase = coreIgnoreCase(root);
+  const live = new Map();
+  for (const l of activeLeases(read)) {
+    live.set(canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path, l);
+  }
   for (const w of resolved) {
-    const rel = leasePathFor(root, w.path);
+    const rel = canonicalLeasePath(root, w.path, { ignoreCase });
     w.lease = rel === null ? null : live.get(rel) ?? null;
   }
   return { command, writes: resolved, leaseError: null, shell };

package/src/agenthooks/opencode.mjs

@@ -0,0 +1,72 @@
+// The OpenCode v2 plugin this tool installs where the other harnesses get a
+// config entry (opencode.ai/v2/docs/build/plugins/server, read 2026-10-29).
+//
+// OpenCode has no hooks file to merge into: a plugin under `.opencode/plugins/`
+// is loaded as-is, so the tool owns this file's whole bytes and `rendered`
+// compares them. The plugin is a thin pipe: it forwards each tool call to the
+// same `agent-hook` entry point every other harness reaches, and translates
+// the answer — a denial (exit 2, `{"reason": …}` on stdout) into a thrown
+// error, which is how OpenCode blocks a tool call and shows the reason to the
+// model. Any other outcome lets the call through: a broken policy must not
+// lock a session, the same fail-open rule the shim follows.
+
+/**
+ * The plugin source for one repository.
+ *
+ * @param {{command: string, prompt?: boolean}} opts `command` is the
+ *   `agent-hook` entry point as one line (`<binary> pre-tool-use --harness
+ *   opencode`); the event word is replaced per call, so the binary and the
+ *   trailing flags must each be single words. `prompt` adds the session hook
+ *   that prepends the delivery packet to every prompt.
+ */
+export function renderOpencodePlugin({ command, prompt = false } = {}) {
+  const promptHook = prompt
+    ? `
+    await ctx.session.hook('prompt', async (event) => {
+      const result = ask('prompt-submit', { prompt: event.prompt.text, cwd: root });
+      if (result.status !== 0 || !result.stdout) return;
+      try {
+        const packet = JSON.parse(result.stdout);
+        if (packet && typeof packet.text === 'string' && packet.text) {
+          event.prompt.text = \`\${packet.text}\\n\\n\${event.prompt.text}\`;
+        }
+      } catch {
+        // a packet we cannot parse is no packet
+      }
+    });
+`
+    : '';
+  return `// Generated by simt-dev — do not edit; reinstall with:
+//   simt agent-hooks install --yes
+
+import { spawnSync } from 'node:child_process';
+
+// The entry point, one word per argument. The event is the first word after
+// the binary and is replaced per call; everything after it stands for every
+// event, so neither may contain a space.
+const [BIN, , ...REST] = ${JSON.stringify(command)}.split(' ');
+
+export default {
+  id: 'simt-dev',
+  async setup(ctx) {
+    const root = ctx.location.directory;
+    const ask = (event, payload) =>
+      spawnSync(BIN, [event, ...REST], { input: JSON.stringify(payload), encoding: 'utf8', cwd: root });
+
+    await ctx.tool.hook('execute.before', async (event) => {
+      if (!['shell', 'write', 'edit'].includes(event.tool)) return;
+      const result = ask('pre-tool-use', { tool: event.tool, input: event.input, cwd: root });
+      if (result.status !== 2) return;
+      let reason = 'simt-dev blocked the tool call';
+      try {
+        const doc = JSON.parse(result.stdout);
+        if (doc && typeof doc.reason === 'string' && doc.reason) reason = doc.reason;
+      } catch {
+        // the default stands
+      }
+      throw new Error(reason);
+    });
+${promptHook}  },
+};
+`;
+}

package/src/agenthooks/prompt.mjs

@@ -26,6 +26,7 @@ import { readManifest } from '../projection/manifest.mjs';
 import { DEFAULT_BRIEF_BYTES, PROMPT_CAP_BYTES } from '../brief/packet.mjs';
 import { assembleBrief } from '../brief/assemble.mjs';
 import { deliveryJson, factsFrom, promptText } from './render.mjs';
+import { repoRoot } from '../repo-root.mjs';
 
 /**
  * Whether this repository asked for a delivered packet, and the ceiling it asked for.
@@ -63,8 +64,11 @@ export async function deliverPrompt(row, payload) {
   const task = promptText(row, payload);
   if (task === null) return { skipped: 'the payload carries no prompt this harness documents' };
 
-  // The root is the same dialect fact for both events, so it is read the same way.
-  const root = factsFrom(row, payload).root;
+  // The root is the same dialect fact for both events, so it is read the same way —
+  // and resolved to the repository's top level the same way: the manifest, like the
+  // lease file, is a repository-relative fact, and a prompt submitted from a
+  // subdirectory must find it (review 0003 Q16).
+  const root = repoRoot(factsFrom(row, payload).root);
   const optIn = await promptOptIn(root);
   if (!optIn.optedIn) return { skipped: optIn.why };