simt-dev 0.1.1 → 0.2.0

package/docs/decisions/ADR-030-what-a-plan-does-not-ship-is-a-decision-with-a-record.md

@@ -56,7 +56,7 @@ correcting at all.
    detectable by reading the file. Corrected in the row.
 
 5. **Two of the four configurations are plain JavaScript with no TypeScript in them,**
-   `simt-api` and `simt-blog`. A "shared 6-rule ESLint block" cannot describe all four,
+   `repo-04` and `repo-06`. A "shared 6-rule ESLint block" cannot describe all four,
    because two of them have no rules to share — they differ in `ignores` and per-file
    `globals`, which are per-repository facts about paths.
 
@@ -67,7 +67,7 @@ correcting at all.
    may make on its own.
 
 7. **The fix for the two conflicts is one dependency each,** and it is not a shared block.
-   Installing `eslint-config-prettier` in `simt-social` and `simt-social-api` and spreading
+   Installing `eslint-config-prettier` in `repo-14` and `repo-11` and spreading
    it last in the config array resolves both. That is a command per repository, run by the
    repositories, and simt-dev has no business writing it.
 

package/docs/decisions/ADR-031-the-suite-stages-the-environment-it-needs.md

@@ -16,9 +16,9 @@ landed. Not intermittently: 22 of 543 tests failed on runs `37476671363` through
 Three separate causes, none of them recent:
 
 1. **`test/install.test.mjs:17` read the estate off the author's disk.**
-   `const WORKSPACE = resolve(HERE, '..', '..')` is `/Users/said.elimam/code/simt`, and the
-   install tests copied skill bodies out of it — `simt-social-api/.agents/skills/d1-safe-change`,
-   and `singleRepoClone()` out of `simt-social`. On a runner the checkout is
+   `const WORKSPACE = resolve(HERE, '..', '..')` is `/home/developer/code/simt`, and the
+   install tests copied skill bodies out of it — `repo-11/.agents/skills/d1-safe-change`,
+   and `singleRepoClone()` out of `repo-14`. On a runner the checkout is
    `/home/runner/work/simt-dev/simt-dev`, so `../..` is `/home/runner/work/simt-dev`,
    which contains this repository and nothing else. The bodies were not there,
    `skills install` exited 3, and nineteen tests asserted on a refusal they never asked for.

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

@@ -25,7 +25,7 @@ Phase 6 asked to "collapse the 7 drifted Social skill twins to canonical + stub"
 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.
+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.
@@ -47,7 +47,7 @@ fixed. The two Android `local.properties` files were not, and were nearly fixed
    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
+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
@@ -74,8 +74,8 @@ 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
+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

package/docs/decisions/ADR-041-the-suite-installs-the-package-in-order-to-test-it.md

@@ -21,7 +21,7 @@ Two facts about this repository make that gap harder to notice than it looks. `t
 reach outside the checkout (ADR-031), and this package has no dependencies (ADR-012). Together
 those mean the suite has no installed copy of itself to test, and the natural workaround —
 borrowing a formatter from a neighbouring checkout — is the one ADR-031 rules out. Prettier 3.8.1
-is sitting in `../simt-blog/node_modules/.bin` and is not available here.
+is sitting in `../repo-06/node_modules/.bin` and is not available here.
 
 ## Ruling
 
@@ -87,6 +87,6 @@ node, git and a POSIX shell; npm is in the same class. A conditional skip conver
 into an unverified one, which is the failure this file was written to stop.
 
 **Copying Prettier out of a sibling checkout.** It exists, it works, and ADR-031 rules it out for
-the same reason it rules out reading skill bodies from `../simt-social`: a suite that passes on
+the same reason it rules out reading skill bodies from `../repo-14`: a suite that passes on
 the author's machine and fails on a runner with only this checkout is evidence about the author's
 directory.

package/docs/decisions/ADR-045-a-dashboard-that-counts-a-defect.md

@@ -16,13 +16,13 @@ Measured over the 16 repositories at `~/code/simt`:
 ```
 staleRuleFiles: 17
 repos naming stale rule files in problems: 0
