simt-dev 0.6.0 → 0.6.3

package/CHANGELOG.md

@@ -6,6 +6,77 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.6.3] — 2026-10-29
+
+### Added
+
+`simt explain <CODE>` names what a `check` finding means, the decision behind
+it, how to fix it, and a concrete trigger — one table row per finding code, so
+every code `check` can emit has an entry.
+
+`simt doctor --fix` applies only the remedies flagged safe (local, idempotent,
+journaled) and lists the rest; a fixture with three safe and two unsafe findings
+fixes exactly three.
+
+`simt status --line` prints the gate state from the last `check` in under
+50 ms from cache — `simt PASS ✓rules ✓hooks 3/3gates` — for shell prompts, tmux
+and agent status lines.
+
+Every write records `{path, beforeDigest, afterDigest, beforeBytes}` in
+`.simt/journal/`, and `simt undo` restores the last set when every file in it
+is untouched since.
+
+`--diff` on every writer prints a unified diff of the plan next to the report,
+changing nothing about what the run writes.
+
+`simt completions <bash|zsh|fish>` prints a completion script generated from the
+command registry, so the three shells complete exactly the commands the binary
+dispatches.
+
+One ignore list (`.simtignore`) renders `.cursorignore`, `.aiderignore`,
+`.geminiignore` and Claude `permissions.deny`, and a zero-dependency
+staged-diff secret scan (vendor patterns plus Shannon entropy over added lines
+only) blocks a commit carrying a probable secret without printing the bytes.
+
+`simt slice start <id>` isolates the work in a linked worktree on branch
+`slice/<id>` with the brief preloaded and flips the tracker row In progress;
+`simt slice finish <id>` runs the declared gates, commits a Conventional
+subject from the row title, and records the SHA and test command on the row.
+
+`simt lease <paths> --session <id>` claims files until a TTL in
+`.simt/leases.json`, and the pre-edit hook denies an edit leased by another
+session (ADR-101).
+
+`simt pr-body [--base <ref>]` assembles the pull request body from the evidence
+ledger, the decision records the diff touches, the gate state from the last
+check, and the residual risk in ADR-008 vocabulary. It is also exposed as the
+`pr_body` MCP tool; the two longest tool descriptions were shortened to hold
+the 2 KB `tools/list` budget.
+
+## [0.6.2] — 2026-10-27
+
+### Fixed
+
+The v0.6.1 tag run failed its own tests step: two decision-corpus lists in
+`test/rules.test.mjs` were not moved with ADR-099 (the partial-supersession
+shapes and the leaking-paths count, both designed to move with the corpus).
+Same product as v0.6.1; this tag exists so the release automation is proven by
+a green run rather than described by a red one.
+
+## [0.6.1] — 2026-10-27 (tagged, never published to npm)
+
+### Fixed
+
+The release automation, which the v0.6.0 tag proved broken in two places. The
+tag workflow compared CI-built binaries against locally-built committed
+checksums, but the build is deterministic per host family, not across them —
+the check could never pass, and darwin binaries cannot be finished on ubuntu
+runners for lack of `codesign` anyway. Each target now builds on its native
+runner, the release verifies the served bytes equal the built bytes, and a
+`sync-formula` job re-renders the committed formula from the served bytes
+(ADR-099). The formula description no longer starts with an article, which is
+what failed the Homebrew channel's `brew style` on v0.6.0. No product change.
+
 ## [0.6.0] — 2026-10-27
 
 ### Added

package/README.md

@@ -26,18 +26,18 @@ to merge. It does not write the projection.
 ## Install
 
 Requires **Node >= 22.20.0** for the npm and PyPI channels; the release binary carries
-its own runtime. The current published release is **0.5.0**. Pin it. The tool writes a
+its own runtime. Pin the release you install. The tool writes a
 content digest into the files it generates, and an unpinned upgrade changes them under
 you.
 
 ```sh
-npm i -D simt-dev@0.5.0
+npm i -D simt-dev
 
 # or globally
-npm i -g simt-dev@0.5.0
+npm i -g simt-dev
 
 # or once, with no install
-npx -y simt-dev@0.5.0 check
+npx -y simt-dev check
 ```
 
 ### From PyPI
