simt-dev 0.0.0-stage → 0.1.1

package/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 `simt-social` 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 `simt-app` and `wakt-app` 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 Social repos on purpose. Deleting
+simt-social'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.

package/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.

package/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>

package/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.

package/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.

package/docs/decisions/ADR-038-the-gate-filter-belongs-to-every-manifest-writer.md

@@ -0,0 +1,95 @@
+# ADR-038 — The gate filter belongs to every writer of a manifest, not to `init`
+
+Status: **accepted** · 2026-10-08 · amends [ADR-017](ADR-017-a-declared-gate-must-be-runnable.md) ruling 1 · affects every code path that calls `buildManifest`
+
+## Context
+
+ADR-017 ruled that a gate is declared only if the repo can run it, and attributed the
+mechanism to one command: *"`init` filters the stack table's proposals through what the
+repo demonstrably has."* The belief is general. The attribution is what was read, and it
+stayed true only as long as `init` was the sole writer of a manifest.
+
+Review 0002's S27 is what the attribution bought. `recordLocal` in `skills install` writes a
+manifest for a repo that has none, and called `buildManifest` with no capability. Measured
+end to end: a bare Node repo — a `package.json` with no scripts and no `node_modules` — ran
+`skills install api-contract-sync --yes`, and the manifest it was handed declared `format`
+and `lint` on pre-commit and `test` and `typecheck` on pre-push. `check` then reported four
+`UNRUNNABLE` findings and exited 1. After `hooks install`, a real commit ran the pre-commit
+gate, which failed both staged gates with their remedies and blocked. The hook's own exit
+code is not the commit's, so the reader's first evidence is a commit that silently did not
+happen.
+
+Four declared gates the repo cannot run, written by a command whose entire job is to pin
+one skill. ADR-017's own wording names this as the failure: *"declaring one would block
+every commit"*.
+
+The test that should have caught it asserted the opposite of the truth. It checked that
+`gates` was present and that `preCommit` and `prePush` were **non-empty**, and read
+non-empty as correct — so the test about manifests being right passed on a manifest
+declaring four gates nobody could run.
+
+## Ruling
+
+**1. `buildManifest` requires a capability from every caller.** The filtering happens in one
+place, and that place is reached only with the evidence it filters on. A caller that passes
+no `capability` is a caller asking for the defaults, and today it gets them — which is
+correct for a pure function and wrong for a writer. Rather than make the parameter
+mandatory and break the three call sites that legitimately want defaults, the ruling is on
+who writes: **a command that writes a manifest for a repo that has none must probe first**,
+because it is making a promise on that repo's behalf.
+
+**2. A command that writes a manifest declares nothing it cannot prove.** This is ADR-017
+ruling 1 with its attribution removed, and it covers a shape ADR-017 did not anticipate:
+a writer that is not an adoption command. `skills install` is not adopting the repo. It
+pins one file into `.agents/skills/`. Writing a full manifest was already the wrong shape
+for it and was ruled on once already; the record for that ruling said *"a `{localSkills}`
+stub would read as authoritative while omitting `gates`"*, and the fix was to write the full
+canonical shape. The reasoning was right and the conclusion drawn from it was wrong, because
+canonical shape and default gates are different things and only one of them is a fact about
+the file's schema.
+
+**3. A manifest that declares no gates is a valid answer.** A repo with no scripts and no
+formatter gets `preCommit: []` and `prePush: []`. ADR-017's consequences section already
+ruled this — `init` has been writing it — so the only new fact is that a reader of the
+record can now see the invariant is not `init`'s to keep.
+
+**4. The test asserts the manifest is true, not that the field is present.** The new test
+runs `unrunnableGates(manifest, await readCapability(root))` — the function `check` runs,
+with the probe `check` uses — and requires an empty result. It also runs against a fixture
+that *can* run gates and requires them to be there, because a fix that hardcoded two empty
+lists would pass the first half and arm the project with no gates at all.
+
+## Consequences
+
+`test/install.test.mjs`'s existing assertion changed from
+`assert.ok(manifest.gates.preCommit.length > 0 && …)` to
+`assert.deepEqual(manifest.gates, { preCommit: [], prePush: [] })`. That is a test whose
+pass condition was the defect, and it is the fourth in this repository to read presence as
+correctness — the shape ADR-030 exists to catch.
+
+Three mutations were applied and reverted, each caught by its own test: the `capability`
+argument removed; a hand-built empty capability substituted for the probe (caught by the
+capable half, not the bare one); and the capable half's non-empty assertion deleted — which
+the bare half alone did not notice, confirming both halves earn their place.
+
+## Rejected
+
+- **Make `capability` a required argument of `buildManifest`.** Three callers legitimately
+  want the unfiltered defaults, including the tests that exercise `planGates` directly. A
+  signature that cannot be called wrongly is worth having, and the wrong call here is one of
+  two lines in a function whose purpose is obvious from its name; ruling on the caller keeps
+  `buildManifest` a pure function that a test can call with any evidence it likes.
+- **Have `skills install` write a `{localSkills}`-only manifest after all.** That was ruled
+  on and the ruling holds: a partial manifest reads as authoritative while omitting `gates`,
+  and `init` would then have to be run to complete it. Probing is the smaller change.
+- **Let `check` repair it, since `check` already reports the finding.** `check` reports
+  findings; it is not the command a reader runs before `skills install` has already blocked
+  their commits. The landmine has to be defused at the moment it is laid.
+- **Leave ADR-017 as written and put the generalisation only in the code.** The code is
+  where the second writer is, and a record that names `init` is a record a reader trusts to
+  have already covered the case. ADR-017's own context section says nothing else owns the
+  manifest — that was true in 2026-10-06 and this is what made it false.
+- **Amend ADR-017's ruling 1 in place.** ADR-017 is accepted and its context is the evidence
+  for why the gate filter exists at all. Rewriting the sentence would leave no trace that the
+  rule was ever narrower than it reads, which is the same trick the gate list itself was
+  performing on its reader.