simt-dev 0.7.0 → 0.8.0

package/rules/mdc/slice-commit.mdc

@@ -15,6 +15,35 @@ one is a mechanical procedure with a fixed order, because every step after it de
 on the one before: you cannot review a diff you have not staged, and you cannot claim
 evidence for a test you have not run.
 
+## Commit message
+
+A message is read by the next agent before they are told what to do. It says what the
+commit is, what it answers, and what it changed, so a reader never reconstructs that
+from the diff.
+
+The title is Conventional Commits: imperative, no trailing period, a short scope slug
+that names the subsystem — not a ticket id.
+
+    feat(dispatcher): skip the test gate on a push that already passed
+
+The body is plain sections in this order. Drop any section that has nothing to say; a
+one-line commit needs none of them.
+
+    What: <one sentence — what this commit is>
+    Why: <what it answers — the task, defect, or decision that asked for it>
+    Before: <the state this replaces, briefly>
+    After: <the state it leaves, briefly>
+
+"Before" and "After" are a short state summary, not a diff: enough to see what moved,
+not enough to need the patch. Cite a decision record where one settles the change, and
+never claim a test in the body that was not run on this tree.
+
+The message ends with a trailer on its own line, after the body - attribution to the
+tool, in the form git renders as a co-author. It is part of the message, not a
+section, so it stays even when every section is dropped:
+
+    Co-Authored-By: Simt Dev <noreply@simt.space>
+
 ## Order
 
 1. **Run the focused test the change needs**, through the repository's own runner,
@@ -24,10 +53,8 @@ evidence for a test you have not run.
    alone. Report what you left alone; silence about it reads as "I reverted it".
 3. **Read the staged diff.** Not the working tree — the diff. It is what will be
    committed, and it is the last chance to notice a file that does not belong.
-4. **Write the message.** Conventional Commits, imperative subject, no trailing period:
-   `fix(gates): declare only gates a repo can run, and report the ones it cannot`.
-   The subject says what changed; the body says why, and what was deliberately not
-   changed.
+4. **Write the message in the format above.** The title names what changed; the body
+   says why, and what was deliberately not changed.
 5. **Commit.** `git commit`, non-interactive. Report the SHA.
 6. **Stop.**
 
@@ -44,6 +71,32 @@ Never use `--no-verify`. A hook that fails is telling you something about the ch
 skipping it turns a gate into a suggestion and the next person has no way to know it
 was skipped.
 
+Once the push is approved, you may push directly without the pre-push gate re-running
+the full suite when you already ran that suite green on the current state and changed
+nothing since: the gate records every run against the tree it ran on, recognises that
+evidence, and skips the re-run, reporting the skip and the record that earned it.
+Cite the already-passing run as the pass — do not claim a re-run that did not happen.
+(ADR-120)
+
+## Worktrees
+
+A worktree is the unit of isolation for concurrent work. The rules that keep it honest:
+
+- **One agent, one worktree, one slice.** Never direct two agents at the same files
+  concurrently; give each its own worktree and a slice whose files do not overlap.
+- **Start from the record, not from memory.** `simt slice start <id>` creates the
+  worktree for the tracker row and returns its path; work in that path, not the main
+  checkout.
+- **Finish where you started.** `simt slice finish <id>` runs the declared gates and
+  commits from the worktree; `simt plan done <id> <sha>` records the SHA in the main
+  checkout's tracker. A slice is not done when its worktree is green — it is done
+  when the tracker row is complete and the SHA is recorded.
+- **Leave the worktree when the slice is done.** A finished worktree that still holds
+  a dirty tree is a claim about work that is not committed; remove it, and report what
+  you left behind if there was any.
+- **Never rewrite history across worktrees.** A rebase, reset or amend in one worktree
+  changes the base every other worktree branched from; coordinate it, or do not do it.
+
 ## What never belongs in a commit
 
 - Failing, partial, or unrun work. A commit is a claim; a partial one is a false one.

package/src/advice/advice.mjs

@@ -21,8 +21,9 @@
 // records or a prices table price the tokens, total tokens otherwise. Ordering by a number
 // that does not exist for any run would be nondeterminism, not economics.
 import { classifyTask } from '../brief/kind.mjs';
