simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-013-genericity-by-facts-and-local-profiles.md

@@ -0,0 +1,114 @@
+# ADR-013 — Genericity comes from emitted facts and repo-local profiles, not from a bigger hardcoded tag table
+
+Status: **accepted** · 2026-10-05
+Affects: the `simt-dev` CLI (fingerprint, profile selection, registry validation)
+
+## Context
+
+The engine is already only loosely coupled to SIMT. Measured, not asserted: `src/argv.mjs`,
+`src/resolve/resolve.mjs` and `src/graph/load.mjs` contain **zero** non-comment,
+non-string references to SIMT. Everywhere else, "SIMT" appears as ADR citations in comments
+documenting *why*, plus one hardcoded npm scope in the hook shim. The project is named SIMT;
+the mechanisms are not.
+
+The coupling that does exist is in the **vocabulary**, not the code. `fingerprint()` emits 17
+tags from three hardcoded tables (`MARKERS`, `EXTENSION_TAGS`, `DEP_TAGS`) plus a literal
+`'wear-os'`, and those tables are keyed by *curated product* names: `connectiq`,
+`maplibre`, `hono`, `react-router`. That has three consequences, and only the first is
+obvious:
+
+1. **A new ecosystem needs a code change.** Detecting Django is one line in `MARKERS`; the
+   engine then hands a Django repo the generic `node` fallback profile, which is wrong advice,
+   and there is nowhere to put the correct profile because `rules/stacks/` is central-only.
+2. **The tag names encode opinions that age badly.** `hono` and `maplibre` are libraries, not
+   stacks. A profile that selects on a library breaks the day the library is swapped.
+3. **Detection is untestable in the abstract.** There is no way to ask "what did the tool
+   actually observe?" other than reading three tables.
+
+There is also an unresolved question from the design review: a **hosted MCP service** would
+make the tool more capable, but it was not clear whether it would make it more *generic*, more
+*accurate*, or merely more available.
+
+## Ruling
+
+### 1. Detection emits facts; profiles select on facts
+
+`fingerprint()` gains a second, orthogonal output: **`facts`** — observable, ecosystem-neutral
+properties of the working tree, named `has-*` (`has-pyproject`, `has-go-mod`,
+`has-cargo-toml`, `has-migrations-dir`, `has-dockerfile`, …). Facts are derived from evidence,
+never from a product taxonomy, so there is no table to grow when a new ecosystem arrives: the
+fact was already being observed.
+
+The existing product tags remain, because a profile that genuinely wants "this is a Cloudflare
+Worker" should say so in words that mean something to a reader. But a profile may now select
+on **either**, and new profiles are expected to prefer facts where a fact will do:
+
+- `applies: [has-cargo-toml]` — honest, survives the framework being replaced
+- `applies: [cloudflare-workers]` — precise, dies with the platform
+
+Selection is the union of both sets. A profile therefore needs **no engine change** to be
+usable by an ecosystem nobody has heard of.
+
+### 2. Profiles are content, and content may live in the repo
+
+`simt-dev init` prints where local profiles live and the manifest gains a `profiles` array
+naming profile ids. The directory needs no creation — the first file in it creates it, and
+an empty directory would not survive git anyway. Central profiles ship in `rules/stacks/`; **repo-local profiles are read from
+`.simt-dev/profiles/*.md`**, use the same frontmatter contract (ADR-009), and are selected
+with the same matcher. A local profile may declare `fallback: true`.
+
+A repo that ships its own profile has made a decision about its own conventions. It does not
+need a central contribution, a release, or a maintainer's permission — and when it is wrong,
+the fix is a one-file PR in the repo that is wrong, which is the correct blast radius
+(ADR-002).
+
+Local profiles are **additive and shadowing**: a local `id` replaces a central one with the
+same id, and otherwise both are considered. Central content is never silently overridden in
+place — it is superseded by an explicit, reviewable file.
+
+### 3. A hosted service may serve authoring; it may never serve resolution
+
+These are different products and must not be conflated.
+
+| | Authoring | Resolution |
+|---|---|---|
+| Hosted MCP is useful | yes — discovering profiles, learning an ecosystem, publishing findings | **no** |
+| Non-determinism | tolerable: a human reviews the output | fatal: "did the agent follow the rules?" becomes unanswerable |
+| Offline | irrelevant | required: a hook and a gate must not depend on a network call |
+| Diffable in a PR | partially | required: `simt-dev check` output is the gate's whole product |
+| Fails | loudly, at authoring time | must fail **closed** with a remedy |
+
+A hosted resolver would make every gate in the estate depend on a network round trip and a
+model's ranking, and would make CI results unreproducible. That is a worse tool, not a more
+capable one.
+
+**Community extensibility therefore ships as a registry of portable profile files** in a git
+repository, fetched and pinned by the same single-SHA mechanism (ruling 4) that already pins
+rules. Same trust model, no hosted runtime, and the diff a reviewer sees is the diff of a
+profile file.
+
+## Consequences
+
+- `fingerprint()` returns `{stack, facts, evidence, manifest, error}`. `evidence` gains the
+  file that proved each fact, so `simt-dev doctor` can answer "why did you think that?" without a
+  human re-deriving it.
+- Every tag a profile may name is still emitted by the engine. The existing test — *tags used
+  by content but not emitted by the engine is the empty set* — now covers facts too, and the
+  registry validator and the profile loader share one derived vocabulary so they cannot
+  desynchronise.
+- `graph lint` validates against the same derived vocabulary, so a profile naming a fact the
+  engine cannot emit fails at lint time rather than selecting nothing at runtime.
+- Step 11 of the implementation sequence is genericity; it lands **before** `compare`, because
+  it changes the tag vocabulary and every later step is cheaper once it is settled.
+
+## Rejected
+
+- **A larger hardcoded tag table.** Moves the wall, does not remove it. Every new ecosystem
+  would still need a maintainer, a code change and a release, and the names would still encode
+  today's libraries rather than the repo's actual properties.
+- **Community profiles in a hosted registry served at runtime.** See the table above.
+- **Semantic or embedding search as the mechanism for choosing rules.** Already rejected in
+  plan 0002 §3, and this ruling reinforces it: it is a resolution mechanism, so it inherits
+  every constraint in row two of the table above.
+- **Fingerprinting on library names alone.** Precise today, and silently wrong the day a
+  dependency is replaced.

simt_dev/vendored/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.

simt_dev/vendored/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 `repo-14`** has the `repo-14` body of `slice-commit` on disk at
+`.agents/skills/slice-commit`. They have no workspace. The registry entry
+`repo-14/.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.

simt_dev/vendored/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** (`repo-14/.cursor/rules/intake-questions.mdc`
+at 1280 against `repo-11`'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**.
+   `repo-14` blocks a consumer that requires an API field with no backward-compatibility
+   or deploy-order evidence; `repo-11` 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: `repo-14`
+   says set `SOCIAL_API_BASE_URL` in the Cloudflare Workers Builds preview environment;
+   `repo-11` says credentials live in the operator keychain only, never in source,
+   chat, D1 or logs.
+3. Two deletions left no trace. `repo-11` dropped `repo-14`'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. `repo-13` 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 `repo-13` (no plan-tracker note) and `repo-15` (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 `repo-15` and `repo-08` — 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
+`repo-11` — 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 `repo-07`'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.** `repo-14`'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.