simt-dev 0.3.0 → 0.4.0

package/docs/decisions/ADR-094-a-change-runs-the-tests-that-import-it.md

@@ -0,0 +1,44 @@
+# ADR-094 — a change runs the tests that import it
+
+Status: **accepted** · 2026-10-18 · filed as R16 (plan 0003)
+
+**Affects:** `src/index/gate.mjs`, `src/commands/gate.mjs`, `test/gate.test.mjs`
+
+## Context
+
+A gate that always runs the whole suite teaches people to skip it. The tests
+that can see a change are the ones that import it, including through another
+file. A name that looks like a test, and a commit that also touched a test,
+are different facts. They are already answered by `simt tests`.
+
+The pre-commit hook, the stop hook and an agent call this command. They do
+not need the dispatcher rewritten to do it.
+
+## Rulings
+
+1. **Selection is the import closure.** A test file is selected when an import
+   reaches a changed file, at any depth. A changed file that is itself a test
+   is selected. A cycle is walked once. A conventional neighbour and a shared
+   commit are not imports, so they are not a selection. A file the test-path
+   rule already treats as a test counts, including a helper that lives beside
+   the tests and imports the change.
+2. **The command is `simt gate`.** Paths name the change. `--changed` reads
+   the diff, staged, unstaged and untracked. No path and no `--changed` is a
+   usage error. A clean diff selects nothing and runs nothing. A repository
+   that is not git is unsupported.
+3. **The run is the package's own runner, and only the selected files.** Tests
+   are grouped by the package that contains them. The runner is the one that
+   package already declares. A package with no runner is unsupported. The
+   child's test-runner environment is cleared, so a parent test process cannot
+   take the child's result and report a pass.
+4. **The hand list for the plan's named file is 51 files, and the selection
+   finished in under 5 seconds.** Eight other test files do not import it, and
+   they are not selected. The set is wide because the shared fixture imports
+   the loader that imports that file. Measured at about 40 ms.
+
+## Consequences
+
+`simt tests` still answers "which tests exercise this file", including a
+conventional name and, when asked, a shared commit. `simt gate` answers "run
+the tests this change can reach". Compaction of the runner's text is a later
+slice. The dispatcher is unchanged.

package/docs/decisions/ADR-095-gate-output-keeps-the-failures.md

@@ -0,0 +1,31 @@
+# ADR-095 — gate output keeps the failures
+
+Status: **accepted** · 2026-10-18 · filed as R18 (plan 0003)
+
+**Affects:** `src/index/compact.mjs`, `src/commands/gate.mjs`, `test/compact.test.mjs`
+
+## Context
+
+A gate that prints every passing test spends the reader's attention on the
+lines that did not fail. A summary that drops a failure is worse: the run
+looks cleaner than it was. The formats this tool's own runners emit are
+known. An arbitrary shell log is not one of them, and guessing at it is how
+a line gets lost.
+
+## Rulings
+
+1. **Compaction applies to a report this tool produced, and only to a format
+   it can read.** Those formats are TAP, JUnit XML, vitest or jest JSON, and
+   `go test -json`. Pytest's junit file is JUnit XML. A stream that is none
+   of these is printed unchanged.
+2. **Failures come first, and each one is kept.** The name, the assertion
+   and the location stay in the printed block. Passing tests become a count.
+   A skip becomes a count when there is one.
+3. **The raw log path is printed.** The log is gitignored. The command does
+   not wrap an arbitrary shell command. The gate is the caller.
+
+## Consequences
+
+`simt gate` is the command that compacts. Another command that wants the same
+treatment calls the same function. A format that is not in the list stays
+raw until it is added with a golden fixture.

package/docs/decisions/ADR-096-impact-names-who-a-change-reaches.md