@@ -68,7 +68,7 @@ runtime: the command works with no Node installed.
 ### As a single-file binary
 
 Each release carries one executable per platform — macOS arm64 and x64, Linux x64 —
-beside its `.sha256`. The channel's first release is the version after 0.5.0; pin that,
+beside its `.sha256`. Pin the release you download,
 and run this from the repository's top level:
 
 ```sh
@@ -85,7 +85,7 @@ published `.sha256` before running anything.
 ```sh
 # Adopt, inspect, and maintain a repository
 simt init                           # adopt or scaffold; prints a plan; --yes writes
-simt doctor                         # stack, facts, evidence, and config health
+simt doctor [--fix]                 # stack, facts, evidence, and config health (--fix applies safe remedies, journaled)
 simt check [--frozen]               # projection drift, manifest, lock, and declared checkers
 simt sync [--explain] --yes         # regenerate the projection
 simt upgrade --yes                  # move every consumer in the workspace to this SHA
@@ -103,6 +103,7 @@ simt why [path]                     # ADRs, rules, skills, gates, and lessons go
 simt rules list [--root <path>]     # rule catalogue and what applies to a repository
 simt rules show <id>                # read one rule body (including rules deferred in kernel mode)
 simt rules why <id|ADR-NNN> [--all] # the decision that settled a rule, and whether it still stands
+simt explain <CODE> [--json]      # what a check finding means, why it is reported, and how to fix it
 simt decide "<title>" --yes         # scaffold the next ADR with structured simt-affects / simt-supersedes
 simt lessons list                   # fail-to-fix, revert, review-block, and hook-denial candidates
 simt lessons review <id> --yes      # promote a candidate to docs/lessons/NNNN-<slug>.md
@@ -125,11 +126,20 @@ simt agent-hooks status             # what each harness will run, and whether Co
 simt agent-hook <event> --harness   # evaluate pre-tool-use, post-tool-use, or prompt-submit
 simt evidence                       # gate and test runs recorded against the current git tree
 simt evidence check <msg-file>      # verify a commit message does not claim unrecorded passing runs
+simt pr-body [--base <ref>]         # a PR body: the evidence block for this tree, changed
+                                    # decisions, gate state, and residual risk in ADR-008 vocabulary
 
 # Plans, context metering, workspace learning, benchmarks, local models, and MCP
 simt plan status                    # count queued, in-progress, complete, and accepted tracker rows
 simt plan next [<id>]               # print the next ready slice section (~1 KB)
 simt plan done <id> [<sha>] --yes   # mark a tracker row complete with its commit SHA and test command
+simt status --line                  # one-line gate state from the last check, for prompts (< 50 ms)
+simt undo --yes                     # restore the last journaled set of writes, if untouched since
+simt slice start <id> --yes         # a worktree on branch slice/<id> with the brief preloaded; row In progress
+simt slice finish <id> --yes        # run the pre-commit gates, commit a Conventional subject from the
+                                    # row's title, and record the SHA and --test command on the row
+simt lease [<paths>] --session      # claim files for this session (--ttl, default 1h) or list claims;
+                                    # the pre-edit hook refuses another session's edit until the TTL
 simt tokens [--repos] [--session]   # measure bytes loaded at session start or split a transcript
 simt harness detect [--user]        # detect configured harnesses at repo and user level
 simt harness loaders [--table]      # what each harness loads, in what order, and where its cap truncates
@@ -143,25 +153,37 @@ simt bench report [--compare a b]   # resolved rate, quality, cost, CPI, bootstr
 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 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
 simt pack lint [dir] [--require-measured] # validate a pack and state its measured ΔR
 simt pack publish [dir] --yes       # publish an npm-sourced pack (git packs name the tag-and-push)
