simt-dev 0.7.0 → 0.8.0

package/docs/decisions/ADR-048-a-baseline-carries-only-keys-a-reader-honours.md

@@ -2,7 +2,7 @@
 
 Status: accepted · 2026-10-09 · amends ADR-025 (withdraws ruling 8, corrects its context)
 **Affects:** `src/projection/baselines.mjs`, `test/baselines.test.mjs`,
-`docs/plans/0001-centralise-agent-rules.md`. Closes S30 of
+`docs/research/0001-centralise-agent-rules.md`. Closes S30 of
 `docs/reviews/0002-full-review-adoption-and-public-release.md`.
 
 ## Context

package/docs/decisions/ADR-082-the-tracker-override-is-a-manifest-key.md

@@ -1,6 +1,6 @@
 # ADR-082 — The tracker override is a manifest key, and init keeps what it did not write
 
-Status: **accepted** · 2026-10-16 · supersedes ADR-081 rulings 1 and 2
+Status: **accepted** · 2026-10-16 · supersedes ADR-081 rulings 1 and 2 · ruling 1 superseded by ADR-128
 
 ## Context
 

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

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

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

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

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

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

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

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

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

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

package/docs/decisions/ADR-122-the-shims-move-into-the-state-directory-and-the-legacy-directory-removes-itself.md