@@ -0,0 +1,38 @@
+# ADR-096 — impact names who a change reaches
+
+Status: **accepted** · 2026-10-18 · filed as R23 (plan 0003)
+
+**Affects:** `src/index/impact.mjs`, `src/commands/impact.mjs`, `test/impact.test.mjs`
+
+## Context
+
+A change has a neighbourhood: the files that import it, the tests of that
+neighbourhood, the decisions and rules that govern the file, and the owner a
+CODEOWNERS line names. In a workspace the neighbourhood crosses a repository
+when another one references a contract this change touches. That is the check
+behind "the producer ships before the consumer".
+
+## Rulings
+
+1. **The argument is a tracked path, or the name of one export.** A private
+   symbol is not an export. Several files exporting the same name is a usage
+   error that names those files. A name that is neither a path nor an export
+   is a usage error. A tree that is not git is unsupported.
+2. **Importers are the non-test files that import the target, at any depth.**
+   The tests are the test files that import that closure. Both lists stop at
+   64. Past that, the report says it was truncated.
+3. **Governance is what `why` would name for the file, limited to decisions
+   and rules.** Owners are the last matching pattern in the first CODEOWNERS
+   file that exists. A pattern with no slash matches the file name in any
+   directory.
+4. **A cross-repo consumer is another repository whose text contains a
+   contract path this change touches.** A contract is an OpenAPI document or
+   a JSON Schema file. The path has to include a directory. No workspace
+   means no consumers, and that is not a failure. The scan stops at 64
+   references and 2000 files in a repository.
+
+## Consequences
+
+`simt impact` answers who is reached. `simt gate` still runs the tests.
+`simt why` still answers governance on its own, including skills, gates and
+lessons, which this report does not repeat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
@@ -37,7 +37,7 @@
     "skills"
   ],
   "scripts": {
-    "test": "node --test test/*.test.mjs",
+    "test": "node --test --test-concurrency=4 test/*.test.mjs",
     "lint": "node bin/simt-dev.mjs doctor"
   }
 }

package/rules/core.md

@@ -7,7 +7,7 @@ simt-priority: hard
 
 # Shared rules
 
-Where a rule cites a decision, run `simt-dev rules why ADR-NNN` to read it,
+Where a rule cites a decision, run `simt rules why ADR-NNN` to read it,
 including whether it is still in force.
 
 These rules are stack-agnostic. Whatever is specific to your stack, your product or your
@@ -60,7 +60,7 @@ commands belongs in this repository, not here.
 
 - No type-system escapes, no unawaited async work, no debug printing in application code.
 - 400 lines is a review trigger; 1000 lines is a hard ceiling. Generated files are exempt
