simt-dev 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,88 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-10-31
+
+### Added
+
+`simt agent-hooks install --harness <id>` writes the policies into one
+harness instead of all of them; an unknown id is a usage error that names
+the valid ones. The readers the run skipped are named in the report
+(`SKIPPED`) and in the JSON document's `notWritten`, so a narrowed install
+cannot read as full coverage (ADR-107).
+
+`simt init --yes` builds the repository index as part of the adoption, so
+the first `simt map` or `simt brief` in a fresh repository answers from real
+files. Commands that read the index (`map`, `brief`, `slice`) now refresh it
+from the git index on every read — unchanged blobs are not re-read, so a
+current repository pays for one `git ls-files -s` — and the prompt hook and
+MCP surface still report a cold index rather than build one (ADR-108).
+
+The rule text names the manifest as `simt.json`, the name it has had since
+the rename; four rule files still said `simt-dev.json`, which resolves in no
+repository.
+
+### Changed
+
+The projection lock is `simt.lock.json`, the name that follows the command
+and the manifest. A lock written under the old `simt-dev.lock.json` is still
+read — including the `variants` winners nothing else records — and migrates
+on the next write (ADR-110).
+
+This repository is now a consumer of itself: `simt init` ran on its own
+source, so the two tests that asserted it was *not* a consumer are rewritten
+to assert the new state, and `AGENTS.md`'s "not self-adopted" section now
+says what is true (ADR-109). A gate finding whose `detail` is absent is now
+`null` rather than `undefined`, so the CLI's JSON and the MCP structured
+surface of one answer deep-equal.
+
+## [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
@@ -16,7 +98,7 @@ 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
+## [0.6.1] — 2026-10-27 (tagged, never published to npm)
 
 ### Fixed
 

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
@@ -142,26 +152,38 @@ 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
 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
@@ -340,7 +369,7 @@ 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 |

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

@@ -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-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-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-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.