simt-dev 0.7.0 → 0.8.0

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/docs/decisions/ADR-126-the-mcp-surface-stays-a-reader-so-there-is-no-write-path-to-build.md

@@ -0,0 +1,68 @@
+---
+simt-affects: ["src/mcp/server.mjs", "src/mcp/tools.mjs", "docs/reviews/0003-pre-plan-0004-review.md"]
+simt-supersedes: []
+---
+
+# ADR-126 — the MCP surface stays a reader, so there is no write path to build
+
+Status: **accepted** · 2026-11-01
+
+## Context
+
+Review 0003's Q66 lists "the two-step write path" among the clauses still open for the
+MCP surface. The clause reads as work to do; the file says otherwise. `src/mcp/server.mjs`
+opens with three decisions, the third of which is that no mutating tool is exposed —
+`init`, `sync`, `hooks install`, `skills install` and `upgrade` are absent on purpose,
+because an editor that can call a tool can call it without a human reading a diff first.
+
+Those two statements have stood in the same repository for months without meeting. The
+question the row asks and the rule the file states are the same question, and the answer
+was written down where the row's reader would not look.
+
+The argument for exposure is real and worth stating: a client that can read a repository
+can also want to fix it, and a plan-then-apply pair would let it see what would change
+before changing anything. What it would not do is make the change reviewed. `--yes` on
+the command line is a human decision with a preview in front of it; the same flag arriving
+inside a tool call is a model deciding to pass it.
+
+## Ruling
+
+### 1. No tool on this surface writes
+
+Every tool returns a value and changes nothing. The capability block advertises no write
+capability, and this is not a gap to be filled later: a tool that writes is a different
+surface with a different review obligation, and it is not this one.
+
+### 2. A caller that wants to write runs the command
+
+The commands already do plan-then-apply properly: they print a preview, refuse without
+`--yes`, journal what they write, and `undo` restores it. A client that wants that power
+runs `simt <command>` as a subprocess, where the human who opened the editor sees the
+preview and passes the flag — or does not.
+
+### 3. Exposing a writer needs a superseding record, not a patch
+
+If a future surface must write, it arrives with its own decision: what the plan token
+proves, who approves the apply, how a half-applied run is undone, and what the journal
+says. Approving a diff in an editor is a claim the server cannot verify, and a
+confirmation prompt is a user interface the server does not own.
+
+## Consequences
+
+- Q66's write-path clause closes as withdrawn, not deferred. The row names this record so
+  the next reader does not reopen it as unfinished work.
+- The read-only guarantee in the server's header, the capability block and the tests now
+  have one record behind them instead of three comments.
+- A tool that returns `{ written: false }` for every input is not a compromise: it is the
+  shape that makes a client believe a write happened.
+
+## Rejected
+
+- **A plan/apply pair behind a confirmation prompt.** The prompt is rendered by the client,
+  which may not render one, and the server cannot tell an approved apply from an unapproved
+  one. A safety property that depends on another program's UI is not a property.
+- **A write tool gated on `--yes` passed through the arguments.** The flag would be asserted
+  by the same model that decided to write; the preview would be read by nobody.
+- **Exposing `sync` alone because it is idempotent.** It rewrites the generated region of
+  every repository in a workspace. Idempotence says a second run changes nothing, not that
+  the first run was reviewed.

package/docs/decisions/ADR-127-the-mcp-tool-list-is-written-by-hand-and-roots-is-not-asked-for.md

