simt-dev 0.1.1 → 0.2.1

package/docs/decisions/README.md

@@ -64,6 +64,10 @@ record's status line — never by editing the ruling in place.
 | [054](ADR-054-the-digest-covers-every-byte-that-leaves-the-package.md) | The digest covers every byte that leaves the package, and a cause is read off the body | accepted · amends ADR-032 |
 | [055](ADR-055-a-status-line-travels-so-it-may-not-name-a-location.md) | A status line travels, so it may not name a location; prose is the record's own argument | accepted |
 | [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
@@ -400,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
@@ -418,7 +437,7 @@ ADR-018's guard could not see the default hooks directory because it looked only
 key, and `hooks status` carried its own copy of the read logic the shared module already had.
 
 A fourth joins them. ADR-019 is the same shape one layer over: `simt init` dropped all
-five gates on `simt-app` and told the reader to add a script to a `package.json` the
+five gates on `repo-05` and told the reader to add a script to a `package.json` the
 repository will never have. The facts were right, the remedy was not followable, and once
 the repository declared what it does have, the dispatcher, `check` and `hooks status`
 gave three different answers about one manifest. Every one of these shipped green because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.1.1",
+  "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.
 #

package/src/ci/workflow.mjs

@@ -50,6 +50,7 @@ import { PACKAGE_ROOT } from '../workspace.mjs';
 import { PACKAGE_NAME, WORKFLOW_FILE_NAME } from '../name.mjs';
 import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -169,12 +170,16 @@ function skeleton(name, steps, { matrix = null } = {}) {
   const job = matrix?.node ? '\${{ matrix.os }} node \${{ matrix.node }}' : name;
   return `name: ${name}
 
+# Pull requests only, and that is a decision rather than a default.
+#
+# A gate that runs on every push re-runs itself for every commit that pushes a
+# branch forward, including the ones nobody asked it about, and its verdict has to
+# be cleared before the next one lands. \`pull_request\` asks one question — may this
+# merge — and answers it once. \`main\` here is the branch protection list, not a
+# trigger: the gate that has to pass is the one the pull request runs, and the one
+# on \`main\` is whatever CI the repository already has there.
 on:
   pull_request:
-  push:
-    branches:
-      - main
-      - master
 
 # Read-only is enough to check a repo, and a gate job does not need to write to it.
 permissions:
@@ -235,7 +240,7 @@ function indent(text, spaces) {
  * @param {{own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderWorkflow({ own = false } = {}) {
+export function renderWorkflow({ own = false, npm = true, version } = {}) {
   if (own) {
     const floor = nodeFloor();
     return `${header(true)}${skeleton(
@@ -267,17 +272,34 @@ export function renderWorkflow({ own = false } = {}) {
     )}\n`;
   }
 
-  const locator = renderLocator('check --root "$ROOT"', {
-    remedy: `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`,
-  });
+  const v = version ?? packageVersion();
+  // The install step is the whole of S35's consumer CI: a repository with npm pins
+  // simt-dev as a devDependency and `npm ci` restores it; one without (Gradle,
+  // Connect IQ) has no node_modules to pin in, so CI installs the same pinned global
+  // binary the machine remedy names. The two must agree, or the gate passes in one
+  // place and cannot start in the other.
+  const install = npm
+    ? [
+        '      - name: install dependencies',
+        '        # `npm ci` needs a lockfile; a repo without one is still gated, not skipped.',
+        '        run: npm ci || npm install',
+      ]
+    : [
+        '      - name: install the pinned gate binary',
+        '        # No node_modules to pin in, so a pinned global install: the same bytes',
+        '        # the machine remedy names, so the gate cannot pass locally and fail here.',
+        `        run: npm i -g ${PACKAGE_NAME}@${v}`,
+      ];
+  const remedy = npm
+    ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
+    : `REMEDY run: npm i -g ${PACKAGE_NAME}@${v}   (the gate runs from a pinned global install)`;
+  const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
     `${CLI} check`,
     [
       uses('checkout'),
       setupNode(nodeFloor()),
-      '      - name: install dependencies',
-      '        # \`npm ci\` needs a lockfile; a repo without one is still gated, not skipped.',
-      '        run: npm ci || npm install',
+      ...install,
       `      - name: ${CLI} check`,
       '        run: |',
       indent(`set -eu\nROOT="\${GITHUB_WORKSPACE}"\n${locator}`, 10),

package/src/commands/graph.mjs

@@ -7,11 +7,17 @@
 // the offending node, the file it disagrees with, and both numbers.
 
 import { EXIT, emit, fail, isJson } from '../output/index.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { CLI } from '../name.mjs';
 
 export async function lintCommand(positional, flags) {
-  const path = positional[0] ?? REGISTRY_PATH;
-  const { ok, registry, errors, warnings, verified, workspace } = await loadRegistry(path, flags);
+  // The resolved path comes back from the loader, because when no positional is given it
+  // falls back to the member that holds the registry in this workspace (ADR-061) - and the
+  // reader should see where it actually looked, not a constant that no longer exists.
+  const { ok, registry, errors, warnings, verified, workspace, path } = await loadRegistry(
+    positional[0] ?? null,
+    flags,
+  );
 
   if (isJson(flags)) {
     emit(
@@ -40,7 +46,10 @@ export async function lintCommand(positional, flags) {
   }
 
   if (!registry) {
-    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY);
+    // The default remedy for this exit code is `run: simt-dev graph lint`, which from
+    // inside `graph lint` is circular: the reader just ran it and got this. Name the
+    // argument the command takes, because an explicit path is the way out (ADR-061).
+    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY, `run: ${CLI} graph lint <path-to-registry>`);
   }
 
   const lines = [

package/src/commands/help.mjs

@@ -4,7 +4,8 @@ import { CLI } from '../name.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
-                           --accept-conflicts; never commits or pushes)
+                           --accept-conflicts; in place unless --backup;
+                           never commits or pushes)
 ${CLI} doctor                 classify a repo and check config health
 ${CLI} check                  the gate: projection drift, manifest validity, policy
 ${CLI} sync [--yes]           regenerate the projection (idempotent)
@@ -19,6 +20,10 @@ ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
 ${CLI} skills why <name>      the signal chain that selected it
 ${CLI} skills find <query>    search across capability and keyword
+${CLI} skills eval [corpus]   measure the resolver against a gold corpus
+                           (reports precision and recall; exits non-zero on
+                            regression; without an argument, the corpus in this
+                            checkout)
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
@@ -26,9 +31,15 @@ ${CLI} skills install <name>  pin a skill into the repo as a local override
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
 ${CLI} rules why <id|ADR-NNN> the decision that settled it, and whether it is still in force
+                           (--all prints every ruling, not the first two)
 ${CLI} hooks install [--yes]   install the shared dispatcher; report what it would run
                            (dry-run unless --yes; refuses to take over routing git
                             already uses, and --yes is that consent)
+${CLI} hooks status            what each git event routes to, and whether it is wired
+${CLI} hooks run <event>       run one event's gates now, as git would
+                           (pre-commit, pre-push, post-merge, ...)
+${CLI} graph lint              check the skill registry against the skills on disk
+                           (byte counts, dangling edges, unresolvable variants)
 ${CLI} ci                     simt-dev's own .github files: create or refresh them
                            (dry-run unless --yes; refreshes the templates' own copies
                             and no repository else's)
@@ -55,9 +66,16 @@ const FLAGS = `--json                 structured output
                         file, then the sibling heuristic if it verifies)
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
---all                   ignore the budget and resolve everything
+--check                 report drift and write nothing (sync, ci)
+--all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
---from <repo/path>      install from a declared source by name`;
+--from <repo/path>      install from a declared source by name
+--list                  print the MCP tool surface without reading stdin (mcp)
+--accept-conflicts      init: adopt rules that collide with hand-written ones
+--backup                init: tag the pre-adoption commit and branch onto
+                        simt-dev/adopt before writing (the undo path)
+--help                  this text
+--version               the version, and the SHA it was built from`;
 
 const PRINCIPLES = `design rules:
   deterministic       same repo + same task = same answer, forever
@@ -78,7 +96,7 @@ export async function help(argv) {
     [
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
       '',
-      'usage: simt-dev <command> [args] [flags]',
+      `usage: ${CLI} <command> [args] [flags]`,
       '',
       'commands:',
       COMMANDS,