simt-dev 0.2.0 → 0.2.1

package/docs/decisions/ADR-062-a-fresh-adoption-seeds-the-gates-it-can-run.md

@@ -0,0 +1,94 @@
+# ADR-062 — A fresh adoption seeds the canonical gates it can run, and never more
+
+Status: **accepted** · 2026-10-13 · filed as S40
+**Affects:** `simt init`, `src/projection/manifest.mjs` (the `ECOSYSTEMS` table, `defaultGates`),
+`src/hooks/capability.mjs` (the tool probe, the `tools` field), `src/commands/init.mjs`,
+eight new files in `rules/stacks/`
+
+## Context
+
+S40's finding: the eight common ecosystems outside the JavaScript world — Rust, Go, .NET,
+Swift, Deno, Ruby, Dart and Elixir — emit no stack tag. The fingerprint recognises them as
+`has-*` facts, and the only reader of those facts was the Dependabot configuration. So a
+fresh Rust repository received the core essay and a manifest that runs nothing: no profile
+was selected because there was none to select, and no gate was proposed because no row keyed
+on a fact. The asymmetry is the defect — the ecosystems the tool recognises were the ones it
+served least, while the ecosystems that do emit stack tags got the full treatment.
+
+Two existing mechanisms make the fix data-only, per ADR-013:
+
+- **Profiles select on tags or facts.** `simt-applies` already accepts a fact, and the
+  genericity tests already assert that a profile may select on a fact no stack tag names.
+- **Gates are planned by signal.** `planGates` takes the union of stack tags and facts, so a
+  row can key on either; the two never cross-match, because facts are `has-*` and tags are
+  not.
+
+What was missing is one artefact per ecosystem: the profile file — and for gates, a row that
+says what a fresh adoption of one should declare. The second is the harder half, because
+declaring a gate is not free:
+
+A declared gate that cannot run is worse than an absent one. Absent, an author sees nothing
+and knows nothing is being checked; declared-and-unrunnable, the dispatcher fails closed on
+every commit, and the only exit an author can find is `--no-verify`, which teaches the whole
+team that the gate is theatre. So the question a seeding design has to answer is not "which
+ecosystem is here" — the marker file answers that — but "can this machine run what the gate
+says it runs". That is ADR-017's probe-before-declare, and it shapes every ruling below.
+
+## Rulings
+
+1. **Every ecosystem the fingerprint names gets a profile.** Eight new stack profiles, each
+   `simt-applies:` on its own fact (the files are named in the Affects line), so one marker
+   file reaches both the region the repository reads and the gates its commits run. Maven's profile (`jvm`) predates
+   this ruling and applies on the same fact, so the table has nine rows and eight new files.
+   An ecosystem arriving later is a profile file and a row: no engine change (ADR-013).
+2. **A fresh adoption seeds the canonical commands, and only where the probe found the
+   tool.** On `init`, when the fingerprint emits an ecosystem fact, the row's commands land in
+   `gates.commands` for each gate it proposes — but only when the probe found `tool`. The
+   probe is the same discipline ADR-017 applies to node tools: a binary on PATH, or a file in
+   the repository when the row says `file` (the Maven wrapper, probed the way `gradlew`
+   already is). A marker says the ecosystem is here; the probe says its program can run. Both
+   must be true for a seed to land. `readCapability` reports the results in a `tools` field
+   next to `binaries`, so the plan can say which seeds fired and which did not.
+3. **A seed is a default, and a default loses to every form of declaration.** A command the
+   repository already declared in `gates.commands` is never re-seeded. An npm runner keeps its
+   own scripts untouched: `package.json` is the repository's own answer to "how do I test and
+   format", and a seed that outranked a script would replace a choice with a default —
+   precisely in the mixed repository (a `package.json` and a `Cargo.toml`) where the script is
+   the deliberate answer. The escape hatch for a repository whose runner differs from the
+   canonical one (a Rails app, a Flutter module) is to declare its own command, and
+   declaration beats seed everywhere.
+4. **Where the probe fails, the gate is dropped with a why and a remedy, never declared.**
+   This is the invariant `planGates` already holds for every proposed gate; seeding inherits
+   it rather than creating an exception to it. A fresh Rust checkout on a machine without
+   cargo gets `dropped gate test: …` with a remedy that names the install, not a gate that
+   blocks its first commit.
+
+## Consequences
+
+- `simt init` on a fresh Rust, Go, .NET, Swift, Deno, Ruby, Dart or Elixir repository declares
+  runnable gates when the toolchain is present — a `seeded` line in the plan output names each
+  command that landed — and drops them with a remedy when it is not.
+- `readCapability` gains the probe and the `tools` field: a PATH lookup, plus an executable
+  check in the repository root for a `file` row.
+- `defaultGates`'s expansion of an ecosystem row tolerates a missing phase key: the Maven row
+  proposes only pre-push, and absence is "none", not a defect.
+- The seed picks one canonical command per gate (`bundle exec rspec`, `dart test`). A
+  repository whose runner differs declares its own; ruling 3 makes that declaration win.
+- Acceptance: one test per ecosystem asserting marker → fact → profile selection; a seeding
+  matrix (every row seeds when the tool can run, every row drops when it cannot, an npm
+  repository takes no seed, a declaration beats a seed); and two end-to-end Rust inits, with
+  and without `cargo` on PATH.
+
+## Rejected
+
+- **Seed on the marker's word alone.** The marker is a file in the repository; the tool is a
+  program on the machine. A repository can have one without the other — a freshly cloned Rust
+  checkout on a machine that has never installed the toolchain is the common case — and
+  seeding there would declare a gate that fails closed on every commit. ADR-017 exists for
+  exactly this.
+- **Seed into an npm repository's scripts.** The scripts are the repository's own answer, and
+  a seed that outranks them replaces a choice with a default. The mixed repository is where
+  this matters most, because there the script and the marker coexist on purpose.
+- **A second gate table or a new engine path for ecosystems.** The fact was already flowing
+  into `planGates`, and the union of tags and facts never cross-matches. What was missing was
+  a row and a file, which is data; the engine that reads it already existed.