-simt-app problems:
+repo-05 problems:
   "the generated region was hand-edited; restore it with: simt-dev sync --yes"
   "core.hooksPath is \"hooks\", not the shared dispatcher; run: simt-dev hooks install --yes"
 ```
 
-Five adopted repositories have stale rule files — `simt-app`, `simt-blog` and `simt-social` at 0
-of 3 current, `simt-social-api` and `simt-social-media` at 0 of 4 — and not one of them said so in
+Five adopted repositories have stale rule files — `repo-05`, `repo-06` and `repo-14` at 0
+of 3 current, `repo-11` and `repo-13` at 0 of 4 — and not one of them said so in
 its problems list. The summary already said `staleRuleFiles: 17`, because `summarise` has always
 counted them. So the dashboard was reporting a count of a defect it refused to call a defect.
 

package/docs/decisions/ADR-046-one-rule-one-copy.md

@@ -14,11 +14,11 @@ Review 0001 §S12, marked P1 and "decision". Measured across the estate before a
 the five repositories selecting `opencode,cursor`:
 
 ```
-simt-app           folded=3  .mdc=3  0/3 current
-simt-blog          folded=3  .mdc=3  0/3 current
-simt-social        folded=3  .mdc=3  0/3 current
-simt-social-api    folded=4  .mdc=4  0/4 current
-simt-social-media  folded=4  .mdc=4  0/4 current
+repo-05           folded=3  .mdc=3  0/3 current
+repo-06          folded=3  .mdc=3  0/3 current
+repo-14        folded=3  .mdc=3  0/3 current
+repo-11    folded=4  .mdc=4  0/4 current
+repo-13  folded=4  .mdc=4  0/4 current
 ```
 
 Seventeen generated rule files. Every one of them byte-identical to the section already folded into

package/docs/decisions/ADR-047-a-profile-selects-on-what-a-repository-runs-on.md

@@ -50,7 +50,7 @@ other `react-native`, and neither receives both.
 **Two.** The Android and uv facts name a path at an unknown depth, which the two existing kinds
 (`file`, `dir`) cannot express. A third kind, `glob`, walks at most `GLOB_DEPTH` directory levels
 below the root. The bound is a convention, not a preference: the Android Gradle Plugin puts a
-module's manifest at `<module>/src/main/AndroidManifest.xml`, and simt-app's sits at
+module's manifest at `<module>/src/main/AndroidManifest.xml`, and repo-05's sits at
 `app/src/main/AndroidManifest.xml`. A shallower bound makes `has-android-manifest` the shape S07
 found — a fact no repository could have. A deeper one is a scan rather than a probe, and
 ADR-013's promise is that adding an ecosystem is data, so a fact must not cost a search.
@@ -78,11 +78,11 @@ repository loses coverage:
 
 | Repo | Before | After |
 | --- | --- | --- |
-| `app-ui`, `simt-app`, `wakt-app` | `core, jvm-android` | `core, android, jvm` |
-| `bunnyland-server` | `container, core, python` | `container, core, python, uv` |
+| `repo-01`, `repo-05`, `repo-03` | `core, jvm-android` | `core, android, jvm` |
+| `repo-02` | `container, core, python` | `container, core, python, uv` |
 
 The three Android repositories gain the profile whose body they actually needed and keep the JVM
-build rules; `simt-app` gaining `android` was the row's acceptance criterion. `bunnyland-server`
+build rules; `repo-05` gaining `android` was the row's acceptance criterion. `repo-02`
 carries a committed `uv.lock`, so its gain is the defect repaired, not a new selection.
 
 The rename is breaking in one narrow way: the id `jvm-android` no longer exists. A consumer that

package/docs/decisions/ADR-048-a-baseline-carries-only-keys-a-reader-honours.md

@@ -63,11 +63,11 @@ it.
 
 | Repository | Prettier config | States `singleQuote` | Adopting `quote_type = single` |
 | --- | --- | --- | --- |
-| `simt-api` | `.prettierrc` | `true` | no change |
-| `simt-blog` | `.prettierrc.json` | `true` | no change |
-| `simt-space` | `.prettierrc.json` | `true` | no change |
-| `simt-social-api` | `.prettierrc.json` | absent | **every source file reformatted** |
-| `simt-social` | `.prettierrc.json` | absent | **every source file reformatted** |
+| `repo-04` | `.prettierrc` | `true` | no change |
+| `repo-06` | `.prettierrc.json` | `true` | no change |
+| `repo-15` | `.prettierrc.json` | `true` | no change |
+| `repo-11` | `.prettierrc.json` | absent | **every source file reformatted** |
+| `repo-14` | `.prettierrc.json` | absent | **every source file reformatted** |
 
 Two repositories would have every source file rewritten on the day they adopted the
 tool, in a commit whose message says it adopted a rules projection. The measurement is

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

package/docs/decisions/ADR-058-one-tool-three-channels-and-the-order-is-forced.md

@@ -0,0 +1,148 @@
+# One tool, three channels, and the order is forced
+
+Status: **accepted** · 2026-10-11
+
+Affects: `pyproject.toml`, `python/simt_dev/`, `Formula/simt-dev.rb`,
+`.github/workflows/publish.yml`, `scripts/release-formula.mjs`,
+`scripts/verify-wheel.mjs`, `test/packaging.test.mjs`
+
+## Context
+
+simt-dev is a Node program. It is also a *repository* tool: somebody adopting a
+repository runs `simt init` inside it, and the places people run that from are
+not all Node projects. A python developer in a repository that has no
+`package.json` has no reason to install a package manager to get a command that
+adopts their repository, and a Homebrew user has no reason to install Node to
+install a tool that needs Node.
+
+So the tool is published to three channels:
+
+| Channel | What it installs |
+| --- | --- |
+| npm | a tarball of `.mjs` files |
+| PyPI | a wheel carrying those same files, plus a `simt` entry point |
+| Homebrew | a formula that downloads the npm tarball at install time |
+
+The design constraint that decided all of it: the tool has **zero runtime
+dependencies and no build step**. The whole thing is ~1.3 MB of text. That makes
+the "packaging for a second language" problem a *copying* problem rather than a
+build one, and copying is a problem with a right answer.
+
+## Ruling
+
+1. **The Python wheel carries the tool's own source, byte for byte.** `files` in
+   `package.json` and `force-include` in `pyproject.toml` name the same paths,
+   and `scripts/verify-wheel.mjs` builds both artefacts and hashes every file in
+   both, failing the release when a single byte differs.
+
+   The wheel is not a wrapper around `npm install`. A wrapper would fetch code
+   at install time - unpinned, unsigned by anything the installer can check, and
+   absent the moment somebody runs `pip install` on a train.
+
+2. **The version is one number, read rather than written.**
+   `pyproject.toml` declares `dynamic = ["version"]` and reads it from
+   `package.json` with a regex. A second literal would drift, and the drift
+   would be invisible until somebody ran `pip show` beside `simt --version` and
+   got two answers about which release they are running.
+
+3. **The Python launcher is standard library only, and has no required
+   dependencies.** The `[node]` extra is optional and imports `nodejs_wheel`
+   *inside a `try`, at the point of use* - never at module level - so the
+   default install cannot fail on a package it never asked for.
+
+   ADR-012 rules out runtime dependencies for the npm package. The reasoning
+   transfers without modification: a dependency is a runtime this package cannot
+   verify and its owner cannot patch, and this package exists to be the thing
+   people run in a repository rather than the thing they have to curate.
+
+4. **`simt` is the one command, on every channel.** `bin` in `package.json` and
+   `[project.scripts]` in `pyproject.toml` are asserted equal, and the formula's
+   `test do` block runs it. A second name under the package name would be a
+   convenience that forks the documentation the first time somebody documents
+   one channel and not the other.
+
+5. **Homebrew installs the npm tarball, and does not use `std_npm_args`.**
+   `depends_on "node"` declares the runtime; the entry point's shebang is
+   rewritten to that node rather than left at `#!/usr/bin/env node`, so the
+   command works from a cron job and from a shell that has moved node out of
+   the way, both of which look identical to a broken install.
+
+   `std_npm_args` invokes npm at build time, which needs the registry at build
+   time. This package has nothing to install, so that would add a network fetch
+   to installing the one thing in the estate that provably needs none.
+
+6. **`Formula/simt-dev.rb` is the source of truth, and `scripts/release-formula.mjs`
+   patches two lines in it.** It does not regenerate the formula from a
+   template: a template would mean the bytes a reader sees in this repository
+   are not the bytes a tap serves, which is the defect ADR-023 ruled out for the
+   gate file. The two lines are matched by content, not by line number, because
+   a line number would make the formula a file that cannot be edited - adding a
+   comment above the `sha256` line would silently write the checksum to the
+   wrong place.
+
+7. **The npm version must be live before `publish-pypi` and `publish-brew`
+   succeed, and both jobs say so when it is not.** The order is not a
+   preference. Homebrew downloads from the npm registry at install time, so a
+   formula naming a version that is still in npm's staging area installs a
+   404 - on somebody else's machine, at a tap, from a release this workflow
+   already declared done.
+
+   Those two jobs are the ones a maintainer runs again after
+   `npm stage approve`. "Re-run failed jobs" carries the tag context, which a
+   `workflow_dispatch` does not: on a dispatch, `github.ref_name` is the branch,
+   and the version guard would compare a tag against a branch.
+
+## Consequences
+
+The invariants split in two, and the split is deliberate.
+
+`test/packaging.test.mjs` holds the **static** ones: that `files` and
+`force-include` name the same paths, that the version is not written twice, that
+the command is one name, that the launcher imports nothing outside the standard
+library, that no second build system sits at the repository root. Every one of
+those is checkable from this checkout with no network and no interpreter, which
+is what lets it run in `npm test`.
+
+`scripts/verify-wheel.mjs` holds the one that is not: that the paths, once
+built, contain the same bytes. It runs in the release workflow, where a Python
+and a registry are available by construction.
+
+That split is ADR-031 applied. A test that needed `pip` would not run for the
+next person who clones this repository, and would run differently on the
+machine that wrote it - which is the failure that suite is about.
+
+Two findings from building it are recorded because they are the kind that only
+appear when a check is real:
+
+- The first run of `verify-wheel.mjs` reported `LICENSE` and `README.md` as
+  differences. They are not defects: npm adds both to every tarball, and the
+  wheel carries them as *distribution metadata* rather than as files. The
+  comparison is now scoped to what `files` names, which is the content the tool
+  reads.
+- The first run of that same comparison reported every one of `bin`, `src`,
+  `graph` and `rules` as missing from both, because `files` names **directories**
+  and npm includes them recursively. The expansion happens in the script now,
+  with the reason stated where the code is.
+
+The check was also tampered with deliberately - a wheel-only `README.md` was
+injected into `force-include` and it failed - because a parity check that has
+never failed is not evidence that it works.
+
+## Rejected
+
+- **A Python wrapper that runs `npm install -g simt-dev` on first use.** This is
+  what the unofficial `pyright` package does, and it has the properties it is
+  reputed to have: a download on first run, unpinned, uncacheable, and a failure
+  mode that reads as a broken package rather than as a missing runtime.
+- **Requiring node, with no bundled fallback.** The reader who installs from
+  PyPI is frequently the reader with no node, which is the whole reason the
+  channel exists. The failure message therefore names the `[node]` extra first,
+  because it is the one remedy that is the same command on every platform.
+- **Guessing where node is.** A hardcoded list of `/opt/homebrew/bin/node`,
+  `/usr/local/bin/node` and `~/.nvm/...` is three guesses and a surprise: it
+  prefers a guess over the reader's own `PATH`, and it is already out of date
+  for anyone who installs node differently. `shutil.which` asks the question
+  instead of answering it.
+- **`std_npm_args`.** See ruling 5.
+- **Publishing all three channels simultaneously.** Rejected by the ordering in
+  ruling 7 - Homebrew cannot name a version npm has not released.

