simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-032-provenance-is-a-content-digest-not-a-commit.md

@@ -0,0 +1,141 @@
+# ADR-032 — provenance is a digest of the content that leaves this package, not a commit id
+
+Status: accepted · 2026-10-08 · ruling 1 narrowed by ADR-054
+**Affects:** `src/projection/rules.mjs`, `src/projection/markers.mjs`, `test/upgrade.test.mjs`,
+`test/install.test.mjs`, `test/project.test.mjs`. **Implements:** proposal P1 in
+`docs/reviews/0002-full-review-adoption-and-public-release.md` §10. **Relates to:**
+ADR-031 (a test that inherits the author's directory is not evidence) — the same defect found
+one layer down, in the tool rather than the suite — and ADR-015 (a source is content, not a
+location), which already argued that a declared skill's identity is its bytes.
+
+## Context
+
+Two tests in `test/upgrade.test.mjs` failed in any copy of this repository that had no `.git`:
+a `git archive` export, a tarball, and — the case that matters — the published npm package.
+
+The proximate cause was `headSha()`, which ran `git rev-parse --short=7 HEAD` in the package
+root and returned the string `unknown` when git could not answer. That fallback was only the
+second of two ways the stamp was wrong, and the quieter one.
+
+**The first way: the stamp recorded the reader's own repository.** `git rev-parse` run inside
+`node_modules/` walks *up* until it finds a `.git`, so for anyone who installed this package
+into a repository — the entire audience for it — the tool stamped the consumer's HEAD. Not a
+near miss: the correct-looking answer to the wrong question. A consumer's HEAD changes on
+every commit they make, including commits that touch nothing this tool projects, so:
+
+- the stamp changed under a region that had not changed, and `check` reported `DRIFT` on all
+  three generated files plus `STALE-GENERATED-FIELD` on the manifest — **after an unrelated
+  commit**, and **exit 1**. A gate that is red on every commit trains people to ignore it,
+  which is the failure mode this tool exists to prevent;
+- `upgrade` reported `state behind`, `pin f9036cd -> f3014d5`, and the cause it named —
+  *"pin moved and region restamped (the rules changed)"* — was false. A pin that moves because
+  the consumer typed a commit message has not detected anything about the rules;
+- no fallback could ever have caught this, because git succeeded and returned a plausible sha.
+
+Review 0002 recorded this as probe #2 and slice S01 and it was correctly read there as
+"provenance stamp comes from the consumer's git, not simt-dev". It reproduced exactly.
+
+**The second way: where git could not answer, `unknown` was treated as a value.** The old
+comment defended the fallback — "a region stamped with an honest `unknown` is visibly
+unverified while one stamped with a wrong answer is not" — and the defence is sound in
+isolation. It is defeated by the fact that `unknown` was then compared and written like any
+other string:
+
+- `files` in `package.json` does not list `.git`, and npm never packs one. **`npm pack`
+  produces 98 entries and no `.git`**, so a tarball or a copy extracted outside a repository
+  got `unknown`.
+- The marker grammar reads `simt-dev:sha=([0-9a-f]{7,40})`. `unknown` does not match, so
+  `parse()` returned `sha: undefined` for a region the tool had just written. **The tool could
+  not read back its own stamp**, and `check` reported `recordedSha: null` for a file that
+  plainly carried one.
+- `planUpgrade` computed `pinBehind = base.pinnedSha !== sha`. With `sha === 'unknown'` this
+  is true for every real pin, so `upgrade` called a repo pinned at `2614462` `behind`, again
+  naming the false cause above. `upgrade --yes` then wrote `unknown` into both the region's
+  stamp and the manifest pin, and the original pin was unrecoverable.
+
+So the identity was never the identity of this tool. It was either the reader's repository or
+a sentinel the tool could not parse — and the review's probe found the first while the test
+suite, written by someone reading a checkout, could not see it.
+
+## Ruling
+
+**Provenance is a SHA-256 digest of the content that leaves this package, truncated to 40 hex
+characters. It is not a commit id, and there is no fallback.** (Which content, precisely, was
+narrowed after this record was written — see ADR-054.)
+
+Three consequences, each of which is the point:
+
+1. **The identity exists wherever the content does, and depends on nothing outside the
+   package.** `rules/` and `graph/` are in the published tarball, so the digest is computable
+   from a checkout, a tarball and an `npm install` alike — one value, no environment to be in.
+   This also ends the walk-up: with no `git` invoked at all, there is no ancestor repository
+   for the stamp to be borrowed from, so a consumer's own commits can no longer move a pin.
+   Verified by the review's own probe, against a package installed inside a repo that then
+   commits an unrelated file: before, `check` reported `DRIFT` on three files plus
+   `STALE-GENERATED-FIELD` and exited 1; after, three `CURRENT` lines and exit 0.
+2. **A stamp the tool cannot read is a defect, not a degraded mode.** `compose()` now throws
+   unless `sha` matches `[0-9a-f]{7,40}`. The write and the read share one grammar by
+   construction, so the failure this record describes cannot be reintroduced by adding a
+   fallback.
+3. **`unknown` is gone, not guarded.** There is no sentinel to compare against, so the
+   comparison that destroyed the pin has nothing to misread. A repo stamped by a version of
+   simt-dev older than this record still carries `unknown`, or a consumer commit's sha, and
+   `upgrade` now repairs it to the digest — the same path as any other stale pin.
+
+### What the digest covers, and what it deliberately excludes
+
+> **Superseded by ADR-054.** The exclusion below is drawn around a *directory*, and the
+> shared `.editorconfig` and `.gitattributes` bodies are not in one — they are constants in
+> `src/`, and they are content every adopting repository receives. `src/` as a path is still
+> excluded; the exclusion is now a rule about content rather than about a location.
+
+`rules/` and `graph/` are the bytes whose change moves a consumer's projection: the shared
+rules, the per-ecosystem profiles, the Cursor rule files, and the skill registry. `src/` is
+excluded deliberately. A refactor that changes no rule and no registry entry produces
+byte-identical regions; stamping those consumers would report drift where there is none, and
+the estate's own rule is that a report must be a fact.
+
+This is the same reasoning as ADR-015: a skill is identified by its bytes, so a projection is
+identified by the bytes it projects.
+
+Entries are hashed in sorted path order, each framed as `path:length:` before its bytes. The
+ordering makes the value independent of `readdir` order — determinism is a feature of this
+tool, not a limitation. The framing means two different renames cannot collide into one
+digest, which is why this is not a hash of concatenated text.
+
+## Consequences
+
+- **Every adopted repo's stamp moves once.** A consumer stamped at a commit sha will report
+  `behind` the first time it runs this version, and `simt-dev upgrade` fixes it. That is the
+  intended reading of a pin, not a regression.
+- **The two `.git`-less test failures are fixed at the source for one of them.** The stale
+  `.mdc` test failed only because it could not find a sha to rewind; it now passes. The other
+  (`upgrade --root` at the package root) is a *test* defect and is fixed as one — see below.
+- **`test/upgrade.test.mjs` no longer asserts a property of the author's checkout.** It had
+  asserted `summary.repos === 1`, which is only reachable when this checkout happens to be a
+  git repo. A `.git`-less package root is a directory holding no repositories, which
+  `discover` correctly refuses with exit 3 and a remedy. Both answers are right, so the
+  invariant is now stated directly: simt-dev is not a consumer of itself, so no
+  `simt-dev.json` appears. Both halves are non-vacuous — planting a manifest fails the first,
+  and forcing the no-manifest case to write one fails the second.
+- **S01 is discharged.** Its proposal is P1; this record implements it, so the slice can move
+  to Complete against this SHA rather than waiting on a second implementation of the same idea.
+
+## Rejected
+
+- **Guard the sentinel instead of removing it.** Treat `unknown` as non-comparable: refuse to
+  move a pin to or from it, and say so. Smaller diff, and it leaves the tool writing a stamp
+  its own parser rejects for every npm consumer. It fixes the data loss and not the lie, and
+  it does nothing at all about the walk-up, which was never a sentinel — git succeeded.
+- **Resolve the repository explicitly** — pass `--git-dir`, or run `git rev-parse` with
+  `GIT_CEILING_DIRECTORIES`, so the stamp names this package and never an ancestor. This is
+  the smallest change that fixes the walk-up, and it is still wrong: in a tarball there is no
+  repository to name, so it restores the `unknown` fallback and with it the pin destruction.
+  It also keeps the identity meaning "which commit of simt-dev", which is a fact about a
+  history a consumer does not have and cannot verify. The ruling is that the stamp answers
+  *what content produced these bytes*, not *which commit was checked out at the time*.
+- **Stamp the package version.** `version` is present in the tarball. But it is `0.0.0` here
+  and rises only at release, so it cannot distinguish two working trees that project
+  differently — which is the case `check` and `upgrade` exist for.
+- **Hash the whole package.** Includes `src/`, with the consequence above, and hashes files
+  the consumer never receives.

simt_dev/vendored/docs/decisions/ADR-033-three-plan-rows-closed-by-decision-not-by-authoring.md

@@ -0,0 +1,82 @@
+# ADR-033 — three plan rows closed by decision, not by authoring
+
+Status: accepted · 2026-10-08
+**Affects:** `docs/plans/0001-centralise-agent-rules.md` §3.1 row 3, §6 phase 6, §6 phase 7.
+Ships no rule text. **Refuses:** the seven agent policies row 3 asks for, the twin collapse
+phase 6 asks for, and untracking the two committed `local.properties` files phase 7 does not
+mention but whose existence made the sweep look unfinished.
+
+## Context
+
+Closing plan 0001 meant auditing each row against the tree rather than against the plan's own
+prose, because the plan was written on 2026-10-05 and three things changed underneath it. This
+record is the audit's residue: three items that read as unfinished work and are not.
+
+Row 3 asked for eight agent policies as separate files. Seven were never authored. A search for
+their source material across every tracked `*.md` and `*.mdc` in the estate returns two files,
+neither of which is a policy: they are a progress ledger and a completed UX plan that happen to
+contain the phrases. The three most specific of the eight — the 70/30 quality-versus-performance
+split, the 12-state coverage list, the matrix-trigger heuristic — have no source anywhere. Writing
+them would mean inventing doctrine this estate never agreed to, into `rules/core.md`, from where
+every adopted repo would inherit it.
+
+Phase 6 asked to "collapse the 7 drifted Social skill twins to canonical + stub". The registry's
+`sources.role` mechanism landed the same evening, two hours after the plan was authored, and
+answers the row directly. All three resolvers select `role === 'canonical'` and nothing else —
+`src/commands/skills.mjs` twice, `src/commands/skillsinstall.mjs:291`, `src/mcp/tools.mjs:192` — so
+a copy declared `duplicate` or `variant` is never installed. The one pair that genuinely had to be
+collapsed, `add-country-galaxy`, is already a stub in `repo-14` pointing at the API repo.
+
+Phase 7 asked for a sweep of hardcoded absolute paths. The sweep found 17 tracked files. Six were
+fixed. The two Android `local.properties` files were not, and were nearly fixed by reflex.
+
+## Rulings
+
+1. **A row is closed by ruling on it when the thing it asks for was never a decision anyone made.**
+   Row 3's eight policies are closed: the four claims `rules/core.md` already carries — the
+   minimum viable team, never weakening a security control, anti-overclaim, and a stated agent
+   budget that never converts a failure into an approval — are the doctrine, and they ship. The
+   other four, including the 70/30 split, the 12-state list and the matrix-trigger heuristic, are
+   recorded here as unmade. If one is wanted it needs someone who held the original
+   conversation, not someone reconstructing it from a table cell.
+
+2. **A mechanism that supersedes a row retires the row, and the deletion is the wrong move.** The
+   `sources.role` vocabulary already distinguishes `canonical`, `duplicate`, `variant`, `stub` and
+   `deprecated`, and `graph lint` passes with all of them in use. Deleting a `duplicate` copy would
+   remove a version-pinned tool from a repo that can still run it, and nothing would detect the loss
+   because resolution never read those bytes. Phase 6's twin collapse is therefore closed as
+   already answered, at `a9983c8`.
+
+3. **`local.properties` stays tracked.** Both `repo-05` and `repo-03` commit it, and both
+   `.gitignore` files have the conventional `# local.properties` line commented out at lines 22 and
+   24 — a deliberate override of Android's own convention, not an oversight. Untracking them would
+   be a house-style change made while closing a plan, and a build machine that checks out without
+   an SDK would stop building. It stays, and plan 0001 says so, so the next sweep does not
+   rediscover it as a defect.
+
+## Consequences
+
+Row 3 reads "done, four of eight" rather than "partial". Phase 6's twin item reads "superseded"
+rather than "outstanding". The estate keeps two `local.properties` files whose `sdk.dir` names a
+developer's home directory, by decision.
+
+The registry's byte counts moved with the two skill bodies corrected in the same pass, because a
+declared source's identity is its size (ADR-015): `cloudflare` 384277 → 384869 and
+`production-quality-review` 5869 → 5904. That changed the provenance digest (ADR-032), so all
+fourteen adopted repos were re-stamped afterwards rather than left pinning a value this tool can no
+longer produce.
+
+## Rejected
+
+**Authoring the seven agent policies.** The plan's one-line summaries are not enough to write seven
+files of rule text, and these rules reach every adopted repo. This is ADR-030's exact shape: an
+unmade decision is not a gap to fill by invention.
+
+**Collapsing `graphify` and `parallel-feature-team`.** Both are declared `duplicate` with matching
+byte counts, so they look like the obvious candidates. `graphify` is `vendored: true` — an
+84 534-byte, ten-file, version-pinned tool present in both one repository on purpose. Deleting
+repo-14's copy would leave nothing to detect the loss, because resolution only ever read the
+canonical copy.
+
+**Untracking `local.properties`.** An Android SDK path is machine state, and two repos chose to
+share it. That is the repo's call to reverse, not a plan's defect sweep.

simt_dev/vendored/docs/decisions/ADR-034-a-staged-tool-refuses-a-partially-staged-file.md

@@ -0,0 +1,91 @@
+# ADR-034 — A staged tool refuses a partially staged file rather than staging around it
+
+Status: **accepted** · 2026-10-08 · affects every repo with a `pre-commit` hook
+
+## Context
+
+`src/hooks/gates.mjs` defines a `staged` gate as one that "run[s] a formatter over the STAGED
+FILES ONLY, then re-stage[s] them", and gives the reason: whole-repo formatting from a
+pre-commit hook "would rewrite unstaged work the author did not ask to touch". (The rule
+that hooks own format and lint for staged files is ADR-004; this record settles what the
+dispatcher does when "staged files" is ambiguous, which ADR-004 does not say.)
+
+The dispatcher did not implement that promise. After a passing `format` gate it ran
+`git add` on **every** path from `git diff --cached --name-only`, and reported success
+whenever anything was staged.
+
+Two defects, both measured against the shipped dispatcher rather than reasoned about:
+
+- **A partial stage was destroyed outright.** With `a.md` staged as `one\nSTAGED\n` and the
+  working tree at `one\nSTAGED\nUNSTAGED-WORK\n`, a formatter that rewrites its inputs left
+  **both** the index and the working tree as `FORMATTED`. The author's unstaged hunk was not
+  merely committed — it was replaced. This is the promise above, broken on the one path that
+  runs on every commit in every adopted repo, and it is silent.
+- **A staged deletion silently skipped the restage.** `--name-only` with no `--diff-filter`
+  lists deleted paths, `git add -- <deleted>` fails, and the `catch` returned `false`. A
+  commit containing a deletion plus a formattable file recorded the **unformatted** bytes and
+  printed no restage line at all.
+
+A third, smaller one: restage reported "re-staged files the formatter rewrote" whenever
+anything was staged, whether or not a byte moved.
+
+## Ruling
+
+**1. A staged gate refuses to run when a file it would format also has unstaged changes.**
+It fails the commit and names the file. It does not stash, and it does not format anyway.
+
+The author staged part of a file deliberately; `git add -p` is how you say "this commit is
+part of that file". A hook cannot know which part, so any answer it picks is a guess about
+someone's intent, and a guess that rewrites their working tree is the one they cannot see
+coming. Failing closed with a remedy the author can act on — `stage the whole file`, or run
+the formatter yourself and stage the result — costs one command. Guessing costs work.
+
+**2. Restage covers the files the formatter was actually given, and only those.** The
+resolved staged tool's `argv` already holds the paths; nothing needed re-deriving them from
+the index. For a gate declared through `gates.commands`, the command line is arbitrary and may
+take a directory or a glob rather than paths, so ruling 1 applies to **every** staged file with
+unstaged changes, because there is no way to know which files it will open. That is the
+conservative reading, and being wrong in that direction fails a commit the author can retry.
+
+**3. Restage reports a file only when that file's staged bytes actually moved**, compared as
+the blob hash before and after. A restage line that fires on every commit is a line nobody
+reads; the ones that fire are the ones that will be read.
+
+A path staged as **deleted** is not a partial stage. The index and the working tree agree it
+is gone, so there is no unstaged work to protect and nothing to refuse.
+
+## Consequences
+
+- `restage` returns the files it staged rather than a boolean, and a failed `git add` is now
+  reported as a `restage` **failure** with a remedy. It was previously swallowed by a `catch`
+  that returned `false`, which is what made defect 2 invisible.
+- `resolveGate` now returns `declared: true` for a `gates.commands` resolution. The dispatcher
+  needed to distinguish argv it chose from words it was handed, and sniffing the `detail`
+  string would have let the guard in ruling 2 quietly stop working the day that wording
+  changed.
+- Repos whose authors habitually commit partially staged files will now see the gate refuse
+  once, with a remedy naming the file, and not again. That is the intended cost: it is
+  visible, and it is a command they choose to run.
+- `rules/core.md` inherits nothing new — this changes when a hook runs, not what an agent is
+  told to do — so the provenance digest is unaffected and no repo needs re-stamping.
+
+## Rejected
+
+- **Stash the unstaged changes, format, restore.** The review offered this as an alternative.
+  It is a hook making the same guess by a longer route: it assumes the stash will apply
+  cleanly after a formatter has rewritten the file underneath it, and a conflict there
+  leaves the author with a stash and no working copy.
+- **Format the staged content rather than the working tree** (e.g. piping `git show :file`
+  through the formatter and updating the index). Correct in principle, and it does not destroy
+  unstaged work — but it leaves the index holding a file the working tree no longer matches,
+  so the next commit sees a phantom edit. Worth revisiting only with a real consumer of the
+  format, which no repo in this estate has.
+- **Skip the restage for deleted paths.** Treating a deletion as a restage failure would make
+  the common case of a renamed-or-deleted file block every commit that also formats.
+- **Keep the boolean return and just filter the file list.** That leaves defect 2's swallowed
+  `catch` in place: the command would silently record unformatted bytes again the next time
+  any `git add` fails.
+
+Review 0001 §`S08` attributes the "would rewrite unstaged work" promise to ADR-004. It is in
+`src/hooks/gates.mjs:7`, the gate definition; ADR-004 settles who runs what, not what the
+dispatcher does with an ambiguous index.

simt_dev/vendored/docs/decisions/ADR-035-one-write-decision-and-one-json-document.md

@@ -0,0 +1,119 @@
+# ADR-035 — One place decides whether a run may write, and one document says whether it did
+
+Status: **accepted** · 2026-10-08 · affects every command that writes or reports
+
+## Context
+
+Review 0001's S10 tabulated eight inconsistencies in the `--yes` / `--dry-run` / `--json`
+contract across six commands. Each was measured against the shipped binary before anything
+was changed, and the table did not survive intact: **six were real, one was partly wrong, one
+was inverted, and one defect the table missed turned up during the fix.**
+
+The six, all reproduced:
+
+- `upgrade --yes --dry-run` **wrote**. `upgrade.mjs` tested `flags.yes === true` and never
+  consulted `flags.dryRun`, so the one flag that says "do not write" was not read on the one
+  path that moves pins across every adopted repo.
+- `skills install --yes --json` **never wrote**. An early `if (isJson(flags)) { emit(plan);
+  return }` returned before the write — the exact combination a script uses.
+- `skills install --yes` printed `note dry-run nothing written` and *then* wrote, because the
+  note was emitted unconditionally.
+- `skills install` read **neither** write flag. `grep -rn "dryRun"` over the file returned
+  nothing.
+- `doctor --json` exited **0** where the same command in a terminal exited **3** on an
+  unparseable workspace config, and omitted the workspace answer entirely: its `isJson`
+  branch returned *before* the `ws.error` check with `ok` hardcoded `true`.
+- `hooks status --json` wrote `ok: true` and exited **0** while text mode exited **1** with
+  four problems listed.
+
+The one the table got backwards: it claimed `sync` and `init` emit JSON errors while `hooks`,
+`skills` and `rules` emit only stderr text. Forcing genuine error paths showed `sync --json`
+emits a JSON error correctly. The actual error-path lie was the `doctor` row above.
+
+`init --json` looked like the same defect and is not one. `grep -rn "resolveWorkspace"
+src/commands/` shows `init` never consults the workspace at all, and both modes agree — exit
+`0`, `ok: true`, and no workspace line in text either. Two modes answering one question two
+different ways is the defect; when neither asks the question there is nothing to disagree
+about. Making `init` fail on a corrupt workspace config would be a new decision, not this one.
+
+## Ruling
+
+**1. Whether a run may write is decided in exactly one function.**
+`writeMode(flags)` in `src/output/index.mjs` returns `{ dryRun, apply }` with
+`apply = flags.yes === true && !dryRun`, and every mutating command reads it. A command that
+consults `flags.yes` directly is a defect whether or not its arithmetic happens to agree
+today, because the third copy is the one that will not.
+
+**2. `dryRun` is reported separately from `apply`.** A run that was not authorised is a dry
+run in effect even when nobody asked for one, and the JSON payload's `dryRun` says so.
+
+**3. Under `--json`, stdout is exactly one JSON document, and its `ok` agrees with the exit
+code.** A caller reads `ok`; a shell reads the exit code. If they disagree, one is a lie and
+the caller cannot tell which, so the invariant is checked across the whole command surface
+rather than per command.
+
+**4. A non-zero exit under `--json` carries `error` and `remedy` in that same document.**
+`ok: false` alone says it failed without saying what to do, and ADR-010 requires the remedy.
+`doctor --json` also carries `workspace`, because the text path prints the workspace answer
+and a JSON document that omits it answers a different question than the terminal does
+(ADR-014).
+
+**5. A caveat is a field, not prose on stdout.** `skills brief` with no task and no staged
+files warns rather than silently answering; under `--json` that warning is a `warning` field
+in the one document, and `--all` carries it too. `ok` stays `true` — the command did what was
+asked, and it is the *answer* that is weak.
+
+**6. Every command that reports honours `--json`, including the ones the review did not
+name.** `skills why` built its output as lines and had no `isJson` branch at all, so
+`skills why <skill> --json` printed prose. Its `gate` is a field rather than a sentence
+because a skill that can never be selected in this repo is a decision, not a line of output.
+
+## Consequences
+
+`test/contract.test.mjs` is a new file because neither contract belongs to one command: a
+test that runs `doctor` and a test that runs `skills install` would each assert their own
+command and miss the other. It drives the shipped binary rather than calling functions,
+because a flag the dispatcher never routes is invisible to a direct unit test — which is how
+`--dry-run` reached `skills install` unreached while every unit test passed. Nineteen
+commands are asserted to emit one parseable document whose `ok` matches the exit code; two
+mutating commands are asserted to leave the filesystem byte-identical without `--yes` and
+under `--dry-run`; and one test asserts an authorised, non-rehearsal run **does** write, so
+"refuse everything" cannot pass.
+
+Two of those tests were themselves broken when first written, and both were found only
+because a mutation failed to fail them. One watched a path that nothing writes to, and in
+doing so **self-adopted simt-dev**: `skills install` reads `flags.root ?? process.cwd()`, the
+row passed the fixture root positionally to a subcommand that takes no positional, and the
+install landed in this checkout, leaving an untracked `.agents/` and `simt-dev.json`. The
+other asserted a fixture was a clean repo when it was not — `init` writes `simt-dev.json`
+without staging it, so `dirtyPaths` was never empty and the no-input branch was never
+reached. Both are the shape of harm ADR-031 exists to prevent, arrived at from the other
+direction. The fixture now commits what `init` wrote and asserts the tree is clean, passes
+`--root` to every command, and asserts the root is under the temp directory.
+
+Six mutations were applied and reverted, each caught by its own test: `upgrade` and
+`skills install` back to reading `flags.yes` alone, `hooks` and `doctor` back to a hardcoded
+`ok: true`, and the `isJson` guard removed from the `skills brief` no-input branch and from
+`skills why`. The `sync --yes` requirement is **not** part of this record; it is review 0002's
+S24 and stays queued, because `sync` already honours `--dry-run` and what it lacks is the
+authorisation gate, which is a separate decision.
+
+## Rejected
+
+- **Make `sync` require `--yes` as part of this record.** It is a real inconsistency and it is
+  someone else's slice. S24 names S10 as its dependency, which is what makes S10 the
+  prerequisite rather than half of it.
+- **Keep a per-command `ok` field and rely on reviewers to notice disagreements.** The
+  disagreement is the defect. It has to be checked where it is introduced, which is a table
+  over the surface, not a discipline applied to each command in turn.
+- **Add an `--json` mode to `skills why` by routing it through the text renderer and parsing
+  the result back.** Printing prose and parsing it is how the no-input path went wrong: the
+  warning was in the output shape and the document was nowhere.
+- **Treat a missing `workspace` in `doctor --json` as cosmetic.** The text path prints the
+  workspace answer; a JSON document that omits it is a second, quieter answer to the same
+  question, and the caller has no way to know one of them is missing.
+- **Record the review's table as the defect list.** Two of its eight rows did not survive
+  measurement — one was backwards and one was not reproducible — and one real defect
+  (`skills why --json`) was absent from it. A table of claimed defects is not a list of the
+  actual ones, and writing one down as if it were is how the `skills why` gap survived.
+</content>

simt_dev/vendored/docs/decisions/ADR-036-a-writer-that-writes-says-so-and-the-instructions-naming-it-move-with-it.md

@@ -0,0 +1,103 @@
+# ADR-036 — A command that writes says so, and every instruction that names it moves with it
+
+Status: **accepted** · 2026-10-08 · affects `sync`, every remedy naming it, and the
+generated-region note shipped into every consumer repository
+
+## Context
+
+ADR-035 gave the command surface one write decision — `writeMode(flags)` — and
+deliberately left `sync` alone, recording the omission twice: in its consequences ("it is
+review 0002's S24 and stays queued") and in its rejected list ("it is a real inconsistency
+and it is someone else's slice"). The reasoning was sound then. S24 depends on S10, so
+making the gate part of S10 would have made the prerequisite half of the change it
+prerequisite'd.
+
+Measured against the shipped binary, `sync` was the last writer writing by default. A
+fixture repository was adopted with `--yes`, a stray line was then inserted inside its
+generated region, and a bare `simt-dev sync` **rewrote the file**: the stray line was gone
+and the file was 14 bytes shorter. It reported success, because it had done what it was
+built to do. Among the six writers in the surface, the other five preview unless told
+otherwise, so this was also the only command where an agent that had learned the
+interface would pattern-match onto the wrong behaviour — the preview was opt-in by command
+line and opt-out by habit.
+
+The second finding was less comfortable. Twenty-six places in `src/` name `simt-dev sync`
+in a remedy, and two of them are not printed to a terminal at all: the note inside every
+generated region, which ships into every consumer's `AGENTS.md`, and the `$comment` in
+every consumer's manifest. Both instruct the reader to run the command that regenerates the
+text they are looking at. Changing the write gate without changing them would have shipped
+an instruction that is no longer true — and it would have shipped it *to the repository
+being written*, which is precisely the reader with no other context. A gate that only
+protects the tool from itself is not a gate on what the tool says.
+
+## Ruling
+
+**1. `sync` decides whether to write through `writeMode(flags)`, like every other writer.**
+Not its own condition, and not a check of `--check` and `--dry-run` read separately. ADR-035
+already ruled that a second copy of the decision is a defect whether or not its arithmetic
+agrees today; this is the copy.
+
+**2. A bare `sync` is a check that prints the plan, and a check that finds drift exits
+non-zero.** It exits 0 only when nothing would change, which is what lets a caller run
+`sync` in place of `sync --check` and get the same verdict. The preview names the command
+that applies it. Exiting 0 after reporting a change would be the one-question-two-answers
+shape ADR-035 exists to prevent, reached from the opposite direction.
+
+**3. `--json` agrees with the exit code, as it must.** `ok` is `false` on a previewing run
+that found work, `written` is `0`, and `dryRun` is `true`. `written` used to be a boolean
+and is now a count, because a preview that says "nothing written" in a field typed as a
+flag cannot distinguish "no changes" from "changes withheld".
+
+**4. Every string that names the command moves with the behaviour, including the ones that
+ship.** The region note, the manifest comment, all 26 remedies, and the help synopsis.
+This is the part that is easy to skip and expensive to miss: the two shipped strings are
+compared by `upgrade` and written into files the reader owns, so a change to the gate with
+no change to them leaves a permanently-false instruction in every repository in the estate.
+
+**5. The test asserts the flag, not the command.** The existing guard read
+`/simt-dev sync/` and passed identically before and after this change — it could not have
+prevented the defect it appeared to cover. It now reads `/simt-dev sync --yes/`, and a new
+test walks `src/` for any occurrence of the bare spelling so the next command to grow an
+authorisation flag cannot inherit twenty-six no-op remedies unnoticed.
+
+## Consequences
+
+The contract table in `test/contract.test.mjs` gains a `sync` row, which is the row that
+would have caught this defect: every writer is asserted to leave the filesystem
+byte-identical without `--yes`. `sync` needs stale region bytes rather than a stale pin,
+because what it writes is the region and the pin was already current — a fixture that
+staled the wrong file would have passed a `sync` that wrote nothing for the wrong reason,
+which is the shape ADR-031 rules out. For `sync` alone the unauthorised case also asserts a
+non-zero exit, because the byte comparison alone passes on a preview that returned success.
+
+Three mutations were applied and reverted, each caught by its own test: the write gate back
+to reading `--check` and `--dry-run` directly, the preview back to exiting 0 on drift, and
+one remedy back to the bare spelling. The third matters most — it is what proves the
+remedy test sees individual occurrences rather than the template literal around them.
+
+One item in this slice's spec could not be done. It asks for a CHANGELOG entry, and there
+is no CHANGELOG in this repository; the row that would add one is queued as S18 and is
+named as its dependency here rather than created, because inventing the file would settle
+a question S18 has not been closed on.
+
+## Rejected
+
+- **Keep `sync --check` as the only no-write mode and teach the difference in help text.**
+  Two spellings for one behaviour means every caller has to know which one it wants, and
+  the one that writes by default is the one a caller reaches for. Help text is not a gate;
+  it is only evidence that a gate was considered.
+- **Make `sync` preview only when it detects a non-interactive caller.** The tool cannot
+  tell an agent from a terminal, and the argument for the flag is that guessing wrong
+  destroys work — which is not a cost worth paying for a convenience nobody asked for.
+- **Exit 0 on a preview so that existing scripts keep passing.** This preserves callers
+  that were checking whether `sync` *ran*, not whether the repository was *current*. The
+  second is the question every one of them was actually asking, and the answer was `ok:
+  true` while a file was rewritten.
+- **Update only the terminal output and leave the shipped region note and manifest comment
+  alone, since they are documentation.** They are the only copy of the instruction a
+  consumer repository's reader ever sees. Changing them is the whole second half of this
+  slice.
+- **Fold this into ADR-035 by editing its ruling in place.** ADR-035 is accepted and its
+  rejected list names this exact change as someone else's slice. Rewriting the ruling would
+  erase the evidence that the omission was deliberate, and a reader diffing the two
+  records would have no way to tell which writer had been considered.

simt_dev/vendored/docs/decisions/ADR-037-unchanged-means-writing-would-not-change-a-byte.md

@@ -0,0 +1,100 @@
+# ADR-037 — `unchanged` means writing would not change a byte, not that the body matches
+
+Status: **accepted** · 2026-10-08 · affects every generated region, in every file style
+
+## Context
+
+Review 0002's S29 reported that a region appended after a single newline fails
+`prettier --check`, and pointed at `markers.mjs:232`, the `absent` branch. Measured against
+the shipped binary, that branch was already correct: it inserts the blank line, and its
+output passes `prettier --check` unchanged.
+
+The defect was two branches over.
+
+**The seam in `splice` had no blank line.** Every fixture built by putting a region into a
+document that already had one — a paragraph, a heading, a list, a fenced block, a
+blockquote — came back rewritten by Prettier 3.8.1, and `--check` exited 1 on every one.
+The list case is worse than a missing blank line: with no gap, Prettier reads the region as
+a continuation of the last list item and indents all of it, so the repair is not one byte
+but a reindent.
+
+**A body that matched behind a wrong seam was reported `unchanged`.** The comparison was on
+the region body alone, so a file whose body was correct and whose seam was not produced no
+drift. `check` found nothing, `sync` had nothing to rewrite, and the repository stayed red
+on its own formatter with no remedy this tool offers. This is the shape ADR-034 and
+ADR-036 both exist to prevent, and it is why the second half of the fix mattered more than
+the first: without it, the seam fix would have applied only to files whose body happened to
+change, and every already-adopted repository would have kept a seam nothing would repair.
+
+Measured end to end: a repo whose region body is current and whose seam is wrong exits 1 on
+`check`, `sync` rewrites 11,217 → 11,218 bytes, Prettier is then satisfied, and `check`
+exits 0.
+
+## Ruling
+
+**1. `seam(before)` is the one place the separator is decided.** It normalises whatever
+follows hand-written text to a blank line, and returns `''` for an empty document so a new
+file does not open with a blank line. The `absent` branch had a hand-rolled equivalent that
+agreed with it exactly; keeping both would have left the next reader looking at the branch
+that looks wrong and is not.
+
+**2. `unchanged` means writing would not change a byte.** Not that the body matches. The
+question `sync` asks is whether it has anything to write, and a file whose seam disagrees
+has something to write even when its body does not.
+
+**3. Top placement is exempt from the byte comparison, and the reason is recorded.** There,
+`splice` is a repair: it moves a region that sits below the file's own settings back above
+them, which moves bytes outside the markers by design. A misplaced region is reported by
+`check` as `misplaced` with its own remedy, and re-laying-out the file there was correct
+before this change and stays correct. Making the exemption explicit is the point — the
+alternative is to discover the reason by breaking `baselines.test.mjs`.
+
+**4. A repair must settle.** After `sync` rewrites the seam, the next run reports
+`unchanged` byte for byte. A rule that reports drift on a file nobody has touched is a
+defect with the sign flipped, and the test asserts the second run rather than the first.
+
+**5. The assertions are about bytes, not about Prettier.** Prettier cannot be a dependency
+of this package (ADR-012), so the tests state the shape the formatter requires and cite the
+measurement in a comment. Every fixture in the seam table was run through
+`prettier --check` before the assertion was written, and every one failed.
+
+## Consequences
+
+`test/markers.test.mjs` gains two tests. The first walks six shapes of preceding text and
+asserts exactly one blank line — not a run of them, because a formatter collapses those
+and `check` must not manufacture drift out of a file nobody touched. The second covers the
+`unchanged` verdict, which no formatter-shaped assertion could reach.
+
+The second test was itself wrong on its first version and a mutation found it. It built its
+fixture from a hand-written region that lacked the do-not-edit note, so the body genuinely
+differed — meaning it passed with the byte comparison removed, while claiming to police it.
+It now builds the fixture from a real composed region and deletes the blank line, which is
+the file the defect actually produced.
+
+Two mutations were applied and reverted, each caught by its own test: `seam` reduced to a
+single newline, and the byte comparison dropped from the verdict.
+
+The second half of the spec's acceptance — the pack-install test running `format:check` in
+a fixture that has Prettier — belongs to S20 and is not done here. S20 is the row that
+stages a packed install, and a test that needs Prettier cannot live in this package.
+
+## Rejected
+
+- **Fix only the branch the review named.** It is already correct. The finding was measured
+  against the shipped binary before anything changed precisely because a plausible line
+  number is not an observation, and stopping there would have shipped a no-op and closed the
+  row.
+- **Leave `unchanged` comparing the body, and let `check` ignore the seam.** Then the seam
+  fix only helps a repository the first time its rules change, which is the one moment
+  nobody is reading. The other half is the defect.
+- **Have `check` report the seam as its own finding rather than as drift.** A formatter is
+  not a consumer of this tool's verdict; the bytes are simply wrong and `sync` fixes them.
+  A second status for one wrong byte gives the reader two questions to ask about it.
+- **Compare bytes for the `top` style too, and re-lay-out its splice to match.** That is
+  the change that would have broken a misplaced region finding. Re-laying-out a file to
+  match a formatting rule is a move onto somebody else's territory, and the region moving
+  home is the only reason those bytes are the tool's business.
+- **Ship Prettier as a devDependency so the seam table can assert against the real
+  formatter.** ADR-012 rules it, and the rule this record settles is expressible in bytes:
+  which is the same reason the projection emits the formatter's shape rather than calling
+  it.