simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/docs/decisions/ADR-053-the-node-floor-is-22-20-0.md

@@ -0,0 +1,49 @@
+# ADR-053 — The Node floor is 22.20.0
+
+Status: **accepted** · 2026-10-10
+**Affects:** `package.json`, `src/ci/workflow.mjs`, `src/resolve/resolve.mjs`.
+
+## Context
+
+Node 20 reached end of life on 2026-04-30. `engines.node` still said `>=20`, both workflow
+templates pinned setup-node to `20`, and `matchesGlob` was a hand-written translation because
+`path.matchesGlob` is stable from Node 22.20.0 (and 24.8). ADR-042 recorded that translation
+and said ruling 1 collapses into the built-in when the floor moves. Review 0002 S47 settles
+the floor at `>=22.20.0` and says the own CI runs 22, 24 and 26.
+
+## Ruling
+
+**One.** `engines.node` is `>=22.20.0`. Both workflow templates pin `actions/setup-node` to the
+version that range names, read from `package.json`, so a template cannot name a version the
+package says it does not run on. This repository's own gate also runs Node 24 and Node 26. A
+floor that is only executed at the minimum is a floor in name.
+
+**Two.** `matchesGlob` is `path.matchesGlob`. A trailing double star also matches the directory
+itself: the built-in requires a child, so `migrations` misses `migrations/**`, and that empty
+path is the one `graph lint` builds (ADR-042, ruling 3). A glob containing `?`, `{` or `[`
+matches nothing, so ruling 4 still holds. Ruling 1 of ADR-042 is superseded by this record.
+Rulings 2, 3 and 4 of ADR-042 stand.
+
+**Three.** The runtime line is the same sentence in `package.json`, both templates, this
+record, plan 0002's live Runtime line, and `README.md`. The README states the floor and
+nothing else; the packaging README is S18 and does not get to pick a different floor.
+
+## Rejected
+
+**Waiting for S18's README before raising the floor.** The floor is what CI and the matcher
+run on. A missing README was not a reason to keep declaring a runtime that is end of life.
+
+**Pinning both templates at Node 24 in this record.** S48 owns "templates use 24", the SHA
+pins, and the macOS matrix. This record's adopting template uses the floor so it agrees with
+`engines`. The own gate's extra versions are coverage, not a second floor.
+
+**Letting `path.matchesGlob` implement `?` and braces.** It does, and that is how `src/a?.ts`
+matches `src/aq.ts`. ADR-042 ruling 4 refused that reading because the registry does not use
+it and a glob that matches the wrong paths is worse than a glob lint rejects.
+
+## Consequences
+
+- `compileGlob` is gone. The cases ADR-042's tests lock (`**/*.ts`, a star that does not cross
+  `/`, a bare `**`) are now the built-in's, and the `?` case still fails lint.
+- SHA-pinning `actions/checkout` and `actions/setup-node`, and the macOS runner, stay with S48.
+- The adopting workflow's install step stays with S35.

simt_dev/vendored/docs/decisions/ADR-054-the-digest-covers-every-byte-that-leaves-the-package.md

