simt-dev 0.6.3 → 0.7.1

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.

package/docs/decisions/ADR-125-a-shared-context-belongs-to-a-read-and-a-writer-reads-directly.md

@@ -0,0 +1,65 @@
+---
+simt-affects: ["src/context.mjs", "src/commands/hooks.mjs", "test/hooks-context.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-125 — a shared context belongs to a read, and a writer reads directly
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+`repoContext` holds one pending promise per question for the length of a command. It
+was threaded through the reads — `check`, the four skills reads, `diagnose`, the rules
+catalogue — and Q67's last clause was to finish the job, which raised the question the
+row did not answer: should a command that *writes* hold a context too?
+
+The two cases are not the same. A reader asks several questions about an unchanging
+tree and pays once. A writer changes the tree between its questions: `init` writes a
+manifest and then renders against it, `upgrade` replaces files and then reports drift,
+`sync` rewrites the region and then computes the lock. A context that survived those
+writes would answer the second question with the first answer, and the command would
+report a repository it had already changed.
+
+## Ruling
+
+### 1. A read command may hold one context for its whole run
+
+A command that only reads creates one `repoContext` at its entry and passes it to
+every reader beneath it. Two questions with the same answer cost one computation, and
+the cache reports its own hits so a context that is wired but never used cannot pass
+for a fast machine.
+
+### 2. A writer reads its repository directly
+
+A writer calls the readers as it always has. It is not an optimisation left undone: a
+shared context would make a stale answer the reward for a correct write, and the
+failure would surface as a drifted manifest in a repository that had just been fixed.
+
+### 3. The hook path keeps its dynamic import
+
+`planHooksInstall` resolves the node runner from a fingerprint, and it imports the
+fingerprint module dynamically so that loading the hooks command does not load it.
+Static-importing a context into `src/commands/hooks.mjs` costs about 3 ms of module
+graph on the shim path, which Q64 measured and removed once. A caller that holds a
+context passes it and shares the walk; a caller that does not keeps the light path.
+
+## Consequences
+
+- Q67 closes with the reads threaded and the writers explained rather than converted.
+- The 3 ms module cost is paid only when a command actually uses a context; `hooks
+  run` keeps the dynamic path.
+- A future writer that wants a context has this record to argue against, instead of
+  discovering the staleness as a bug report.
+
+## Rejected
+
+- **Giving every writer a context and invalidating entries after each write.** The
+  invalidation is the whole bug surface: forget one entry and the failure is a stale
+  answer that looks like a correct one, in the command whose job is to make the tree
+  correct.
+- **A process-lifetime context.** `bench` writes manifests mid-run; a process-wide
+  memo would answer a benchmark for a repository it had just changed.
+- **Making the context required on every reader signature.** It would put the cache in
+  the contract of functions that do not need one, and a caller with no context would
+  have to invent an empty one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "An intelligence amplifier for AI coding agents: rules and dual gates adopted by one command, plus local retrieval, task briefs, benches and repo memory — deterministic by default, with local-model adapters that propose and never select.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
@@ -25,6 +25,8 @@
     "src",
     "rules",
     "templates",
+    "agents",
+    "skills",
     "docs/decisions",
     "CHANGELOG.md"
   ],
@@ -41,7 +43,15 @@
     "skills"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=4 test/*.test.mjs",
-    "lint": "node bin/simt.mjs doctor"
+    "test": "node --test --test-concurrency=$(node -p 'os.cpus().length') test/*.test.mjs",
+    "lint": "node bin/simt.mjs graph lint",
+    "verify:shipped": "node --test test/shipped.test.mjs",
+    "build:sea": "node scripts/build-sea.mjs",
+    "verify:wheel": "node scripts/verify-wheel.mjs"
+  },
+  "exports": {
+    ".": "./src/api.mjs",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
   }
 }

package/rules/core.md

@@ -24,9 +24,16 @@ commands belongs in this repository, not here.
 
 ## Git
 
+The commit and push procedure - order, message format, worktrees - is the `slice-commit`
+rule; follow it for every commit and push.
+
 - Commit locally, report the SHA. **Push only on explicit approval.** (ADR-001)
 - Before asking for push approval, state whether the push triggers a deployment, a migration
   or any remote mutation.
+- Once approved, you may push directly without the pre-push gate re-running the full suite
+  when you already ran that suite green on the current state and changed nothing since: cite
+  the already-passing run as the pass, and the gate recognizes the evidence and skips the
+  re-run rather than paying for it again. (ADR-120)
 - Never use `--no-verify`, amend, rebase, reset or rewrite history unless explicitly asked.
 - Never commit failing, partial, secret-bearing or unrelated work.
 
@@ -45,8 +52,8 @@ commands belongs in this repository, not here.
 - Name the exact commands and test files. Partial pass is a blocker; `6/8 pass` is the
   canonical example of a blocked state. Never justify a skip without a pre-existing written
   reason. (ADR-006)
-- Evidence discipline is mandatory everywhere. A **numeric** bar is declared per repo in
-  `simt-dev.json`, never assumed centrally. (ADR-006)
+- Evidence discipline is mandatory everywhere. A **numeric** bar is declared per repo in the
+  repository's manifest (`{manifest}`), never assumed centrally. (ADR-006)
 - The pre-commit hook owns format and lint for staged files; do not re-run what it just ran.
   Manual runs are correct when the hook is absent, when diagnosing a failure, or for a check
   the hook does not cover. (ADR-004)