-import { computeRunCost, isRunResolved, loadPrices, loadRunRecords } from '../bench/report.mjs';
-import { loadTasks } from '../bench/tasks.mjs';
+import { computeRunCost, isRunResolved, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
+import { loadTasks } from '../measure/tasks.mjs';
 import { CONFIG_DIR } from '../name.mjs';
 
 /**

package/src/agenthooks/prompt.mjs

@@ -60,7 +60,7 @@ export async function promptOptIn(root) {
  * a minute while a repository is walked — is how the hook gets uninstalled, and the
  * packet is not worth a prompt that cannot be typed.
  */
-export async function deliverPrompt(row, payload) {
+export async function deliverPrompt(row, payload, { root: flagRoot } = {}) {
   const task = promptText(row, payload);
   if (task === null) return { skipped: 'the payload carries no prompt this harness documents' };
 
@@ -68,7 +68,10 @@ export async function deliverPrompt(row, payload) {
   // 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);
+  // `--root` outranks the payload here as it does on the decision path: a packaged hook
+  // runs from the plugin directory, so the payload's cwd would name the wrong repository
+  // and find no manifest, which delivered nothing and looked like an opt-out.
+  const root = repoRoot(factsFrom(row, payload, { root: flagRoot }).root);
   const optIn = await promptOptIn(root);
   if (!optIn.optedIn) return { skipped: optIn.why };
 

package/src/agenthooks/render.mjs

@@ -48,6 +48,7 @@
 
 import { CLI } from '../name.mjs';
 import { LOADERS } from '../projection/loaders.mjs';
+import { harnessHooks, harnessPayloads } from '../harness/records.mjs';
 import { renderOpencodePlugin } from './opencode.mjs';
 import { EVENTS } from './policy.mjs';
 import { AGENT_HOOK_SHIM } from './shim.mjs';
@@ -183,188 +184,93 @@ function patchFiles(text) {
   return files.filter((f) => f.path !== '');
 }
 
-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,
-      // NotebookEdit spells its target `notebook_path`, not `file_path`: a key list
-      // that misses it is a lease the notebook can walk straight through (review
-      // 0003 Q16). Edit details travel with the path so the generated-region
-      // check can tell an edit outside the region from one inside it (Q17).
-      writes: ['Edit', 'Write', 'MultiEdit'].includes(p.tool_name)
-        ? [writeOf(p.tool_input?.file_path, p.tool_input)].filter(Boolean)
-        : p.tool_name === 'NotebookEdit'
-          ? [writeOf(p.tool_input?.notebook_path, p.tool_input)].filter(Boolean)
-          : [],
-    }),
-    deny: (message) => ({
-      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
-    }),
-    // The delivery door. `additionalContext` is documented for this event and is
-    // wrapped into the conversation at the point the hook fired, which is why the
-    // packet goes here rather than into a system prompt: the cached prefix survives.
-    prompt: {
-      event: 'UserPromptSubmit',
-      verified: 'code.claude.com/docs/en/hooks, read 2026-10-19',
-      context: (text) => ({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }),
-    },
-    post: {
-      event: 'PostToolUse',
-      matcher: 'Bash',
-      verified: 'code.claude.com/docs/en/hooks, read 2026-10-19',
-      context: (text) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }),
-    },
-  },
-  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;
-      // a move names its destination on the `+++` line after `*** Move File:`, and the
-      // destination is the file the move writes (review 0003 Q16).
-      writes:
-        p.tool_name === 'apply_patch'
-          ? patchWrites(String(p.tool_input?.command ?? ''))
-          : [], // entries carry {path, patch} so the region check maps hunks (Q17)
-    }),
-    deny: (message) => ({
-      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
-    }),
-    prompt: {
-      event: 'UserPromptSubmit',
-      verified: 'developers.openai.com/codex/hooks, read 2026-10-19',
-      context: (text) => ({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }),
-    },
-    post: {
-      event: 'PostToolUse',
-      matcher: 'Bash',
-      verified: 'developers.openai.com/codex/hooks, read 2026-10-19',
-      context: (text) => ({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } }),
-    },
-  },
-  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)
-        ? [writeOf(p.tool_input?.file_path ?? p.tool_input?.path, p.tool_input)].filter(Boolean)
-        : [],
-    }),
-    deny: (message) => ({ permission: 'deny', user_message: message, agent_message: message }),
-    // beforeSubmitPrompt is documented as continue/block and nothing else, so there is no
-    // key to deliver a packet in. Writing the entry anyway would put a command that reads
-    // a repository on the path of every prompt a person types, to say nothing.
-    prompt: null,
-    post: null,
-  },
-  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)
-          ? [writeOf(args.TargetFile, args)].filter(Boolean)
-          : [], // CodeContent/old/new travel with the path for the region check (Q17)
-      };
-    },
-    deny: (message) => ({ decision: 'deny', reason: message }),
-    // No prompt event is documented for this harness's hooks file, and a guessed event
-    // name is a hook that never fires while its config says it does.
-    prompt: null,
-    post: null,
-  },
-  gemini: {
-    id: 'gemini',
-    event: 'BeforeTool',
-    matcher: 'run_shell_command|write_file|replace',
-    // The vendor's timeout unit is milliseconds (default 60000), not the seconds every
-    // other row uses; a bare 10 here would be a ten-millisecond budget, which is a hook
-    // that never finishes. The row carries its own value so the shared constant stays
-    // honest for the four vendors that measure in seconds.
-    timeout: 10000,
-    // The reference documents the decision JSON and an exit-2 system block; the denial
-    // travels in the JSON, as antigravity does.
-    denyExit: 0,
-    verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
-    root: (p) => p.cwd,
-    extract: (p) => ({
-      command: p.tool_name === 'run_shell_command' ? (p.tool_input?.command ?? null) : null,
-      writes: ['write_file', 'replace'].includes(p.tool_name)
-        ? [writeOf(p.tool_input?.file_path, p.tool_input)].filter(Boolean)
+// The payload a hook reads: where the tool name and its input sit, and the keys that
+// name a command and a file. A record cannot carry a function, so the engine reads the
+// record's keys and applies them: a harness that puts a field somewhere new is a new
+// record, not a new branch here (Q71).
+function pick(obj, keys) {
+  if (!obj || typeof obj !== 'object') return null;
+  for (const k of keys) {
+    const v = obj[k];
+    if (v !== undefined && v !== null) return v;
+  }
+  return null;
+}
+
+function extractOf(spec) {
+  return (p) => {
+    const payload = p ?? {};
+    // antigravity nests the call under `toolCall`; the rest name the tool at the top
+    // level. `toolNameKey` is present only on the nested shape, so its presence is
+    // the detector.
+    const nested = spec.toolNameKey !== undefined;
+    const call = nested ? (payload[spec.toolKey] ?? {}) : null;
+    const toolName = nested ? call[spec.toolNameKey] : payload[spec.toolKey];
+    const input = nested ? (call[spec.inputSubKey] ?? {}) : (payload[spec.inputKey] ?? {});
+    return {
+      command: (spec.shellTools ?? []).includes(toolName) ? (input[spec.commandKey] ?? null) : null,
+      // apply_patch carries its targets inside the patch text (writesFrom: "patch");
+      // every other write tool names its file through the path keys.
+      writes: (spec.writeTools ?? []).includes(toolName)
+        ? spec.writesFrom === 'patch'
+          ? patchWrites(String(input[spec.commandKey] ?? ''))
+          : [writeOf(pick(input, spec.pathOverrides?.[toolName] ?? spec.pathKeys), input)].filter(Boolean)
         : [],
-    }),
-    deny: (message) => ({ decision: 'deny', reason: message }),
-    // BeforeAgent appends text to the prompt for this turn only — the same lifetime as a
-    // brief. The documented output has no hookEventName field, unlike Claude's.
-    prompt: {
-      event: 'BeforeAgent',
-      verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
-      context: (text) => ({ hookSpecificOutput: { additionalContext: text } }),
-    },
-    // AfterTool appends to the tool result; its input carries tool_response, which is
-    // what the lesson recall reads.
-    post: {
-      event: 'AfterTool',
-      verified: 'geminicli.com/docs/hooks/reference/, read 2026-10-26',
-      context: (text) => ({ hookSpecificOutput: { additionalContext: text } }),
-    },
-  },
-  opencode: {
-    id: 'opencode',
-    event: 'execute.before',
-    matcher: 'shell|write|edit',
-    // The plugin is a file the tool owns whole, not a config entry to merge:
-    // `file` routes `rendered` and `hookDocument` to its source (opencode.mjs).
-    file: true,
-    // A thrown error is the block; exit 2 is how the entry point signals it,
-    // and the reason the plugin throws is what `deny` prints.
-    denyExit: 2,
-    verified: 'opencode.ai/v2/docs/build/plugins/server, read 2026-10-29',
-    root: (p) => p.cwd,
-    extract: (p) => ({
-      command: p.tool === 'shell' ? (p.input?.command ?? null) : null,
-      writes: ['write', 'edit'].includes(p.tool) ? [writeOf(p.input?.path, p.input)].filter(Boolean) : [],
-    }),
-    deny: (message) => ({ reason: message }),
-    // session.hook('prompt') admits the prompt; the packet goes in front of it.
-    prompt: {
-      event: 'prompt',
-      verified: 'opencode.ai/v2/docs/build/plugins/server, read 2026-10-29',
-      context: (text) => ({ text }),
+    };
+  };
+}
+
+// The record's `rootKeys`: a list of accessor paths, first non-null wins. The caller
+// applies its `?? process.cwd()` floor (factsFrom).
+function rootOf(spec) {
+  return (p) => {
+    for (const path of spec.rootKeys ?? []) {
+      let v = p;
+      for (const seg of path) v = v?.[seg];
+      if (v !== undefined && v !== null) return v;
+    }
+    return null;
+  };
+}
+
+// The `__SIMT_TEXT__` sentinel in a record's deny and delivery templates: the text a
+// decision or a delivery carries is substituted for it, and JSON.stringify downstream
+// escapes whatever it carries.
+const TEXT = '__SIMT_TEXT__';
+
+function applyText(value, text) {
+  if (typeof value === 'string') return value === TEXT ? text : value;
+  if (Array.isArray(value)) return value.map((v) => applyText(v, text));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = applyText(v, text);
+    return out;
+  }
+  return value;
+}
+
+// The hooks dialect per harness, as records (Q71): the data a config document and a
+// decision are shaped by, with the page each shape was read from. What a record cannot
+// carry is attached here — `root` and `extract` read the record's payload keys, and
+// `deny`, `prompt.context` and `post.context` apply its templates. Module-internal on
+// purpose: `adapters()` and `adapter()` are the only doors in, and both check the
+// reader table, so an id with no hooks file is no adapter.
+const HOOKS = harnessHooks();
+const PAYLOADS = harnessPayloads();
+
+const ADAPTERS = Object.fromEntries(
+  Object.entries(HOOKS).map(([id, h]) => [
+    id,
+    {
+      ...h,
+      root: rootOf(PAYLOADS[id]),
+      extract: extractOf(PAYLOADS[id]),
+      deny: (message) => applyText(h.deny, message),
+      ...(h.prompt ? { prompt: { ...h.prompt, context: (text) => applyText(h.prompt.delivery, text) } } : {}),
+      ...(h.post ? { post: { ...h.post, context: (text) => applyText(h.post.delivery, text) } } : {}),
     },
-    post: null,
-  },
-};
+  ]),
+);
 
 /** The six adapters, in the order the reader table lists them. */
 export function adapters() {

package/src/agenthooks/shim.mjs

@@ -4,7 +4,7 @@
 // harness's PATH. A harness config naming the bare `simt` binary therefore
 // runs nothing on Claude (a non-2 exit is silent: no enforcement) and blocks
 // every tool call on Cursor (its hook fails closed). The fix is a shim beside
-// the git shims, resolved the same way: `.simt-hooks/agent-hook` locates the
+// the git shims, resolved the same way: `.simt/hooks/agent-hook` locates the
 // dispatcher with the shared `renderLocator` block and hands over, so every
 // harness config names the shim and never the bare binary (review 0003 Q21).
 //

package/src/agents/render.mjs

@@ -25,9 +25,12 @@ import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { PACKAGE_ROOT } from '../workspace.mjs';
-import { splitFrontmatter } from '../memory/decide.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 import { LOADERS } from '../projection/loaders.mjs';
 import { journaledWriteFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
+import { readBefore } from '../diff.mjs';
+import { readIfExists } from '../util/fs.mjs';
 
 /** The one agent this tool ships, and the filename stem every harness shares. */
 const AGENT_FILE = 'simt-agent.md';
@@ -149,7 +152,7 @@ function parseSimpleFront(front) {
  */
 export async function loadAgent() {
   const raw = await readFile(join(PACKAGE_ROOT, 'agents', AGENT_FILE), 'utf8');
-  const { front, body } = splitFrontmatter(raw);
+  const { front, body } = parseFrontmatter(raw);
   const meta = parseSimpleFront(front ?? '');
   if (!meta.name || !meta.description) {
     throw new Error(`${AGENT_FILE} must declare a name and a description in its frontmatter`);
@@ -213,15 +216,6 @@ export function rendered(adapterRow, agent, existing) {
   return { text, action: 'updated' };
 }
 
-/** Read a file as UTF-8, or null when it is not there. */
-async function readIfExists(path) {
-  try {
-    return await readFile(path, 'utf8');
-  } catch {
-    return null;
-  }
-}
-
 /**
  * The agent files a repository should carry, one per harness that documents an
  * agents directory, plus the companion skill file. Reads each existing file and
@@ -252,13 +246,16 @@ export async function planAgents(root, { harness } = {}) {
  * Skips files that are already unchanged. Returns the paths written.
  */
 export async function writeAgentPlan(root, journal, plan) {
-  const written = [];
-  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
-    await mkdir(join(root, dirname(p.path)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, p.path), p.text);
-    written.push(p.path);
-  }
-  return written;
+  const changes = await Promise.all(
+    plan
+      .filter((x) => x.action !== 'unchanged')
+      .map(async (p) => {
+        const path = join(root, p.path);
+        return change({ path, before: await readBefore(path), after: p.text, owner: 'agents', reason: p.action });
+      }),
+  );
+  await applyPlan(root, changes, { mode: { apply: true }, journal, commit: false });
+  return plan.filter((x) => x.action !== 'unchanged').map((p) => p.path);
 }
 
 /**

package/src/api.mjs

@@ -0,0 +1,31 @@
+// The library surface: the read commands as data (review 0003 Q63).
+//
+// Every function here is the one the CLI and the MCP tools already call. Nothing in
+// this file renders: a caller that wants text, JSON or an MCP result renders these
+// results itself, which is the whole point - a UI, a harness and a terminal asking the
+// same question must not get three answers, and they cannot disagree if they are
+// reading one function's return value.
+//
+// The write half arrives through `run(command, input)`: a writer still renders its plan
+// from the command module, because a person reviews that diff before it is applied
+// (ADR-001), but a library caller now gets that plan back as text and documents instead
+// of having it printed at a terminal it does not own. `run` resolves the same registry
+// and calls the same handler `dispatch` does, so the two surfaces cannot answer
+// differently.
+//
+// The exports map in package.json points `import 'simt-dev'` here, and keeps
+// `./src/*` because the plugin runtime and the harness shims import deep paths.
+// Removing that subpath would break them to make the surface look tidier.
+
+export { run, renderText, renderJson } from './run.mjs';
+export { checkRepo, checkTargets, checkTarget, frozenFindings } from './commands/sync.mjs';
+export { diagnose, serialisedFindings } from './commands/doctor.mjs';
+export { rulesCatalogue, rulesWhyFacts } from './commands/rules.mjs';
+export { skillsBriefFacts, skillsFindFacts, skillsShowFacts, skillsWhyFacts } from './commands/skills.mjs';
+export { assembleBrief } from './brief/assemble.mjs';
+export { loadRegistry } from './graph/load.mjs';
+export { discover } from './compare/discover.mjs';
+export { buildRows, resolveConcurrency, summarise } from './compare/row.mjs';
+export { planNext } from './plan/index.mjs';
+export { buildPrBody } from './prbody.mjs';
+export { federationAccess, readFederation } from './federation/config.mjs';

package/src/argv.mjs

@@ -26,6 +26,11 @@ import { EXIT } from './output/index.mjs';
 // mean something, which it could not while three accepted flags had no description.
 
 export const BOOL_FLAGS = new Set([
+  // bench ablate: compare across harness, model and experiment groups. The command
+  // read `flags.crossGroup` while the parser accepted no such flag, so the override
+  // existed only in the error message that told the reader to pass it (review 0003
+  // Q62, found by the spec-vs-parser drift test).
+  'cross-group',
   'json',
   'all',
   'dry-run',
@@ -39,6 +44,14 @@ export const BOOL_FLAGS = new Set([
   'pretty',
   'accept-conflicts',
   'backup',
+  // init: opt out of the agent files and the agent-hooks in one flag. The parser's
+  // `no-` convention spells the flag as a negation of the positive `agents`, so the
+  // positive name is what belongs here and `init` reads `flags.agents === false` -
+  // the user-facing flag stays `--no-agents`. They are the two halves of the same
+  // decision - which harnesses the adoption speaks to - and the standalone agents /
+  // agent-hooks install commands remain for a repo that wants them later. Off by
+  // default because the adoption writes them by default.
+  'agents',
   '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
@@ -89,6 +102,10 @@ export const BOOL_FLAGS = new Set([
   // bench.json marked unmeasured, and a lint that failed it on arrival would make
   // every new pack red before its author wrote the rule (plan 0003 R45).
   'require-measured',
+  // bench mine: restore the old "reflect exactly this history" semantics by
+  // deleting task files the current history does not reproduce. Off by default
+  // because mining is append-only (review 0003 Q48).
+  'replace',
   // distill: propose the summary from the configured local chat model instead of
   // the deterministic outline. Off by default: no model in the default path (P1),
   // and a model that is not asked for should not be opened against (ADR-090).
@@ -166,6 +183,9 @@ export const VALUE_FLAGS = new Set([
   // lease: how long the claim lasts, in seconds. A value, because "a lease is short"
   // is not a number any reader can act on, and an expiry nobody chose is an expiry
   // nobody can plan around (plan 0003 R54, ADR-101).
+  // lessons capture: how long a captured candidate stays eligible. A value, because a
+  // default would be a deadline nobody chose (review 0003 Q62, found by the drift test).
+  'expires',
   'ttl',
   // map: outline (paths), names (exported symbols) or signatures (the line).
   // A boolean would not say which of the three the caller wanted.
@@ -184,6 +204,10 @@ export const VALUE_FLAGS = new Set([
   // name only the author's branch knows, and the default (origin/main, then main)
   // is a guess the report states out loud rather than a question it asks.
   'base',
+  // slice start: the id for a prompt slice, overriding the slug derived from the
+  // prompt text. A value, because the derived slug is a guess a reader may want to
+  // pin, and a flag without a value would not say what to name the slice.
+  'id',
 ]);
 
 /**
@@ -229,6 +253,11 @@ export function parse(argv) {
   const flags = {};
   const positional = [];
   let passthrough = false;
+  // `--` is consumed as a separator, but its presence is a fact a command may need:
+  // `slice start -- "<text>"` reads the prompt as everything after the marker, and a
+  // positional that merely happens to sit there is a different command. Carried as a
+  // flag so it reaches the command the way every other parsed fact does.
+  let dashdash = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -239,6 +268,7 @@ export function parse(argv) {
     }
     if (arg === '--') {
       passthrough = true;
+      dashdash = true;
       continue;
     }
 
@@ -281,15 +311,30 @@ export function parse(argv) {
         flags.reps = n;
       } else {
         const key = camel(raw);
-        flags[key] = REPEATABLE_FLAGS.has(raw)
-          ? [...(Array.isArray(flags[key]) ? flags[key] : []), value]
-          : value;
+        if (REPEATABLE_FLAGS.has(raw)) {
+          flags[key] = [...(Array.isArray(flags[key]) ? flags[key] : []), value];
+        } else if (flags[key] !== undefined) {
+          // `--root a --root b` kept `b`, so half of what the caller asked for vanished
+          // with no error and no way to tell which half. Only a flag declared repeatable
+          // accumulates (review 0003 Q62); a second value for any other is a usage error.
+          return {
+            ok: false,
+            error: usage(
+              `--${raw} was given twice; it takes one value (repeatable: ${[...REPEATABLE_FLAGS]
+                .map((name) => `--${name}`)
+                .join(', ')})`,
+            ),
+          };
+        } else {
+          flags[key] = value;
+        }
       }
       continue;
     }
     return { ok: false, error: usage(`unknown flag --${raw}`) };
   }
 
+  if (dashdash) flags.dashdash = true;
   return { ok: true, value: { flags, positional } };
 }
 

package/src/bench/ablate.mjs

@@ -19,15 +19,14 @@ import { plan } from '../projection/project.mjs';
 import { isEligible, loadRules, readDeclared, ruleValues, select } from '../projection/rules.mjs';
 import { resolveSurfaces, rulePath, SURFACES } from '../projection/surfaces.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { evaluateRunRecord, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
 import {
   DEFAULT_BOOTSTRAP_SAMPLES,
   DEFAULT_BOOTSTRAP_SEED,
   compareArms,
-  evaluateRunRecord,
   holmAdjust,
-  loadPrices,
-  loadRunRecords,
-} from './report.mjs';
+} from '../measure/stats.mjs';
 
 export const DEFAULT_CANARY_SIZE = 10;
 export const DEL_R_TOLERANCE = 0.01;