@@ -0,0 +1,100 @@
+# ADR-054 — The digest covers every byte that leaves the package, and a cause is read off the body
+
+Status: **accepted** · 2026-10-10 · amends [ADR-032](ADR-032-provenance-is-a-content-digest-not-a-commit.md)
+**Affects:** `src/projection/rules.mjs`, `src/upgrade/plan.mjs`.
+
+## Context
+
+ADR-032 made the stamp a SHA-256 digest of `rules/` and `graph/`, and said why `src/` is
+excluded: a refactor that changes no rule and no registry entry projects byte-identical
+output, and stamping those consumers would report drift where there is none.
+
+That reasoning is right and the boundary was drawn one level too low. ADR-032 excluded a
+*directory*; the shared `.editorconfig` and `.gitattributes` blocks are not in a directory,
+they are two string constants in `src/projection/baselines.mjs` — and every adopting
+repository receives them. By ADR-015's own rule, a source is identified by its content rather
+than by the file it happens to live in, so the body defined in `src/` is a source like any
+other, and excluding `src/` as a path excluded content that leaves the package with it.
+
+The finding arrived sideways, which is the only way this class gets found. Removing the
+inert `[prettier]` block (S30) deleted seven lines from a shipped baseline — the first change
+in this repository that moves bytes out of `src/` without moving the provenance digest.
+Measured on a scratch repository with **only** that baseline body changed:
+
+- `check` reported `DRIFT .editorconfig`, which is correct: the gate compares bytes, and the
+  bytes were wrong.
+- `upgrade` reported the pin as `(unchanged)` and named the cause as
+  *"region restamped; the pin was already current (the rules changed)"*.
+
+Both halves of that sentence are false. The pin was unchanged because the stamp could not see
+the change, and the rules did not change — seven lines of an indentation setting did. The
+first false statement made the second one reachable: with the stamp silent, the only cause
+left to report was the one that was least true.
+
+The severity is the estate's own: a report that names a cause which did not happen sends the
+reader to diff `rules/` when the change is in `.editorconfig`. This is ADR-050's mistake one
+layer up — a field read for the thing it was not — and ADR-036's, where an instruction that
+is false in every repository is worse than one that is missing.
+
+## Ruling
+
+**One. The digest covers every byte string that leaves the package: `rules/` and `graph/` on
+disk, plus the rendered baseline bodies.** The baselines enter keyed by the file each becomes
+in the adopting repository (`baselines/.editorconfig`), not by the module that defines it,
+because the stamp answers what content produced those bytes and `.editorconfig` is the name
+a reader of a generated region recognises. `src/` remains excluded *as a directory*; the
+ruling narrows ADR-032's exclusion from a path to a rule about content. Ruling 1 of ADR-032
+and its "what the digest covers" section are superseded; ADR-032's framing, its framing
+discipline and its other two consequences stand.
+
+**Two. `provenanceInputs()` is exported, and `provenanceDigest()` hashes what it returns.**
+"The digest covers the right things" is a claim about a set, and a set assembled only inside
+the function that hashes it cannot be asserted from outside — the test would have to mutate
+the package to get an answer. Reading the list and hashing it in one place is ADR-042's
+ruling 3 applied to the stamp: the rendering is shared, so narrowing it narrows the test with
+it, and the test passed with the rendering sabotaged is not evidence.
+
+**Three. `upgrade`'s cause is read off the projected body, and the two kinds of content are
+counted apart.** A baseline region is not a rule: `.editorconfig` and `.gitattributes` are
+settings the repository owns. `rulesChanged` and `baselineChanged` are computed separately
+and the sentence names one, both, or neither. The comparison is body to body rather than
+byte to byte, because the region header carries the stamp and folding it in would make every
+pin bump claim a change of policy — which is ADR-050's ruling, and it is why a target whose
+seam moved reads as `updated` with no cause.
+
+**Four. "Neither" is a real answer and is not collapsed into the nearest cause.** A seam
+repair, a stamp-only move and a generated-field move are three different problems that one
+command fixes, and the sentence distinguishing them is the whole reason the command exists.
+
+## Consequences
+
+- **Every adopted repo's stamp moves once more.** A repo pinned at a digest computed without
+  the baselines reports `behind` the first time it runs this version and `simt-dev upgrade`
+  fixes it. That is a pin doing its job, not a regression — the same reading as ADR-032's own
+  first consequence.
+- **`upgrade` can no longer report a cause it cannot see.** The two defects were independent
+  and are now separately guarded: the digest test asserts the baselines are in the hashed set
+  and that changing one changes the value; the planner test asserts a baseline body move
+  produces "a baseline changed" and not "the rules changed".
+- **The planner needed a `kind` it did not have.** Baseline targets already carried
+  `kind: 'baseline'`; rule and primary targets carry none. That is the discriminator, and it
+  is read from the targets `plan` produced rather than recomputed from the file list, so the
+  two cannot disagree about which file is a baseline.
+- **A `src/` refactor still moves nobody.** The exclusion was narrowed from a path to a rule
+  about content, and the test asserts no `src/` entry appears in the hashed set — so the
+  narrowing cannot be re-widened silently by a future import.
+
+## Rejected
+
+- **Hash `src/` as a directory.** The smallest diff and the wrong one: it puts every
+  refactor, comment change and test edit into every consumer's stamp, which is precisely the
+  false report ADR-032 ruled out.
+- **Leave the stamp alone and fix only the wording.** The wording was the visible half. With
+  the pin reporting `(unchanged)` beside a restamped region, `upgrade` would still be
+  describing a move that did not happen — and the reader has no way to tell which line of
+  the output to disbelieve.
+- **Give baselines their own stamp field.** A second identity per repository, and the reader
+  would have to know which of two values to compare against. One stamp, covering everything
+  it stamps.
+- **Call the baseline a "rule" in the message.** Cheaper than a discriminator, and it sends
+  the reader to `rules/` — which is the defect.