-simt mcp [--list]                   # serve the 13 read-only tools over stdio JSON-RPC
+simt mcp [--list]                   # serve the 15 read-only tools over stdio JSON-RPC
+simt completions <bash|zsh|fish>    # a completion script generated from the command registry
+simt ignore [--yes] [--diff]        # render the one .simtignore list into .cursorignore,
+                                    # .aiderignore, .geminiignore and Claude's permissions.deny
 ```
 
 `init`, `sync`, `upgrade`, `hooks install`, `agent-hooks install`, `shared install`,
-`skills install`, `plan done`, `lessons review`, `decide`, `pack new`, `pack publish`
-and the `bench` writers print
-a plan and write nothing without `--yes`. None of them commit or push. `simt index`
+`skills install`, `plan done`, `lessons review`, `decide`, `ignore`, `pack new`,
+`pack publish`, `slice start`, `slice finish`, `lease` and the `bench` writers print
+a plan and write nothing without `--yes`. None of them push, and only
+`slice finish` commits — locally, through the pre-commit gates, and only what is
+staged. `simt index`
 writes its cache without asking: the file is gitignored and `git ls-files` can rebuild it.
 
+Declare `secret-scan` in `gates.preCommit` to block a commit whose staged diff
+carries a probable secret: the scan runs inside the binary (vendor patterns plus
+Shannon entropy, over added lines only), needs no install, and its report never
+prints the matched bytes.
+
 `check` runs the checkers a rule names (`max-file-lines`, `forbid-regex`,
 `forbidden-path-edit`, `required-file`), verifies structured ADR supersessions
 (`prose-partial-supersession`), and flags expired lessons (`LESSON-EXPIRED`). A marked
 rule line leaves the projection as `Enforced:` and the checker's name. The file-length
 line warns past 400 lines and fails past 1000. `simt evidence check` warns when a commit
 message claims a passing run this tree does not have, and the commit fails when
-`gates.evidence` is `block`.
+`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
 
@@ -180,6 +202,7 @@ through `simt mcp`.
 | 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 |