@@ -0,0 +1,65 @@
+---
+simt-affects: ["src/mcp/tools.mjs", "src/commands/spec.mjs", "test/mcp-spec.test.mjs", "docs/reviews/0003-pre-plan-0004-review.md"]
+simt-supersedes: []
+---
+
+# ADR-127 — the MCP tool list is written by hand and held to the spec, and roots is not asked for
+
+Status: **accepted** · 2026-11-01
+
+## Context
+
+Two clauses of review 0003's Q66 read as work still to do: "`tools/list` generated from
+spec rows with `mcp` set", and "`roots`". Both were written before the spec rows existed,
+when the four lists this review found disagreeing were the live problem and generation
+looked like the answer to all of them.
+
+The spec rows now exist, and they carry `path`, `summary`, `flags` and, for the commands
+the surface exposes, `mcp: {name, flags}`. That is enough to say *which* flags a tool
+exposes and not enough to say what they are: no types, no per-argument descriptions, and
+no vocabulary shared with the transport. `check` declares no `mcp` flags and its tool
+takes `root`; `compare` declares none and its tool takes `root`, `limit`, `cursor` and
+`concurrency`. An `inputSchema` derived from the rows would describe `--dry-run` as a
+property and omit `root`, which is a contract a client cannot call.
+
+`roots` is the other direction. It is a client capability: the server sends `roots/list`
+and the client answers with the directories it may touch. `src/mcp/server.mjs` answers
+requests and never sends them — the only thing it writes unprompted is a notification for
+a progress token the client supplied. A server that asks a question needs a correlation
+table for replies, a timeout for a client that never answers, and a fallback for the
+clients that do not implement the capability; and every tool here already takes its root
+as an argument (`root`, `workspace`, or `--paths`), which is the same information stated
+once, by the caller, where it can be read in the call rather than inferred from a
+handshake.
+
+## Ruling
+
+### 1. The tool list stays written by hand, and tests hold it to the spec
+
+The spec row is the source of the *command*: its path, its summary and its flags. It is
+not the source of the transport's schema, which carries descriptions, types and defaults
+the row does not have, and arguments the command line does not spell as flags.
+
+What generation was meant to prevent — a tool with no command, a command nobody can reach
+over the transport, an advertised flag the tool refuses — is enforced in
+`test/mcp-spec.test.mjs`, in all three directions, plus `MCP_ONLY` for the one tool that is
+deliberately not a command (`federation_query`, which names its reason). A hand-written
+list under a test that fails on every kind of drift is the same guarantee as a generated
+one, without a schema nobody would trust enough to keep descriptions in.
+
+### 2. `roots` is withdrawn, not deferred
+
+No tool is changed to accept an implicit root, and the server gains no request path. A
+client that wants a tool to run against a directory passes it as the argument the schema
+already names. If a future capability genuinely needs an answer from the client, that is
+a different surface with its own correlation and timeout design, and it needs its own
+record.
+
+## Consequences
+
+- Reading `mcp: {name, flags}` tells a reader which flags reach the transport; reading
+  `src/mcp/tools.mjs` tells them what a caller sees. Both are checked against each other.
+- Adding a second MCP-only tool means a `MCP_ONLY` entry with a reason, which is a place a
+  reviewer looks, rather than a hole in the table.
+- The 2 KB `tools/list` budget keeps being spent on descriptions a reader can act on,
+  because nothing regenerates them from a summary phrase.

package/docs/decisions/ADR-128-a-research-plan-is-a-plan-and-the-tracker-reads-it.md

@@ -0,0 +1,42 @@
+---
+simt-affects: ["templates/plan/tracker.json", "src/plan/index.mjs", "src/projection/manifest.mjs", "test/rules.test.mjs", "test/plan.test.mjs"]
+simt-supersedes: ["ADR-082"]
+---
+
+# ADR-128 — A research plan is a plan, and the tracker reads it
+
+Status: **accepted** · 2026-11-01 · supersedes ADR-082 ruling 1
+
+## Context
+
+The four founding plans left `docs/plans` for `docs/research`: completed work of a
+different kind — research — but plans nonetheless, with tracker tables, slice ids and wave
+dependencies. The tracker reads only the directories its template lists, so the move
+de-indexed all four at once. A wave dependency that resolved through them broke with it:
+`R01` in the research plan 0003 depends on `review 0002 Wave 0`, and the slices it names
+live in the de-indexed documents.
+
+The directory set was never code. ADR-081 and ADR-082 settled the mechanism — a template
+lists any number of directories, each with a `kind`, a `word` and a `path`, and the parser,
+the help text and `plan status` all read it — and ADR-082 ruling 1 fixed the *delivered*
+set at two. Fixing the delivered set is a ruling, and this is the new one.
+
+## Ruling
+
+1. **The delivered template lists `docs/research` as a third directory, kind `research`,
+   word `research`.** A repository that sets nothing gets all three; a repository that
+   overrides `plans` replaces the `directories` section wholesale, exactly as before, so no
+   existing override is disturbed.
+2. **The directory is data, not a special case.** Nothing in `src/` names `research`; the
+   parser, help and status keep reading the template. A fourth directory arrives the same
+   way: one entry in the file, one record here.
+
+## Consequences
+
+- `simt plan status` names three directories, and the research plans are indexed again:
+  their slices count, and a dependency may name one as `research 0003 R01`.
+- Template order is index order. `research` sits between `plans` and `reviews`, which keeps
+  the moved documents ahead of the reviews they depend on — the same relative order they
+  had while they were in `docs/plans`.
+- The tests that walk the tracker's documents (`test/rules.test.mjs`) read the template's
+  directories instead of a hardcoded pair, so a future entry reaches them without an edit.