simt_dev/vendored/docs/decisions/ADR-055-a-status-line-travels-so-it-may-not-name-a-location.md

@@ -0,0 +1,98 @@
+# ADR-055 — A status line travels, so it may not name a location; prose is the record's own argument
+
+Status: **accepted** · 2026-10-10 · filed as S54 · affects `src/decisions/index.mjs`
+
+## Context
+
+`rules why` prints a decision record's `Status:` line into whatever repository the reader
+is standing in, and most of them are repositories that adopted simt-dev and therefore own
+none of this package's files. The `summarise` contract said so itself, in the module that
+produces the output: *"Never contains a path, because a record read inside a consumer repo
+cannot name one."*
+
+The `ruled` half honoured that. The `status` half did not, because it is the record's own
+prose: five records wrote `· affects src/resolve/resolve.mjs` into a field the tool parses,
+copies and prints verbatim on every `rules why`, `rules show` and MCP call. The review
+measured this as "two records out of forty-eight, pre-existing". The corpus says **five**,
+and **three of them were written after that measurement** — ADR-053 and ADR-054 in this
+cycle, and ADR-041 days earlier. A finding that grows while it is being fixed is a finding
+whose real cause is a convention rather than a typo, and the convention is what needed
+ruling.
+
+The convention was ADR-038's: *"That is what the `Affects:` line on a record is for."* Five
+records had an `Affects:` field available and put the clause in `Status:` instead — because
+`Status:` is the line the tool reads, so putting it there feels like the place that counts.
+It is the opposite: it is the one field guaranteed to travel.
+
+## Ruling
+
+**One. A `Status:` line may not name a location.** It is this tool's own metadata — accepted,
+the date, what superseded what, what it affects — and every clause in it is a statement about
+*this package* by construction. There is no benign reading to confuse it with, so the
+predicate needs no judgement: a location resolving at this package's root is redacted to a
+phrase naming the thing rather than the path. The redaction happens once, in `loadDecisions`,
+so the text command, the JSON payload and the MCP surface cannot disagree about it — which is
+the same "one place decides" shape ADR-035 settled for writers.
+
+**Two. `Affects:` is where a location belongs, and it stays unprinted.** The loader already
+stops the status paragraph at a sibling field, so moving the clause is a reformat rather
+than a change of ruling, and the five records are corrected in place for the clause only.
+
+**Three. The exempt list is what `init` writes, and it is executed.** Dot-entries and three
+named files (`AGENTS.md`, `package.json`, `simt-dev.json`) are excluded from redaction,
+because a repository that adopted simt-dev has them. That is a claim about a set held in a
+comment, and a claim about a set held in a comment is a value nobody runs — so a test adopts
+a repository and asserts that every top-level file the tool writes survives the predicate
+unchanged. A name that drifts on stops being redacted; a name that drifts off starts
+redacting a file the reader does have.
+
+**Four. Prose is the record's argument and is left as written.** The `ruled` and `rejected`
+excerpts are a human argument, and they may legitimately quote a location — `docs/plans/`
+means *this package's* plan in one record and *the reader's own plans* in another, and no
+amount of reading the string separates them. Redaction there would have to guess, and a
+guessed redaction makes a correct sentence wrong, which is the worse defect. `redactEstate`
+redacts prose and is not a counter-example: an estate repository name is never the reader's
+business either, whereas a path inside an argument sometimes is.
+
+**Five. The cost of ruling four is a number, not a shrug.** Seven records still print a
+location in their prose — six older ones, and this record, which quotes the collision it
+turns on — and a test asserts the count and the ids. A record that stops quoting one moves
+it; a record that starts moves it too. The alternative — leaving it unmeasured — is how "two
+of forty-eight, pre-existing" came to describe ten.
+
+**Six. The `summarise` docstring's overclaim is withdrawn.** It asserted a property of prose
+that the function never had and could not have had. An unverifiable promise in a comment is
+the defect ADR-049 is about, one level down: a sentence that reads like evidence and carries
+none. The comment now states the scope it can keep.
+
+## Consequences
+
+- **Five records changed, and only their `Status:` line.** No ruling, no context and no
+  rejected alternative was touched. ADR-049's supersession machinery is unaffected:
+  `partialSupersessions` still reads the raw paragraph, because a ruling number is not a
+  location and redacting it would have been the wrong trade.
+- **`rules why ADR-042` no longer prints `src/resolve/resolve.mjs`.** It prints
+  `accepted · 2026-10-08 · ruling 1 superseded by ADR-053`, which is the whole of what the
+  line is for.
+- **A sixth record with a path in `Status:` is scrubbed rather than blocked.** The records
+  are corrected so they stay readable to a maintainer on this repository, where the path is
+  the useful part; the loader is hardened so a future one is harmless. The corpus test
+  asserts the *unscrubbed* status carries none, which is the stronger statement.
+- **Prose leaks are visible rather than absent.** Seven records — six older and ADR-055
+  itself, which quotes the collision it turns on. Anyone who decides that is still too many
+  now has the count and the argument against redaction.
+
+## Rejected
+
+- **Redact the prose too.** The `docs/plans/` collision is not hypothetical — ADR-014,
+  ADR-016, ADR-025 and ADR-030 all use that exact string for both meanings, and `test/leaks.mjs`
+  already singles it out as a substitution *default* that names where a repo keeps its own
+  plans. Redacting it would corrupt four records to protect six.
+- **Rewrite the ten records to drop the paths.** This repository's rule is that a record is
+  never edited in place, and the argument these records make is better with the file named.
+  The clause moves to the field designed for it; the sentence does not change.
+- **Stop printing the status line.** It carries the supersession, which is the one thing a
+  reader needs in order not to act on a reversed ruling.
+- **Put the redaction in `commands/rules.mjs`.** It would then apply to the text output and
+  not to `--json` or MCP, and the three surfaces would disagree about what a record says —
+  the copy ADR-052 exists to prevent.

