simt-dev 0.2.1 → 0.3.0

package/src/agenthooks/decide.mjs

@@ -0,0 +1,123 @@
+// What a policy decides, given facts and one session's overrides.
+//
+// Pure, so the whole decision is testable without a harness: hand it the facts a
+// renderer would extract and an environment, and it answers. The filesystem is
+// consulted in exactly one place — `generatedBytes`, which asks whether a file being
+// written to holds bytes this tool generates — because that is the one fact a payload
+// cannot carry.
+//
+// Two properties are deliberate and both are about an author standing still:
+//
+// Every matching policy is reported, not the first. `git push --force` is a push and a
+// rewrite; a build that stopped at the first match would let `SIMT_ALLOW=push` lift the
+// approval rule and carry a force-push through, because the rewrite rule was never
+// consulted. Lifting a policy lifts that policy.
+//
+// No fact is not a violation. A payload whose shape we did not read — a harness that
+// renamed a tool, an agent writing through some tool we have never seen — yields no
+// command and no path, and the decision is to say nothing. Turning "we do not
+// understand this" into "blocked" makes the hook a false-positive machine, and a hook
+// that blocks real work is uninstalled the same afternoon.
+
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+import { parse } from '../projection/markers.mjs';
+import { ALLOW_ENV, EVENTS, POLICY_IDS, policiesFor } from './policy.mjs';
+
+/**
+ * The policies this session has lifted, and the names in `SIMT_ALLOW` that are not
+ * policies at all.
+ *
+ * An unknown name is reported rather than ignored: `SIMT_ALLOW=push,rewrit` typed once
+ * and relied on would otherwise look like a lift that did nothing, and the author would
+ * conclude the hook was broken rather than the spelling.
+ */
+export function overrides(env = {}) {
+  const raw = env[ALLOW_ENV];
+  const named = typeof raw === 'string' ? raw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+  return {
+    ids: new Set(named.filter((n) => POLICY_IDS.includes(n))),
+    unknown: named.filter((n) => !POLICY_IDS.includes(n)),
+  };
+}
+
+/** Whether one row applies to the facts. A row with no matcher reads the facts itself. */
+function applies(row, facts) {
+  if (row.inspects === 'command') {
+    return typeof facts.command === 'string' && row.match !== null && row.match.test(facts.command);
+  }
+  if (row.inspects === 'write') {
+    return (facts.writes ?? []).some((w) => w.generated !== null && w.generated !== undefined);
+  }
+  return false;
+}
+
+/**
+ * The decision for one event.
+ *
+ * `blocked` and `lifted` are ids, not rows, because the caller prints them and an id is
+ * what a reader types into `SIMT_ALLOW`. The messages carry their own override hint, so
+ * a denial is actionable without the reader knowing the variable exists.
+ */
+export function decide({ event = EVENTS[0], facts = {}, env = {} } = {}) {
+  const { ids: lifted, unknown } = overrides(env);
+  const matched = policiesFor(event).filter((p) => applies(p, facts));
+  const blocked = matched.filter((p) => !lifted.has(p.id));
+  return {
+    event,
+    decision: blocked.length > 0 ? 'deny' : 'allow',
+    blocked: blocked.map((p) => p.id),
+    lifted: matched.filter((p) => lifted.has(p.id)).map((p) => p.id),
+    unknown,
+    messages: blocked.map((p) => `${p.message} (override: ${ALLOW_ENV}=${p.id})`),
+    adrs: blocked.map((p) => p.adr),
+  };
+}
+
+/** Whether this file's bytes are generated: a region this tool writes, or a submodule. */
+function holdsRegion(text) {
+  // Both marker styles, because the region is written in whichever one the file's own
+  // syntax allows — `<!-- simt:begin -->` in markdown, `# simt:begin` in an
+  // .editorconfig. A malformed region is still a region: a begin marker with no end is
+  // the file somebody has already been editing by hand.
+  return parse(text).status !== 'absent' || parse(text, 'hash').status !== 'absent';
+}
+
+/** The submodule paths `.gitmodules` declares, as repository-relative directories. */
+async function submodules(root) {
+  const text = await readFile(join(root, '.gitmodules'), 'utf8').catch(() => null);
+  if (text === null) return [];
+  return text
+    .split('\n')
+    .map((line) => /^\s*path\s*=\s*(.+?)\s*$/.exec(line))
+    .filter(Boolean)
+    .map((m) => m[1].replace(/\/+$/, ''));
+}
+
+/**
+ * Why this path is not the author's to write, or null when it is.
+ *
+ * The reason is returned rather than a boolean because the two answers are different
+ * facts and the author of a fix needs to know which one applies: a region is repaired by
+ * editing its source, a submodule by committing in the other repository.
+ */
+export async function generatedBytes(root, file) {
+  const abs = resolve(root, file);
+  const text = await readFile(abs, 'utf8').catch(() => null);
+  if (text !== null && holdsRegion(text)) return 'region';
+  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';
+  }
+  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) })),
+  );
+  return { command, writes: resolved };
+}

