simt-dev 0.6.3 → 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
 
@@ -152,7 +161,7 @@ simt bench run --yes                # evaluate arms (bare, current, kernel, brie
 simt bench report [--compare a b]   # resolved rate, quality, cost, CPI, bootstrap CIs, McNemar/Wilcoxon
 simt bench ablate --yes             # leave-one-out rule ablation ranked by value per KB
 simt bench probes --yes             # 12 deterministic rule-compliance probes
-simt bench variants --yes           # evaluate simt-variants slots and lock winners in simt-dev.lock.json
+simt bench variants --yes           # evaluate simt-variants slots and lock winners in simt.lock.json
 simt review [--local]               # an advisory ADR-008 verdict skeleton over the staged diff
 simt distill <skill|doc>            # a budgeted proposal summary with line citations, for a person to merge
 simt pack new <name> --source <spec> # scaffold a versioned pack: pack.json, bench.json, one rule
@@ -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
 
@@ -369,10 +255,10 @@ history. All remain off until named and propose rather than write projected text
 | --- | --- |
 | `AGENTS.md` (and `<package>/AGENTS.md` in monorepos) | the projection, between `<!-- simt:begin -->` and `<!-- simt:end -->`. The old `simt-dev:` markers are still read, and a region migrates on its next write |
 | `simt.json` | the manifest: `gates`, `substitutions`, `budget`, `mode`, `shared`, `surfaces`, `plans`, `packs`, `federation`, `local` |
-| `simt-dev.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants` |
+| `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/agents/simt-agent.md

@@ -0,0 +1,84 @@
+---
+name: Simt-Agent
+description: Operates a repository with simt-dev: creates plan and review docs from the template, plans the next slice from the tracker, builds it, tests it, and commits it with evidence.
+---
+
+You are the simt-dev operator for this repository. You do three jobs in one:
+you **create the plan or review doc** when starting new work, you **plan** the
+next piece of work from the tracker, and you **build** it. You act through the
+`simt` commands the repository already runs, and you never claim a step you
+did not take.
+
+## Orient before you act
+
+- On a new task, run `simt brief "<task>"` before exploring. The packet tells
+  you how to run the tests, which files the task touches, and what governs them
+  — so you stop re-discovering what the repository already knows.
+- Before editing a file, run `simt why <file>`. It lists the decisions, rules,
+  skills, gates and lessons that govern that file. Edit with those in mind.
+
+## Plan the next slice
+
+- Read the tracker with `simt plan status` and `simt plan next`. `next` names
+  the smallest slice that is independently valuable, in dependency order.
+- Resolve the open material decisions for that slice before building: ask 1–5
+  questions, recommended option first, and only where the authority documents
+  leave a real choice. Apply documented defaults without asking — operational
+  and procedural choices are not questions.
+- State the slice you will take, the owning repository, the tracker task id,
+  and the acceptance checks, before you start.
+
+## Create the plan or review doc
+
+When starting a new feature or a review, the deliverable is a file, not a
+conversation. Write it before you build:
+
+- **Plan:** `docs/plans/NNNN-slug.md` — the next number after the highest one
+  already in that directory. Open with `# Plan NNNN — Title`, a `Status:` line
+  (`**queued**` · created date), scope, and a tracker table with one row per
+  slice carrying an id, a state, and an evidence column. Each slice gets its
+  own section below the table.
+- **Review:** `docs/reviews/NNNN-slug.md` — same numbering rule. Open with
+  `# Review NNNN — Title`, a `Status:` line, scope and method, severity
+  levels, and a tracker table or a pointer to the plan that owns the slices.
+- Do not display the plan in the conversation and stop. The file is the
+  deliverable; the conversation is the working session.
+- After the doc exists, track it with `simt plan status` and drive its rows
+  with `simt slice start` / `simt slice finish` / `simt plan done`.
+
+## Build one slice
+
+- Start it with `simt slice start <id>`. This isolates the tracker row in its
+  own worktree with a task brief. Work only in that worktree.
+- Make the smallest change that is independently valuable on its own. Do not
+  refactor outside the slice's blast radius.
+- Run the focused test the change needs, through the repository's own runner,
+  naming the exact command and the exact test file. Every test must pass; a
+  partial pass is a blocker, not a result to quote.
+- Stage only the files the slice touched. Leave unrelated work alone and say so.
+  Read the staged diff — not the working tree — before you commit.
+- Finish it with `simt slice finish <id>`. This runs the declared gates, commits
+  with a Conventional Commits subject drawn from the row, and records the SHA.
+- Record the slice complete with `simt plan done <id> <sha> --test "<command>"`,
+  carrying the evidence for the test you ran.
+
+## Dry run
+
+Most simt-dev commands that write to the repository default to **dry-run**:
+they print what they would change and exit without writing. Add `--yes` to
+apply. Read the dry-run output first — it is the plan — then re-run with
+`--yes`. A dry-run that shows an unexpected file is a reason to stop, not to
+add `--yes` and hope.
+
+For the full command reference — which commands are mutating vs read-only, and
+the scenario-to-command mapping — read the `simt-commands` skill.
+
+## Boundaries you do not cross
+
+- Never claim a test you did not run, a check you did not execute, or a commit
+  you did not make.
+- Commit locally and report the SHA. Pushing is a separate decision that needs
+  its own approval; a finished slice is not a reason to push.
+- Never use `--no-verify`, and never amend, rebase, reset or rewrite history
+  unless explicitly asked.
+- A gate that cannot run blocks the commit; do not skip it to get a green line.

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-009-skill-layout.md