package/docs/decisions/ADR-063-the-adoption-escape-hatch-is-opt-in.md

@@ -0,0 +1,69 @@
+# ADR-063 — The adoption escape hatch is opt-in, and the default writes in place
+
+Status: **accepted** · 2026-10-13 · filed after a consumer asked why every adoption branched
+**Affects:** `simt init`, `src/commands/init.mjs` (`establishEscapeHatch` and its call site),
+`src/argv.mjs`, `src/commands/help.mjs`; amends plan 0002 §8.2 item 3
+
+## Context
+
+Plan 0002 §8.2 item 3 ruled: "Create a branch and a `backup-before-simt-dev` tag before the
+first write, always." The tool complied — `simt init --yes` in a git repository tagged the
+pre-adoption commit, checked out a branch named after the tool, and wrote every adoption file
+onto it. The reviewable-diff argument is sound: adoption writes a dozen files into a
+repository the tool does not own, and doing it on a dedicated branch leaves the mainline
+untouched with two named undo paths.
+
+The "always" was the part that failed. Consumers kept reporting the branch switch as a
+surprise: they ran the documented command to adopt their repository, and found themselves on
+a branch they had not chosen, with a tag they had not asked for. Review 0001's S15 fixed the
+silence — the output now names both operations and the command that undoes each — but a
+well-announced surprise is still a surprise. The branch and the tag are an undo path for
+readers who want one; making them unconditional turned a safety feature into a default that
+every consumer has to explain away.
+
+## Rulings
+
+1. **The default adoption writes in place and creates no git object.** `simt init --yes`
+   without the new flag leaves the reader on the branch they were on, tags nothing, and
+   writes the adoption files as uncommitted changes. The reviewable diff survives: `git diff`
+   shows the whole adoption, and discarding it is `git checkout -- .` plus a clean. The run
+   says so in an `in place` line that names the flag which restores the undo path.
+2. **The escape hatch moves behind a flag named for what it gives.** `--backup` is the
+   opt-in: tag the pre-adoption commit as the backup tag and branch onto the adopt branch
+   before the first write, exactly as the tool did before. The name is the promise — a way
+   back to what the repository was — and it already appears in the output the tool prints, so
+   the flag and its effect share one word.
+3. **Whatever a run does to git state is reported, including doing nothing.** Plan 0002's
+   heading over the adoption rules is "Nothing is silent". With the hatch opt-in, the
+   in-place run is a git-state event too — the deliberate absence of one — and it gets a line
+   that says what was not done and how to get it done. The `--backup` run keeps the two lines
+   S15 established: what was tagged, and where the branch came from.
+
+## Consequences
+
+- `simt init --yes` on a git repository no longer moves the reader or writes a tag; consumers
+  who scripted against the old default add `--backup`. This is the one behaviour the change
+  invalidates, and it is named here rather than discovered in a broken pipeline.
+- The `in place` line appears on every real adoption that does not pass the flag, and the
+  help text for `init` and for the flag say what it means.
+- The dry-run path is untouched: it already created no git object, and it still says `apply
+  with: simt init --yes`.
+- Acceptance: the S15 test now runs with the flag and asserts both operations are reported;
+  a new test runs without it and asserts no tag, no branch, the reader stays put, and the
+  in-place line names the flag; the not-a-git-work-tree test runs with the flag, because that
+  is where the best-effort note lives now.
+
+## Rejected
+
+- **Keep "always" and add a flag to opt out.** An opt-out flag fixes the surprise for those
+  who read the help, and it still surprises everyone else — which is every consumer of a tool
+  whose default action is to touch someone's repository. The cost of the wrong default is
+  paid on every adoption; the cost of the right default is one flag on the few that want it.
+- **Two flags, one per operation.** The tag and the branch arrive together in the code and in
+  the undo story: the tag is the reset target, the branch is where the adoption sits while it
+  is reviewed. Splitting them lets a reader build a state the tool has never tested — a branch
+  without a tag to reset to, or a tag with nothing isolated under it.
+- **Move the decision into the dry-run preview.** The dry run shows what would change in the
+  files; git state is not a file, and a preview line for an operation that now does not happen
+  by default would describe the opt-in as if it were the plan. The `in place` line after
+  `--yes` is where the reader learns what the real run did not do.