package/ecosystems/bun.json

@@ -0,0 +1,6 @@
+{
+  "id": "bun",
+  "dependabot": [
+    { "order": 20, "fact": "has-bun-lock", "value": "bun", "manifest": "bun.lock" }
+  ]
+}

package/ecosystems/cargo.json

@@ -0,0 +1,25 @@
+{
+  "id": "cargo",
+  "facts": ["has-cargo-toml"],
+  "tool": "cargo",
+  "manifestOrder": 1,
+  "gates": {
+    "preCommit": ["format", "lint"],
+    "prePush": ["test"],
+    "commands": {
+      "format": "cargo fmt --check",
+      "lint": "cargo clippy -- -D warnings",
+      "test": "cargo test"
+    }
+  },
+  "card": {
+    "build": { "order": 1, "condition": { "fact": "has-cargo-toml" }, "command": "cargo build" },
+    "focused": [
+      { "order": 5, "kind": "Rust", "condition": { "fact": "has-cargo-toml" }, "template": "cargo test {name}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 6, "fact": "has-cargo-toml", "value": "cargo", "manifest": "Cargo.toml" }
+  ],
+  "languages": [{ "lang": "rust", "exts": [".rs"] }]
+}

package/ecosystems/composer.json

@@ -0,0 +1,6 @@
+{
+  "id": "composer",
+  "dependabot": [
+    { "order": 8, "fact": "has-composer", "value": "composer", "manifest": "composer.json" }
+  ]
+}

package/ecosystems/dart.json

@@ -0,0 +1,24 @@
+{
+  "id": "dart",
+  "facts": ["has-pubspec"],
+  "tool": "dart",
+  "manifestOrder": 7,
+  "gates": {
+    "preCommit": ["format", "lint"],
+    "prePush": ["test"],
+    "commands": {
+      "format": "dart format --output=none --set-exit-if-changed .",
+      "lint": "dart analyze",
+      "test": "dart test"
+    }
+  },
+  "card": {
+    "focused": [
+      { "order": 12, "kind": "Dart", "condition": { "fact": "has-pubspec" }, "template": "dart test {file}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 16, "fact": "has-pubspec", "value": "pub", "manifest": "pubspec.yaml" }
+  ],
+  "languages": [{ "lang": "dart", "exts": [".dart"] }]
+}

package/ecosystems/deno.json

@@ -0,0 +1,21 @@
+{
+  "id": "deno",
+  "facts": ["has-deno-config"],
+  "tool": "deno",
+  "manifestOrder": 5,
+  "gates": {
+    "preCommit": ["format", "lint"],
+    "prePush": ["test", "typecheck"],
+    "commands": {
+      "format": "deno fmt --check",
+      "lint": "deno lint",
+      "test": "deno test",
+      "typecheck": "deno check ."
+    }
+  },
+  "card": {
+    "focused": [
+      { "order": 10, "kind": "Deno", "condition": { "fact": "has-deno-config" }, "template": "deno test {file}" }
+    ]
+  }
+}

package/ecosystems/devcontainers.json

@@ -0,0 +1,6 @@
+{
+  "id": "devcontainers",
+  "dependabot": [
+    { "order": 21, "fact": "has-devcontainer", "value": "devcontainers", "manifest": "devcontainer.json" }
+  ]
+}

package/ecosystems/docker-compose.json

@@ -0,0 +1,6 @@
+{
+  "id": "docker-compose",
+  "dependabot": [
+    { "order": 11, "fact": "has-compose", "value": "docker-compose", "manifest": "compose file" }
+  ]
+}

package/ecosystems/docker.json

@@ -0,0 +1,6 @@
+{
+  "id": "docker",
+  "dependabot": [
+    { "order": 10, "fact": "has-dockerfile", "value": "docker", "manifest": "Dockerfile" }
+  ]
+}

package/ecosystems/dotnet.json

@@ -0,0 +1,25 @@
+{
+  "id": "dotnet",
+  "facts": ["has-nuget"],
+  "tool": "dotnet",
+  "manifestOrder": 3,
+  "gates": {
+    "preCommit": ["format"],
+    "prePush": ["test", "typecheck"],
+    "commands": {
+      "format": "dotnet format --verify-no-changes",
+      "test": "dotnet test",
+      "typecheck": "dotnet build -warnaserror"
+    }
+  },
+  "card": {
+    "build": { "order": 3, "condition": { "fact": "has-nuget" }, "command": "dotnet build" },
+    "focused": [
+      { "order": 8, "kind": ".NET", "condition": { "fact": "has-nuget" }, "template": "dotnet test --filter {test}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 15, "fact": "has-nuget", "value": "nuget", "manifest": "*.csproj" }
+  ],
+  "languages": [{ "lang": "csharp", "exts": [".cs"] }]
+}

package/ecosystems/elixir.json

@@ -0,0 +1,23 @@
+{
+  "id": "elixir",
+  "facts": ["has-mix"],
+  "tool": "mix",
+  "manifestOrder": 8,
+  "gates": {
+    "preCommit": ["format"],
+    "prePush": ["test"],
+    "commands": {
+      "format": "mix format --check-formatted",
+      "test": "mix test"
+    }
+  },
+  "card": {
+    "build": { "order": 5, "condition": { "fact": "has-mix" }, "command": "mix compile" },
+    "focused": [
+      { "order": 13, "kind": "Elixir", "condition": { "fact": "has-mix" }, "template": "mix test {file}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 18, "fact": "has-mix", "value": "mix", "manifest": "mix.exs" }
+  ]
+}

package/ecosystems/gitsubmodule.json

@@ -0,0 +1,6 @@
+{
+  "id": "gitsubmodule",
+  "dependabot": [
+    { "order": 14, "fact": "has-submodules", "value": "gitsubmodule", "manifest": ".gitmodules" }
+  ]
+}

package/ecosystems/go.json

@@ -0,0 +1,25 @@
+{
+  "id": "go",
+  "facts": ["has-go-mod"],
+  "tool": "go",
+  "manifestOrder": 2,
+  "gates": {
+    "preCommit": ["format", "lint"],
+    "prePush": ["test"],
+    "commands": {
+      "format": "test -z \"$(gofmt -l .)\"",
+      "lint": "go vet ./...",
+      "test": "go test ./..."
+    }
+  },
+  "card": {
+    "build": { "order": 2, "condition": { "fact": "has-go-mod" }, "command": "go build ./..." },
+    "focused": [
+      { "order": 4, "kind": "Go package", "condition": { "fact": "has-go-mod" }, "template": "go test ./{pkg} -run {Test}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 5, "fact": "has-go-mod", "value": "gomod", "manifest": "go.mod" }
+  ],
+  "languages": [{ "lang": "go", "exts": [".go"] }]
+}

package/ecosystems/gradle.json

@@ -0,0 +1,13 @@
+{
+  "id": "gradle",
+  "card": {
+    "build": { "order": 6, "condition": { "stack": "gradle" }, "command": "./gradlew build" },
+    "focused": [
+      { "order": 1, "kind": "Android", "condition": { "fact": "has-android-manifest" }, "template": "./gradlew :{module}:testDebugUnitTest --tests {class}" },
+      { "order": 2, "kind": "JVM", "condition": { "stack": "gradle" }, "template": "./gradlew test --tests {class}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 13, "stack": "gradle", "value": "gradle", "manifest": "build.gradle" }
+  ]
+}

package/ecosystems/maven.json

@@ -0,0 +1,23 @@
+{
+  "id": "maven",
+  "facts": ["has-maven-pom"],
+  "tool": "mvnw",
+  "file": true,
+  "manifestOrder": 9,
+  "gates": {
+    "prePush": ["test"],
+    "commands": { "test": "./mvnw -q verify" }
+  },
+  "card": {
+    "focused": [
+      { "order": 3, "kind": "Maven", "condition": { "fact": "has-maven-pom" }, "template": "./mvnw test -Dtest={class}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 9, "fact": "has-maven-pom", "value": "maven", "manifest": "pom.xml" }
+  ],
+  "languages": [
+    { "lang": "java", "exts": [".java"], "testConventions": { "base": ["Tests?\\.(?:java|kt)$"] } },
+    { "lang": "kotlin", "exts": [".kt", ".kts"], "testConventions": { "base": ["Tests?\\.(?:java|kt)$"] } }
+  ]
+}

package/ecosystems/node.json

@@ -0,0 +1,25 @@
+{
+  "id": "node",
+  "card": {
+    "focused": [
+      {
+        "order": 14,
+        "kind": "Node",
+        "condition": { "stack": "node" },
+        "template": {
+          "static": "node --test {file}",
+          "ifScriptMatches": "vitest|jest",
+          "dynamic": "{runner} test -- {file}"
+        }
+      }
+    ]
+  },
+  "dependabot": [
+    { "order": 1, "stack": "node", "value": "npm", "manifest": "package.json" },
+    { "order": 2, "stack": "typescript", "value": "npm", "manifest": "package.json" }
+  ],
+  "languages": [
+    { "lang": "javascript", "exts": [".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx"], "canonical": [".js", ".mjs", ".cjs", ".jsx"] },
+    { "lang": "typescript", "exts": [".ts", ".tsx", ".js", ".mjs", ".jsx"], "canonical": [".ts", ".tsx"] }
+  ]
+}

package/ecosystems/python.json

@@ -0,0 +1,20 @@
+{
+  "id": "python",
+  "card": {
+    "focused": [
+      { "order": 6, "kind": "Python", "condition": { "fact": "has-uv-lock" }, "template": "uv run -m pytest {file}::{test}" },
+      { "order": 7, "kind": "Python", "condition": { "facts": ["has-pyproject", "has-requirements"] }, "template": "pytest {file}::{test}" }
+    ],
+    "fallback": [
+      { "order": 1, "condition": { "fact": "has-uv-lock" }, "commands": { "test": "uv run -m pytest" } },
+      { "order": 2, "condition": { "facts": ["has-pyproject", "has-requirements"] }, "commands": { "test": "pytest" } }
+    ]
+  },
+  "dependabot": [
+    { "order": 3, "fact": "has-pyproject", "value": "pip", "manifest": "pyproject.toml" },
+    { "order": 4, "fact": "has-requirements", "value": "pip", "manifest": "requirements.txt" }
+  ],
+  "languages": [
+    { "lang": "python", "exts": [".py"], "testConventions": { "base": ["^test_[^/]+\\.py$"] } }
+  ]
+}

package/ecosystems/ruby.json

@@ -0,0 +1,23 @@
+{
+  "id": "ruby",
+  "facts": ["has-gemfile"],
+  "tool": "bundle",
+  "manifestOrder": 6,
+  "gates": {
+    "preCommit": ["format"],
+    "prePush": ["test"],
+    "commands": {
+      "format": "bundle exec rubocop",
+      "test": "bundle exec rspec"
+    }
+  },
+  "card": {
+    "focused": [
+      { "order": 11, "kind": "Ruby", "condition": { "fact": "has-gemfile" }, "template": "bundle exec rspec {file}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 7, "fact": "has-gemfile", "value": "bundler", "manifest": "Gemfile" }
+  ],
+  "languages": [{ "lang": "ruby", "exts": [".rb"] }]
+}

package/ecosystems/swift.json

@@ -0,0 +1,25 @@
+{
+  "id": "swift",
+  "facts": ["has-swift-package"],
+  "tool": "swift",
+  "manifestOrder": 4,
+  "gates": {
+    "preCommit": ["format"],
+    "prePush": ["test", "typecheck"],
+    "commands": {
+      "format": "swift format lint -r .",
+      "test": "swift test",
+      "typecheck": "swift build"
+    }
+  },
+  "card": {
+    "build": { "order": 4, "condition": { "fact": "has-swift-package" }, "command": "swift build" },
+    "focused": [
+      { "order": 9, "kind": "Swift", "condition": { "fact": "has-swift-package" }, "template": "swift test --filter {test}" }
+    ]
+  },
+  "dependabot": [
+    { "order": 17, "fact": "has-swift-package", "value": "swift", "manifest": "Package.swift" }
+  ],
+  "languages": [{ "lang": "swift", "exts": [".swift"] }]
+}

package/ecosystems/terraform.json

@@ -0,0 +1,6 @@
+{
+  "id": "terraform",
+  "dependabot": [
+    { "order": 12, "fact": "has-terraform", "value": "terraform", "manifest": "*.tf" }
+  ]
+}

package/ecosystems/uv.json

@@ -0,0 +1,6 @@
+{
+  "id": "uv",
+  "dependabot": [
+    { "order": 19, "fact": "has-uv-lock", "value": "uv", "manifest": "uv.lock" }
+  ]
+}