@@ -0,0 +1,94 @@
+---
+simt-affects: ["src/hooks/shim.mjs", "src/commands/hooks.mjs", "src/journal.mjs", "src/agenthooks/shim.mjs", "test/hooks.test.mjs", "test/agenthooks.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-122 — the shims move into the state directory, and the legacy directory removes itself
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+The git shims live in a top-level `.simt-hooks/` directory, and `core.hooksPath` points
+git at it. Every other piece of per-repo state — the journal, the ledger, the evidence,
+the index — lives under the state directory `.simt/`, which the repository ignores as a
+single line. The top-level split has no technical reason: `core.hooksPath` accepts any
+path, and nothing about the shims requires a location of its own. It does have a cost —
+two roots for what is one body of state, and an ignore line that exists only for the
+shims.
+
+The move has one genuine collision. The journal's stated boundary is that nothing under
+the state directory is journaled: the journal recording itself is recursion, and the
+ledger, index and candidates are evidence and caches whose byte-shape must not be
+rolled back. Review 0003 Q22 ruled the opposite for the shims: `undo` restores
+`core.hooksPath` and the shims together, because a routing restored without its shims is
+a hook that no longer runs. Shims that land under the state directory unjournaled would
+recreate Q22 exactly — the undo restores the routing and the shims stay. The move is
+therefore not a rename; it is a rename plus a named exception to a recorded boundary.
+
+Repositories installed before the move carry the legacy directory. The move must be
+self-healing in those repositories, and the cleanup must obey the rule that already
+governs the hooks directory: a file this tool cannot recognise as its own is never
+deleted on its way.
+
+## Ruling
+
+### 1. The shims live in the state directory, and everything derives from one constant
+
+`HOOKS_DIR` is `.simt/hooks`. The shim file names (`fileFor`), the agent-hook shim
+(`.simt/hooks/agent-hook`), the `core.hooksPath` value a write installs, the hooks
+status, and the agent-hooks `rm` policy all derive from that one constant, so the
+location has exactly one home. The preceding location is `HOOKS_DIR_LEGACY`
+(`.simt-hooks`), named because it is read during cleanup and cited in the plan.
+
+### 2. The legacy directory removes itself on install, judged in the plan
+
+On `hooks install` (and `doctor --fix`, which shares the plan), a present legacy
+directory is scanned and judged removable in the plan: every entry in it must be a
+regular file carrying a simt-dev marker — the shim marker or the chain marker. Removable
+means the plan announces the removal and the apply removes each file journaled and then
+takes the directory down, so `undo` re-creates the files and their directory. A single
+entry the tool cannot recognise as its own — a foreign file, or anything that is not a
+regular file — leaves the directory in place, unannounced and untouched. The judgment
+lives in the plan and the deletion in the apply, so preview and apply agree by
+construction, the way every other write in this command does.
+
+### 3. The shim directory is the one named exception to the unjournaled state directory
+
+`journaledWriteFile` and `journaledRemoveFile` record writes under the state directory
+only when the path is the shim directory. The exception is named, not broadened: the
+recursion and evidence arguments for the rest of the directory are untouched, and the
+module header states the exception alongside the rule. Without it, `undo` after an
+install restores `core.hooksPath` to unset and leaves the shims behind — the Q22
+defect, relocated.
+
+## Consequences
+
+- `src/hooks/shim.mjs` exports both constants; `src/commands/hooks.mjs` gains
+  `legacyHooksScan` (the plan-side judgment) and the apply-side removal; `doctor --fix`
+  inherits both through the shared plan.
+- `src/journal.mjs` imports the shim location from `src/hooks/shim.mjs` — the
+  dependency direction is the journal learning one named path, not the location module
+  learning about the journal.
+- The repository's ignore file drops the `.simt-hooks/` line: the state directory line
+  already covers the shims.
+- A repository installed before the move self-heals on its next `hooks install --yes`:
+  the routing re-points, the new shims land, and the legacy directory is gone — journaled,
+  so an `undo` brings it back.
+- `src/toolwords.mjs` keeps `simt-hooks` as a tool word: the legacy name is still a
+  reference to the tool in remedies and history, and the estate pattern that exempts it
+  is unchanged.
+- The agent-hook shim is re-rendered at its new location by the agent-hooks installer,
+  which reads the same constant.
+
+## Rejected
+
+- **Leaving the shims at the top level.** The split buys nothing and costs an ignore
+  line, a second state root, and a location that the state-directory story does not
+  explain.
+- **Removing the legacy directory without the marker check.** A file a person put there
+  is not the tool's to delete, and the hooks directory already carries exactly this rule
+  for its own files; the cleanup is the same principle applied to the directory.
+- **Journaled everything under the state directory.** The recursion and evidence
+  arguments are load-bearing for the ledger and the index; the exception must be the one
+  directory git's routing points at, and no wider.

package/docs/decisions/ADR-123-a-surplus-positional-is-not-refused-because-arity-is-not-in-the-source.md

@@ -0,0 +1,57 @@
+---
+simt-affects: ["src/commands/index.mjs", "src/commands/spec.mjs", "test/argv-repeat.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-123 — a surplus positional is not refused, because a command's arity is not in its source
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+Review 0003 Q62 asked dispatch to validate a command's positionals the way it validates
+its flags, and the cheapest place to read the maximum looked like the module that
+receives `args`: a command that reads `args[0]` takes one, a command that reads nothing
+takes none, and a command that joins or spreads `args` has no maximum at all.
+
+Measured against the tree, that rule is wrong for five of the 76 rows. `init`, `tokens`,
+`explain`, `graph lint` and `bench report` all accept a positional that their own module
+does not index — it is forwarded to a helper in another module, or deliberately ignored.
+Enforcing the derived maximum failed 27 tests, 11 of them on `init` alone (`init` a path
+is the command's most ordinary call). The source tells you where an argument is *read*;
+it does not tell you what the command *accepts*, and for the five commands whose reading
+happens elsewhere the two answers differ.
+
+## Ruling
+
+### 1. Dispatch does not enforce a maximum number of positionals
+
+Dispatch enforces what a spec row can state truthfully: the flags a command reads, the values a closed set accepts, and that a single-valued flag is given once. It does not enforce a positional maximum, and a surplus positional is accepted exactly as it was before the rule was attempted.
+
+### 2. A command that refuses a surplus positional says so itself, in its own words
+
+
+
+### 3. The withdrawn arity is recorded here rather than carried as a spec field
+
+
+
+## Consequences
+
+- Q62's surplus-positional clause is withdrawn. The arity it would have needed (29 rows
+  with a maximum, 47 unbounded) is not shipped, and no row carries an `args` field.
+- `test/argv-repeat.test.mjs` keeps the refusal of a repeated flag and the closed set;
+  the surplus-positional test is gone with the rule that would have made it pass.
+- The source-reading heuristic is recorded here rather than kept in a comment, because
+  the next agent to read Q62 will propose it again, and it will fail the same 27 tests.
+
+## Rejected
+
+- **Reading arity from the module, as written.** A command's accepted positionals are a
+  contract, and the source is an implementation of it; `init` proves they diverge. A
+  check that refuses `init <path>` is worse than the silence it replaces.
+- **Declaring arity by hand for all 76 rows.** A number nobody derives and no caller
+  checks drifts silently, and a wrong maximum refuses a real call — the same failure,
+  arriving a release later and without a test to find it.
+- **Making every surplus positional an error.** The forwarding commands would need a
+  per-command exception list, which is the manual declaration above with extra steps.

package/docs/decisions/ADR-124-the-manifest-has-a-schema-in-the-tool-and-its-unknown-keys-stay-the-repositorys.md

@@ -0,0 +1,64 @@
+---
+simt-affects: ["src/manifest/schema.mjs", "src/resolve/fingerprint.mjs", "test/manifest-schema.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-124 — the manifest has a schema in the tool, and its unknown keys stay the repository's
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+`simt.json` is read in 29 places and 41 keys are read ad hoc across the tree. There was
+no list of the keys, so `"mode": "kernal"` was accepted by every reader and reached the
+projection as a mode nothing had heard of, and one reader (`fingerprint`) returned
+`{error}` as the manifest, so a file that did not parse looked like a declaration of a
+key called `error`.
+
+Writing that list is where this repository's characteristic mistake is easiest to make:
+the first draft was written from memory and called `limits.fileLines` a positive integer
+and `surfaces` an object. In the only manifest the tool has to hand, the first is an
+object of two tiers and the second is a list.
+
+## Ruling
+
+### 1. One table declares the manifest keys, their owner and their check
+
+One table in `src/manifest/schema.mjs` declares every key with its owner (`tool` or
+`repo`), the version it arrived in, and a check that returns a sentence naming what is
+wrong. One loader, `loadManifest(root)`, returns the manifest, whether a file exists,
+the version, and the problems. The table is held to this repository's own `simt.json` by
+a test, because a schema written from memory fails that test in the same run that proves
+the loader works.
+
+### 2. An unparseable file is no manifest, and an absent version field is version 1
+
+A caller that receives a half-read object cannot tell it from a declaration, so a file
+that does not parse yields no manifest and one problem naming the parse error. `version`
+arrived after every manifest now on disk, so absent means 1 rather than a problem.
+
+### 3. An unknown key is not a problem, because the file invites the repository's own
+
+The manifest comment tells a repository that a value it adds survives a re-init. A
+validator that refused an unknown key would make the tool the owner of a file it calls
+the repository's, so only a known key with an impossible value is reported.
+
+## Consequences
+
+- `fingerprint` reads through the loader, so a broken manifest no longer arrives as an
+  object with an `error` key; a dependent read sees no declaration.
+- The 29 direct `JSON.parse` call sites remain. Migrating them is the rest of Q69 and
+  changes no behaviour this table already answers for a single call.
+- `GENERATED_KEYS` is not yet derived from the table; the table distinguishes `tool`
+  from `repo` keys, so the derivation is possible and is not taken here.
+
+## Rejected
+
+- **A JSON Schema file and a validator dependency.** `package.json` declares an empty
+  dependency set (ADR-012), and a schema in a second language would be a second place
+  the keys are stated.
+- **Refusing unknown keys.** The file comment invites a repository to keep its own
+  keys, and refusing them breaks every repository that already does.
+- **Throwing on a bad value.** A manifest is read on the path of every command; a throw
+  turns a typo into a crash with no remedy, where a named problem can be printed beside
+  the answer.