package/docs/decisions/README.md

@@ -66,6 +66,8 @@ record's status line — never by editing the ruling in place.
 | [056](ADR-056-three-names-one-of-which-is-cheap-to-move.md) | The command, the package and the project are three names, and only one of them is cheap to move | accepted · amends ADR-023 |
 | [057](ADR-057-an-identity-is-per-developer-and-a-repository-does-not-own-it.md) | An identity is per-developer, and a repository does not own it | accepted |
 | [058](ADR-058-one-tool-three-channels-and-the-order-is-forced.md) | One tool, three channels, and the order is forced | accepted |
+| [059](ADR-059-the-version-a-repository-runs-is-the-one-it-pinned.md) | The version a repository runs is the one it pinned, and the gate refuses otherwise | accepted |
+| [060](ADR-060-a-repository-with-nothing-to-run-is-adopted-and-says-so.md) | A repository with nothing to run is adopted and says so; a gate is verified where it runs | accepted |
 
 ADR-001 to ADR-010 resolve the contradictions found across the 16 repos in the 2026-10-05
 audit; each record names the repos whose text it replaces. ADR-011 and ADR-012 are the
@@ -402,6 +404,21 @@ docstring that used to claim the whole output "never contains a path" is withdra
 asserted a property the function never had, which is the same defect as a citation that
 cannot be resolved — a sentence that reads like evidence and carries none.
 