-  when the hook names the generator. (ADR-005)
+  when the hook names the generator. (ADR-005) <!-- simt-check: max-file-lines -->
 - Never weaken CSP, CORS, auth, audit, cache or validation controls to silence a test, warning
   or alert.
 - Review verdicts are exactly three: `BLOCK`, `APPROVE WITH RESIDUAL RISK` (must list what was

package/src/agenthooks/policy.mjs

@@ -21,8 +21,16 @@
 
 import { CLI } from '../name.mjs';
 
-/** The events an agent-time hook can answer, normalised across harnesses. */
-export const EVENTS = ['pre-tool-use'];
+/**
+ * The events an agent-time hook can answer, normalised across harnesses.
+ *
+ * `pre-tool-use` is a decision: a payload in, a deny or nothing out, and exit 2 means
+ * block. `prompt-submit` is a delivery: the same payload shape in, context out, and it
+ * never denies anything — a hook that could stop a person's prompt would be a hook whose
+ * own bug is a person who cannot type (R29). `post-tool-use` recalls a lesson as one
+ * paragraph when a tool call fails with a signature matching `docs/lessons/*.md` (R33).
+ */
+export const EVENTS = ['pre-tool-use', 'prompt-submit', 'post-tool-use'];
 
 /** The environment variable that lifts named policies for one session. */
 export const ALLOW_ENV = 'SIMT_ALLOW';

package/src/agenthooks/prompt.mjs

@@ -0,0 +1,81 @@
+// The prompt-submit surface: the packet delivered where the agent will read it.
+//
+// This module must stay off the tool-call path, and the code's shape is what keeps it
+// there: `src/commands/agenthook.mjs` reaches it through a dynamic `import()` that only a
+// prompt event takes. The pre-tool hook is a latency promise — it answers before every
+// shell command an agent runs — so it imports the policy table, the decision and the
+// renderer and nothing that walks the repository, and `test/agenthooks.test.mjs` asserts
+// exactly that set. A delivery, by contrast, is the one thing here that must read the
+// repository, so it lives behind a door the pre-tool path never opens.
+//
+// Three rules shape what gets delivered:
+//
+//   * The repository opts in. The opt-in is a `brief` key in the repository's manifest,
+//     not the presence of a hook in a harness config: a repository that declared nothing
+//     is not spending its owner's context on a packet they did not ask for, and the
+//     manifest is the one file a person reviews before they commit the change.
+//   * The packet is capped, at PROMPT_CAP_BYTES. A packet is delivered into a prompt that
+//     already exists, and the ceiling is the measured bar of this slice rather than a
+//     value a repository is free to raise.
+//   * A delivery never blocks and never fails loudly. Everything that could go wrong —
+//     no index, no prompt in the payload, a registry that will not load — ends in no
+//     injection and a line on stderr. A hook that stopped a person's prompt because this
+//     tool could not answer would be worse than a hook that said nothing.
+
+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';
+
+/**
+ * Whether this repository asked for a delivered packet, and the ceiling it asked for.
+ *
+ * Presence is the opt-in and the value is a preference, so `"brief": {}` means "yes, at
+ * whatever you measured" and `"brief": { "bytes": 900 }` means "yes, and keep it small".
+ * A declared zero is not honoured as a ceiling: zero is this tool's word for "no ceiling"
+ * on the command line, and a delivered packet that meant "the whole repository" would be
+ * the one thing the cap exists to prevent. It is read from the manifest rather than from
+ * the harness config because the manifest is the file the repository reviews.
+ */
+export async function promptOptIn(root) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists || error) {
+    return { optedIn: false, bytes: DEFAULT_BRIEF_BYTES, why: `${exists ? error : 'no manifest'}` };
+  }
+  if (manifest?.brief === undefined || manifest.brief === null) {
+    return { optedIn: false, bytes: DEFAULT_BRIEF_BYTES, why: 'no `brief` key in the manifest' };
+  }
+  const declared = manifest.brief?.bytes;
+  const asked = Number.isFinite(declared) && declared > 0 ? declared : PROMPT_CAP_BYTES;
+  return { optedIn: true, bytes: Math.min(asked, PROMPT_CAP_BYTES) };
+}
+
+/**
+ * The context one prompt-submit call should deliver, or the reason it delivers nothing.
+ *
+ * `build: false` is the latency promise in one argument: a delivery reports a cold index
+ * rather than building one, so the first prompt in a fresh clone gets nothing and the
+ * second gets the packet. The alternative — a person watching their first prompt sit for
+ * 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) {
+  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;
+  const optIn = await promptOptIn(root);
+  if (!optIn.optedIn) return { skipped: optIn.why };
+
+  // Federation is off on this path and on no other: a delivery has 300 ms to answer, and
+  // starting a declared server is a wait a prompt submit must not take. The task is the
+  // question a federation would ask, and a person is not made to wait for it here.
+  const result = await assembleBrief({ root, task, budget: optIn.bytes, build: false, federate: false });
+  if (result.error) return { skipped: 'the packet could not be assembled' };
+  if (result.cold) return { skipped: 'the index is empty, and a delivered packet never builds one' };
+
+  const json = deliveryJson(row, result.packed.text);
+  if (json === null) return { skipped: `${row.id} has no prompt event that can inject` };
+  return { json, root, bytes: result.packed.after };
+}

package/src/agenthooks/render.mjs

@@ -11,6 +11,26 @@
 //   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
 //   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
 //
+// The prompt-submit event (R29) is a second table, and it is shorter because the vendors
+// are: two of the four document a prompt event that can put text into the model's context,
+// and a delivery is the only thing this tool does there. Neither takes a matcher — both
+// document that field for tool events, and a matcher a harness ignores is a matcher the
+// next person believes is filtering something.
+//
+//   claude       .claude/settings.json   UserPromptSubmit   hookSpecificOutput.additionalContext
+//   codex        .codex/hooks.json       UserPromptSubmit   hookSpecificOutput.additionalContext
+//   cursor       .cursor/hooks.json      beforeSubmitPrompt CANNOT INJECT: block-only
+//   antigravity  .agents/hooks.json      (no prompt event documented)
+//
+// Cursor is the one that would be a mistake to write anyway. Its `beforeSubmitPrompt` hook
+// can only continue or block, so the entry would carry no packet and a broken one would
+// stop a person from typing — and its only injection point, `sessionStart.additional_context`,
+// fires once when the session is created, which is a different lifetime from the brief a
+// task needs. Gemini CLI documents `BeforeAgent`, which does inject, but the product was
+// replaced by Antigravity CLI on 2026-06-18 and its config is not in the reader table this
+// module takes its paths from; a harness this tool did not verify is a harness it does not
+// write to.
+//
 // 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.
@@ -36,8 +56,8 @@ const TIMEOUT_SECONDS = 10;
  * 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}`;
+export function hookCommand(id, event = EVENTS[0]) {
+  return `${CLI} agent-hook ${event} --harness ${id}`;
 }
 
 /** The path a config file lives at, from the reader table rather than a second list. */