simt_dev/vendored/docs/decisions/ADR-056-three-names-one-of-which-is-cheap-to-move.md

@@ -0,0 +1,160 @@
+# ADR-056 — The command, the package and the project are three names, and only one of them is cheap to move
+
+Status: **accepted** · 2026-10-10 · filed as S18 · amends [ADR-023](ADR-023-the-gate-ships-as-a-file-the-repo-owns.md) · affects `src/name.mjs`, `package.json`, `src/projection/manifest.mjs`, `src/projection/markers.mjs`
+
+## Context
+
+This tool had four names and no record of which was which. `PACKAGE_NAME` was spelled in
+`locate.mjs`, the manifest name in `manifest.mjs`, the config directory in `workspace.mjs`
+and the gate filename in `workflow.mjs` — four definitions, four places to forget. The
+command itself appeared **276 times across 33 files**, in remedy strings, help columns, shim
+source, MCP tool descriptions and the note every generated region carries.
+
+Publishing forced the question S18 had been asking since it was filed: *what is this
+called?* And the answer turned out to be four different answers depending on what you were
+asking about, which is not an answer.
+
+The measurements that settled it:
+
+- `simt-dev.json` is on disk in **fourteen repositories** that adopted the tool.
+- `<!-- simt-dev:begin -->` is in every projected `AGENTS.md` in every one of them.
+- `.simt-hooks/` and `SIMT_DEV_BIN` are in the `.git` directories of those repositories.
+- `simt-dev-check.yml` is in the `.github/workflows` of each of them.
+- The command name appears in **no file at all** until a reader types it.
+
+## Ruling
+
+**One. There are three names, and they are recorded as three.** `src/name.mjs` owns all of
+them and nothing else spells them:
+
+- `PROJECT` — the repository, and the artefacts already on somebody else's disk.
+- `CLI` — the command a reader types.
+- `PACKAGE_NAME` — what you install to get the command.
+
+They are three constants that happen to be related. Deriving one from another was
+considered and rejected: a derivation that picks between a package and a scope turns a
+one-line rename into a one-line diff whose meaning depends on a comparison nobody reading
+it would think to check.
+
+**Two. The command is `simt`; the project and the package keep `simt-dev`.** This is the
+whole ruling, and it rests on the asymmetry in the measurement above: the command appears
+only in text the tool itself writes, and that text migrates on the next write, while the
+other two names sit in files the tool cannot rewrite in place. Spending the rename on the
+cheap name is what made this a rename instead of a fourteen-repository roll-forward.
+
+**Three. The manifest follows the command, and its move is a read-both/write-new.** The
+manifest was one of the on-disk names and it is the one that moved: `simt-dev.json` is now
+`simt.json`. Without a fallback, all fourteen adopting repositories would read as "no
+manifest" on their next `check` — and "no manifest" is the answer that offers to re-adopt a
+repository that is already done. So:
+
+- **Read** takes `simt.json` if it exists, else `simt-dev.json`. Every read site goes
+  through one resolver (`manifestPath`) rather than knowing the fallback itself, because a
+  fallback that lives in five places is a fallback that eventually stops living in one of
+  them. The fingerprint, which reads the directory listing rather than a path, accepts both
+  spellings for the same reason: a fingerprint that misses the manifest silently loses the
+  repository's declared stack, which is the one input no amount of marker reading replaces.
+- **Write** goes to `simt.json`, and a lone `simt-dev.json` is moved, not shadowed: two
+  manifests in one repository is a state nobody can reason about, and the second would be
+  the one that is never read.
+- **The window closes per repository** on its first `init` or manifest write after the
+  upgrade. Until then, the old name keeps working everywhere.
+
+The fallback is asserted in `test/naming.test.mjs` with both spellings — the new name wins
+when both exist, the old name is still read, and a write moves the old file — because its
+failure mode is silent: the tool would simply stop seeing a repository it has been
+managing.
+
+**Four. The region namespace follows the command, and its move is read-both/write-new
+too.** The second on-disk name to move: the region was stamped `simt-dev:begin` /
+`simt-dev:end`, and so was the provenance header inside it (`simt-dev:generated`,
+`simt-dev:sha=`, `simt-dev:sources=`); all of those lines are now `simt:`. A marker cannot
+be renamed the way a manifest can, because a region cannot be moved — it lives inside a
+file the reader owns. So the fallback lives in the marker grammar itself, one read regex
+per dialect:
+
+- **Read** accepts either spelling in both dialects (HTML comment and `#` comment),
+  because a marker that does not match is simply not a region, and a caller that does not
+  accept the old spelling would silently report an adopted repository as unadopted.
+- **Write** emits only the `simt:` spelling, so the first write to each region migrates it
+  in place: the body comparison in `inject` finds the header prefix drifted and rewrites
+  the region where it stands. The window closes per repository on its first `sync`.
+- **A file holding both spellings is malformed, not merged.** Only a hand edit can produce
+  it — the tool writes one region per file and finds it by either spelling. Guessing which
+  region wins would silently delete the other, so `parse` reports it and a human deletes
+  the old one.
+
+The provenance digest covers `rules/`, `graph/` and `baselines/` — not `src/`, where the
+marker strings live (ADR-032, S53) — so the stamp *value* does not move with this rename;
+only the key's prefix does. No repository needs re-pinning, and `upgrade` sees no version
+change: the migration is marker bytes only.
+
+The fallback is asserted in `test/markers.test.mjs` — a legacy region is read and its
+stamp recovered, the first write migrates it in place, the migrated region is stable, and
+a mixed file is reported malformed — because its failure mode is the manifest's: the tool
+would simply stop seeing a repository it has been managing.
+
+**Five. The remaining on-disk names are locked, and the lock is asserted.**
+`test/naming.test.mjs` pins `simt-dev-check.yml`, `.simt-hooks`, `SIMT_DEV_BIN` and the
+project name as literals, so renaming one is a deliberate edit to a test rather than a
+constant change that looks harmless. A lock nobody can trip is a comment.
+
+**Six. The command name lives in one constant and is executed, not agreed.**
+`test/naming.test.mjs` walks `src/` and fails on any command string that *spells* the
+command instead of interpolating it. The pattern matches the real verb list rather than
+"space then a lowercase word", because the looser rule flags the tool naming itself in
+prose — `simt-dev will not remove a file it wrote` and `the simt-dev region is not at the
+top of the file` are the project talking about itself, and the project keeps its name.
+The guard was proven with a negative control: one injected spelled command, one failure
+naming the file and line, reverted.
+
+**Seven. The package is unscoped.** `@simt` and `@quazarmedia` were both free on npm; an
+unscoped `simt-dev` was already reserved by this project's own account. An unscoped name
+is the one a reader can guess, and the reserved one was the only spelling already pointing
+at something.
+
+## Consequences
+
+- **No repository has to do anything by hand, and the migration announces itself.** Every
+  adopted repo keeps its hooks directory and gate. The manifest is read under either name
+  and moves to `simt.json` on its first write; the region is read under either namespace
+  and migrates to `simt:` on its first `sync`. Until each repository has written once,
+  `check` reports the region as drifted — which is the migration making itself visible
+  rather than hiding, and it disappears on the `sync` that performs it. The migration is
+  real, but it runs itself — one repository per write — instead of running as a
+  fourteen-repository roll-forward.
+- **The generated gate file names the command correctly.** `name: simt check`, "If `simt`
+  cannot be found the job FAILS", "run `simt ci --yes`". These are shipped bytes into
+  every adopting repository, which is why they were checked by rendering them, not by
+  reading the source.
+- **One upgrade step is real and is documented.** A shim written before this change looks
+  for `simt-dev` on `PATH`. A machine that installed the package and never re-ran
+  `hooks install` finds nothing until the dependency is refreshed and `simt hooks install
+  --yes` re-runs. That is in the CHANGELOG rather than left to be discovered.
+- **The remaining on-disk names can still move, but only deliberately.** The gate file,
+  the hooks directory and the shim's environment variable would each need the shape the
+  manifest and the markers got — read-both, write-new, an asserted fallback — and S36's
+  estate roll-out to execute it.
+
+## Rejected
+
+- **Rename the artefacts too — `masar.json`, `masar-hooks/`, `<!-- masar:begin -->`.**
+  This was the shape the slice was originally taken in and it is strictly worse: it turns
+  a rename into a fourteen-repository migration, every one of which would see its
+  `AGENTS.md` stop being managed on the first `check` after the upgrade. It was rejected
+  for what it would have cost, not for being unclear. The manifest and the region markers
+  are exceptions to this rejection, and they are exceptions only because rulings three
+  and four make their moves safe: a marker that does not match is simply not a region, so
+  the fallback lives in the marker grammar itself — one read regex per dialect that
+  accepts both spellings — and a file holding two regions is reported malformed rather
+  than merged. The hooks directory and the gate remain fully rejected: they have no
+  second spelling a reader's file could fall back to.
+- **`@quazarmedia/simt-dev` as the package name.** Free, but already named in the shim
+  remedy, the review and the workflow install step. Changing it would have edited all
+  three for no availability gain, since the unscoped name was already reserved.
+- **Rename the command by a script that rewrites every literal.** The first attempt at the
+  propagation used "space then a lowercase word" and rewrote `user.name=simt-dev tests`
+  and a test title — both of which would have passed. A rename that cannot tell a command
+  from a git identity in a fixture is a rename that will eventually rewrite a sentence.
+- **Derive `PACKAGE_NAME` from `SCOPE` and `PROJECT`.** Rejected above; the three names
+  will not always agree, and the day they disagree the derivation picks for you.