+ADR-059 is the first record here whose subject is the version of the tool itself, and it
+exists because a check that runs from the wrong binary is a pass that never happened. ADR-010
+allowed a tool that is not a project dependency to be invoked directly, *provided its version
+is pinned* — and for a repository without npm that "pinned" half had no mechanism. The version
+on `PATH` was whatever the last global install left there, and the gate that ran on commit was
+the one in it: a green tick from a check running a different gate than CI is worse than a red
+build, because it is the failure that looks like evidence. The record rules that the version a
+repository adopted is recorded in the manifest, that the gate refuses when the running binary
+differs, and that the install and the remedy are per kind — so the check CI runs is the one the
+machine remedy names. Its most load-bearing consequence is the one that keeps it from becoming a
+trap: a repository adopted before the field existed has nothing to compare against, so it is
+skipped rather than failed, and reported as drift instead — because a gate that turns red on the
+day a check ships, for a mismatch nobody can resolve until they re-adopt, is a gate no one will
+trust again.
+
 ## The rule these records enforce
 
 Every shared rule has exactly **one** canonical home. Every other location is either a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
@@ -19,7 +19,6 @@
   "files": [
     "bin",
     "src",
-    "graph",
     "rules",
     "docs/decisions",
     "CHANGELOG.md"

package/rules/stacks/dart.md

@@ -0,0 +1,38 @@
+---
+simt-id: dart
+simt-title: Dart
+simt-applies: [has-pubspec]
+---
+
+# Stack profile: Dart
+
+Applies to: `has-pubspec` — a `pubspec.yaml`. A Flutter project is a Dart project
+with the `flutter` SDK dependency; the Flutter-specific rules live with the tools
+that build it, not here.
+
+## Build and gates
+
+- `dart analyze`, `dart test` are the entrypoints; `dart format --output=none
+  --set-exit-if-changed .` is the formatting gate. A Flutter project runs the same
+  commands through `flutter`, and the two must not be mixed in one change.
+- Dependencies are declared in `pubspec.yaml`; `pub get` resolves them into
+  `pubspec.lock`, which is committed for an application. A package that imports a
+  library the manifest does not list resolves only by accident.
+
+## Style
+
+- `package:lints` (or the repo's stricter set) is the lint source; a rule the repo
+  disabled is a decision, and re-enabling it is a change, not a fix.
+- No `dynamic` where a real type exists. A `dynamic` that is guessed rather than
+  checked is a hole the analyzer was told to stop looking through.
+- `late` and `?` are decisions: a field that is `late` because the author did not
+  know when it is set is a defect, not a convenience.
+- Prefer a small `sealed` class hierarchy over booleans; a pair of `bool` fields is
+  four states, one of which is always wrong.
+
+## Testing
+
+- `dart test` is the gate; a library with no tests is allowed to have none, but a
+  change that touches one must not break its neighbours.
+- Assert on values through the public API; a test that reaches into a private field
+  is coupled to an implementation it should not own.

package/rules/stacks/deno.md

@@ -0,0 +1,36 @@
+---
+simt-id: deno
+simt-title: Deno
+simt-applies: [has-deno-config]
+---
+
+# Stack profile: Deno
+
+Applies to: `has-deno-config` — a `deno.json` or `deno.jsonc`.
+
+## Build and gates
+
+- `deno test`, `deno check .` are the entrypoints; `deno fmt --check` and
+  `deno lint` are the formatting and lint gates. A repo that vendors dependencies
+  runs them with `--vendor`; one that does not must not add the flag.
+- The lockfile (`deno.lock`) is committed where it exists; a build that ignores it
+  is not reproducible. A lockfile the repo chose to delete is a decision, and
+  re-adding it is a change, not a fix.
+- Import from `npm:` specifiers where the repo does; do not introduce a second
+  registry convention into a repo that has one.
+
+## Style
+
+- Types are checked with `deno check .`; a file that compiles under `deno run` but
+  not under `deno check` is a defect the gate exists to catch.
+- No `any`. An `unknown` that is narrowed at the boundary is a type; an `any` is a
+  hole the checker was told to stop looking through.
+- Prefer a small `enum`-shaped union over booleans; a pair of `boolean` fields is
+  four states, one of which is always wrong.
+
+## Testing
+
+- `Deno.test` is the runner; a test that needs a fixture reads it from a path
+  relative to the test file, never from a machine-specific location.
+- Assert on values through the public API; a test that reaches into module-private
+  state is coupled to an implementation it should not own.

package/rules/stacks/dotnet.md

@@ -0,0 +1,35 @@
+---
+simt-id: dotnet
+simt-title: .NET
+simt-applies: [has-nuget]
+---
+
+# Stack profile: .NET
+
+Applies to: `has-nuget` — a `.csproj` or solution.
+
+## Build and gates
+
+- `dotnet build`, `dotnet test` are the entrypoints; `dotnet format
+  --verify-no-changes` is the formatting gate. A solution builds with `dotnet build
+  <solution>`, never a bare project path that skips the solution's configuration.
+- Build with `-warnaserror` where the repo sets it; a warning that is not an error
+  is a defect the gate is being asked to ignore.
+- Restore is deterministic: commit `global.json` and any NuGet.config the repo has,
+  so a build does not depend on a machine's cache.
+
+## Style
+
+- Prefer `required` members and `init` over a public setter that exists to satisfy
+  the constructor. A mutable property nobody should write is a hole in the type.
+- `async`/`await` all the way: no `.Result`, no `.Wait()`. A synchronous call into
+  an async boundary is a deadlock waiting for the thread pool.
+- Nullability is on: `#nullable enable` in new code, and a `?` that is guessed
+  rather than checked is a defect.
+
+## Testing
+
+- `dotnet test` runs xUnit, NUnit or MSTest — whichever the project references; do
+  not add a second framework to a repo that has one.
+- Assert on behaviour through the public surface; a test that reaches into a private
+  field is coupled to an implementation it should not own.

package/rules/stacks/elixir.md

@@ -0,0 +1,39 @@
+---
+simt-id: elixir
+simt-title: Elixir
+simt-applies: [has-mix]
+---
+
+# Stack profile: Elixir
+
+Applies to: `has-mix` — a `mix.exs`.
+
+## Build and gates
+
+- `mix test` is the entrypoint; `mix format --check-formatted` is the formatting
+  gate. A repo that uses `mix credo` runs it with `mix credo --strict` where the
+  `.credo.exs` exists; a check the repo configured is a decision, and skipping it
+  is a change, not a fix.
+- Dependencies are declared in `mix.exs`; `mix deps.get` resolves them into
+  `mix.lock`, which is committed. A module that imports a library the manifest does
+  not list compiles only by accident.
+- A release is built with `mix release` where the repo defines one; do not run a
+  `mix run` against a release's expectations.
+
+## Style
+
+- Pattern-match on the way in, not guard-and-raise on the way out. A function that
+  takes a map and digs three levels deep is a boundary somebody refused to name;
+  match the shape at the edge and pass values in.
+- Errors are returned, not raised, for expected failures; `raise` is for bugs, not
+  for a missing record. A caller that cannot handle the failure is a defect in the
+  caller's contract, not a reason to crash.
+- Prefer a small `struct` with named fields over a map of strings; a `%{}` that is
+  passed through five functions is a type somebody refused to give a name.
+
+## Testing
+
+- `mix test` is the gate; ExUnit is the runner, and a change that touches a module
+  must not break its neighbours.
+- Assert on behaviour through the public API; a test that reaches into a private
+  field is coupled to an implementation it should not own.

package/rules/stacks/go.md

@@ -0,0 +1,34 @@
+---
+simt-id: go
+simt-title: Go
+simt-applies: [has-go-mod]
+---
+
+# Stack profile: Go
+
+Applies to: `has-go-mod` — a module.
+
+## Build and gates
+
+- `go build ./...`, `go test ./...` are the entrypoints; `go vet ./...` runs with
+  them. Never rely on a file the build does not include.
+- Format with `gofmt` (or `go fmt ./...`). A diff that is only formatting is a
+  defect: the gate fails closed on it.
+- Depend on the module, not on a `GOPATH` layout. A package import that resolves
+  only because of a local checkout is a broken dependency.
+
+## Style
+
+- Errors are values, not exceptions. Wrap with `fmt.Errorf("...: %w", err)` so the
+  caller can `errors.Is`/`errors.As`; a bare string loses the chain.
+- `context.Context` is the first parameter of anything that can be cancelled; never
+  store one in a struct.
+- Table-driven tests: one `for range` over named cases beats ten copy-pasted
+  subtests.
+
+## Testing
+
+- `go test ./...` is the gate; a package with no test file is allowed to have none,
+  but a change that touches one must not break its neighbours.
+- Benchmark with `-bench` only where the number is a decision; an unowned benchmark
+  is decoration.

package/rules/stacks/ruby.md

@@ -0,0 +1,36 @@
+---
+simt-id: ruby
+simt-title: Ruby
+simt-applies: [has-gemfile]
+---
+
+# Stack profile: Ruby
+
+Applies to: `has-gemfile` — a Bundled application or gem.
+
+## Build and gates
+
+- `bundle install` then `bundle exec rspec` are the entrypoints; run every command
+  through `bundle exec`, never a bare binary, so the Gemfile.lock is the only
+  source of truth for versions.
+- `bundle exec rubocop` is the lint gate where the repo has a `.rubocop.yml`; a
+  cop the repo disabled is a decision, and re-enabling it is a change, not a fix.
+- `Gemfile.lock` is committed for an application; for a library it is not, and the
+  distinction is a decision the repo made, not one to reverse silently.
+
+## Style
+
+- Frozen string literals (`# frozen_string_literal: true`) at the top of new files
+  where the repo already uses them; a mixed repo is a transition, not a licence to
+  pick either.
+- Prefer `case`/`when` or a hash over a chain of `if`/`elsif` on one variable; a
+  five-branch if-chain is a lookup table somebody refused to name.
+- `raise` with a message that names the failure and the value that caused it; a
+  bare `raise` is a defect the next reader cannot debug.
+
+## Testing
+
+- RSpec is the runner where the repo has one; do not add a second framework to a
+  repo that has one.
+- Assert on behaviour through the public interface; a spec that stubs everything
+  and asserts on the stub is testing the stub, not the code.

package/rules/stacks/rust.md

@@ -0,0 +1,34 @@
+---
+simt-id: rust
+simt-title: Rust
+simt-applies: [has-cargo-toml]
+---
+
+# Stack profile: Rust
+
+Applies to: `has-cargo-toml` — a Cargo workspace or crate.
+
+## Build and gates
+
+- `cargo build`, `cargo test` are the entrypoints; a workspace builds with
+  `cargo build --workspace`. Never invoke a toolchain the manifest does not pin.
+- Format with `cargo fmt`; lint with `cargo clippy -- -D warnings`. A warning is a
+  defect, not a note: fix it or the gate fails.
+- Pin the toolchain in `rust-toolchain.toml` where one is committed; a rustup
+  default on the developer's machine is not a floor anything enforces.
+
+## Style
+
+- No `unwrap()` or `expect()` outside tests. A panic path in library code is an
+  unhandled error; return a `Result` and let the caller decide.
+- `#[must_use]` on fallible constructors; a `Result` that is ignored is a bug the
+  compiler should flag.
+- Prefer a small `enum` of states over booleans; a pair of `bool` fields is four
+  states, one of which is always wrong.
+
+## Testing
+
+- Unit tests live in `#[cfg(test)]` next to the code; integration tests in `tests/`
+  exercise the public API only.
+- Assert on values, not on panic messages. A test that asserts a panic string has
+  coupled itself to an implementation detail it should not own.

package/rules/stacks/swift.md

@@ -0,0 +1,37 @@
+---
+simt-id: swift
+simt-title: Swift
+simt-applies: [has-swift-package]
+---
+
+# Stack profile: Swift
+
+Applies to: `has-swift-package` — a Swift package.
+
+## Build and gates
+
+- `swift build`, `swift test` are the entrypoints; `swift format lint -r .` is the
+  formatting gate. A platform build (Xcode) is a different question from a package
+  build — do not conflate the two in one command.
+- Pin the toolchain where the repo does (a `Package.swift` tools version or a
+  pinned Xcode); a compiler on the developer's machine is not a floor anything
+  enforces.
+- Dependencies are declared in `Package.swift`; a package that imports a module the
+  manifest does not list builds only by accident.
+
+## Style
+
+- Concurrency is checked, not assumed: `Sendable` conformance is a decision. A
+  `@unchecked Sendable` that papers over a real race is a defect the compiler was
+  told to stop reporting.
+- `throws` for expected failures, not `fatalError`. A crash path in library code is
+  an unhandled error; return a `Result` or throw.
+- Prefer a small `enum` of states over optionals of optionals; a triple `??` is a
+  state machine somebody refused to name.
+
+## Testing
+
+- `swift test` is the gate; a target with no tests is allowed to have none, but a
+  change that touches one must not break its neighbours.
+- Assert on values through the public API; a test that reaches into an internal
+  field is coupled to an implementation it should not own.

package/src/argv.mjs

@@ -12,23 +12,34 @@
 
 import { EXIT, fail } from './output/index.mjs';
 
-const BOOL_FLAGS = new Set([
+// `--quiet`, `--semantic` and `--mermaid` were here and were read by nothing (review
+// 0001 filed it; it survived every change to this file since). Each was a plan's
+// intention rather than a feature: `--semantic` was to be an explicitly non-canonical
+// escape hatch, `--mermaid` belonged to a `skills graph` command that was never built,
+// and `--quiet` was to shorten `help`. The plans keep those records; the parser does not
+// need to keep a promise no code makes.
+//
+// An accepted flag that changes nothing is worse than an absent one. `--nonsense` exits
+// 2 and tells the reader the flag does not exist; `--quiet` exits 0 and tells them
+// nothing happened, which is indistinguishable from the output being quiet on purpose.
+// Removing them makes `test/help.test.mjs`'s "every flag is described" assertion able to
+// mean something, which it could not while three accepted flags had no description.
+
+export const BOOL_FLAGS = new Set([
   'json',
   'all',
   'dry-run',
   'yes',
   'check',
-  'quiet',
   'plan',
-  'semantic',
-  'mermaid',
   'help',
   'version',
   'accept-conflicts',
+  'backup',
   'list',
 ]);
 
-const VALUE_FLAGS = new Set([
+export const VALUE_FLAGS = new Set([
   'budget',
   'max-bytes',
   'paths',
@@ -43,6 +54,21 @@ const VALUE_FLAGS = new Set([
   'surfaces',
 ]);
 
+/**
+ * Flags that accumulate rather than overwrite.
+ *
+ * `--skill` was documented as "(repeatable)" and was not: `flags.skill = value` meant
+ * `--skill a --skill b` resolved to `b`, with `a` silently dropped. No error, no
+ * warning, and a brief that quietly lacked a skill the caller named — which is the one
+ * failure mode a tool whose job is to be explainable cannot have (ADR-009, "the answer
+ * is a function of what was asked").
+ *
+ * Comma separation still works, because the consumer splits on commas either way. This
+ * is a superset of the old behaviour, not a replacement: `--skill a,b` parsed before it
+ * parses now.
+ */
+export const REPEATABLE_FLAGS = new Set(['skill']);
+
 /**
  * @param {string[]} argv raw arguments, excluding node and the script path
  * @returns {{ok: true, value: object} | {ok: false, code: number}}
@@ -96,7 +122,10 @@ export function parse(argv) {
         }
         flags[camel(raw)] = n;
       } else {
-        flags[camel(raw)] = value;
+        const key = camel(raw);
+        flags[key] = REPEATABLE_FLAGS.has(raw)
+          ? [...(Array.isArray(flags[key]) ? flags[key] : []), value]
+          : value;
       }
       continue;
     }

package/src/ci/dependabot.mjs

@@ -142,7 +142,7 @@ function header(own) {
 # only writer here, so an entry is added deliberately rather than as a side effect.
 `;
   }
-  return `# Written by simt-dev when this repo was adopted. Yours from here: simt-dev
+  return `# Written by simt-dev when this repo was adopted. Yours from here: ${CLI}
 # creates this file once and never rewrites it, so your own cadence, ignore rules
 # and groups stay yours.
 #