simt-dev 0.0.0-stage → 0.1.1

package/docs/decisions/ADR-014-workspace-is-configuration.md

@@ -0,0 +1,211 @@
+# ADR-014 — The workspace is configuration, and a single repo is a first-class case
+
+Status: **accepted** · 2026-10-05
+Affects: `simt-dev` CLI (workspace resolution, `compare`, `skills`, registry validation, packaging)
+
+## Context
+
+ADR-013 made the *vocabulary* generic. It did not make the *filesystem layout* generic, and the
+gap was invisible from inside the checkout. Three failures were measured rather than reasoned
+about, by running the tool from a throwaway repo outside `/code/simt` and from a simulated
+`node_modules` install:
+
+1. **Every `skills` command and `graph lint` fails outside the SIMT workspace.** `WORKSPACE_ROOT`
+   was `resolve(HERE, '..', '..', '..')` — three levels up from the source file. In the checkout
+   that is `/code/simt`, which is correct. In an npm install it is
+   `node_modules/@quazarmedia`:
+
+   | install location | `WORKSPACE_ROOT` resolves to |
+   |---|---|
+   | `/code/simt/simt-dev/src/graph` | `/code/simt` — correct |
+   | `…/node_modules/@quazarmedia/simt-dev/src/graph` | `…/node_modules/@quazarmedia` — wrong |
+
+   The symptom is `ENOENT` for all 38 sources. The *remedy* printed is
+   `run: simt-dev graph lint`, which is itself wrong, because the reader has no workspace to lint.
+
+2. **`rules why` cannot work in the published package.** `package.json` `files` lists
+   `bin src graph rules skills agents tooling hooks` and not `docs`. `npm pack` produces 39 files
+   and zero from `docs/`, so every ADR lookup fails in a real install. The whole provenance
+   feature — the reason `rules why` exists — is unusable outside the checkout.
+
+3. **`compare` treats a repo as a workspace and rejects it.** `--root <a-repo>` fails with
+   `contains no git repositories` and exit 3, because `discover` scans the *children* of the
+   given directory. The most common invocation outside a multi-repo workspace — point the tool at
+   one repo — is an error. The remedy, `no git repositories found under <path>`, is also
+   misleading: there is one, you are standing in it.
+
+None of this was visible in the tests, because every test ran from the checkout. That is the
+general lesson and it is the reason this record exists: **a tool's own layout is part of its
+interface, and a test suite that only runs the tool from its source tree cannot detect that the
+tool only works from its source tree.**
+
+The related question — how does `simt-dev upgrade` know which repos to bump? — has the same root
+cause. There is no consumer registry on disk. The only thing aware of sibling repos is
+`compare`'s one-level-deep scan, rooted at `..` of the *current checkout*. That is why
+`compare` already prints `run: simt-dev upgrade` for every drifted repo: the detection half exists and
+the remedy is a dangling reference.
+
+## Ruling
+
+### 1. The workspace is configuration, resolved in a fixed, reported order
+
+Precedence, highest first:
+
+1. `--workspace <path>` — an explicit flag always wins.
+2. `SIMT_DEV_WORKSPACE` — the environment variable, for CI and one-off invocations.
+3. A user config file at the platform's conventional location (§2).
+4. The sibling heuristic — the parent of this package, when that parent actually contains git
+   repositories. This is what makes a fresh clone of the checkout work with no configuration at
+   all, and it is a **heuristic, not a rule**: it is consulted last and it is only accepted when
+   it verifies.
+
+**Every command that consults the workspace reports where it came from.** `simt-dev doctor` prints
+the resolved root and its source. An invisible configuration is a configuration nobody can debug,
+and a silent fallback to a wrong directory is the worst outcome available: every answer is then
+confidently wrong.
+
+### 2. The user config file lives where the platform expects it, with a documented fallback
+
+Candidate paths, searched in order; the first that exists wins, and the first is the one named
+when reporting a path to create:
+
+| Platform | Candidates, in order |
+|---|---|
+| any | `$XDG_CONFIG_HOME/simt-dev/config.json` |
+| POSIX | `$HOME/.config/simt-dev/config.json` |
+| macOS | `$HOME/Library/Application Support/simt-dev/config.json` |
+| Windows | `%APPDATA%/simt-dev/config.json` |
+
+`$XDG_CONFIG_HOME` first because it is the only way to *override* the location on a POSIX system,
+and honouring an explicit override before guessing is the whole point. macOS is listed after the
+XDG candidates deliberately: `~/Library/Application Support` is Apple's documented location for
+application data, but a tool that honours XDG where set is friendlier to a developer who already
+uses it, and the fallback means neither convention is unsupported.
+
+The file is JSON. Its shape is deliberately **not** a workspace-shaped object:
+
+```json
+{
+  "workspace": "/path/containing/repos"
+}
+```
+
+`workspace` is an optional key. An empty, absent or unreadable file is not an error — it means
+"not configured", and resolution continues down the precedence list. Only a file that exists and
+does not parse is reported, because that is a real mistake the reader can fix.
+
+Windows appears in the table although [ADR-012](ADR-012-drop-windows-support.md) drops Windows
+support. The lookup function stays total so it is testable on any host and correct if that
+reversal ever happens; `package.json` still refuses to install on Windows.
+
+### 3. A workspace is optional; a single repo is a normal, supported case
+
+Every command that needs a workspace must work with **one repo and no workspace at all**. Concretely:
+
+- `compare --root <path>` where `<path>` is a repository compares that repository. Where it is a
+  directory, its git-repository children are compared. The distinction is detected, not configured,
+  because the two cases are already distinguishable from the filesystem.
+- Discovery no longer reports "no git repositories" when it is standing in one.
+- Nothing anywhere requires a second repo to exist.
+
+### 4. A missing workspace is a fact, reported once — never a fatal error
+
+When no workspace is configured and the heuristic does not verify, the skill catalogue cannot be
+resolved from disk. That is a **warning with one remedy**, not an error:
+
+```
+WARNING skill sources are not available: no workspace configured
+REMEDY  set one with --workspace <path>, SIMT_DEV_WORKSPACE, or the config file
+```
+
+Registry disk verification is **skipped** in that state, with the skip itself reported by
+`graph lint`. The alternative — 38 `ENOENT` lines — teaches the reader that the lint is noisy,
+and a lint that is always noisy is a lint that is always ignored.
+
+The exit code follows the same principle as `compare`'s non-adoption rule
+([ADR-013](ADR-013-genericity-by-facts-and-local-profiles.md), and step 9 of plan 0002): exit
+non-zero when something is **wrong**, zero when something is merely **absent**.
+
+### 5. The decision records ship with the package
+
+`docs/decisions` is added to `package.json` `files`. A feature whose input is not packaged is not
+a feature; `rules why` is the provenance mechanism the whole one-canonical-home doctrine rests
+on, and it cannot depend on a git checkout being present.
+
+`docs/plans` ships with it, because every non-zero exit prints a remedy pointing at
+`docs/plans/0002-simt-dev-cli.md section 11`.
+
+### 6. "Absent", "wrong" and "moved" are three different facts
+
+Section 4 settled the case where **no** workspace is configured. Writing the tests for it exposed
+two more, and they are not the same case:
+
+| State | Reported as |
+|---|---|
+| Nothing configured | `no workspace configured` + the remedy |
+| Configured, directory **missing** | `the configured workspace <path> (from <source>) does not exist` |
+| Configured, directory exists but **holds none of the named repositories** | `<path> contains none of the repositories the registry names (…)` |
+
+All three are warnings and all three skip disk verification. What changed is the **specificity**
+of the message, and that specificity is the whole value: "you configured nothing" and "you
+configured the wrong directory" are different problems with different fixes, and the reader can
+only fix the one they are told about.
+
+The third state is the one that mattered. Existence is not a sufficient test for a workspace, and
+before this section `--workspace <an empty directory>` produced 38 `ENOENT` lines reading as a
+broken registry — precisely backwards, because the registry is fine and the pointer is wrong. So
+verification requires that the workspace hold at least one of the repositories the registry
+names, checked before any file is measured.
+
+### 7. A workspace can be declined, and a broken config is reported whatever outranks it
+
+Two things the first implementation got wrong, both found by running the CLI rather than by
+testing a function:
+
+- **There was no way to say "no workspace".** The sibling heuristic always fired when nothing
+  was configured, so a reader who did not want a directory guessed for them had no way to refuse
+  — and no test running from the checkout could reach the unconfigured path at all, because the
+  checkout always has a verifying sibling. `--workspace off`, `SIMT_DEV_WORKSPACE=off` and
+  `"workspace": "off"` now all mean *declined*, and return the same shape as any other answer so
+  callers need no special case.
+- **A config file that does not parse was only read if nothing outranked it.** Precedence decided
+  the *answer*, but it was also suppressing a *defect*: an unparseable config is a real mistake in
+  the reader's setup, and hiding it because `SIMT_DEV_WORKSPACE` happened to be set sends them
+  looking for a configuration problem in the wrong place. The config file is therefore read
+  first, and a parse failure is returned immediately.
+
+That second bug is the standing lesson of this record, discovered by its own meta-lesson:
+`configPaths` defaulted `env` to `{}` so that tests could inject a fake environment, which meant
+`XDG_CONFIG_HOME` — the one documented way to *override* the config location — was ignored on
+every real invocation. Every unit test passed `{env}` explicitly. **A test that supplies a
+dependency explicitly cannot detect that the default for that dependency is wrong.**
+
+## Consequences
+
+- The checkout keeps working with zero configuration, because the sibling heuristic is consulted
+  last and verified.
+- A single developer with one repository never has to learn what a workspace is. `compare`,
+  `rules`, `sync`, `check`, `hooks` and `init` all work against one repo.
+- The skill catalogue — which is SIMT content — degrades to a single warning outside the SIMT
+  workspace, while the *rules* engine stays fully functional, because `rules/` ships in the
+  package and `rules/*.md` has no external sources.
+- `simt-dev upgrade` gets a real answer for consumer discovery: the resolved workspace, plus an
+  explicit `--root` for a single repo. No consumer list needs to be maintained in simt-dev,
+  because a repo that has not adopted cannot be listed by the thing it has not adopted.
+
+## Rejected
+
+- **A consumer list inside simt-dev.** A repo that has not adopted has no manifest, so it cannot
+  appear in a manifest kept by the tool it has not adopted. Discovery has to come from the
+  filesystem.
+- **Inferring the workspace from git remotes.** Fragile, and wrong in the common case: several
+  sibling repos legitimately share one remote organisation, and a personal fork of one repo has a
+  remote that points nowhere useful.
+- **Requiring a workspace.** It would make the common case — one repo, one user, no org — pay a
+  configuration tax to use a tool whose rules engine is already ecosystem-neutral.
+- **A machine-wide registry of skill sources.** A directory of symlinks into the workspace would
+  reintroduce exactly the cross-repo symlink fragility that made plan 0001 choose a generated
+  projection instead.
+- **Treating an unresolvable workspace as a registry error.** Same failure as printing 38
+  `ENOENT` lines: it converts an absent thing into a loud failure and trains the reader to ignore
+  the output.