package/src/agenthooks/policy.mjs

@@ -0,0 +1,78 @@
+// The policies an agent-time hook enforces, in one table.
+//
+// One table and four harnesses. The renderers in ./render.mjs map a harness's own
+// payload onto the facts named here and a decision back onto that harness's own JSON,
+// so a policy is written once and cannot be enforced in one harness and forgotten in
+// another — which is the failure the four vendor documents make easy: they agree on
+// nothing, not the config path, not the shape, not the name of the tool that runs a
+// shell command (Bash, Shell, run_command), not the key holding the command, not the
+// JSON the hook answers with. Every one of those differences lives in the renderer
+// beside the vendor page it was read from; the table only knows facts.
+//
+// The facts are deliberately few: the shell command an agent is about to run, and the
+// path it is about to write. A payload the renderer cannot recognise yields no facts,
+// and no fact is not a violation — guessing from a shape we did not read would block
+// real work in a harness whose payload changed under us.
+//
+// The messages are the bytes an author reads while being stopped, so each one names
+// the rule, the record that settled it, and the override that lifts it. An override
+// nobody is told about is a policy the author learns to route around instead of one
+// they can ask about.
+
+import { CLI } from '../name.mjs';
+
+/** The events an agent-time hook can answer, normalised across harnesses. */
+export const EVENTS = ['pre-tool-use'];
+
+/** The environment variable that lifts named policies for one session. */
+export const ALLOW_ENV = 'SIMT_ALLOW';
+
+/**
+ * One row per policy.
+ *
+ * `inspects` names the fact the matcher is handed, and `match` the condition. The
+ * `generated` row has no matcher because what it asks — does this file hold bytes this
+ * tool generates — is answered by reading the file, not by the text of a payload.
+ *
+ * Order matters where two policies match one command: `git push --force` is both a
+ * push and a rewrite, so both are reported and both have to be lifted before it runs.
+ */
+const POLICIES = [
+  {
+    id: 'push',
+    adr: 'ADR-001',
+    event: 'pre-tool-use',
+    inspects: 'command',
+    match: /(?:^|[\s;&|(])git\s+push(?:\s|$)/,
+    message: `Push needs explicit approval (ADR-001); ask the user.`,
+  },
+  {
+    id: 'rewrite',
+    adr: 'ADR-017',
+    event: 'pre-tool-use',
+    inspects: 'command',
+    match:
+      /--no-verify|git\s+commit\b[^;&|]*\s--amend|git\s+reset\s+--hard|git\s+rebase\b|git\s+push\b[^;&|]*(?:--force\b|\s-f\b)/,
+    message:
+      `Never amend, rebase, reset --hard, force-push or --no-verify unless asked; ` +
+      `each is the escape that turns the declared gates into a suggestion (ADR-017).`,
+  },
+  {
+    id: 'generated',
+    adr: 'ADR-036',
+    event: 'pre-tool-use',
+    inspects: 'write',
+    match: null,
+    message:
+      `That file carries bytes this tool generates, so an edit there is overwritten on the next ` +
+      `write; edit the source the region comes from, then run \`${CLI} sync --yes\` (ADR-036).`,
+  },
+];
+
+/** The policy ids, in table order: the vocabulary an override is checked against. */
+export const POLICY_IDS = POLICIES.map((p) => p.id);
+
+/** The rows for one event, so a renderer and the table cannot disagree about events. */
+export function policiesFor(event) {
+  return POLICIES.filter((p) => p.event === event);
+}

package/src/agenthooks/render.mjs

@@ -0,0 +1,240 @@
+// One renderer per harness: the payload in, the decision out, and the config written.
+//
+// Four harnesses read a hook and no two agree on anything. The config path, the event
+// name, the shape of the document, the tool name for a shell command, the key holding
+// the command, and the JSON a hook answers with are all different, and none of them is
+// the same fact. So this module owns the differences and `policy.mjs` owns none of
+// them:
+//
+//   claude       .claude/settings.json   PreToolUse      {"hooks":{E:[{matcher,hooks:[h]}]}}
+//   codex        .codex/hooks.json       PreToolUse      {"hooks":{E:[{matcher,hooks:[h]}]}}
+//   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
+//   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
+//
+// The paths are not written here. They come from the reader table (R14) because that is
+// where each one was verified against its vendor page, and a second copy of a verified
+// fact is a copy that drifts the first time a vendor moves the file.
+//
+// Two things are recorded per row that a reader of the code cannot get from the code:
+// the page the shape was read from, and whether anything about the row is inferred.
+// An inferred key is marked as inferred rather than presented as documented, because
+// the failure that matters is not a missing policy — it is a policy that silently never
+// fires in a harness whose payload we guessed wrong.
+
+import { CLI } from '../name.mjs';
+import { LOADERS } from '../projection/loaders.mjs';
+import { EVENTS } from './policy.mjs';
+
+/** The seconds a hook is allowed before the harness gives up on it. */
+const TIMEOUT_SECONDS = 10;
+
+/**
+ * The hook's own entry point, as it appears inside every harness's config.
+ *
+ * A repository that has this tool has its binary on PATH, and `--harness` is explicit
+ * rather than detected from the payload: a hook that guessed would answer in the wrong
+ * harness's dialect when a payload arrived in an unexpected shape, and the harness would
+ * read a decision it does not understand as no decision at all.
+ */
+export function hookCommand(id) {
+  return `${CLI} agent-hook ${EVENTS[0]} --harness ${id}`;
+}
+
+/** The path a config file lives at, from the reader table rather than a second list. */
+export function hookPath(id) {
+  const row = LOADERS.find((l) => l.id === id);
+  return row?.hooks?.path ?? null;
+}
+
+/** The reader rows that document a hooks file, and the ones that document none. */
+export function hookRows() {
+  return LOADERS.map((l) => ({
+    id: l.id,
+    label: l.label,
+    path: l.hooks?.path ?? null,
+    note: l.hooks ? l.hooks.verified : (l.hooksNote ?? 'no hooks file is documented'),
+  }));
+}
+
+const ADAPTERS = {
+  claude: {
+    id: 'claude',
+    event: 'PreToolUse',
+    matcher: 'Bash|Edit|Write|MultiEdit|NotebookEdit',
+    denyExit: 2,
+    verified: 'docs.claude.com/en/docs/claude-code/hooks, read 2026-10-16',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
+      writes: ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(p.tool_name)
+        ? [p.tool_input?.file_path].filter(Boolean)
+        : [],
+    }),
+    deny: (message) => ({
+      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
+    }),
+  },
+  codex: {
+    id: 'codex',
+    event: 'PreToolUse',
+    matcher: 'Bash|apply_patch',
+    denyExit: 2,
+    verified: 'developers.openai.com/codex/hooks, read 2026-10-16',
+    // Codex is the one harness that will not run a hook until a person has approved the
+    // exact definition, keyed by its hash — so an install that does not say this leaves
+    // the repository with a hook that never fires and no way to tell why.
+    trust: 'Codex skips a hook nobody has trusted: review it with /hooks, or the entry stays inert.',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
+      // apply_patch carries its targets inside the patch text, one header line per file.
+      writes:
+        p.tool_name === 'apply_patch'
+          ? [...String(p.tool_input?.command ?? '').matchAll(/^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm)].map((m) => m[1].trim())
+          : [],
+    }),
+    deny: (message) => ({
+      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
+    }),
+  },
+  cursor: {
+    id: 'cursor',
+    event: 'preToolUse',
+    matcher: 'Shell|Write|Edit',
+    denyExit: 2,
+    verified: 'cursor.com/docs/agent/hooks, read 2026-10-16',
+    root: (p) => p.working_directory ?? p.cwd,
+    extract: (p) => ({
+      command: p.tool_name === 'Shell' ? (p.tool_input?.command ?? null) : null,
+      writes: ['Write', 'Edit'].includes(p.tool_name)
+        ? [p.tool_input?.file_path ?? p.tool_input?.path].filter(Boolean)
+        : [],
+    }),
+    deny: (message) => ({ permission: 'deny', user_message: message, agent_message: message }),
+  },
+  antigravity: {
+    id: 'antigravity',
+    event: 'PreToolUse',
+    matcher: 'run_command|write_to_file|replace_file_content|multi_replace_file_content',
+    // The page documents the decision JSON and not an exit code, so the denial travels
+    // in the JSON only: a non-zero exit whose meaning the vendor has not stated is not
+    // a block, it is a guess that happens to be loud.
+    denyExit: 0,
+    verified: 'antigravity.google/docs/hooks, read 2026-10-16',
+    root: (p) => p.workspacePaths?.[0] ?? p.cwd,
+    extract: (p) => {
+      const call = p.toolCall ?? {};
+      const args = call.args ?? {};
+      return {
+        command: call.name === 'run_command' ? (args.CommandLine ?? null) : null,
+        writes: ['write_to_file', 'replace_file_content', 'multi_replace_file_content'].includes(call.name)
+          ? [args.TargetFile].filter(Boolean)
+          : [],
+      };
+    },
+    deny: (message) => ({ decision: 'deny', reason: message }),
+  },
+};
+
+/** The four adapters, in the order the reader table lists them. */
+export function adapters() {
+  return hookRows()
+    .filter((r) => r.path !== null)
+    .map((r) => ADAPTERS[r.id])
+    .filter(Boolean);
+}
+
+export function adapter(id) {
+  const row = ADAPTERS[id];
+  return row && hookPath(id) !== null ? row : null;
+}
+
+/** The facts a payload carries, and the root it names. An unknown shape yields none. */
+export function factsFrom(row, payload) {
+  return { root: row.root(payload) ?? process.cwd(), ...row.extract(payload ?? {}) };
+}
+
+/** The document to print for a decision, or null when there is nothing to say. */
+export function decisionJson(row, decision) {
+  if (decision.decision !== 'deny') return null;
+  return row.deny(decision.messages.join('\n'));
+}
+
+// ---------------------------------------------------------------------------
+// The config file: reading ours out of somebody else's JSON, and putting it back.
+// ---------------------------------------------------------------------------
+
+/** The name antigravity's document keys its hooks by; its events live under a name. */
+const NAMED_HOOK = 'simt-dev-policies';
+
+/** Where a document keeps its event keys. Antigravity is the odd one: by name. */
+function container(row, config, { create = false } = {}) {
+  if (row.id === 'antigravity') {
+    if (config[NAMED_HOOK] === undefined && create) config[NAMED_HOOK] = {};
+    return config[NAMED_HOOK] ?? null;
+  }
+  // Before `hooks`, so a file this tool creates reads the way the vendor's own example
+  // does rather than with the version key appended wherever it happened to land.
+  if (row.id === 'cursor' && config.version === undefined && create) config.version = 1;
+  if (config.hooks === undefined && create) config.hooks = {};
+  return config.hooks ?? null;
+}
+
+/** The group this tool owns for one event, in that harness's shape. */
+function group(row) {
+  const command = hookCommand(row.id);
+  if (row.id === 'cursor') {
+    // failClosed is set because a hooks file this tool wrote should not silently
+    // degrade to fail-open on its own crash: the vendor's default turns a broken hook
+    // into an absent one, and the whole point of writing it is that it runs.
+    return { command, timeout: TIMEOUT_SECONDS, matcher: row.matcher, failClosed: true };
+  }
+  return { matcher: row.matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+}
+
+/** Whether a group is this tool's, judged by the command it runs and not by position. */
+function ours(entry) {
+  return JSON.stringify(entry).includes(`${CLI} agent-hook`);
+}
+
+function entries(row, config) {
+  const box = container(row, config);
+  const list = box?.[row.event];
+  return Array.isArray(list) ? list : [];
+}
+
+/** Our entries in this document, for `status`; the document is not modified. */
+export function installedIn(row, config) {
+  return entries(row, config).filter(ours);
+}
+
+/**
+ * The document with this tool's hook added, everything else left alone.
+ *
+ * Written as JSON with two spaces and a trailing newline because that is what a file in
+ * a repository reads like; a config that is rewritten with different indentation on
+ * every run is a diff nobody can review. Keys this tool does not own are preserved
+ * exactly, including their order, because the file belongs to the repository.
+ */
+function withHook(row, config) {
+  const box = container(row, config, { create: true });
+  const kept = entries(row, config).filter((e) => !ours(e));
+  box[row.event] = [...kept, group(row)];
+  return config;
+}
+
+/** The text `install` would write, or the reason the existing file cannot be read. */
+export function rendered(row, existing) {
+  if (existing === null) return { text: `${JSON.stringify(withHook(row, {}), null, 2)}\n`, action: 'created' };
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch (e) {
+    return { error: `not valid JSON (${e.message}); left alone` };
+  }
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    return { error: 'not a JSON object; left alone' };
+  }
+  const text = `${JSON.stringify(withHook(row, config), null, 2)}\n`;
+  return { text, action: text === existing ? 'unchanged' : 'updated' };
+}