@@ -312,16 +335,16 @@ returns a JSON object with `task`, `commands`, `files`, `tests`, `decisions`, `s
 | **Governance & Provenance** | `simt why [path]`, `simt rules list`, `simt rules show <id>`, `simt rules why <id\|ADR-NNN>`, `simt decide` | `rules_list`, `rules_why` | Before touching governed files (`why`), when reading deferred kernel rules (`rules show`), or when checking/scaffolding ADRs (`rules why`, `decide`) |
 | **Skills & Disclosure** | `simt skills index\|brief\|show\|why\|find\|install\|compile\|eval`, `simt graph lint` | `skills_index`, `skills_find`, `skills_brief`, `skills_show`, `skills_why` | When a task requires domain workflows or reference docs without blowing the session token budget |
 | **Memory & Lessons** | `simt lessons list`, `simt lessons review <id> --yes` | — | After fixing a failing test/gate or hitting a hook denial, to inspect or promote reusable failure-to-fix lessons |
-| **Plans & Trackers** | `simt plan status`, `simt plan next [<id>]`, `simt plan done <id> [<sha>] --yes` | `plan_next`, `plan_done` | When executing a phased implementation or review plan row by row |
+| **Plans & Trackers** | `simt plan status`, `simt plan next [<id>]`, `simt plan done <id> [<sha>] --yes`, `simt slice start\|finish <id>`, `simt lease`, `simt pr-body`, `simt status --line`, `simt undo` | `plan_next`, `plan_done`, `pr_body` | When executing a phased implementation or review plan row by row |
 | **Adoption & Projection** | `simt init`, `simt doctor`, `simt check [--frozen]`, `simt sync`, `simt upgrade`, `simt ci` | `doctor`, `check` | When adopting a repo, diagnosing stack/config health, or verifying zero drift before commit |
 | **Dual Gates & Evidence** | `simt hooks install\|status\|run`, `simt agent-hooks install\|status`, `simt agent-hook`, `simt evidence [check]` | — | When installing git/agent hooks, running gates manually, or verifying test claims before committing |
 | **Context & Harnesses** | `simt tokens [--repos] [--session]`, `simt harness detect\|loaders`, `simt shared plan\|install` | — | When auditing startup token cost across harnesses (`claude`, `codex`, `cursor`, `opencode`, `antigravity`, `copilot`, `deepseek`) or deduplicating workspace rules |
-| **Workspace & Benchmarks** | `simt compare`, `simt bench mine\|run\|report\|ablate\|probes\|variants`, `simt local doctor` | `compare` | When auditing an entire multi-repo estate, measuring rule uplift/cost, or probing local model endpoints |
+| **Workspace & Benchmarks** | `simt compare`, `simt bench mine\|run\|report\|ablate\|probes\|variants`, `simt local doctor`, `simt review [--local]`, `simt distill` | `compare` | When auditing an entire multi-repo estate, measuring rule uplift/cost, or probing local model endpoints |
 
 ## Where the plan finishes
 
-Slices `R01`–`R45` are complete and shipped in `0.6.0`. The remaining queued slices are the
-small ergonomics:
+Slices `R01`–`R55` are all complete. The small ergonomics (`R46`–`R55`) shipped
+on top of `0.6.0`:
 
 - **The small doors (`R46`–`R55`).** `simt explain <CODE>` for every finding code, safe
   idempotent `simt doctor --fix`, a `< 50 ms` `simt status --line`, a write journal with
@@ -329,6 +352,12 @@ small ergonomics:
   plus a staged-diff secret scan, `simt slice start/finish <ID>` worktrees, file leases
   for parallel agents, and `simt pr-body` assembled from the evidence ledger.
 
+The last two rows of review `0002` (`S38` workspace token cost, `S39` estate policy
+as a pack) are closed by ruling in ADR-102: the instrument, the declaration and the
+non-blocking finding shipped, the blocking gate and the registry-carrying pack were
+refused by ruling, and the estate-side move is recorded as whose commit it waits on.
+Everything in plans `0001`–`0003` and reviews `0001`–`0002` is Complete or Accepted.
+
 The local-model slices (`R38`–`R40`) shipped as they lab-written: `simt distill` proposes
 budgeted summaries with line citations, `simt review` proposes an advisory ADR-008
 verdict over the staged diff, and `simt brief` carries model/effort advice from bench

package/bin/simt.mjs

@@ -4,26 +4,33 @@
 // 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 } from '../src/argv.mjs';
+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) {
-    process.exit(parsed.code);
+    // 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));
   }
 
-  jsonIndentDefault(flags.pretty === true);
-  jsonFailMode(flags.json === true);
-
   // 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
@@ -41,7 +48,13 @@ try {
   }
 
   const { dispatch } = await import('../src/commands/index.mjs');
-  process.exit((await dispatch(argv)) ?? EXIT.OK);
+  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));
 }

package/docs/decisions/ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md

@@ -5,7 +5,7 @@ simt-supersedes: [{ adr: "ADR-058", ruling: 5 }, { adr: "ADR-058", ruling: 7, ki
 
 # ADR-098 — The fourth channel is one file, and it needs no toolchain
 
-Status: **accepted** · 2026-10-26 · supersedes ADR-058 ruling 5 · narrows ADR-058 ruling 7 and ADR-097 ruling 3 · supersedes ADR-059 ruling 3
+Status: **accepted** · 2026-10-26 · supersedes ADR-058 ruling 5 · narrows ADR-058 ruling 7 and ADR-097 ruling 3 · supersedes ADR-059 ruling 3 · ruling 3's cross-host byte-identicality narrowed by [ADR-099](ADR-099-the-release-verifies-served-bytes-and-the-formula-mirrors-them.md)
 
 Affects: `scripts/build-sea.mjs`, `src/distribute/release.mjs`, `src/locate.mjs`,
 `src/hooks/shim.mjs`, `src/ci/workflow.mjs`, `.github/workflows/publish.yml`,

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

@@ -0,0 +1,79 @@
+---
+simt-affects: [".github/workflows/publish.yml", "scripts/build-sea.mjs", "scripts/verify-release-asset.mjs", "Formula/simt-dev.rb"]
+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
+
+Affects: `.github/workflows/publish.yml`, `scripts/build-sea.mjs`,
+`scripts/verify-release-asset.mjs`, `Formula/simt-dev.rb`
+
+## Context
+
+ADR-098 ruling 3 made determinism the release contract in its strongest form: the
+same tree builds byte-identical assets on any host, so the tag workflow rebuilds
+each asset and fails when its checksum is not the one `Formula/simt-dev.rb` in the
+tagged tree promises. The v0.6.0 tag proved the strong form false. The CI-built
+`linux-x64` asset hashed to `809dcda7…` while the same tree built on a darwin host
+hashed to `b55bffc2…` — and the local rebuild is reproducible, so the difference is
+the host, not the tree. The SEA blob is generated by a node running on the build
+host, and a darwin-generated blob and a linux-generated blob of the same tree
+differ. A check comparing CI bytes against locally-built committed checksums can
+therefore never pass, and keeping it means every release fails at tag time for a
+reason no tree change can fix.
+
+The same run surfaced the second defect in the arrangement: all three targets built
+on `ubuntu-latest`, but darwin binaries are finished with `codesign`, which exists
+only on macOS. The darwin jobs never ran anywhere before v0.6.0 — v0.5.0 predates
+the binary channel — so the runner assignment was never exercised either.
+
+## Ruling
+
+1. **Each target builds on its native runner.** `darwin-arm64` and `darwin-x64` on
+   `macos-14`, `linux-x64` on `ubuntu-latest`, with `fail-fast: false` so one
+   target's failure no longer cancels the others. Determinism is per host family —
+   the same tree rebuilt on the same OS family hashes identically — and the matrix
+   is what makes that claim checkable instead of aspirational.
+
+2. **The release checks upload integrity, not cross-host equality.** After uploading
+   each asset, the workflow downloads what GitHub serves for it
+   (`scripts/verify-release-asset.mjs`) and fails when the served sha256 is not the
+   one the build just wrote. A torn or clobbered upload graduates into a release
+   nobody can detect any other way; the tap installing bytes whose checksum refuses
+   them is exactly that failure arriving on somebody else's machine.
+
+3. **The committed formula is a mirror, refreshed after the release moves it — never
+   a prediction.** A `sync-formula` job renders `Formula/simt-dev.rb` from the
+   served bytes with `scripts/release-formula.mjs` and commits it to `main` when it
+   changed. A re-run that finds the mirror current exits quietly, and a formula
+   that already names a newer version is left alone, so an older tag can never
+   rewrite a newer mirror. The tap push (`publish-channels.yml`) already renders
+   from served bytes, so it was correct by construction throughout; this closes the
+   loop for the in-repo copy.
+
+## Consequences
+
+- **The v0.6.0 equality check is gone, and its premise with it.** Nothing in the
+  release compares bytes built on different hosts. The `build-sea.mjs` header no
+  longer claims cross-host byte-identicality.
+- **The formula in a tagged tree is the previous release's mirror, and that is
+  stated rather than hidden.** Between the tag and `sync-formula`'s commit it names
+  the served bytes of the last release, which is what makes it a mirror and not a
+  promise.
+- **`verify-release-asset.mjs` is runnable by hand.** It takes `--version` and
+  `--target` and answers whether the release serves what a build of this tree
+  wrote — the same question the workflow asks, askable from any checkout.
+
+## Rejected
+
+- **Generating one blob on one host and sharing it across targets.** It would make
+  the three assets share a blob while their node bases still differ per target, so
+  cross-host equality would still fail at the base — the part this repository does
+  not build. Sharing would add artifact plumbing to preserve a comparison the
+  release no longer makes.
+- **Committing the formula from the tag before the assets exist.** That restores the
+  prediction in a new place: the committed checksums would again be bytes no
+  download has served, and the first thing that reads them (the tap) would read a
+  promise instead of a record.

package/docs/decisions/ADR-100-a-staged-diff-is-the-last-gate-before-history-and-it-runs-inside-the-tool.md

@@ -0,0 +1,94 @@
+---
+simt-affects: ["src/hooks/gates.mjs", "src/hooks/resolve.mjs", "src/hooks/dispatcher.mjs", "src/projection/manifest.mjs", "src/secrets.mjs"]
+simt-supersedes: []
+---
+
+# ADR-100 — a staged diff is the last gate before history, and it runs inside the tool
+
+Status: **accepted** · 2026-10-27
+
+Affects: `src/hooks/gates.mjs`, `src/hooks/resolve.mjs`,
+`src/hooks/dispatcher.mjs`, `src/projection/manifest.mjs`, `src/secrets.mjs`
+
+## Context
+
+Git history is append-only: a secret committed is a rotation exercise, not a
+revert, and the one moment it can still be kept out is the commit. Every other
+leak path in this tool is already gated — the projection, the manifest, the
+evidence claim — but nothing gated the staged diff.
+
+The three existing gate kinds cannot express this check. `staged` hands files
+to a formatter binary in `node_modules/.bin`, `script` runs a `package.json`
+script, and `command` runs a line the manifest declares: each resolves
+something ON DISK, and each therefore has a way to be missing. A secret scan
+has nothing to resolve — the implementation is the question being asked — and
+making it a `command` gate would mean a repository declares `simt secrets`
+(or installs a third-party scanner) before the check exists at all. That is
+backwards for the repositories most at risk, which are frequently the ones with
+the least toolchain to install into.
+
+Plan 0003 R52 asks for both halves from one list and one binary: a
+zero-dependency staged-diff scan (vendor patterns plus entropy), and no
+repository needing anything to run it.
+
+## Ruling
+
+1. **A fourth gate kind, `builtin`, runs inside this binary.** It is declared
+   in the manifest like any other gate, a `gates.commands` entry overrides it
+   exactly as it overrides every other kind (the dispatcher's precedence is
+   unchanged), and its result flows through the same ledger line, the same
+   fail-closed reporting and the same `hooks status` view. What it never does
+   is resolve anything on disk: there is no script to miss, no formatter to
+   install and no command to declare, so `gateRunnable` reports it runnable and
+   `check` counts it as such. A `builtin` name with no implementation fails the
+   event with the name of the gate rather than passing.
+
+2. **`secret-scan` reads only the added lines of `git diff --cached`.** Two
+   detectors, both local: a pattern library for the shapes vendors publish
+   (AWS key ids, private key blocks, GitHub/Slack/Stripe/Google/OpenAI-style
+   tokens, JWTs, assigned secrets) and Shannon entropy (≥ 4.5 bits per
+   character over runs of ≥ 32 base64-ish characters) for the blobs no vendor
+   named. Values carrying placeholder markers (`example`, `changeme`,
+   `your_`, …) are documentation, not findings. Context lines are not
+   scanned: blocking a commit over bytes the author did not stage reproduces
+   the prohibition `format`'s staged-only rule exists for. If git cannot
+   answer, the gate fails rather than reading silence as a clean diff.
+
+3. **A finding never prints the matched bytes.** The report carries the
+   pattern id, the file, the line and a four-character prefix — the part a
+   vendor publishes as a type (`AKIA`, `sk-`, `ghp_`). Hook output lands in a
+   terminal, a CI log and often an agent's own transcript, and echoing the
+   secret into the report about the secret is the leak with extra steps.
+
+4. **The gate is opt-in, not an `init` default.** Entropy has a false-positive
+   rate no threshold eliminates, and a gate that blocks a first commit over a
+   sha256 digest teaches exactly the `--no-verify` habit the dispatcher exists
+   to prevent. A repository opts in by adding `secret-scan` to
+   `gates.preCommit`; from then on it is reported, counted and fail-closed like
+   every other declared gate.
+
+## Consequences
+
+- A repository gets the scan by declaring the gate; nothing is installed,
+  nothing is fetched at hook time, and a fresh clone runs it identically.
+- `unresolved()` and `gateRunnable()` know `builtin` as a runnable kind, so
+  `check` no longer has a gate it must call unrunnable-but-isn't; `hooks
+  status` prints `run builtin` for the entry.
+- A `gates.commands["secret-scan"]` declaration replaces the built-in scan
+  with whatever line the repository names — the escape hatch every other kind
+  has, preserved for this one.
+- The matcher lives in `src/secrets.mjs` and is unit-tested against sentinel
+  values, including the negative cases (hex digests, UUIDs, placeholders) that
+  decide whether the threshold is usable rather than merely strict.
+
+## Rejected
+
+- **Shipping a third-party scanner (gitleaks, trufflehog).** It violates the
+  zero-dependency rule outright, and a hook that downloads a scanner at commit
+  time is a hook that fails on an offline machine — the failure mode ADR-010's
+  no-fetch-at-hook-time rule already refuses for `npx`.
+- **Scanning the working tree or the whole repository.** That flags secrets
+  already in history on every subsequent commit (unfixable by the author of
+  this commit) and scans unstaged work nobody was about to record. The staged
+  diff is precisely the bytes the next commit would make permanent, and it is
+  the only bytes this gate claims to judge.

package/docs/decisions/ADR-101-a-file-lease-belongs-to-one-session-and-the-pre-edit-hook-refuses-another.md

@@ -0,0 +1,95 @@
+---
+simt-affects: ["src/lease.mjs", "src/commands/lease.mjs", "src/agenthooks/policy.mjs", "src/agenthooks/decide.mjs"]
+simt-supersedes: []
+---
+
+# ADR-101 — a file lease belongs to one session, and the pre-edit hook refuses another's edit
+
+Status: **accepted** · 2026-10-28
+
+Affects: `src/lease.mjs`, `src/commands/lease.mjs`,
+`src/agenthooks/policy.mjs`, `src/agenthooks/decide.mjs`
+
+## Context
+
+Parallel agents share one working tree, and the cheapest collision between them
+is two sessions editing the same file at once: each edit is valid alone, and
+the pair is neither — one session's work is overwritten by the other's save,
+with no gate, no diff and no hook that ever sees a conflict. Git notices this
+only at merge time, which is far after the fact either session can explain.
+
+Plan 0003 R54 asks for a claim mechanism: `simt lease <paths>` records which
+session is working on which path, with a TTL, and the pre-edit half of the
+agent hook denies an edit from a session that does not hold the claim.
+
+The policy table is where every other agent-time refusal lives (`push`,
+`rewrite`, `generated`), so a lease refusal belongs there too — one table,
+four harness dialects, one message. What the table has never had is a fact
+that is not in the payload: which session is asking, and who else has claimed
+the path.
+
+## Ruling
+
+1. **A lease is a claim, not a lock.** `.simt/leases.json` records one entry
+   per path: the repo-relative path, the session name, and an absolute expiry
+   timestamp. It is taken with `simt lease <paths>` (preview unless `--yes`),
+   the session comes from `--session` or `SIMT_SESSION`, and the TTL defaults
+   to an hour. There is no lock on the file and no daemon: a claim is advisory
+   data that expires on its own, last writer wins, and a claim lost to a race
+   is simply re-made. Coordination machinery would be a system built around a
+   file a TTL already cleans up.
+
+2. **A live claim held by a different session refuses a re-claim.** Stealing
+   is what expiry is for: the refusal names the holder and the expiry, and
+   the session that wants the path waits for the TTL or asks the holder. The
+   holder may re-claim (refresh) its own paths at any time.
+
+3. **The pre-edit hook denies an edit to a path another session holds.** The
+   check joins two facts at decision time: the active claims in the file, and
+   the asking session's name from `SIMT_SESSION` — one variable for the claim
+   and the check, because a denial is only explainable if the session it
+   protected is the same name the claim was filed under. A session that cannot
+   prove ownership is treated as another session: an unrecognised edit is
+   refused with the holder's name, not waved through. Expiry is read when the
+   hook runs, so a TTL needs no sweeper, and a claim with no file (the default
+   state of every repository) denies nothing.
+
+4. **An unreadable claim file fails closed for edits and only for edits.**
+   A `.simt/leases.json` that does not parse is evidence someone — possibly a
+   session routing around the check — broke the claims the hook is about to
+   enforce, so any write is refused until the file is fixed or removed; a
+   `lease` command refuses to write over it for the same reason. A shell
+   command with no file fact is not an edit and is not refused. This mirrors
+   the fail-closed contract every gate has, scoped to the question the lease
+   can actually answer.
+
+5. **The refusal is the `lease` policy, with the table's full machinery.** It
+   carries `ADR-101`, is lifted by `SIMT_ALLOW=lease` exactly as every other
+   policy is, exits with the harness's deny code, and its message names the
+   held paths, the holders and the expiry in ISO — the three things the
+   blocked session needs to act. The per-instance detail is a `detail` hook on
+   the row, so the message that quotes a timestamp does not become a special
+   case inside `decide`.
+
+## Consequences
+
+- Two sessions in one working tree can coordinate with one command and no
+  shared process; a crashed session's claims lapse on their own.
+- The hook's hot path gains one small `readFile` of a file that is usually
+  absent, and only when the payload named a file to write.
+- `learn.mjs` reads policy rows by `id` and `adr` only, so the `lease` row
+  joins the estate's violation aggregation with no further wiring.
+- The claim file is local state under `.simt` like the index and the journal:
+  never projected, never committed.
+
+## Rejected
+
+- **File locking (`flock`, a lockfile protocol).** A lock that blocks is a
+  deadlock with a crashed session in it, and it needs the very daemon ruling 1
+  refuses. The TTL already bounds every claim.
+- **Inferring leased paths from shell commands.** Only the edit tools name a
+  file with no guesswork; guessing at what a `sh -c` line will write is the
+  payload-shaped false positive the policy table was built to avoid — no fact
+  is not a violation.
+- **A lease the holder must release to finish.** Forgetting to release is the
+  expected failure of any release-based protocol; an expiry is not.

package/docs/decisions/ADR-102-the-two-queued-review-rows-are-closed-by-ruling.md

@@ -0,0 +1,49 @@
+---
+simt-affects: ["docs/reviews/0002-full-review-adoption-and-public-release.md"]
+simt-supersedes: []
+---
+
+# ADR-102 — the two rows review 0002 left queued are closed by ruling
+
+Status: **accepted** · 2026-10-28
+
+## Context
+
+Review 0002's §3 tracker is the only tracker of slice state, and two rows in it
+still read Queued while everything around them shipped: S38 (workspace token
+cost) and S39 (estate policy as a pack). Both rows' evidence cells are
+palimpsests — notes from three different landings disagreeing about what is
+still open — so reading them as a work list sends the next reader to build what
+is already built. Closing plan 0001 meant the same audit, and ADR-033 is the
+precedent: rows closed by saying what shipped, what was refused by ruling, and
+where the remainder lives, not by authoring what they asked for.
+
+## Ruling
+
+1. **S38 is Complete.** The instrument shipped (`simt tokens`, ADR-064), the
+   declaration shipped (`budget.bytes` beside `limits` and `gates`, ADR-072),
+   and the gate raises it as a finding through one `budgetFinding` read from
+   one place by both `tokens` and `check` — the "still open" clause the row's
+   first note ends on. Kernel-line packing shipped with it (R07's `mode:
+   kernel`, R08's budget compilation). Blocking enforcement is refused, not
+   outstanding: a gate that fails a repository for exceeding a ceiling it set
+   itself, when nothing was cut, has no repair except lowering the declared
+   number (ADR-072). The one genuine remainder is the kernel-default
+   compliance study, and it is owned by plan 0003 R07's own note, not by this
+   row — the study gates making `kernel` the default, which no row asks to
+   decide here.
+
+2. **S39 is Complete.** The mechanism shipped (packs vendored and digest-pinned,
+   ADR-065; measured ΔR, plan 0003 R45). P4's pack-carries-the-registry line was
+   superseded by ADR-061, which made the registry workspace data, so there is
+   no registry-carrying pack to build. The remaining half — moving estate
+   policy into a pack — is the estate's own commit: no estate content may enter
+   this repository, and a row that waits on another repository's commit is
+   closed by recording whose commit it waits on.
+
+## Consequences
+
+- The §3 tracker reads Complete on both rows, with this record as the evidence,
+  so the next audit starts from rulings rather than from mid-flight notes.
+- A reader asking for a blocking budget gate or a registry-carrying pack gets
+  the refusal and its reason instead of an open row that looks like a promise.