simt_dev/vendored/docs/decisions/ADR-057-an-identity-is-per-developer-and-a-repository-does-not-own-it.md

@@ -0,0 +1,115 @@
+# An identity is per-developer, and a repository does not own it
+
+Status: **accepted** · 2026-10-11
+
+Affects: `simt init`, `src/identity.mjs`, `test/identity.test.mjs`
+
+## Context
+
+Two repositories in the estate carried a `git.config` file in their tracked files.
+It holds a name and an email address:
+
+```ini
+[user]
+	name = <one developer's name>
+	email = <that developer's email address>
+```
+
+Both had a local `include.path` pointing at it, and both worked. Both were also
+wrong in ways that had nothing to do with each other.
+
+**It was a tracked file.** A repository has more than one person in it. Committed,
+one developer's name and email is published to every other developer and to
+everybody who can read the repository. This repository's own release review had
+already said so, in the table of findings, as: *"`git.config` tracked at the root
+with a personal name and email — Identity file in a public tree, read by nothing
+— Remove it from the tree."* The finding was recorded and the file stayed.
+
+**It pointed somewhere else.** Both `include.path` values named
+`../../simt-dev/git.config` — another repository's identity file, resolved through
+the git directory rather than the working tree. Including the git config's own
+file from a relative path three directories up means one repository's commits
+depend on a sibling checkout existing at an expected path, which fails the moment
+anybody clones without it. It went unnoticed because every developer here has a
+global identity configured, so the include resolved to the same person the
+include would have skipped to, and the file it never read was the reason nothing
+broke.
+
+The interesting part is that these are opposite mistakes with the same root.
+`git.config` is not the repository's to own, and treating it as the repository's
+produced both: a file that should have been ignored got committed, and an
+`include` that should have named the repository's own file named a stranger's.
+
+## Ruling
+
+1. **`simt init` writes `git.config` when the repository has none.** It is planned
+   like everything else `init` writes, so it appears in the same preview that lists
+   the rest, and its source is named on the line — writing somebody's name is a
+   statement about a person and the plan says where the name came from.
+
+2. **An existing `git.config` is left exactly as it is.** Not updated, not merged,
+   not reformatted. It may have been written by a person, by an older version of
+   this tool, or by hand years ago, and none of those are this tool's to
+   second-guess.
+
+3. **The identity is derived, in this order, and the first answer wins:**
+   the repository's **last commit author**, then the identity **git would use on
+   this machine anyway**, then nothing.
+
+   Last commit first because it is a fact rather than a default: it is who has
+   actually been working here. It is read from `git log`, not from
+   `git config user.email`, because at that moment the configured value is what the
+   file is about to be derived from, and the step would be circular.
+
+   The second is `--get` rather than `--global`, so it resolves through git's own
+   precedence and returns what a commit would have used had this file never
+   existed. That is the fallback's whole point: it must not be a second opinion
+   about what identity means.
+
+4. **When nothing is available, no file is written.** A placeholder is an identity
+   git would use on the next commit, and an adopting command is the last thing that
+   should invent one. The refusal is printed with its reason rather than swallowed.
+
+5. **Only the keys that were found are written.** A partial identity is written as a
+   partial identity, for the same reason.
+
+6. **`init` adds `git.config` to `.gitignore`** when it creates one, and points
+   `include.path` at `../git.config` — the repository's own file.
+
+   `--replace-all`, not `--add`: a value naming *another* repository's identity file
+   is not an addition to keep, it is a link to break.
+
+   A repository that already *tracks* `git.config` is not untracked by `init`.
+   Removing a tracked file is not something an adopting command should do silently,
+   and doing it would be a change to that repository's history rather than to its
+   working tree.
+
+## Consequences
+
+`src/identity.mjs` is new and is the single answer to "whose identity is this, and
+may we write it". `init` plans it, writes it, gitignores it and repoints the
+include; the four refusals are asserted in `test/identity.test.mjs` rather than
+described, because each of them is the correct answer rather than a failure to try
+harder.
+
+One test scrubs `HOME` and `GIT_CONFIG_GLOBAL` before asserting the "nothing
+anywhere" case. That is not tidiness: a developer with a global `user.email` — which
+is most of them — makes the identity resolvable, so without scrubbing the test
+would pass for the wrong reason on that machine and nowhere else. ADR-031 is about
+a result depending on the author's environment; this test would have been the next
+instance of it.
+
+## Rejected
+
+- **Write `git.config` into the tracked tree, as a shared record of who works
+  here.** This is what the two repositories did, and it is a publication of a
+  person's email address with a commit attached.
+- **Take the identity from the OS (the login name, the home directory).** It
+  produces `<login-name>@example.com` and similar: an identity nobody configured,
+  used for authorship. Ruling 4's refusal covers it.
+- **Overwrite an existing `git.config` when it differs from the derived one.**
+  Difference is not error. A file that has been there for years and disagrees with
+  the last commit author is a decision somebody made.
+- **Fix the `include` only when it is wrong.** The include is only written when it
+  is missing or does not name this repository's own file. Rewriting it when it is
+  already correct would be a no-op that reads as a change.