package/src/argv.mjs

@@ -34,9 +34,31 @@ export const BOOL_FLAGS = new Set([
   'plan',
   'help',
   'version',
+  // JSON output: indent it. Off by default because a pipe is not a person, and the
+  // bytes an agent pays for indentation are bytes it never reads.
+  'pretty',
   'accept-conflicts',
   'backup',
   'list',
+  // tokens: measure every repository under the root, not just the one. Plan 0003 R06
+  // names this flag `--workspace`, and that name has been a VALUE flag since plan
+  // 0002 - it is where the skill sources live. One flag with two meanings is the
+  // silent-ignore defect this file's header refuses, so the meter's switch is named
+  // for what it selects.
+  'repos',
+  // harness detect: also report the directories in the user's home. Off by default
+  // because the home directory belongs to the reader rather than the repository, and a
+  // command whose output changes because something was installed elsewhere is one a
+  // reader stops trusting.
+  'user',
+  // harness loaders: print the vendor facts (order, caps, imports, hooks and MCP
+  // config) without measuring a repository. The measurement is the other mode; this is
+  // the one that answers "what does this reader do", which does not depend on the repo.
+  'table',
+  // sync: name every line the inferability filter dropped and the evidence behind it
+  // (plan 0003 R09). Off by default because a count is enough to act on; the per-line
+  // detail is what an author needs, and a reader is not an author.
+  'explain',
 ]);
 
 export const VALUE_FLAGS = new Set([
@@ -52,6 +74,32 @@ export const VALUE_FLAGS = new Set([
   'variant',
   'from',
   'surfaces',
+  // graph lint: which specification to check the skills against. A value rather than a
+  // boolean because "lint against the spec" would not say WHICH spec, and a lint that
+  // silently applied an unnamed set of rules is the decoration this repository exists
+  // to refuse. One is on offer today, so the command rejects any other by name.
+  'spec',
+  // harness loaders: which reader to report. A value rather than a boolean because
+  // "--loader" would not say WHICH loader, and a report that silently applied to all
+  // of them would be decoration that misdescribes the artefact.
+  'reader',
+  // harness loaders: measure as if the agent were standing here. The chain rows walk
+  // the project root down to the working directory, so this is what makes them mean
+  // anything beyond the root document.
+  'at',
+  // tokens: split a local Claude Code or Codex session transcript into rules, file
+  // reads and tool output. Local paths only (ADR-075).
+  'session',
+  // bench run / report: arms, harness adapter, model id, repetition count, regrade target and arm comparison.
+  'arm',
+  'harness',
+  'model',
+  'reps',
+  'regrade',
+  'compare',
+  // plan done: the test command that proves the slice. Plan 0003 R31.
+  'test',
+  'state',
 ]);
 
 /**
@@ -67,7 +115,7 @@ export const VALUE_FLAGS = new Set([
  * is a superset of the old behaviour, not a replacement: `--skill a,b` parsed before it
  * parses now.
  */
-export const REPEATABLE_FLAGS = new Set(['skill']);
+export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare']);
 
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
@@ -121,6 +169,12 @@ export function parse(argv) {
           return { ok: false, code: usage(`--${raw} must be a non-negative integer, received ${value}`) };
         }
         flags[camel(raw)] = n;
+      } else if (raw === 'reps') {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1) {
+          return { ok: false, code: usage(`--reps must be a positive integer, received ${value}`) };
+        }
+        flags.reps = n;
       } else {
         const key = camel(raw);
         flags[key] = REPEATABLE_FLAGS.has(raw)