@@ -1,6 +1,6 @@
 # ADR-009 — Skills are `<name>/SKILL.md` with mandatory frontmatter
 
-Status: **accepted** · 2026-10-05 · affects all repos
+Status: **accepted** · 2026-10-05 · affects all repos · ruling 4 superseded by ADR-112
 
 ## Context
 

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-086-the-stable-prefix-comes-first-and-the-lock-records-both-digests.md

@@ -1,6 +1,6 @@
 # ADR-086 — The stable prefix comes first, and the lock records both digests
 
-Status: **accepted** · 2026-10-18 · filed as R13 (plan 0003)
+Status: **accepted** · 2026-10-18 · filed as R13 (plan 0003) · ruling 3's file name is superseded by [ADR-110](ADR-110-the-lock-file-follows-the-manifest-name-and-the-old-name-is-read-until-the-next-write.md)
 
 **Affects:** `src/projection/rules.mjs`, `src/projection/lock.mjs`, `src/commands/sync.mjs`,
 `src/argv.mjs`, `test/lock.test.mjs`, `test/card.test.mjs`

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-106-the-harness-hook-runs-through-a-repo-shim.md

@@ -0,0 +1,46 @@
+---
+simt-affects: ["src/agenthooks/shim.mjs", "src/agenthooks/render.mjs", "src/commands/agenthook.mjs"]
+simt-supersedes: []
+---
+
+# ADR-106 — the harness hook runs through a repo shim, and `failClosed` only with it
+
+Status: **accepted** · 2026-10-29
+
+## Context
+
+Review 0003 (Q21) verified by code-read that every harness config named the
+bare `simt` binary. A devDependency install puts `simt` in
+`node_modules/.bin`, not on a harness's PATH, so that entry runs nothing on
+Claude — a non-2 exit is silent: no enforcement — and blocks every tool call
+on Cursor, whose entry sets `failClosed: true`. The install wrote a command
+that worked only on machines that happened to have the binary on PATH, which
+are exactly the machines that least need the hook.
+
+## Ruling
+
+1. **Every harness config names the repo shim, never the binary.**
+   `agent-hooks install` writes `.simt-hooks/agent-hook` beside the git shims,
+   rendered with the same `renderLocator` block from `src/locate.mjs`, and
+   every entry's command is `<shim> <event> --harness <id>`. The shim takes its
+   arguments through (`agent-hook "$@"`), so one file serves every event and
+   every harness, and `--harness` stays explicit rather than detected.
+2. **`failClosed` is set only because the command is the shim.** Cursor keeps
+   `failClosed: true` on entries that point at the shim. It is never set on a
+   bare-PATH binary: that combination blocks every tool call on the machines
+   where the binary is not installed, which is exactly the machines the shim
+   exists for.
+3. **A shim that cannot resolve refuses.** When no binary is reachable the shim
+   exits 1 with a remedy, the way the git shims do. On Claude that is still a
+   non-2 exit — silent, no enforcement — and that limitation is accepted and
+   stated here rather than hidden: the shim fixes the machines where `simt`
+   is installed but not on PATH, not the machines where it is absent.
+
+## Consequences
+
+- `ours()` recognises both spellings, so an install over a pre-shim config
+  migrates the entry in place instead of stacking a second one.
+- The shim is journaled with the configs, so `undo` removes or restores it
+  with the run that wrote it.
+- A hand-written bare-`simt` entry is the author's, not this tool's: `status`
+  does not claim it, and `install` replaces it.