package/docs/decisions/ADR-015-a-source-is-content-not-a-location.md

@@ -0,0 +1,117 @@
+# ADR-015 — A source is identified by its content; the repository is a location, not a precondition
+
+Status: **accepted** · 2026-10-05
+Affects: `resolve/source.mjs`, `skills install`, `skills show`, `skills brief`
+
+## Context
+
+[ADR-014](../decisions/ADR-014-workspace-is-configuration.md) made the workspace optional and
+single-repo use first class. It fixed resolution, not lookup, and the next defect was found
+immediately by the user who asked for the previous one.
+
+Someone who cloned **only `simt-social`** has the `simt-social` body of `slice-commit` on disk at
+`.agents/skills/slice-commit`. They have no workspace. The registry entry
+`simt-social/.agents/skills/slice-commit` is satisfied by that file. Both commands refused:
+
+```
+$ simt-dev skills install slice-commit
+ERROR 2 slice-commit has 2 variants and none matches this repo (node)
+
+$ simt-dev skills show slice-commit
+(body unavailable: this installation has no workspace, so slice-commit has no body to fetch; …)
+```
+
+The body was in the current directory for both.
+
+The root cause is a definition that was never written down. `sources: [{repo, path, bytes, role}]`
+resolves at exactly one place — `join(workspaceRoot, repo, path)`. There is a second place, and it is
+not even exotic: **`<root>/<path>`**, because the repository being operated on is itself a location
+for a declared source when the registry entry's `repo` is that repository.
+
+The refusal was also wrong for a reason that had nothing to do with the workspace. `slice-commit`
+has two variants, `web` and `api`, discriminated by stack tag. That clone's `package.json` emitted
+`node`, which matches neither, so variant selection failed — while the clone's own 5048 bytes were
+an exact answer sitting in the working tree. **The tool asked the manifest a question the manifest
+could not answer, and ignored the evidence in front of it.**
+
+## Ruling
+
+### 1. A declared source is found by content, at every legal location
+
+`resolve/source.mjs` exports `candidateLocations(source, {workspaceRoot, root})` — the workspace
+location first, then the repo-relative location — and `locateSource(source, options)`, which accepts
+a candidate **only when the measured size equals the declared size**.
+
+Bytes are what make this safe rather than hopeful. Every source declares its size, and `graph lint`
+already verifies every declared size against the file on disk. A candidate that exists at the right
+path with the wrong size is not a degraded match; it is a different file, and it is rejected.
+
+Two rules keep this from becoming a way to install the wrong body:
+
+- **A workspace location wins over a repo location.** The canonical body beats the incidental copy.
+- **Content decides identity, never location.**
+
+### 2. What the repo already holds is a resolution signal, not a fallback
+
+`sourceHeldLocally(skill, root)` is a first-class input to source selection, placed after explicit
+flags and after the repo's stack signals, and ahead of refusing. `chooseSource`'s precedence is now:
+
+1. `--from` — explicit. Obeyed even when it contradicts the repo's contents; the disagreement is a
+   note, because the author is answering a question the tool cannot.
+2. `--variant` — explicit, same treatment.
+3. **The repo's signals name exactly one variant.** The normal path.
+4. **The repo already holds exactly one declared source.** Its bytes are an exact answer, so this
+   settles both an unmatched repo (step 3 found nothing) and an ambiguous one (step 3 found several).
+5. Refuse — with the reason named.
+
+Content beats taxonomy because a byte count cannot be a coincidence. A stack tag can.
+
+### 3. A contradiction is a refusal; an ambiguity is a decision
+
+Two rules that look similar and are not:
+
+- **Signals name one variant and the repo holds another** → **refuse.** One of two inputs is wrong
+  and the reader needs to know which; installing either silently picks a side.
+- **Signals name several variants and the repo holds one of them** → **install that one**, because
+  the repo's bytes are not a guess. Reported as `the repo's own copy decides`.
+
+### 4. A file of the right shape and the wrong body gets its own message
+
+`simt-dev skills install` reports `<path> exists but is not the declared body (5048 bytes declared)`.
+The alternative message — "none of the variants matches this repo" — is true and useless: it sends
+the reader to inspect their stack tags when the actual problem is the file in front of them.
+
+### 5. `skills show` and `skills brief` read a repo-local body, and say which
+
+`sourcePath` tries the canonical source first and falls back to what the repo holds.
+`skills show` gained a `body <workspace|repo> <path>` line, because a reader who has two candidate
+locations needs to know which one answered. `skills install` gained a matching `read` line.
+
+An install that cannot read a body **fails**. `skills show` that cannot read one still answers,
+because a catalogue plus a pointer is useful with no workspace at all. The asymmetry is deliberate
+and is the same asymmetry as ADR-014's: degrade the read, never the write.
+
+## Consequences
+
+- A clone of any single repository is fully self-sufficient for `skills show`, `skills brief` and
+  `skills install`, with no configuration at all.
+- A repo holding two declared sources at once (`{ambiguous: true}`) is refused: the registry and the
+  repo disagree, and neither is authoritative enough to break the tie.
+- `graph lint` remains the thing that proves the registry still matches the world. It is unchanged,
+  and it is the reason a byte comparison is trustworthy rather than optimistic.
+- The `--from` and `--variant` escapes are load-bearing: they are now the only ways to override the
+  repo's own contents, which is correct, because overriding the evidence should be deliberate.
+
+## Rejected
+
+- **Treat any existing path as a match.** A near-miss body would install silently, which is worse
+  than refusing: the tool would have written a file it had not verified.
+- **Ask for a workspace when the repo holds the body.** The workspace would then be required for the
+  one case where it is provably unnecessary.
+- **Select the variant from the repo's directory name.** `<root>/.agents/skills/slice-commit` says
+  which skill it is, not which variant it is; only its bytes do.
+- **Prefer the repo's copy over the workspace's.** A workspace checkout is the canonical body, and a
+  symlink fan-out can make them the same file; preferring either silently would hide a divergence.
+- **Make variant selection advisory everywhere.** "Signals say api, the repo holds web" would
+  install one of them and print nothing, which is exactly the silent divergence variants exist to
+  prevent.

package/docs/decisions/ADR-016-a-divergent-rule-is-retired-not-merged.md

@@ -0,0 +1,180 @@
+# ADR-016 — A divergent rule is retired, not merged
+
+Status: **accepted** · 2026-10-06 · one ruling narrowed by [ADR-045](ADR-045-a-dashboard-that-counts-a-defect.md)
+Affects: `rules/mdc/*.mdc`, `projection/mdc.mjs`, `projection/project.mjs`, `projection/conflicts.mjs`, `sync`, `check`, `init`
+
+> **Narrowed by ADR-045.** The bullet below that says `compare` reports "using `AGENTS.md`
+> only" still governs the row's **display**, which is where it was aimed. It was read more
+> broadly than it was written, and `compare`'s *problems list* stayed silent about stale rule
+> files as a result: seventeen of them across five adopted repositories, none named. The
+> problems list is not a display — it is the exit code. Every other ruling here stands, which
+> is why this is a narrowing and not a supersession.
+
+## Context
+
+The estate carried three always-on `.mdc` rule families across three repos, in eight
+files, with no two byte-identical.
+
+The worst pair differed by **one byte** (`simt-social/.cursor/rules/intake-questions.mdc`
+at 1280 against `simt-social-api`'s at 1281) while hiding three semantically loaded line
+changes: a plan-tracker path rewritten to point at the other repo, `migrations` added to the
+list of decisions worth asking about, and a requirement silently dropped. No size-, hash-,
+hash-adjacency- or line-count-based duplicate detector could ever have flagged that pair. The
+reason is not that the detectors were weak: it is that **divergence here is not a formatting
+difference, it is a semantic loss**, and the smaller copy is the one missing a rule.
+
+Reading all eight produced three findings that a variant mechanism cannot represent:
+
+1. `test-gate`'s fourth `BLOCK` bullet is **complementary across the pair, not alternative**.
+   `simt-social` blocks a consumer that requires an API field with no backward-compatibility
+   or deploy-order evidence; `simt-social-api` blocks a producer that ships without a test
+   asserting the new invariant. Each repo's reviewer was told to check only its own half.
+2. `preview-postflight`'s second Requirements bullet is likewise complementary, and looks
+   like a conflict because the two files put different rules in the same slot: `simt-social`
+   says set `SOCIAL_API_BASE_URL` in the Cloudflare Workers Builds preview environment;
+   `simt-social-api` says credentials live in the operator keychain only, never in source,
+   chat, D1 or logs.
+3. Two deletions left no trace. `simt-social-api` dropped `simt-social`'s worked example
+   (`Partial pass (e.g. 6/8 pass) is a hard blocker`) — the example is what does the work,
+   and its removal is invisible in a diff review because the rule's normative force looks
+   unchanged. `simt-social-media` dropped the entire `## Allowed Without Account` section, so
+   it has no documented set of probes that are legal without credentials.
+
+A variant mechanism models "these are the same rule, rendered per stack". None of these three
+is that. Two are **unions**, and one is a **deletion that must be undone**.
+
+## Rulings
+
+### 1. Canonical `.mdc` rules are unions, never variants
+
+`rules/mdc/*.mdc` holds one body per rule, carrying every clause any repo needs. Where two
+copies disagreed, both clauses are present and both are unconditional. Concretely:
+
+- `test-gate` keeps both `BLOCK` bullets and says explicitly that they are complementary, so
+  a reader cannot tell that checking one is sufficient.
+- `preview-postflight` keeps both Requirements bullets.
+- `test-gate` keeps the `6/8 pass` example, and `preview-postflight` restores
+  `## Allowed Without Account` with social-api's `D1 migration verification` addition.
+
+**Why:** a variant preserves a choice. These files do not record a choice; they record three
+independent accidents, and two of the eight copies are strictly weaker than the best one. A
+mechanism that keeps choosing between them will keep choosing the weaker one.
+
+### 2. Only substrate is a substitution; only what varies per repo is declared
+
+What genuinely differs between the copies is paths and names: a plan-tracker glob, a test
+file path, a path vocabulary, a production domain, a preview Worker name. Those become
+`{{placeholders}}` with **declared defaults**, in `rules/mdc/*.mdc`:
+
+```yaml
+substitutions:
+  - key: plansGlob
+    default: docs/plans/*
+    describe: glob for this repo's active plan tracker tables
+```
+
+Values live in the repo's `simt-dev.json` under `substitutions`, keyed by rule id. They are
+facts about the repo, while a rule is shared by every repo that adopts it — putting them in
+the rule would either hard-code one repo's paths for everyone or push the decision back into
+prose, which is the drift this mechanism exists to remove.
+
+An **empty** value, or an empty default, drops the line it sits on. That is how one canonical
+file reaches `simt-social-media` (no plan-tracker note) and `simt-space` (not a Workers repo
+at all) without printing a blank bullet. A placeholder with neither a default nor a
+declaration is a **gate failure**, because a rule shipping a literal `{{key}}` reads as
+finished and is not.
+
+### 3. A rule that names one product's infrastructure is opt-in, not stack-detected
+
+`preview-postflight` declares `applies: []` and `optIn: true`. It names specific preview
+Workers, `AUTH_PROVIDER_POLICY`, `POSTFLIGHT_PASSWORD_UID` and specific production domains.
+Selecting it on `cloudflare-workers` would hand it to `simt-space` and `simt-goto` — Workers
+repos with no preview Workers and no Social identity — which is the same over-match bug that
+`rules/stacks/react-web.md` had when it declared `typescript` and `vitest`.
+
+Detection cannot distinguish a Workers repo that has this problem from one that does not, so
+the repo declares it: `"substitutions": { "__optIn": ["preview-postflight"] }`. `intake-questions`
+and `test-gate` are `applies: always`, because they are genuinely stack-agnostic.
+
+This is the first place ADR-013's fact-based detection is deliberately **not** used. A fact
+answers "what is this repo made of"; opt-in answers "does this repo have this problem", which
+is a different question and detection cannot reach it.
+
+### 4. A managed `.mdc` rule is a generated file, not a region inside a hand-owned one
+
+`AGENTS.md` keeps its hand-written prose and receives a region. A `.mdc` rule does not: the
+body after the frontmatter **is** the region, full stop. There is no hand-owned prose to
+preserve, because any prose that was there is exactly the divergent copy being retired.
+
+This was found by running it. The first implementation appended the region and produced a
+file with two `## Requirements` sections and every bullet twice — the duplication the
+estate's own review agent (`principal-slice-reviewer` checklist item 5) is explicitly
+instructed to block, produced by the tool meant to remove it. Appending is the obvious
+implementation and it is wrong here.
+
+So `sync` keeps the existing frontmatter (the editor reads `description` and `alwaysApply`
+before any rule text) and replaces everything below it. `check` compares against the same
+reconstruction, or it would demand the divergent text still be present.
+
+Because that is a destructive edit to a real file, `init` and `sync` report it:
+
+```
+note  .cursor/rules/test-gate.mdc: retiring 928 bytes of divergent hand-written rule text
+```
+
+Silent deletion is the one thing a reviewer cannot audit.
+
+### 5. The conflict scanner must reach every rule surface, including ones added later
+
+`RULE_FILES` named only `AGENTS.md`, `CLAUDE.md` and `CONTRIBUTING.md` for the whole life of
+the tool. `simt-dev init` therefore reported **`CONFLICTS none detected`** on
+`simt-social-api` — the repo holding the worst-drifted content in the estate — because it
+never looked at the `.mdc` files at all.
+
+A detector that only knows the filenames it was written for will quietly miss a whole rule
+surface added later, and it will miss it *confidently*, reporting a clean result. Rule
+discovery is now by name **and** by glob (`.cursor/rules/*.mdc`,
+`.github/instructions/*.md`), and generated regions are stripped before scanning so that
+quoting a ruling is never mistaken for contradicting it.
+
+Writing that test found a second-order bug worth recording: the glob was split at its first
+`*` and the tail matched as a name *prefix*, so `.cursor/rules/*.mdc` matched nothing. A
+detector that silently matches zero files is indistinguishable from a repo with no rules —
+the same failure, one level down.
+
+### 6. An autonomous-push probe must match every phrasing the estate actually used
+
+The probe matched `committed and pushed`, which is `simt-garmin`'s exact DoD wording. A
+different author wrote `Always commit and pushed`; another would write `commit and push`. The
+first version matched only the first form and reported a real autonomous-push rule as clean.
+
+The general lesson is the one this repository keeps re-learning: **probes are tested against
+the estate's real text, not against text written to match the probe.**
+
+## Consequences
+
+- `rules/mdc/{intake-questions,test-gate,preview-postflight}.mdc` are the canonical bodies.
+  Eight files in three repos become generated output.
+- `simt-dev.json` gains a `substitutions` object, and the manifest generator seeds it empty
+  rather than leaving the key absent, so the shape is visible before anything needs it.
+- `simt-dev sync` and `simt-dev check` handle four targets, not one. A malformed region in any target
+  refuses the whole run **before the first write** — writing the good three and skipping the
+  broken one would leave a repo half-adopted with no record of which half.
+- `compare` continues to report one row per repo using `AGENTS.md` only, because a dashboard
+  row cannot represent four files. The gate uses the full finding list, so the dashboard's
+  coarser view is not inherited by the thing that must not be wrong.
+
+## Rejected
+
+- **A variant mechanism per stack** (one `test-gate.mdc` per repo). This is what produced the
+  drift; modelling it as intended behaviour would make the drift permanent and legitimate.
+- **Picking the "best" copy per family and adopting it as canonical.** `simt-social`'s
+  `test-gate` is the better copy only by accident; it is missing the producer-side `BLOCK`
+  bullet that social-api has. Choosing one per family would have discarded a real rule.
+- **Deleting the 8 files outright** rather than generating over them. A repo with no
+  `intake-questions.mdc` and one with a generated one must behave identically to an agent, and
+  only the second is verifiable by `simt-dev check`.
+- **Making `preview-postflight` apply to `cloudflare-workers`.** Hands an un-actionable rule
+  to two repos, and is the same bug `react-web.md` had.
+- **Leaving `RULE_FILES` as a fixed list** on the grounds that the three families are the only
+  `.mdc` rules that exist. They are the ones that exist *today*; that is not a reason.

package/docs/decisions/ADR-017-a-declared-gate-must-be-runnable.md

@@ -0,0 +1,89 @@
+# ADR-017 — A declared gate must be one the repo can actually run
+
+Status: **accepted** · 2026-10-06
+Affects: `hooks/capability.mjs`, `projection/manifest.mjs`, `commands/init.mjs`, `commands/sync.mjs` (`check`), `hooks/dispatcher.mjs`
+
+## Context
+
+The first real adoption wrote a manifest declaring five gates into `simt-social-media`.
+Three of them could not run:
+
+| Gate | Kind | Why it could not run |
+|---|---|---|
+| `format` | staged | prettier is not a dependency and is not in `node_modules/.bin` |
+| `lint` | script | there is no `lint` script in `package.json` |
+| `i18n-completeness` | command | nothing is declared under `gates.commands` |
+
+It reported as healthy. `simt-dev check` was green, the projected files were current, and the
+repo's own 37 tests passed. The defect was invisible to all of that because nothing had asked
+whether the gates could run — the stack table proposed them from the repo's tags, and the tags
+said `node` and `cloudflare-workers`, which is true.
+
+The dispatcher would have caught it, and correctly: it fails closed. Installing it on that
+manifest blocks **every commit** with `FAILED format … [ADR-004]`. So the first thing a new
+user does after adopting simt-dev is discover that the tool makes committing impossible, and
+the only escape any of them will find is `--no-verify`.
+
+That is the exact spiral the dispatcher was built to prevent. Step 8's design note says a gate
+that cannot run must be a failure rather than a skip, precisely because `simt-space` removed
+tests from `pre-commit` for being slow and the team's answer was `--no-verify`. Failing closed
+is right; declaring an unrunnable gate is wrong.
+
+Two further facts made it survivable for as long as it was:
+
+- **Nothing else owns the manifest.** `sync` writes the projected rules; `init` writes the
+  manifest. A manifest written by an older version is therefore never revisited, which is the
+  same class of bug as the stale `$comment` fixed in `c607d0a`.
+- **`hooks status` already said so** — *"gate `i18n-completeness` in preCommit is a command
+  gate with no declared command; the hook will fail"*. The information existed. It was printed
+  by the one command nobody runs before installing hooks.
+
+## Rulings
+
+1. **A gate is declared only if the repo can run it.** `init` filters the stack table's
+   proposals through what the repo demonstrably has: a script that exists in `package.json`,
+   a binary installed in `node_modules/.bin`, a command the manifest itself names. This is
+   `has-*` fact discipline applied to gates (ADR-013): detection reports evidence, it does not
+   assume capability.
+
+2. **Every drop is named, with the remedy that undoes it.** A silently shorter gate list reads
+   as "this repo needs no formatting check", when the truth is "declaring one would block every
+   commit". The three ways to make a gate runnable are a real choice the repo owns, so the
+   reader is given all three — install the tool, add the script, or name the command.
+
+3. **A gate the repo already declared is never dropped.** Quietly disarming a gate somebody
+   declared on purpose is a worse surprise than a visible one, and a re-init that silently
+   removed gates would make the gate list look like simt-dev's opinion rather than the repo's.
+
+4. **`check` reports an unrunnable declared gate as a finding.** The repo must be red *before*
+   anyone installs hooks, not after. `check` is the gate that runs in CI, so this is where a
+   landmine belongs; `hooks status` saying so is not enough when it is the command nobody runs.
+
+5. **The remedy differs by whether a manifest already exists.** A re-init never re-adds a gate
+   to a manifest that already declares one, so on an existing manifest "install prettier, then
+   re-run init" would send the reader round the loop and back to where they started. The remedy
+   there names the declaration as the second half of the fix.
+
+## Consequences
+
+- `simt-dev init` needs to read the repo before it writes the manifest, so `init` now depends on
+  the hooks subsystem. The dependency runs one way: `gates.mjs` imports nothing.
+- `check` is no longer only about the generated rules. It is the gate over what the manifest
+  promises, which is what a gate is for.
+- A repo whose only answer is "no tool for any of these" gets `preCommit: []`. That is a valid
+  manifest, and the dispatcher says so in one line rather than passing in silence. A string
+  where the caller expected an array once printed that line one character at a time.
+
+## Rejected
+
+- **Fail open in the dispatcher when a gate cannot run.** The spiral is the point; failing open
+  makes the tool's green meaningless, which is worse than a blocked commit because it is silent.
+- **Infer capability from the dependency graph.** A repo with `prettier` in `devDependencies`
+  and no `node_modules` cannot run a formatter. Reading the manifest and the installed binaries
+  are two facts; guessing a third from a lockfile is how the two get to disagree.
+- **Have `init` refuse to adopt a repo that cannot run its gates.** Refusing is worse than
+  writing fewer gates: the repo gets no rules at all, and the obstacle is a formatting tool.
+- **Leave it to `hooks status`.** It is the command run after installing hooks, which is one
+  step after the commit that fails.
+- **Drop unrunnable gates on re-init too.** Silently; the reader sees a shorter list and no
+  explanation, and cannot tell a removed gate from one that was never there.