package/docs/decisions/README.md

@@ -64,6 +64,8 @@ record's status line — never by editing the ruling in place.
 | [054](ADR-054-the-digest-covers-every-byte-that-leaves-the-package.md) | The digest covers every byte that leaves the package, and a cause is read off the body | accepted · amends ADR-032 |
 | [055](ADR-055-a-status-line-travels-so-it-may-not-name-a-location.md) | A status line travels, so it may not name a location; prose is the record's own argument | accepted |
 | [056](ADR-056-three-names-one-of-which-is-cheap-to-move.md) | The command, the package and the project are three names, and only one of them is cheap to move | accepted · amends ADR-023 |
+| [057](ADR-057-an-identity-is-per-developer-and-a-repository-does-not-own-it.md) | An identity is per-developer, and a repository does not own it | accepted |
+| [058](ADR-058-one-tool-three-channels-and-the-order-is-forced.md) | One tool, three channels, and the order is forced | accepted |
 
 ADR-001 to ADR-010 resolve the contradictions found across the 16 repos in the 2026-10-05
 audit; each record names the repos whose text it replaces. ADR-011 and ADR-012 are the
@@ -418,7 +420,7 @@ ADR-018's guard could not see the default hooks directory because it looked only
 key, and `hooks status` carried its own copy of the read logic the shared module already had.
 
 A fourth joins them. ADR-019 is the same shape one layer over: `simt init` dropped all