package/docs/decisions/ADR-107-an-install-can-name-one-harness-and-the-skipped-ones-are-named.md

@@ -0,0 +1,51 @@
+---
+simt-affects: ["src/commands/agenthook.mjs", "src/commands/help.mjs", "test/agenthooks.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-107 — an install can be narrowed to one harness, and the skipped ones are named
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+`agent-hooks install` wrote every harness that documents a hooks file. A
+repository whose agents run in one of them received entries in the others'
+files as well — files no agent there reads, which a later `status` then
+reports PRESENT while nothing in that harness enforces anything. For a
+one-harness repository the install wrote more files than it needed to, and
+there was no way to ask for fewer.
+
+ADR-079 ruling 11 settled that the readers this tool does not write are
+*named* in the report — a command that writes four files and stays silent
+about the fifth reads as covering it. A narrowed install creates a third
+category that ruling did not anticipate: readers this tool *can* write and
+did not.
+
+## Ruling
+
+1. **`agent-hooks install --harness <id>` writes that one reader.** The id is
+   validated against the adapter table before anything is planned, and an
+   unknown id is a usage error that names the valid ids — the same validation
+   `agent-hook` applies, with the same remedy. The shim is written as before:
+   every config points at it, and a one-harness install would leave a config
+   pointing at a shim that is not there.
+2. **The skipped adapters are named in both surfaces.** The text report
+   prints a `SKIPPED` line per skipped reader with a note that says how to
+   write them all, and the JSON document carries them in `notWritten` with
+   `state: "skipped"`. A narrowed install that stays silent about the readers
+   it left alone is the failure ADR-079 ruling 11 ruled out for the full one.
+3. **`status` is unchanged.** It reports what each harness *will* run, and a
+   file that was never written is `ABSENT` there — the true answer. The
+   narrowing is a choice the install made, and the install's report is where
+   that choice is recorded.
+
+## Consequences
+
+- A repository that installs for one harness and later adds a second runs
+  install again — with the new id, or without any — and the merge creates the
+  entry in the new file while the files it already wrote come back
+  `UNCHANGED`. Nothing about a narrowed install has to be undone.
+- The prompt opt-in hint prints only when the selected harness can receive a
+  packet; a narrowed install to a harness with no prompt event does not ask
+  for an opt-in it cannot use.

package/docs/decisions/ADR-108-an-adoption-builds-the-index-and-a-command-refreshes-it-on-read.md

@@ -0,0 +1,59 @@
+---
+simt-affects: ["src/commands/init.mjs", "src/commands/map.mjs", "test/init.test.mjs", "test/map.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-108 — an adoption builds the index, and a command that reads it refreshes it on read
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+The index is a cache of git blobs (ADR-089): gitignored, rebuildable from
+`git ls-files -s`, and the data source for `simt map`, `simt brief` and
+`simt slice`. Two states of that cache were wrong for an adopted repository.
+
+First, `simt init` adopted a repository and left the index unbuilt. The
+first `simt map` in a fresh adoption paid for a walk of the whole tree, and
+the prompt-submit hook delivered a cold index — "the index is empty" — until
+somebody happened to run `simt index`. An adoption that promises the tool
+works in that repository should leave it able to answer.
+
+Second, once built, the cache went stale silently. `loadGraph` rebuilt only
+when the index was *empty*, so a file added after the build was invisible to
+every command that reads the index, with no way to tell from their output
+that they were answering from an old tree.
+
+## Ruling
+
+1. **`init` builds the index in the apply phase**, after the manifest is
+   written — `reindex` reads it for the declared parsers, so the manifest has
+   to exist first. The plan names the file it will build, and the JSON
+   document carries the result. A failure is a *note*, not a failed adoption:
+   the index is a cache, and an adopted repository whose index build failed
+   is better than one that refused to be adopted for it. The next read
+   rebuilds what the apply could not.
+2. **A command that reads the index refreshes it on read.** `loadGraph` with
+   `build` (the default) reindexes from the git index before it reads. The
+   refresh is incremental — a blob that has not changed is not re-read — so
+   the cost of a current repository is one `git ls-files -s`, not a walk of
+   the tree. The callers that build are commands a person typed: `map`,
+   `brief`, `slice`.
+3. **The `build: false` callers are unchanged.** The prompt-submit hook (R29)
+   and the MCP surface report a cold index rather than build one: a delivered
+   packet that walked the whole repository would make a person's first prompt
+   in a fresh clone wait, and a prompt that takes a minute to appear is how a
+   hook gets uninstalled.
+
+## Consequences
+
+- Amends ADR-091's consequence that "`simt map` reads the index and rebuilds
+  it when the cache is empty": the refresh now happens on every read, not
+  only on an empty one.
+- In an adopted repository the prompt hook can deliver a packet from the
+  *first* prompt: `init` has already built the index, so R29's "the first
+  prompt gets nothing, the second gets the packet" no longer applies to a
+  repository that was adopted rather than cloned.
+- `simt why` is unchanged: it deliberately does not write the cache to answer
+  a question, because writing a cache to answer a question would change the
+  tree.

package/docs/decisions/ADR-109-simt-dev-is-its-own-consumer-and-the-guards-that-kept-it-from-being-one-are-retired.md

@@ -0,0 +1,47 @@
+---
+simt-affects: ["AGENTS.md", "rules/core.md", "rules/stacks/node.md", "rules/stacks/python.md", "rules/stacks/connectiq.md", "src/projection/project.mjs", "test/baselines.test.mjs", "test/upgrade.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-109 — simt-dev is its own consumer, and the guards that kept it from being one are retired
+
+Status: **accepted** · 2026-10-30
+
+## Context
+
+This repository ran `simt init` on itself, and the suite still believed the
+opposite. Two tests asserted that simt-dev is *not* a consumer of itself — no
+manifest, no region — and `AGENTS.md` explained why self-adoption was
+impossible: the region's stamp records a SHA, so every commit would make the
+file stale.
+
+That explanation is no longer true. The `simt:sha=` stamp is a digest of the
+rule *content* — `rules/` and the baselines — not of this repository's HEAD.
+A commit here does not move it, so `check` stays green until the rule text
+itself changes, and `simt sync --yes` re-renders it when that happens.
+
+## Ruling
+
+1. **This repository is a consumer of itself.** `simt.json` declares its
+   gates, and the generated region in `AGENTS.md` carries the rules it
+   projects. The two tests that asserted the opposite are rewritten to assert
+   the new state: the baselines exist with the region first, and an `upgrade`
+   from its own source is a no-op that moves no stamp.
+2. **The rule text names the manifest by the name that resolves in every
+   repository.** Four rule files said `simt-dev.json`, the pre-rename name;
+   ADR-056 reads both and writes the new one, so a reader in any repository
+   finds only `simt.json`. The text now says `simt.json`.
+3. **A gate finding whose `detail` is absent is `null`, not `undefined`.** A
+   key with an `undefined` value survives into the structured MCP surface but
+   is dropped by `JSON.stringify`, so the two surfaces of one answer no longer
+   deep-equal. The four constructions of a region verdict now share one helper
+   that emits `null`.
+
+## Consequences
+
+- The suite's view of this repository is the adopted one: `check` here is
+  green until the rule content changes, and the baselines test asserts the
+  region-first placement that keeps a hand-written setting below it winning
+  (ADR-025).
+- `AGENTS.md`'s hand-written section now says what is true: the repository
+  adopts itself, and the stamp is a content digest.