simt-dev 0.7.0 → 0.7.1

package/README.md

@@ -1,6 +1,8 @@
 # simt-dev
 
-![simt-dev, the intelligence amplifier for coding agents, and its four claims. One: say less, always — a kernel under 2 KB whose bytes stay stable so the prompt cache survives. Two: answers over exploration — a local code graph and a short task brief. Three: enforce, don't instruct — dual gates, before a tool call and at git time. Four: close the loop — benches and memory. Beneath them, the harnesses it works across and its three channels.](https://raw.githubusercontent.com/QuazarMedia/simt-dev/main/res/59e21e6d-6bf2-4d7d-b6ea-c7349a697d11.jpg)
+![simt-dev, the intelligence amplifier for coding agents, and its four claims. One: say less, always — a kernel under 2 KB whose bytes stay stable so the prompt cache survives. Two: answers over exploration — a local code graph and a short task brief. Three: enforce, don't instruct — dual gates, before a tool call and at git time. Four: close the loop — benches and memory. Beneath them, the harnesses it works across and its three channels.](https://raw.githubusercontent.com/QuazarMedia/simt-dev/main/res/hero.jpg)
+
+[![simt-dev own gate](https://github.com/QuazarMedia/simt-dev/actions/workflows/simt-dev-check.yml/badge.svg)](https://github.com/QuazarMedia/simt-dev/actions/workflows/simt-dev-check.yml)
 
 `simt` adopts a repository for the agents that work in it, and builds an intelligence
 amplifier around them: a brief that answers before the agent explores, gates that
@@ -72,13 +74,20 @@ beside its `.sha256`. Pin the release you download,
 and run this from the repository's top level:
 
 ```sh
-mkdir -p .simt/bin && os=$(uname -s | tr A-Z a-z) && arch=$(uname -m | sed "s/x86_64/x64/") && curl -fsSL "https://github.com/QuazarMedia/simt-dev/releases/download/v<version>/simt-dev-<version>-$os-$arch" -o .simt/bin/simt && chmod +x .simt/bin/simt
+version=<version>; os=$(uname -s | tr A-Z a-z); arch=$(uname -m | sed "s/x86_64/x64/")
+base="https://github.com/QuazarMedia/simt-dev/releases/download/v$version"
+asset="simt-dev-$version-$os-$arch"; tmp=$(mktemp -d)
+curl -fsSL "$base/$asset" -o "$tmp/$asset"
+curl -fsSL "$base/$asset.sha256" -o "$tmp/$asset.sha256"
+(cd "$tmp" && shasum -a 256 -c "$asset.sha256")
+mkdir -p .simt/bin && mv "$tmp/$asset" .simt/bin/simt && chmod +x .simt/bin/simt
 ```
 
 The locator checks `.simt/bin/simt` before `PATH`, so the repository's own copy is the
 one its hooks and its CI run — this is the same command the hook shim prints as its
-remedy. The generated CI workflow downloads the same asset and verifies it against the
-published `.sha256` before running anything.
+remedy. Both the snippet above and the generated CI workflow verify the asset against the
+published `.sha256` before it runs: a digest that does not match stops the copy, so a
+truncated or substituted download never becomes the command.
 
 ## What `simt` does
 
@@ -185,134 +194,11 @@ line warns past 400 lines and fails past 1000. `simt evidence check` warns when
 message claims a passing run this tree does not have, and the commit fails when
 `gates.evidence` is `block`. Every finding `check` can emit is explained by `simt explain <CODE>` (DRIFT, UNMANAGED, PACK-DIGEST-MISMATCH, ...).
 
-## Agent playbook: how and when to use each module
-
-An agent working in an adopted repository should use `simt` as its primary orientation,
-retrieval, validation and memory layer rather than scanning the tree by hand. Every
-read-only command supports `--json` (and `--max-bytes <n>`) or can be called over stdio
-through `simt mcp`.
-
-### Decision tree: which command to run when
-
-| Situation | First command | If you need more |
-| --- | --- | --- |
-| New task, no context yet | `simt brief "<task>"` | `simt map --task "<task>"` for broader file ranking |
-| About to edit a file | `simt why <file>` | `simt impact <file>` for blast radius |
-| Need to know what tests to run | `simt tests <file>` | `simt gate --changed` to run them |
-| Rule violation or error | `simt lessons list` | `simt rules why <rule-id>` for the decision |
-| Working from a plan | `simt plan next` | `simt plan done <id> <sha> --yes` when finished |
-| Before committing | `simt check` | `simt evidence` to verify test claims |
-| Opening a pull request | `simt pr-body` | `--base <ref>` to diff against another fork point |
-| Repository adoption | `simt init --yes` | `simt doctor` to verify stack detection |
-| Multi-repo workspace | `simt compare` | `simt shared plan` to find deduplication opportunities |
-| Local model available | `simt local doctor` | `simt index --embed` to build vector embeddings |
-
-### 1. Start of task — orient in one call instead of broad exploration
-
-1. **Assemble the task packet first.** Run `simt brief "<task>"` (or call MCP `brief`, or
-   read the packet injected automatically when `agent-hooks install --yes` wired
-   `prompt-submit`). Within `--budget 2048` bytes (pass `--budget 0` for unlimited or
-   `--explain` to see why items were kept or cut), the packet gives:
-   - `TASK`: the classified task kind (`bugfix`, `feature`, `refactor`, `test`, `docs`,
-     `config`) and the evidence behind it.
-   - `COMMANDS`: the exact `build`, `test`, `lint`, `format`, `typecheck`, and focused
-     test templates for this repository.
-   - `LIKELY FILES`: top files ranked by reciprocal-rank fusion (`RRF_K = 40`) across
-     SQLite FTS5 `bm25()`, PageRank graph proximity, and resolver signals.
-   - `TESTS`: the test files mapped to those likely files.
-   - `DECISIONS`, `SKILLS`, `LESSONS`, `CAUTIONS`, and `FEDERATION`: governing ADRs,
-     matched skills, promoted lessons for those paths, active worktree/hook cautions, and
-     any structural answer from a declared external code-graph server.
-2. **Pull the next tracker slice when working from a plan.** Instead of reading a multi-thousand-line
-   plan in `docs/plans/` or `docs/reviews/`, run `simt plan next` (or MCP `plan_next`) to
-   load only the next queued slice (~1 KB) whose dependencies are already `Complete` or
-   `Accepted`.
-
-**When to use `--json` format.** When piping output to other tools or when the agent needs
-structured data, add `--json` to any read-only command. For example, `simt brief "<task>" --json`
-returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `skills`,
-`lessons`, `cautions`, and `federation` fields that can be programmatically consumed.
-
-### 2. Before editing — query the graph, blast radius, and governance
-
-1. **Rank files or symbols at the right granularity.** When `brief`'s file list is too
-   narrow or the task evolves, run `simt map --task "<task>" --level outline` for paths,
-   `--level names` for exported symbols, or `--level signatures` for declaration lines.
-   Pass `--embed` when `local.embed` is configured in `simt.json` and clears the +10-point
-   recall@10 bar.
-2. **Check blast radius before changing a shared file or export.** Run
-   `simt impact <file|symbol>` to see every direct and transitive importer, the tests
-   covering them, the governing rules and ADRs, and any sibling repository in the
-   workspace that imports that symbol.
-3. **Read the governance on a path before changing its behaviour.** Run `simt why <path>`
-   to list every ADR whose `simt-affects` matches the file, every scoped rule, skill,
-   gate, and promoted lesson. Run `simt why` with no path to audit the repository for
-   `UNRESOLVED-AFFECTS` tokens.
-4. **Resolve deferred rules and citations on demand.** When `simt.json` sets
-   `"mode": "kernel"`, only `hard` and `command` rules are loaded at session start;
-   `convention` and `style` rules are listed by ID at the foot of the projection. Fetch a
-   deferred rule with `simt rules show <id>`, and read any cited `ADR-NNN` with
-   `simt rules why ADR-NNN` (or MCP `rules_why`) to see its rulings and whether any ruling
-   was superseded or narrowed.
-5. **Load skills progressively (Tier 0 → Tier 1 → Tier 2).** Never read every skill file
-   upfront:
-   - Tier 0: `simt skills index` (or MCP `skills_index`) lists one line per skill.
-   - Tier 1: `simt skills brief --task "<task>"` (or MCP `skills_brief`) ranks compatible
-     skills within budget (`--plan` emits a fetch plan without bodies).
-   - Tier 2: `simt skills show <name> --max-bytes 8192` (or MCP `skills_show`) loads only
-     the chosen skill's body.
-
-**Optimal retrieval strategy.** For best performance, use this sequence:
-1. `simt brief "<task>"` — gets the most relevant files and tests in one call
-2. If more files are needed, `simt map --task "<task>" --level outline` — broader ranking
-3. If you need to understand a specific file's impact, `simt impact <file>` — blast radius
-4. If you need to understand governance, `simt why <file>` — ADRs and rules
-
-### 3. During implementation — validate incrementally under dual gates
-
-1. **Keep the local index current.** After adding, renaming, or changing exports/imports,
-   run `simt index`. It hashes tracked blobs via `git ls-files --stage` and re-extracts
-   only changed files in under 300 ms.
-2. **Run only the tests your change reaches.** Use `simt tests <path>` to inspect which
-   tests cover a file (via import edges, naming conventions, or coverage records; add
-   `--cochange` to include historical co-change pairs). Run `simt gate --changed` (or
-   `simt gate <path...>`) to execute only the tests reachable from the diff, with gate
-   output compacted so every failure line survives while passing noise is trimmed.
-3. **Respect agent-time hooks and learn from failures.** With `simt agent-hooks install --yes`,
-   `pre-tool-use` blocks unapproved `git push`, history rewrites (`--no-verify`,
-   `--amend`, `reset --hard`, `rebase`), and direct edits to generated regions before the
-   tool executes. When a test or gate fails, `post-tool-use` hashes the normalised first
-   error line against `docs/lessons/*.md` and injects the matching lesson into context.
-
-**Incremental validation workflow.** After each meaningful code change:
-1. Run `simt tests <changed-file>` to see which tests cover your changes
-2. Run `simt gate --changed` to execute only the affected tests
-3. If a test fails, check `simt lessons list` for known issues and their remedies
-4. If the failure is new, fix it and consider promoting the lesson with `simt lessons review <id> --yes`
-
-### 4. Before committing and closing a slice — verify drift, evidence, and memory
-
-1. **Run the repository gate.** Run `simt check` (or MCP `check`). Fix any reported
-   `DRIFT` with `simt sync --yes`, and resolve any rule checker or manifest findings.
-2. **Verify execution evidence matches the current tree.** Run `simt evidence` to confirm
-   that the tests and gates you plan to cite were recorded against the current
-   `git write-tree` digest in `.simt/ledger.jsonl`. Any file edit invalidates earlier
-   evidence.
-3. **Record decisions, lessons, and tracker state:**
-   - If the change alters what the repository or tool believes, scaffold an ADR with
-     `simt decide "<title>" [--supersedes ADR-NNN[:<ruling>]] --yes`.
-   - If a failing gate or test was fixed during the session, inspect captured candidates
-     with `simt lessons list` and promote reusable ones with
-     `simt lessons review <id> --yes`.
-   - After committing locally (never push without explicit approval per `ADR-001`), close
-     the tracker slice with `simt plan done <id> <sha> --test "<cmd>" --yes`.
-
-**Pre-commit checklist.** Before committing, run this sequence:
-1. `simt check` — verify no drift and all rules pass
-2. `simt evidence` — confirm test runs are recorded against current tree
-3. `simt lessons list` — check for any unreviewed lesson candidates
-4. `git commit` — commit locally (never push without explicit approval)
-5. `simt plan done <id> <sha> --yes` — close the tracker slice if working from a plan
+## Agent playbook
+
+The full agent playbook — the decision tree for which command to run when, and the
+workflow for orienting, editing, implementing and closing a slice — lives in
+[PLAYBOOK.md](PLAYBOOK.md).
 
 ## Optimal setup for every project, repository, and workspace shape
 
@@ -372,7 +258,7 @@ history. All remain off until named and propose rather than write projected text
 | `simt.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants`. The old `simt-dev.lock.json` is still read, and a lock migrates on its next write |
 | `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, and only for a harness that reads that directory |
 | `.editorconfig`, `.gitattributes` | baseline regions, placed first so a later setting still wins |
-| `.simt-hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |
+| `.simt/hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |
 | `docs/decisions/ADR-NNN-<slug>.md` | numbered decision records scaffolded by `simt decide --yes` with `simt-affects` and `simt-supersedes` frontmatter |
 | `docs/lessons/NNNN-<slug>.md` | reviewed lessons promoted by `simt lessons review <id> --yes` with `simt-trigger`, `simt-evidence`, and `simt-expires` frontmatter |
 

package/bin/simt.mjs

@@ -1,60 +1,24 @@
 #!/usr/bin/env node
-// simt-dev - developer and agent tooling for the SIMT ecosystem.
+// The entry point, and the one place the runtime floor is enforced.
 //
-// POSIX only (ADR-012). package.json declares os: [darwin, linux], so npm refuses
-// the install elsewhere rather than letting a hook fail obscurely.
-
-import { parse, rawJsonFlag } from '../src/argv.mjs';
-import { EXIT, fail, jsonFailMode, jsonIndentDefault } from '../src/output/index.mjs';
-
-try {
-  const argv = process.argv.slice(2);
-  const parsed = parse(argv);
-  if (!parsed.ok) {
-    // The flags do not exist yet, so the JSON mode is read off the raw words:
-    // a parse failure under `--json` is a JSON document on stdout, not text on
-    // stderr with an empty stdout (Q11, ADR-070 ruling 4).
-    jsonFailMode(rawJsonFlag(argv));
-    process.exit(fail(parsed.error.message, parsed.error.code));
-  }
-  const { flags, positional } = parsed.value;
-
-  // Set before anything can fail: `no command given` under `--json` is a JSON
-  // document too, and a failure that prints as text with an empty stdout breaks
-  // the same ruling the parse failure above honours (Q11, ADR-070 ruling 4).
-  jsonIndentDefault(flags.pretty === true);
-  jsonFailMode(flags.json === true);
-
-  // No arguments at all is a usage error, not a silent help dump: an agent that
-  // ran the wrong thing should be told so rather than handed 40 lines of prose.
-  if (positional.length === 0 && !flags.help && !flags.version) {
-    process.exit(fail('no command given', EXIT.USAGE));
-  }
+// `package.json` declares `engines.node >= 22.20.0`, and npm only warns: an older
+// runtime used to reach the CLI and fail somewhere inside the module graph — a syntax
+// error or a missing API — instead of the one sentence that says what to install
+// (review 0003 Q54). Nothing but this tiny module is imported before the check, so the
+// message is what a reader gets; the CLI is imported only once the floor holds.
+//
+// 5 is EXIT.UNSUPPORTED. `output/index.mjs` is the CLI graph this file exists to avoid
+// loading before the check, so the literal is repeated here and asserted by
+// `test/node-version.test.mjs`.
 
-  // The one command that runs on somebody else's hot path, and therefore the one that
-  // does not load the registry. `agent-hook` is called before every tool call an agent
-  // makes, so its latency is a product requirement rather than a nicety (plan 0003
-  // R15), and the registry's imports - detection, projection, the bench corpus - cost
-  // tens of milliseconds before the command itself starts. Measured on the machine
-  // this was written on: 127.7 ms through the registry against 91.5 ms with only this
-  // module's imports, where the bare runtime is 86.9 ms of it.
-  //
-  // Only the exact spelling the renderers write takes this path. Anything else -
-  // including `agent-hook --help` - loads the registry, so help stays the one list of
-  // every command and this shortcut cannot become a second, thinner command surface.
-  if (positional[0] === 'agent-hook' && !flags.help && !flags.version) {
-    const { agentHookCommand } = await import('../src/commands/agenthook.mjs');
-    process.exit((await agentHookCommand(positional.slice(1), flags)) ?? EXIT.OK);
-  }
+import { MIN_NODE, satisfiesMinimum } from '../src/node-version.mjs';
 
-  const { dispatch } = await import('../src/commands/index.mjs');
-  const code = (await dispatch(argv)) ?? EXIT.OK;
-  // Assigned, not forced: a large document on stdout (a `--json --diff` over a
-  // skill-sized body exceeds the 64 KiB pipe buffer) is still draining when the
-  // command resolves, and `process.exit()` cuts it — exit 0 with half a JSON
-  // document on stdout. Letting the loop empty first makes the exit honest
-  // (plan 0003 R50; the S10 contract asserts the document parses).
-  process.exitCode = code;
-} catch (error) {
-  process.exit(fail(error?.message ?? String(error), EXIT.FAIL));
+if (!satisfiesMinimum(process.versions.node)) {
+  process.stderr.write(
+    `ERROR 5 simt-dev needs Node >= ${MIN_NODE}; this is ${process.versions.node}\n` +
+      `REMEDY install Node ${MIN_NODE} or newer, then rerun: simt --version\n`,
+  );
+  process.exit(5);
 }
+
+await import('../src/cli.mjs');

package/docs/decisions/ADR-014-workspace-is-configuration.md

@@ -1,6 +1,6 @@
 # ADR-014 — The workspace is configuration, and a single repo is a first-class case
 
-Status: **accepted** · 2026-10-05
+Status: **accepted** · 2026-10-05 · ruling 1 superseded by [ADR-119](ADR-119-the-environment-variable-points-into-a-workspace-the-repo-declared.md)
 Affects: `simt-dev` CLI (workspace resolution, `compare`, `skills`, registry validation, packaging)
 
 ## Context

package/docs/decisions/ADR-099-the-release-verifies-served-bytes-and-the-formula-mirrors-them.md

@@ -5,7 +5,7 @@ simt-supersedes: [{ adr: "ADR-098", ruling: 3, kind: "narrowed" }]
 
 # ADR-099 — the release verifies served bytes, and the formula mirrors them
 
-Status: **accepted** · 2026-10-27 · narrows ADR-098 ruling 3
+Status: **accepted** · 2026-10-27 · narrows ADR-098 ruling 3 · ruling 1 superseded by [ADR-117](ADR-117-the-darwin-release-builds-on-supported-macos-15-runners-and-a-re-run-is-idempotent.md)
 
 Affects: `.github/workflows/publish.yml`, `scripts/build-sea.mjs`,
 `scripts/verify-release-asset.mjs`, `Formula/simt-dev.rb`

package/docs/decisions/ADR-117-the-darwin-release-builds-on-supported-macos-15-runners-and-a-re-run-is-idempotent.md

@@ -0,0 +1,81 @@
+---
+simt-affects: [".github/workflows/publish.yml", "test/binary.test.mjs"]
+simt-supersedes: [{ adr: "ADR-099", ruling: 1, kind: "superseded" }]
+---
+
+# ADR-117 — the darwin release builds on supported macOS 15 runners, and a re-run is idempotent
+
+Status: **accepted** · 2026-10-31 · supersedes ADR-099 ruling 1
+
+## Context
+
+The v0.7.0 release run `41215349142` reached the first binary release: the npm stage
+succeeded, the release record was created, and `linux-x64` built. Both darwin jobs failed
+in the same place — `macos-14`, the runner ADR-099 ruling 1 named, is deprecated, and
+GitHub was running scheduled brownouts of that image ahead of its retirement.
+
+The old matrix also used one label for two architectures. GitHub's runner-images table
+now names `macos-14` as arm64 and `macos-14-large` as Intel, so "both targets on
+`macos-14`" was not the native-runner arrangement ADR-099 claimed. The replacement has
+to name the arm64 and Intel images explicitly.
+
+The same run exposed a second release-path defect. `publish-npm` decided whether to skip
+by asking the registry whether the version was published. A staged version is not
+published, so re-running the workflow after every other job succeeded would try to stage
+the same version again and fail on the duplicate. "Re-run all jobs" is the normal way to
+recover a partially failed release, and it must not turn a completed stage into a red
+job.
+
+## Ruling
+
+1. **Darwin targets build on the supported native macOS 15 images.**
+   `darwin-arm64` runs on `macos-15` and `darwin-x64` runs on `macos-15-intel`;
+   `linux-x64` stays on `ubuntu-latest`. These are the standard, non-deprecated labels
+   for the two architectures, not the larger-runner variants. ADR-099's per-host
+   determinism and upload-integrity claims are unchanged; only the label that provides
+   the native host moves.
+
+2. **A re-run is idempotent for a stage that already succeeded.**
+   `publish-npm` checks the npm staging queue as well as the registry. A version that is
+   published *or* already staged sets `SKIP=true`, so the tests, the wheel check and
+   `npm stage publish` are not repeated. The staging check runs after npm 11 is
+   available, because `npm stage list` is the command that makes the queue visible. A
+   failed stage list is not treated as proof of absence: the job attempts the stage and
+   fails loudly rather than silently skipping a release that does not exist.
+
+   The release record, asset upload and formula mirror were already idempotent —
+   `create-release` edits an existing release, `gh release upload --clobber` replaces
+   assets, and `sync-formula` exits when the mirror already names the served bytes.
+   They stay that way. A re-run does not skip a build on the grounds that an asset with
+   the same name exists: the tag can have moved, and the asset must be built from the
+   tree the tag now names.
+
+## Consequences
+
+- A darwin failure is recovered on a runner GitHub supports, and the arm64 and Intel
+  assets are produced on the architectures they claim.
+- "Re-run all jobs" after a successful stage is green: the stage job says the version is
+  already staged, the release record is refreshed in place, and the formula is compared
+  rather than overwritten.
+- "Re-run failed jobs" remains the narrower recovery: it rebuilds only the targets that
+  failed, which is the path the v0.7.0 run needed.
+- ADR-099 ruling 1 is superseded. Its ruling 2 (upload integrity) and ruling 3 (the
+  formula mirrors served bytes) still govern the release.
+- `test/binary.test.mjs` reads the committed workflow and asserts the two darwin labels,
+  so a future edit that returns to a deprecated or wrong-architecture runner fails the
+  suite instead of a release.
+
+## Rejected
+
+- **`macos-latest` for arm64.** It moves with GitHub's newest stable image. A release
+  builder should change when this repository decides to change it, not when a label
+  migrates.
+- **`macos-26`.** It is newer than the release needs, and no run has proven the pinned
+  Node base and `codesign` pipeline on it. Moving to it is a separate reviewed change.
+- **`macos-14-large`.** It is the Intel half of a deprecated image, so it inherits the
+  brownout that caused this failure.
+- **Skipping a build because the asset name already exists.** The tag this workflow runs
+  for can be moved, and an asset left from an earlier tree would then be served as the
+  new tag's binary. Rebuilding and clobbering keeps the bytes tied to the tagged tree.
+- **Detecting a prior stage through the registry alone.** A stage is deliberately not
+  public, so the registry cannot answer whether it exists.

package/docs/decisions/ADR-118-the-bench-corpus-is-keyed-on-history-is-append-only-and-is-portable-as-a-sealed-document.md

@@ -0,0 +1,91 @@
+---
+simt-affects: ["src/bench/mine.mjs", "src/bench/corpus.mjs", "src/bench/grade.mjs", "src/argv.mjs", "src/commands/bench.mjs", "src/commands/index.mjs", "src/commands/help.mjs", "test/bench.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-118 — the bench corpus is keyed on history, is append-only, and is portable as a sealed document
+
+Status: **accepted** · 2026-10-31 · filed as review 0003 Q48
+
+## Context
+
+Review 0003 (Q48) verified four failures in the mined bench corpus:
+
+- The vault was keyed on the absolute checkout path, so the 20 committed tasks
+  failed from every clone (`ENOENT …/vault/repo-ca1b5891/…/gold.patch`): a corpus
+  was unrunnable from any machine that was not the one that mined it.
+- Re-mining silently replaced the corpus: `mineTasks(target 3)` deleted all 20
+  committed tasks and wrote 3 others, with no signal that anything was lost.
+- The Gradle grader read one report file and the Maven grader read none, while
+  both runners write one JUnit XML *per test class* under a directory: both
+  graders graded on an empty parse.
+- Code-read: 7-character ids with a fixed `-01` suffix can collide, and the
+  exclusion list and the per-test timeout were hardcoded, so a repository could
+  not declare its own.
+
+## Ruling
+
+1. **The vault is keyed on the repository's history, not its checkout path.**
+   The key is the checkout basename plus the root commit
+   (`git rev-list --max-parents=0 HEAD`), read synchronously like
+   `package-version.mjs`: a vault path that throws is worse than one that is
+   occasionally less specific. The root commit is identical in every clone and
+   survives remote renames; a root with no git history degrades to the path
+   digest, because a vault path must never fail because git is absent.
+2. **Re-mining is append-only, and taking over the corpus is explicit.** Tasks
+   the current mine does not reproduce survive a re-mine; only `--replace`
+   deletes them. An id that already holds a task from a different
+   `sourceCommit` is a hard error naming `--replace`, not a silent overwrite —
+   guessing which corpus the reader wants is worse than refusing.
+3. **New task ids are 12 hex characters plus `-01`.** The 20 committed tasks
+   keep their 7-character ids: the corpus is not regenerated to widen them, and
+   the collision check — not a wider prefix — is what makes a collision an
+   error.
+4. **JUnit XML is read from the directory the runners write.**
+   `readReports(paths)` walks report directories recursively in sort order
+   (Gradle `build/test-results/test/`, Maven `target/surefire-reports/`), reads
+   single files, and skips missing paths. The miner and the grader clean
+   `reportPaths` before every run — a report left by a prior run would be
+   graded as this run's result — and read through `readReports`.
+5. **Exclusion and timeout are repository-declared.** `simt.json`
+   `bench.mine.{exclude,timeoutMs}`; an explicit option wins, then the manifest,
+   then the default (`['test/pack.test.mjs']`, 5000 ms).
+6. **The corpus is portable as a sealed document.** `bench export <corpus.json>`
+   and `bench import <corpus.json>` (in `src/bench/corpus.mjs`) carry the task
+   descriptors and both hidden patches for every task in a single file: tasks
+   sorted by id, canonical key-sorted JSON, base64 patches, no timestamp, and a
+   sha256 seal over everything but the seal. The seal is verified before a
+   single byte is trusted, and two exports of the same corpus are
+   byte-identical.
+7. **The mine records where the corpus came from.** `.simt/bench/corpus.json`
+   carries `{minedFrom, target, simtVersion}` — no timestamp, so a re-mine at
+   the same HEAD is byte-identical.
+
+## Consequences
+
+- A `bench export` on the machine that mined a corpus and a `bench import` on
+  any other machine reproduce it exactly, hidden test patches included: the
+  committed corpus is runnable from a clone.
+- 7-character and 12-character ids coexist in one corpus; the schema test
+  asserts the committed corpus keeps its 7-character ids and the miner asserts
+  12 for every new mine.
+- `bench import` and `bench export` preview like every other write: without
+  `--yes` nothing is written, and a dry-run import writes nothing.
+- The sealed document lives in its own module (`src/bench/corpus.mjs`);
+  `mine.mjs` is trimmed to the 1000-line ceiling so the slice adds no new
+  file-lines finding.
+
+## Rejected
+
+- **Keying the vault on the remote URL.** It breaks on a remote rename, and it
+  is a second mutable identity where the root commit is immutable and
+  clone-invariant.
+- **Regenerating the committed corpus to 12-character ids.** It churns 20 task
+  files and their vault layout for a width only new mines need; the collision
+  check, not a wider prefix, is what protects the corpus.
+- **A timestamp in the exported document.** It breaks byte-identity: two
+  exports of the same corpus differ, and a reader cannot tell content drift
+  from time drift.
+- **Silent overwrite on re-mine.** The failure this ADR exists to fix: a corpus
+  is data, and a routine command deleting twenty tasks is a data loss wearing a
+  success exit code.

package/docs/decisions/ADR-119-the-environment-variable-points-into-a-workspace-the-repo-declared.md

@@ -0,0 +1,90 @@
+---
+simt-affects: ["src/workspace.mjs", "src/graph/load.mjs", "test/workspace.test.mjs", "simt.json"]
+simt-supersedes: [{ adr: "ADR-014", ruling: 1, kind: "superseded" }]
+---
+
+# ADR-119 — the environment variable points into a workspace the repo declared
+
+Status: **accepted** · 2026-10-31 · supersedes ADR-014 ruling 1
+
+## Context
+
+ADR-014 made the workspace configuration, resolved in a fixed, reported order:
+`--workspace`, then `SIMT_DEV_WORKSPACE`, then the user config file, then the sibling
+heuristic. Its ruling 1 named the variable's purpose as "CI and one-off invocations".
+
+A variable that is *exported* is not a one-off invocation. Measured: a developer whose
+shell exports `SIMT_DEV_WORKSPACE` for a multi-repo workspace, working in a single repo
+that declared no workspace, gets that repo treated as a member of the exported workspace
+— `repo/path` skill sources resolve against it, `compare` discovers its siblings, and
+`doctor` reports `env` as the source. The default case ADR-014 ruling 3 exists to keep
+first-class — a single repo with no workspace — silently depends on ambient environment.
+
+The asymmetry is the defect: the user config file is a *per-developer* fact, and an
+exported variable is one too, but a workspace is a *per-repo* fact. Nothing in the
+precedence list asked the repository whether it has a workspace at all.
+
+## Ruling
+
+### 1. The precedence gains the repository's own declaration, above the environment variable
+
+Precedence, highest first:
+
+1. `--workspace <path>` — an explicit flag always wins.
+2. The repository's own manifest declaration — a `workspace` key in `simt.json` (or the
+   legacy `simt-dev.json`, read by the same reader every other command uses). An `off`
+   value declines exactly as it does from any other source, and the environment variable
+   cannot override a decline: a repo that said it has no workspace is not one.
+3. `SIMT_DEV_WORKSPACE` — a value that names a directory is honoured **only where
+   the manifest declares a non-declining workspace**: the variable is a pointer INTO
+   a workspace the repo opted into, not one imposed on a repo that never declared
+   one. A value that declines is honoured from anywhere, because a decline points
+   at nothing and so needs no declaration to work.
+4. The manifest's value — a relative path resolves against the manifest's directory, not
+   the process's, so `workspace: ".."` means the same thing from any subdirectory.
+5. The user config file — unchanged, and honoured regardless of the declaration, because
+   it is a per-developer fact that predates the repo.
+6. The sibling heuristic — unchanged: consulted last, accepted only when it verifies.
+
+Every command that consults the workspace reports where it came from, as before; the
+declaration introduces the source label `repo`.
+
+### 2. A manifest that exists and does not parse is an error, and it names the file
+
+Same shape as the unparseable-config error ADR-014 ruling 2 established: precedence
+decides which *answer* wins, but a file that exists and does not parse is a defect in
+the reader's setup, and hiding it because some other source outranked it would send
+them looking in the wrong place.
+
+### 3. The memoisation key names the directory whose manifest decides
+
+`src/graph/load.mjs` memoised the resolution per flag, variable and config location.
+The current directory's manifest now decides part of the answer, so the key names it;
+a memo that cannot see the directory serves one caller's declaration to a later caller
+standing in another repo.
+
+## Consequences
+
+This repository dogfoods the declaration: its own `simt.json` carries
+`"workspace": ".."`. The resolved root is unchanged — the sibling heuristic already
+verified the same directory — but the source label moves from `heuristic` to `repo`,
+which is the point: the workspace this repo resolves is declared, not guessed.
+
+An exported `SIMT_DEV_WORKSPACE` is inert in a repo that declared no workspace, which
+is the measured case this record exists to fix. In a repo that did declare one, the
+variable still overrides the declared value, so CI pinning a workspace for a known
+multi-repo checkout is unchanged.
+
+## Rejected
+
+- **Honouring the variable only in CI.** The tool has no CI detector, and "CI" is not
+  a fact about the repository; a detector that is wrong in one direction reproduces
+  the measured defect, and wrong in the other breaks the one-off use the variable
+  exists for.
+- **Making the declaration a precondition for the config file too.** The config file
+  is per-developer and works from any repo, including one that has no manifest yet;
+  requiring a declaration would break the single-repo reader with a config, which is
+  the audience ADR-014 ruling 3 protects.
+- **Renaming the variable.** It is the documented pointer in every remedy string this
+  tool ships; renaming it moves the defect into the reader's muscle memory rather
+  than deleting it.

package/docs/decisions/ADR-120-a-pre-push-whose-tree-is-already-proven-green-skips-the-test-gate-on-that-evidence.md

@@ -0,0 +1,96 @@
+---
+simt-affects: ["src/hooks/dispatcher.mjs", "rules/core.md", "rules/mdc/slice-commit.mdc", "test/hooks.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-120 — a pre-push whose tree is already proven green skips the test gate on that evidence
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+The shared dispatcher runs a repository's declared pre-push gates on every push. For
+this repository that is the full test suite — minutes of wall clock — and the common
+shape of push pays it twice: the author ran the suite green on the very tree being
+pushed, committed nothing further, and the gate runs it again at push time.
+
+ADR-113 already ruled that a push carrying only documentation skips the test gate and
+says so. It is the right shape of the answer and the template for this one: a skip
+earned by a property of the push, reported with a reason, and the record that earned it
+named in the report. This record extends it with a second property: a push whose
+committed tree is one the suite has already passed.
+
+The dispatcher records every gate run against the tree it ran on (ADR-087). A passing
+run is evidence about one tree and no other; editing any file afterwards produces a
+different tree, and the old line no longer proves anything about what is on disk. The
+evidence the ledger already keeps is exactly the evidence this skip needs, and no
+other state is required.
+
+## Ruling
+
+### 1. The skip is unconditional, evidence-driven, and fail-closed
+
+A pre-push `test` gate is skipped when — and only when — the ledger records a passing
+`test` run whose tree equals the committed tree being pushed (`HEAD^{tree}`). There is
+no manifest key to declare: the condition is a fact about the evidence, not a policy
+choice. Every uncertainty fails closed to the suite — an unborn HEAD, an unreadable
+ledger, no entry for this tree, or a later failure on the same tree. A gate that cannot
+prove it need not run does not run; a gate that cannot prove it is a failure, not a
+skip.
+
+"No changes since" is enforced by the digest, not by trusting the author: a clean
+working tree's recorded `worktreeTree` equals `HEAD^{tree}`, and any later edit changes
+the tree id, so the match fails and the suite runs.
+
+### 2. The skip is reported, and names the record that earned it
+
+The report prints the skip with its reason and the ADR that earned it — the same shape
+ADR-113 fixed for the docs-only path. The `test` gate line reads
+`SKIPPED test … [ADR-120]`, so a skip is never silent and the two skip paths are
+distinguishable in the same report.
+
+### 3. The docs-only skip keeps its own record
+
+The two skips are independent and compose: the docs-only classification is consulted
+first (it is cheaper — no ledger read), and where it does not fire, the evidence check
+decides. A push that earns both is reported under whichever fired first; both earn the
+same outcome, and the report names the one that did the work.
+
+### 4. The rule tells the agent to cite the pass, not re-run it
+
+`rules/core.md`'s Git section and the `slice-commit` rule both state the agent-side
+half: once a push is approved and the suite ran green on the current state with nothing
+changed since, the agent pushes directly and cites the already-passing run as the pass.
+The gate recognising the evidence is what makes that citation verifiable — the agent
+claims a run the ledger records, and a claim the ledger does not record is a claim the
+evidence check flags.
+
+## Consequences
+
+- `src/hooks/dispatcher.mjs` gains `resolveAlreadyPassedSkip(root)` and threads the
+  earning record (`adr`) through `skipTest` so the report distinguishes ADR-113 from
+  ADR-120.
+- The `slice-commit` rule becomes the git-workflow home — commit order, message
+  format, push approval, worktrees — and the Git section of `rules/core.md` points
+  at it. This is a change to shipped rule text: every adopting repository's
+  projection re-renders on its next sync.
+- A repository that never records a run (a fresh clone, a clean checkout) is
+  unaffected: the ledger is empty, the check fails closed, and the suite runs exactly
+  as before.
+- The skip is strictly weaker than the re-run — it proves the same tree, with the
+  same suite, already passed — so it cannot admit a state the suite would have
+  rejected.
+
+## Rejected
+
+- **A manifest key (opt-in).** Consistent with ADR-113's declared skip, but the
+  condition here is a fact about the evidence, not a policy a repository chooses; a
+  key would let a repository declare a skip it never earns and hide the evidence
+  requirement. The docs-only skip stays declared because its condition — the shape of
+  the push — is not observable from the ledger.
+- **Matching the working tree.** The pre-push gate runs at HEAD, so the evidence that
+  matters is a pass on the committed tree. Matching the working tree would let a
+  dirty tree skip on a pass that did not include its changes.
+- **A TTL or recency window.** The tree digest is a stronger condition than age: an
+  entry from a week ago is valid if the tree is the one being pushed, and a fresh
+  entry is void the moment a file changes. Age is not evidence; the digest is.