-five gates on `simt-app` and told the reader to add a script to a `package.json` the
+five gates on `repo-05` and told the reader to add a script to a `package.json` the
 repository will never have. The facts were right, the remedy was not followable, and once
 the repository declared what it does have, the dispatcher, `check` and `hooks status`
 gave three different answers about one manifest. Every one of these shipped green because

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.",
   "license": "Apache-2.0",
   "author": "Said Elimam",

package/src/commands/hooks.mjs

@@ -6,11 +6,11 @@
 //
 // Installing is the only mutating command, it is idempotent, it previews unless
 // told to write, and it refuses to clobber an existing core.hooksPath without
-// --yes. The estate has four incompatible conventions and one of them (simt-app)
-// points at a directory whose pre-push is 0 bytes, so overwriting silently would
-// be the worst available outcome. simt-space keeps its hook in the DEFAULT
-// location, which core.hooksPath being unset does not reveal, so a foreign hook
-// is found by asking git rather than by reading config.
+// --yes. Repositories in the wild use incompatible conventions, including a
+// hooksPath pointing at a directory whose pre-push is 0 bytes, so overwriting
+// silently would be the worst available outcome. Others keep their hook in the
+// DEFAULT location, which core.hooksPath being unset does not reveal, so a
+// foreign hook is found by asking git rather than by reading config.
 
 import { execFile } from 'node:child_process';
 import { chmod, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
@@ -176,7 +176,7 @@ async function installHooks(root, flags) {
   // the hook runs as a gate and its verdict appears in the report beside the others,
   // rather than after the gates passed where an author cannot see it.
   //
-  // Keying this on the event vocabulary instead of on the manifest cost simt-app its
+  // Keying this on the event vocabulary instead of on the manifest cost a repository
   // git-lfs hook: pre-push is a gated event in general, but this repo declares no
   // pre-push gate, so nothing replaces its hook and routing would have dropped it.
   const chained = [
@@ -188,7 +188,7 @@ async function installHooks(root, flags) {
     // Foreign hooks on events THIS repo has no gate for.
     //
     // Per repository, not per event vocabulary - and the difference is not academic.
-    // simt-app declares no pre-push gate, and its pre-push is git-lfs: routing without a
+    // declares no pre-push gate, and its pre-push is git-lfs: routing without a
     // shim for that event means git finds no pre-push hook at all and LFS objects stop
     // being uploaded, silently, with nothing to notice it. An event this repo gates is
     // different: the dispatcher replaces the hook there by design, and the hook's real
@@ -228,9 +228,9 @@ async function installHooks(root, flags) {
 
   // Refuse to take over routing git is already using without explicit consent.
   // Two cases, and the second one is the one that bites: core.hooksPath already
-  // pointing elsewhere (simt-app points at a directory whose pre-push is 0 bytes),
-  // and core.hooksPath being unset while a hook sits in the default location
-  // (simt-space, 4 KB of real logic in .git/hooks/pre-commit). Reading unset as
+  // pointing elsewhere (a hooksPath whose pre-push is 0 bytes), and core.hooksPath
+  // being unset while a hook sits in the default location (4 KB of real logic in
+  // .git/hooks/pre-commit). Reading unset as
   // "no hooks" is what let install replace a working gate with no warning.
   const takeover = (current !== null && current !== wants) || state.foreign.length > 0;
   if (takeover && !flags.yes) {

package/src/commands/init.mjs

@@ -29,6 +29,15 @@ import { readHooksState } from '../compare/hooksstate.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOWS_DIR } from '../ci/workflow.mjs';
 import { planDependabot, renderDependabot } from '../ci/dependabot.mjs';
 import { planTsconfigBase, renderTsconfigBase, TSCONFIG_BASE_FILE } from '../tsconfig.mjs';
+import {
+  IDENTITY_FILE,
+  INCLUDE_KEY,
+  ignoreIdentity,
+  includeOwnIdentity,
+  includesOwnIdentity,
+  renderIdentityFile,
+  resolveIdentity,
+} from '../identity.mjs';
 import { pointerState, pointerTargets } from '../projection/project.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { plan, provenanceDigest, PRIMARY_TARGET, LOCAL_PROFILE_DIR } from '../projection/project.mjs';
@@ -58,7 +67,7 @@ export async function initCommand(positional, flags) {
 
   // What this repo can demonstrably run, not what its stack suggests. Without this the
   // stack table proposes gates the repo has no way to execute — the adoption of
-  // simt-social-media declared five and could run two, which would have blocked every
+  // a repository declared five and could run two, which would have blocked every
   // commit once hooks were installed.
   const capability = await readCapability(root);
   const { dropped } = planGates(detected.stack, capability);
@@ -98,6 +107,26 @@ export async function initCommand(positional, flags) {
   const ci = await planWorkflow(root);
   const dependabot = await planDependabot(root);
   const tsconfigBase = await planTsconfigBase(root);
+  // Per-developer, and planned with the rest so the operator sees it in the same
+  // preview that lists everything else. `exists` short-circuits the write: a
+  // repository that already has one keeps it exactly as it is.
+  const identity = await resolveIdentity(root);
+  const identityPlan = {
+    file: IDENTITY_FILE,
+    action: identity.exists ? 'unchanged' : identity.from === null ? 'skip' : 'created',
+    from: identity.from,
+    name: identity.name,
+    email: identity.email,
+    reason: identity.exists
+      ? `${IDENTITY_FILE} already exists and is left exactly as it is`
+      : identity.from === null
+        ? 'no identity is configured anywhere, and this tool does not invent one'
+        : null,
+    // Only worth fixing when this repository is the one being routed: an include
+    // pointing at another repository's identity file works here and breaks for the
+    // next person who clones without that sibling checkout.
+    include: await includesOwnIdentity(root),
+  };
 
   const payload = {
     ok: summary.conflicts === 0 || flags.acceptConflicts === true,
@@ -117,6 +146,7 @@ export async function initCommand(positional, flags) {
     pointers: pointerPlan.map((p) => ({ file: p.file, to: p.to, readers: p.readers, state: p.state })),
     pointersBlocked: pointerBlocked,
     ci: { file: ci.file, action: ci.action, bytes: ci.bytes, own: ci.own, reason: ci.reason },
+    identity: identityPlan,
     dependabot: {
       file: dependabot.file,
       action: dependabot.action,
@@ -239,6 +269,30 @@ export async function initCommand(positional, flags) {
   await writeManifest(root, manifest);
   note(`wrote    ${MANIFEST_FILE} (${manifestAction})`);
 
+  // Identity last, and for the same reason the gate is written after the manifest:
+  // the things that change what this repository does come first, and the one that
+  // only records who is doing them comes once there is something to be committing.
+  //
+  // Three separate refusals, each of which is the correct answer rather than a
+  // failure to try harder. An existing file is not this tool's to rewrite. An
+  // unconfigured identity is not one to invent - a placeholder is an identity git
+  // would use. And the include is only repointed when it is missing or wrong,
+  // because replacing it when it is already right would be a no-op that reads as
+  // a change.
+  if (payload.identity.action === 'created') {
+    await writeFile(join(root, IDENTITY_FILE), renderIdentityFile(identity));
+    await ignoreIdentity(root);
+    note(`wrote    ${IDENTITY_FILE} (${identity.from === 'last-commit' ? 'from the last commit in this repository' : 'from the identity configured on this machine'}); gitignored, because it is yours and not the repository's`);
+  } else if (payload.identity.action === 'unchanged') {
+    note(`kept     ${IDENTITY_FILE} (${payload.identity.reason})`);
+  } else {
+    note(`skipped  ${IDENTITY_FILE}  ${payload.identity.reason}`);
+  }
+  if (!payload.identity.include) {
+    await includeOwnIdentity(root);
+    note(`set      ${INCLUDE_KEY} = ../${IDENTITY_FILE}  this repository's own identity file`);
+  }
+
   // Written after the manifest so the gate exists in the same adoption that declares
   // what the gates are. Skipped with its reason printed rather than silently: a repo
   // with no `.github/workflows` has no CI surface to attach to, and inventing one
@@ -444,6 +498,18 @@ function render(payload, manifest) {
       `coverage=${manifest.limits.coverage ?? 'undeclared (ADR-006)'} ` +
       `fileLines=${manifest.limits.fileLines.warn}/${manifest.limits.fileLines.error} (ADR-005)`,
   );
+  // The identity line, with its source named. "Created" is a statement about somebody's
+  // name landing in a file, so where the name came from is not a detail of the line.
+  const id = payload.identity;
+  if (id) {
+    const verb = id.action === 'skip' ? 'skip' : id.action;
+    const detail = id.action === 'unchanged'
+      ? id.reason
+      : id.action === 'skip'
+        ? id.reason
+        : `${id.name} <${id.email}>  from ${id.from === 'last-commit' ? "this repository's last commit" : 'the identity configured on this machine'}`;
+    lines.push(`  ${verb.padEnd(9)} ${id.file}${detail ? `\n            ${detail}` : ''}`);
+  }
   // Every gate the stack suggested and this repo cannot run is named, with the reason.
   // A silently shorter gate list reads as "this repo needs no formatting check", when
   // the truth is "declaring one would block every commit". The remedy is stated because

package/src/commands/skillsinstall.mjs

@@ -39,7 +39,7 @@ import { MANIFEST_FILE } from '../name.mjs';
 /**
  * Where skills live in this repo. The estate already has a convention - a
  * canonical directory plus symlink fan-out - and it is not the same directory in
- * every repo (`.agents/skills` in five, `.cursor/skills` in simt-app). So the
+ * every repo (`.agents/skills` in some, `.cursor/skills` in others). So the
  * existing layout is respected and only invented when there is none.
  */
 export function skillsDir(root, entries) {

package/src/compare/discover.mjs

@@ -12,7 +12,7 @@
 //      so it must be attributed to its parent or a projection drift gets reported
 //      against the wrong directory.
 //   3. Directories that are not repos are not candidates, but they are still
-//      COUNTED. `simt-space-review` is 25 PNG screenshots; silently dropping it
+//      COUNTED. A directory of 25 PNG screenshots is not a rule source; silently dropping it
 //      hides the fact that a directory in the workspace is unmanaged, which is a
 //      real finding during a migration.
 //