@@ -73,6 +93,20 @@ const ADAPTERS = {
     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',
@@ -96,6 +130,17 @@ const ADAPTERS = {
     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',
@@ -111,6 +156,11 @@ const ADAPTERS = {
         : [],
     }),
     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',
@@ -133,6 +183,10 @@ const ADAPTERS = {
       };
     },
     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,
   },
 };
 
@@ -160,6 +214,37 @@ export function decisionJson(row, decision) {
   return row.deny(decision.messages.join('\n'));
 }
 
+/**
+ * The document to print for a delivery, or null when the harness takes none.
+ *
+ * A delivery is never a decision: nothing here can deny, and the caller exits 0 whatever
+ * this returns. That is the whole difference between the two events, and it is why the
+ * prompt event has no `denyExit` — there is no exit code that means "here is some context".
+ */
+export function deliveryJson(row, text) {
+  return row.prompt ? row.prompt.context(text) : null;
+}
+
+/** The document to print for a post-tool lesson recall delivery, or null when the harness takes none. */
+export function postDeliveryJson(row, text) {
+  return row.post ? row.post.context(text) : null;
+}
+
+/**
+ * The submitted text a prompt payload carries, or null when it carries none we recognise.
+ *
+ * Marked inferred rather than documented: both harnesses that take this event place the
+ * prompt at the top level, but only in the example on each page, not as a stated contract.
+ * An unrecognised payload therefore delivers nothing and says so on stderr. The failure
+ * this must not have is the opposite one — a packet delivered as though it answered a task
+ * it never saw, which reads as a confident answer about the wrong question.
+ */
+export function promptText(row, payload) {
+  if (!row.prompt) return null;
+  const text = payload?.prompt ?? payload?.user_prompt ?? payload?.message;
+  return typeof text === 'string' && text.trim().length > 0 ? text : null;
+}
+
 // ---------------------------------------------------------------------------
 // The config file: reading ours out of somebody else's JSON, and putting it back.
 // ---------------------------------------------------------------------------
@@ -180,9 +265,36 @@ function container(row, config, { create = false } = {}) {
   return config.hooks ?? null;
 }
 
+/** The vendor's name for one of our events on this row, or null when it has none. */
+function vendorEvent(row, event) {
+  if (event === EVENTS[0]) return row.event;
+  if (event === 'prompt-submit') return row.prompt?.event ?? null;
+  if (event === 'post-tool-use') return row.post?.event ?? null;
+  return null;
+}
+
+/** The events a row answers, and the name each one goes under in its config file. */
+function eventsOf(row, { prompt = false, post = false } = {}) {
+  const pairs = [[EVENTS[0], row.event]];
+  if (prompt && row.prompt) pairs.push(['prompt-submit', row.prompt.event]);
+  if (post && row.post) pairs.push(['post-tool-use', row.post.event]);
+  return pairs;
+}
+
 /** The group this tool owns for one event, in that harness's shape. */
-function group(row) {
-  const command = hookCommand(row.id);
+function group(row, event = EVENTS[0]) {
+  const command = hookCommand(row.id, event);
+  if (event === 'prompt-submit') {
+    // No matcher: both vendors document that field for tool events, and a matcher a
+    // harness ignores is a matcher the next reader believes is filtering something.
+    return { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+  }
+  if (event === 'post-tool-use') {
+    const matcher = row.post?.matcher;
+    return matcher
+      ? { matcher, hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] }
+      : { hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS }] };
+  }
   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
@@ -197,35 +309,44 @@ 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];
+function entries(row, config, event = EVENTS[0]) {
+  const name = vendorEvent(row, event);
+  if (name === null) return [];
+  const list = container(row, config)?.[name];
   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);
