simt-dev 0.7.0 → 0.8.0

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,97 +74,193 @@ 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
 
+<!-- simt:commands:begin -->
+<!-- Rendered from the spec by `simt docs readme --yes`; do not edit by hand. -->
+
 ```sh
-# Adopt, inspect, and maintain a repository
-simt init                           # adopt or scaffold; prints a plan; --yes writes
-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
-
-# Orient on a task and query the local code and governance graph
-simt brief "<task>"                 # one <= 2 KB packet: kind, commands, files, tests, ADRs, skills, lessons
-simt index [--embed]                # files, symbols, edges, FTS5 tokens (+ optional local embeddings)
-simt map --task "<task>"            # hybrid BM25 + PageRank + resolver file ranking (outline|names|signatures)
-simt impact <file|symbol>           # importers, covering tests, governance, and cross-repo consumers
-simt tests <path> [--cochange]      # tests covering a file via imports, naming, coverage, or co-change
-simt gate --changed                 # run only the tests the current diff reaches, with compacted output
-simt why [path]                     # ADRs, rules, skills, gates, and lessons governing a path
-
-# Rules, skills, decisions, and lessons
-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
-simt skills index                   # tier-0 catalogue: every skill, one line each
-simt skills brief --task "<task>"   # tier-1 ranked skill selection within budget
-simt skills show <name>             # tier-2 skill body on demand (respects --max-bytes)
-simt skills why <name>              # the signal chain that selected or rejected a skill
-simt skills find <query>            # search skills by capability and keyword
-simt skills install <name> --yes    # pin a skill into the repository
-simt skills compile [<name>]        # compile to Agent Skills layout, split > 5,000-token bodies, report triggers
-simt skills eval [corpus]           # measure resolver precision and recall against a gold corpus
-simt graph lint [--spec agentskills]# verify the skill registry against skills on disk
-
-# Dual gates (git time and agent tool-call time) and execution evidence
-simt hooks install --yes            # install the shared POSIX git hook dispatcher
-simt hooks status                   # what each git event routes to, and whether it is wired
-simt hooks run <event>              # run pre-commit or pre-push gates now, as git would
-simt agent-hooks install --yes      # write pre/post-tool and prompt-submit hooks for active harnesses
-simt agent-hooks status             # what each harness will run, and whether Codex trusts it
-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
-simt shared plan                    # rules repeated across a workspace and the bytes saved by sharing
-simt shared install --yes           # write shared rules once at user level and record the repo delta
-simt compare                        # workspace matrix, violated rules, noisy/slow gates, and ADR drafts
-simt local doctor [--allow-remote]  # probe configured OpenAI-compatible local chat and embed endpoints
-simt bench mine --yes               # mine verified fail-to-pass tasks from git history into the vault
-simt bench run --yes                # evaluate arms (bare, current, kernel, brief) in isolated exports
-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.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 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
+# agent-hook
+simt agent-hook <event> --harness            # the harness entry point: decide one tool call, or deliver the prompt packet
+
+# agent-hooks
+simt agent-hooks install --yes               # write this repository's policies into each harness hooks file
+simt agent-hooks status                      # what each harness will run, and what is not trusted yet
+
+# agents
+simt agents install --yes                    # write the Simt-Agent into each harness agents file
+simt agents status                           # what each harness carries, and what is not installed yet
+
+# bench
+simt bench ablate --yes                      # measure one arm of the brief against its ablation
+simt bench critic                            # score the review critic against the labelled bench set
+simt bench export --yes                      # write the sealed bench corpus as one signed document
+simt bench import                            # verify a sealed corpus and load it into the vault
+simt bench mine --yes                        # mine tasks out of a repository history
+simt bench probes --yes                      # run the deterministic probes against a workspace
+simt bench report [--compare a b]            # summarise the runs recorded in the vault
+simt bench run --yes                         # run agents against the mined tasks
+simt bench variants --yes                    # run one task across its variant prompts
+
+# brief
+simt brief "<task>"                          # the packet for a task: rules, skills and the files it names, within a budget
+
+# check
+simt check                                   # report stale or missing generated regions and every check finding
+
+# ci
+simt ci                                      # refresh simt-dev's own .github workflow and Dependabot files
+
+# compare
+simt compare                                 # the adoption and drift matrix across every sibling repository
+
+# completions
+simt completions <bash|zsh|fish>             # print a bash, zsh or fish completion script generated from this spec
+
+# decide
+simt decide "<title>" --yes                  # scaffold a numbered decision record with its frontmatter
+
+# distill
+simt distill <skill|doc>                     # turn a repository into a skill or rule proposal
+
+# docs
+simt docs readme                             # render the README command list from the spec
+
+# doctor
+simt doctor [--fix]                          # report what is wrong with this installation
+
+# evidence
+simt evidence                                # the runs recorded against the tree on disk
+simt evidence check <msg-file>               # a commit message claiming a run this tree does not have
+
+# explain
+simt explain <CODE>                          # what one check finding code means, and how to fix it
+
+# gate
+simt gate --changed                          # the tests a change reaches, and only those
+
+# graph
+simt graph lint [--spec agentskills]         # check the skill registry against the skills on disk
+
+# harness
+simt harness detect [--user]                 # which harness is installed, and what it carries
+simt harness loaders [--table]               # the instruction files each harness loads, and what they cost
+
+# hooks
+simt hooks install --yes                     # install the shared dispatcher and report what it would run
+simt hooks run <event>                       # run one git event's gates now, as git would
+simt hooks status                            # what each git event routes to, and whether it is wired
+
+# ignore
+simt ignore [--yes] [--diff]                 # render the one ignore list into every harness ignore file
+
+# impact
+simt impact <file|symbol>                    # who a change reaches: importers, their tests and the contract
+
+# index
+simt index [--embed]                         # rebuild the local file index from git blob hashes
+
+# init
+simt init [path]                             # adopt this repository: manifest, region, hooks, agents and agent-hooks
+
+# lease
+simt lease [<paths>] --session               # claim files for one session, or list the claims
+
+# lessons
+simt lessons capture                         # scan the ledger and history for new lesson candidates
+simt lessons list                            # deterministic lesson candidates and the promoted lessons
+simt lessons review <id> --yes               # promote one lesson candidate into docs/lessons
+
+# local
+simt local doctor [--allow-remote]           # the local model endpoints, and whether they answer
+
+# map
+simt map --task "<task>"                     # the files a task is most likely to touch, within a byte budget
+
+# mcp
+simt mcp [--list]                            # serve the read-only MCP surface over stdio
+
+# pack
+simt pack lint [dir] [--require-measured]    # lint a rule pack in the working directory
+simt pack new <name> --source <spec>         # scaffold a rule pack
+simt pack publish [dir] --yes                # publish a rule pack
+
+# plan
+simt plan done <id> [<sha>] --yes            # mark one tracker row complete, with its SHA and its evidence
+simt plan next [<id>]                        # one ready slice's section, or the one named
+simt plan status                             # count the tracker rows
+
+# plugin
+simt plugin <claude|gemini|cursor|opencode>  # generate a harness package from the same tables the hooks use
+
+# pr-body
+simt pr-body [--base <ref>]                  # the pull request body: evidence, decisions, gate state and residual risk
+
+# review
+simt review [--local]                        # review the staged diff against the estate rules
+
+# rules
+simt rules decisions                         # every known decision, and which layer each came from
+simt rules list [--root <path>]              # the rule catalogue, marked with what applies to this repository
+simt rules show <id>                         # one rule body
+simt rules why <id|ADR-NNN> [--all]          # the decision that settled a rule, and whether it is still in force
+
+# shared
+simt shared install --yes                    # install the shared rules into a reader home directory
+simt shared plan                             # what the shared install would write, and where
+
+# skills
+simt skills brief --task "<task>"            # the packet for a task, read from the skill registry
+simt skills compile [<name>]                 # compile a skill to the Agent Skills standard
+simt skills eval [corpus]                    # score the skill registry against transcripts
+simt skills find <query>                     # skills that match a query
+simt skills index                            # rebuild the skill index
+simt skills install <name> --yes             # install skills into the workspace
+simt skills show <name>                      # one skill packet
+simt skills why <name>                       # which skill covers a task
+
+# slice
+simt slice abandon <id>                      # remove a slice worktree, delete its branch, and return the row
+simt slice finish <id> --yes                 # run the gates, commit the slice and record its evidence
+simt slice start <id> --yes  |  -- "<text>"  # give a slice its worktree, branch and brief; -- starts one from a prompt, no row
+
+# status
+simt status [--line]                         # the repository snapshot, or one line of the last check
+
+# sync
+simt sync [--explain] --yes                  # re-render the generated regions from the rule content
+
+# tests
+simt tests <path> [--cochange]               # the tests that exercise a file
+
+# tokens
+simt tokens [--repos] [--session]            # count tokens per instruction file and per skill
+
+# undo
+simt undo --yes                              # restore the last journaled set of writes, if untouched
+
+# upgrade
+simt upgrade --yes                           # replace this installation with the pinned release
+
+# why
+simt why [path]                              # what governs a file: decisions, rules, skills, gates and lessons
 ```