+/** Our entries in this document for one event, for `status`; the document is not modified. */
+export function installedIn(row, config, event = EVENTS[0]) {
+  return entries(row, config, event).filter(ours);
 }
 
 /**
- * The document with this tool's hook added, everything else left alone.
+ * The document with this tool's hooks 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.
+ *
+ * One file can carry both events — Claude and Codex each hold a tool hook and a prompt
+ * hook in the same document — so this writes one group per event the row answers rather
+ * than one group per file. `prompt` is the caller's opt-in: a repository that has not
+ * asked for a delivered packet gets the tool hook and nothing extra, and the file it never
+ * asked to change is a file this tool does not touch.
  */
-function withHook(row, config) {
+function withHook(row, config, { prompt = false, post = false } = {}) {
   const box = container(row, config, { create: true });
-  const kept = entries(row, config).filter((e) => !ours(e));
-  box[row.event] = [...kept, group(row)];
+  for (const [event, name] of eventsOf(row, { prompt, post })) {
+    const kept = entries(row, config, event).filter((e) => !ours(e));
+    box[name] = [...kept, group(row, event)];
+  }
   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' };
+export function rendered(row, existing, options = {}) {
+  if (existing === null) return { text: `${JSON.stringify(withHook(row, {}, options), null, 2)}\n`, action: 'created' };
   let config;
   try {
     config = JSON.parse(existing);
@@ -235,6 +356,6 @@ export function rendered(row, existing) {
   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`;
+  const text = `${JSON.stringify(withHook(row, config, options), null, 2)}\n`;
   return { text, action: text === existing ? 'unchanged' : 'updated' };
 }

package/src/argv.mjs

@@ -59,6 +59,27 @@ export const BOOL_FLAGS = new Set([
   // (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',
+  // check: the lock must match. Off by default because a repository that has not
+  // written one yet is not drift, and a gate that failed for the absence would be
+  // red on every repository this package already adopted.
+  'frozen',
+  // map: report gold-file recall@10 instead of rendering the ranking. Off by
+  // default because the ranking is the answer a task asked for, and the recall
+  // figure needs the hidden benchmark patches.
+  'recall',
+  // tests: also list files that only changed in the same commits as a test.
+  // Off by default because a shared commit is not a test.
+  'cochange',
+  // gate: read the working-tree diff instead of the paths named after the command.
+  // Off by default because a path is the change the caller named, and the diff
+  // is a different question.
+  'changed',
+  // local doctor: allow non-loopback model URLs. Off by default because nothing leaves
+  // the machine unless explicitly overridden (ADR-075, plan 0003 R37).
+  'allow-remote',
+  // index / map / brief: opt into local vector embeddings configured under local.embed
+  // (plan 0003 R28, R37). Off by default unless recall@10 gains at least 10 points.
+  'embed',
 ]);
 
 export const VALUE_FLAGS = new Set([
@@ -100,6 +121,11 @@ export const VALUE_FLAGS = new Set([
   // plan done: the test command that proves the slice. Plan 0003 R31.
   'test',
   'state',
+  // map: outline (paths), names (exported symbols) or signatures (the line).
+  // A boolean would not say which of the three the caller wanted.
+  'level',
+  // decide: structured supersession spec (ADR-NNN or ADR-NNN:<ruling>[:<kind>], repeatable).
+  'supersedes',
 ]);
 
 /**
@@ -115,7 +141,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', 'arm', 'compare']);
+export const REPEATABLE_FLAGS = new Set(['skill', 'arm', 'compare', 'supersedes']);
 
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
@@ -189,6 +215,13 @@ export function parse(argv) {
   return { ok: true, value: { flags, positional } };
 }
 
+export function parsePathList(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
 /** `--max-bytes` -> `maxBytes`. Callers use camelCase; users type kebab-case. */
 function camel(name) {
   return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());

package/src/bench/grade.mjs

@@ -173,6 +173,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
       resolved: false,
       gatesPassed: false,
       diff,
+      goldFiles: [...goldFiles],
       agentPatch: diffPatchRes.stdout,
     };
   }
@@ -183,6 +184,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
       resolved: false,
       gatesPassed: false,
       diff,
+      goldFiles: [...goldFiles],
       agentPatch: diffPatchRes.stdout,
     };
   }
@@ -224,6 +226,7 @@ export async function gradeWorkspace(workDir, task, { vaultRoot, initialHead, ti
     resolved,
     gatesPassed,
     diff,
+    goldFiles: [...goldFiles],
     agentPatch: diffPatchRes.stdout,
   };
 }