+<!-- simt:commands:end -->
 
 `init`, `sync`, `upgrade`, `hooks install`, `agent-hooks install`, `shared install`,
 `skills install`, `plan done`, `lessons review`, `decide`, `ignore`, `pack new`,
@@ -185,134 +283,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
 
@@ -353,7 +328,7 @@ on top of `0.6.0`:
   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
+as a pack) are closed by ruling: 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.
@@ -372,7 +347,7 @@ history. All remain off until named and propose rather than write projected text
 | `simt.lock.json` | the digest of the inputs, the digest of the projection, and locked `variants` winners from `simt bench variants`. The old `simt-dev.lock.json` is still read, and a lock migrates on its next write |
 | `.cursor/rules/*.mdc`, `.claude/rules/*.md`, `.agents/rules/*.md`, `.github/instructions/*.instructions.md` | one file per rule, and only for a harness that reads that directory |
 | `.editorconfig`, `.gitattributes` | baseline regions, placed first so a later setting still wins |
-| `.simt-hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |
+| `.simt/hooks/` and `core.hooksPath` | the shared dispatcher. It fails closed |
 | `docs/decisions/ADR-NNN-<slug>.md` | numbered decision records scaffolded by `simt decide --yes` with `simt-affects` and `simt-supersedes` frontmatter |
 | `docs/lessons/NNNN-<slug>.md` | reviewed lessons promoted by `simt lessons review <id> --yes` with `simt-trigger`, `simt-evidence`, and `simt-expires` frontmatter |
 

package/bin/simt.mjs

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

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

@@ -1,6 +1,6 @@
 # ADR-014 — The workspace is configuration, and a single repo is a first-class case
 
-Status: **accepted** · 2026-10-05
+Status: **accepted** · 2026-10-05 · ruling 1 superseded by [ADR-119](ADR-119-the-environment-variable-points-into-a-workspace-the-repo-declared.md)
 Affects: `simt-dev` CLI (workspace resolution, `compare`, `skills`, registry validation, packaging)
 
 ## Context
@@ -133,7 +133,7 @@ a feature; `rules why` is the provenance mechanism the whole one-canonical-home
 on, and it cannot depend on a git checkout being present.
 
 `docs/plans` ships with it, because every non-zero exit prints a remedy pointing at
-`docs/plans/0002-simt-dev-cli.md section 11`.
+`docs/research/0002-simt-dev-cli.md section 11`.
 
 ### 6. "Absent", "wrong" and "moved" are three different facts
 

package/docs/decisions/ADR-025-a-baseline-is-a-region-in-a-file-the-repo-owns.md

@@ -4,7 +4,7 @@ Status: accepted · 2026-10-06 · rulings 1 and 2 narrowed by ADR-026 · ruling
 **Affects:** `src/projection/baselines.mjs`, `src/projection/markers.mjs`,
 `src/projection/project.mjs`, `src/commands/init.mjs`, `test/baselines.test.mjs`,
 `test/leaks.mjs`, `test/surfaces.test.mjs`. Settles §3.1 row 5 and row 7 of
-`docs/plans/0001-centralise-agent-rules.md` for the files it names, and leaves the rest ruled
+`docs/research/0001-centralise-agent-rules.md` for the files it names, and leaves the rest ruled
 out by name rather than outstanding.
 
 Rulings 1 and 2 did not survive whole: ADR-026 rules that a config whose grammar cannot

package/docs/decisions/ADR-026-a-config-without-a-region-is-a-file-the-repo-owns.md

@@ -5,7 +5,7 @@ Status: accepted · 2026-10-06
 `src/commands/help.mjs`, `src/projection/project.mjs`, `test/ci.test.mjs`.
 **Narrows:** ADR-025 rulings 1 and 2. **Extends:** ADR-023 (bytes copied, written once),
 ADR-024 (simt-dev's own copies are refreshed by `simt-dev ci`). Settles the Dependabot
-item §3.1 row 8 of `docs/plans/0001-centralise-agent-rules.md` named as still missing.
+item §3.1 row 8 of `docs/research/0001-centralise-agent-rules.md` named as still missing.
 
 ## Context
 

package/docs/decisions/ADR-027-the-one-gitattributes-line-that-is-neither-dangerous-nor-empty.md

@@ -5,7 +5,7 @@ Status: accepted · 2026-10-06
 `test/baselines.test.mjs`, `test/surfaces.test.mjs`.
 **Supersedes:** ADR-025 ruling 9, which ruled `.gitattributes` out for now and required this
 record. Settles the `.gitattributes` item in §3.1 row 5 of
-`docs/plans/0001-centralise-agent-rules.md`.
+`docs/research/0001-centralise-agent-rules.md`.
 
 ## Context
 

package/docs/decisions/ADR-028-a-base-file-is-a-floor-so-the-disagreement-it-cannot-repair-becomes-a-check.md

@@ -5,7 +5,7 @@ Status: accepted · 2026-10-07
 `test/tsconfig.test.mjs`. **Narrows:** ADR-026 ruling 2 (ownership does not depend on
 content being mergeable) by applying it to a file whose mechanism is `extends` rather than
 a copied byte range. Settles the `tsconfig.base.json` item of §3.1 row 5 and row 7 of
-`docs/plans/0001-centralise-agent-rules.md`.
+`docs/research/0001-centralise-agent-rules.md`.
 
 ## Context
 

package/docs/decisions/ADR-029-the-pins-a-repository-declares-are-its-own.md

@@ -3,7 +3,7 @@
 Status: accepted · 2026-10-07
 **Affects:** `src/toolchain.mjs`, `src/projection/project.mjs`, `test/toolchain.test.mjs`.
 **Settles:** the `packageManager`/`engines`/`.nvmrc` items of §3.1 row 5 of
-`docs/plans/0001-centralise-agent-rules.md`. **Extends:** ADR-026 ruling 9 (absence and
+`docs/research/0001-centralise-agent-rules.md`. **Extends:** ADR-026 ruling 9 (absence and
 disagreement are reportable; content is not) to a file this tool authors no part of.
 
 ## Context

package/docs/decisions/ADR-030-what-a-plan-does-not-ship-is-a-decision-with-a-record.md

@@ -1,7 +1,7 @@
 # ADR-030 — what a plan does not ship is a decision with a record, not a silence
 
 Status: accepted · 2026-10-07
-**Affects:** `docs/plans/0001-centralise-agent-rules.md` §3.1 row 5 and row 7. Ships no
+**Affects:** `docs/research/0001-centralise-agent-rules.md` §3.1 row 5 and row 7. Ships no
 code. **Refuses:** the commitlint baseline and the shared ESLint block named in row 5 and
 row 7, and records why in the plan itself rather than leaving the rows to imply that two
 mechanisms are merely unwritten.