simt-dev 0.2.1 → 0.3.0

package/docs/decisions/ADR-067-which-harnesses-read-agents-md-is-a-column.md

@@ -0,0 +1,110 @@
+# ADR-067 — Which harnesses read AGENTS.md is a column, and a row without a document gets none
+
+Status: **accepted** · 2026-10-13 · filed as S42
+**Affects:** `harness detect`, `src/projection/surfaces.mjs`, `src/commands/harness.mjs`, the
+table tests in `test/surfaces.test.mjs`, `test/harness.test.mjs`
+
+## Context
+
+Review 0002 filed the finding as "harness coverage stops at five surfaces", and the table
+stops at five: opencode, Cursor, Claude Code, Antigravity and Copilot. The same review then
+listed a dozen more harnesses that read instruction files — Gemini CLI, Windsurf, Zed, Kiro,
+Cline, Roo Code, Junie, Aider, Continue, Amp, Goose — and its own fix had two halves that pull
+against each other.
+
+The first half is mechanical: add a column recording whether each harness reads AGENTS.md,
+and add rows only for the ones that do not. Most of the candidates need no row at all,
+because most of them read AGENTS.md natively, and that fact is exactly what the column is for:
+it turns "which harnesses do we support" from an open question into a lookup.
+
+The second half is the one the review flagged on itself. It proposes a row per vendor and a
+`verified` field citing that vendor's documentation — while stating in the same paragraph that
+it did not re-verify each vendor's current documentation and that its list should be treated as
+candidates. So the rows would carry a field whose entire purpose is to say "this was checked
+against a source", filled in by a list that was not checked.
+
+That combination is the failure this repository exists to prevent, in its exact form. The
+repository's own ruling on manifest comments records the shape of it: a comment claiming each
+value cites its decision record, where none did, is decoration that misdescribes the artefact.
+A surface row is not decoration — it decides whether a reader's agent gets a rule at all. A
+guessed row puts an unverified assumption into every repository that adopts the release, and
+the reader who is wrong about it cannot tell, because the field that would tell them is the
+one that was invented.
+
+Detection was the other half and it has no such trap. "Which harnesses is this repository set
+up for" is answerable from directories that exist, provided the command claims exactly that
+much and no more.
+
+## Rulings
+
+1. **Whether a harness reads AGENTS.md is a vendor fact recorded per row, in three values.**
+   `all` means every reader the row names loads it; `some` means a subset does and the row
+   says which, in its own words; `none` means the row is the only channel those readers have.
+   Two values would be wrong in a way that matters: Copilot's CLI reads AGENTS.md and its
+   editor, code review and cloud agent do not, and a boolean there would have to be read as
+   "this repository is covered for Copilot", which is false for two of its three readers.
+   Every row whose value is not `all` carries the sentence that makes it true.
+
+2. **The column is not the existing `readsPrimary` flag, and the two must not be merged.**
+   That flag answers whether a per-rule file would repeat text the folded region already
+   carries, and it is only meaningful while folding is on. This column answers whether the
+   file is read at all, and it decides whether a harness needs a row. Merging them would make
+   a duplication question stand in for a coverage question, and the value would then change
+   answer a reader is relying on.
+
+3. **A row requires provenance, so no row ships from the candidate list.** Review 0002's
+   candidates are recorded as configuration directory names, not as surfaces. Adding a row
+   requires a vendor document, and a row whose `verified` cites nothing does not get added —
+   which means this ruling lands fewer surfaces than the review asked for, deliberately. The
+   cost of waiting is that a harness which does not read AGENTS.md is not served until
+   somebody reads its documentation; the cost of guessing is that every adopting repository
+   inherits the guess and the reader of the row is the only one who can catch it.
+
+4. **Detection reports presence and calls it presence.** A directory that exists implies a
+   harness is in use. It does not imply the harness reads AGENTS.md, is installed, or is
+   configured the way this tool would configure it, and the output never says it does. The
+   candidate list claims nothing about what those readers load for the same reason ruling 3
+   does: the directory name is evidence of a harness, and the fact nobody has verified is
+   what it loads.
+
+5. **A configuration directory with no channel is a note, never a problem.** It is the
+   expected shape of a repository whose team uses something this release does not serve, and
+   the remedy for it is not something the reader can be told to do. The command also exits 0
+   whatever it finds, including on a repository with no harness configuration at all: a
+   non-zero exit would be read as "this repository is set up wrong", which is the one thing a
+   directory scan can never establish.
+
+6. **The home directory is opt-in.** `--user` adds it. A command whose answer changes because
+   something was installed elsewhere is one a reader stops trusting, and the repository is
+   not the reader's machine.
+
+## Consequences
+
+A harness that does not read AGENTS.md and has no row is now visible rather than invisible:
+`harness detect` names its configuration directory as present with no channel, and says in the
+same breath that presence is not a coverage claim. That is the honest answer available without
+vendor documentation, and it is the one a reader can act on — by asking, or by adding a row
+with a citation.
+
+The candidate list will be wrong sometimes: a harness may name its directory differently, or
+use a dotless one, or write its config elsewhere. Each of those produces a miss, and a miss is
+silent. That is the shape of the problem as it stands; the alternative was a table of claims.
+
+## Rejected
+
+- **Adding a row per review-0002 candidate with `verified` citing the review.** The field would
+  name a document that was never read. It is the exact defect the ruling on manifest comments
+  records, and it would be harder to spot later because each row would look like a verified
+  one.
+- **A two-valued column.** Every row would have to pick the more flattering half, and the
+  flattering half for Copilot is the one two of its three readers contradict.
+- **Merging the column into `readsPrimary`.** It would turn "does this harness read the file"
+  into "would this duplicate the region", and the answer a reader gets would depend on whether
+  they had folded the rules.
+- **Reporting an unclaimed configuration directory as a finding.** It would put a red mark on a
+  repository for using a tool this project has not documented, which is a statement about the
+  project, not about the repository.
+- **Scanning for configuration files rather than directories.** A file such as a workflow or
+  a settings blob is not evidence that a harness is in use, and the one directory deliberately
+  excluded here — the one that holds workflows and issues — would have been reported for every
+  repository with CI.

package/docs/decisions/ADR-068-the-mcp-revision-list-cites-what-was-read.md

@@ -0,0 +1,111 @@
+# ADR-068 — The revision list is a claim about revisions that were read
+
+Status: **accepted** · 2026-10-13 · filed as S43
+**Affects:** `mcp`, `src/mcp/server.mjs`, `src/mcp/tools.mjs`, `src/mcp/schema.mjs`, the
+protocol tests in `test/mcp.test.mjs`
+
+## Context
+
+Review 0002 found the MCP surface pinned to one protocol revision and two behind the
+published specification, and returning text only: no structured content, no output
+schemas, and no hint that any of the ten tools were read-only. The finding is accurate and
+so is its severity, which is P2 rather than P1 for a reason the row states itself — a
+client that predates a field still reads the text block, so the surface works, it just
+cannot be validated and cannot cache.
+
+The tempting fix is to look up what the newest revision says and implement it. ADR-067
+settled a neighbouring question one release ago: a row that cites a document nobody read
+is decoration that misdescribes the artefact. The same trap waits here, and it is worse,
+because a protocol is the one thing in this repository where being confidently wrong is
+not a style defect — it is a client that believes a feature is on.
+
+So the revisions this server speaks were read. Each of the three changelogs was fetched
+and read, and what follows is what actually changed for a server on stdio — which is a
+smaller list than the changelogs, because most of each revision's changes are about HTTP
+transports, sessions and authorization that a stdio server never had.
+
+## Rulings
+
+1. **The revision list cites what changed for this transport.** Three revisions are
+   supported. The 2025-06-18 revision already had structured tool output, so the gap this
+   review found was never the missing feature — it was the missing declaration. The
+   2025-11-25 revision changed nothing a stdio server depends on, and is supported because
+   a client on it is a real client. The 2026-07-28 revision removed the handshake, made
+   every request carry its own version in `_meta`, added a discovery method that servers
+   must implement, required a result-type field on every result, required a cache lifetime
+   on list results, removed the liveness method, and moved the resource-not-found code from
+   the implementation range to the invalid-params one. Each of those is implemented and
+   each has a test.
+
+2. **The version is read from the request, and remembered only where a client needs it.**
+   A request that names its version in `_meta` is answered at that version, with no
+   memory involved — that is the newest revision's shape, and it is stateless by design. A
+   client that negotiated through `initialize` sends bare requests forever after, so the
+   stream keeps one remembered revision for it. A client that never says anything gets the
+   newest. The remembered value exists for exactly one group of clients and is labelled as
+   the residue of a handshake the specification removed.
+
+3. **An unsupported version fails at the one place the client checks.** `initialize`
+   answers with the server's own revision, which is the older revision's guidance and the
+   only thing that works there. A per-request version we do not speak returns the
+   specification's own error for it, naming every revision we do. Silence there would be
+   the failure this whole row is about: a client proceeding against a shape we never
+   implemented.
+
+4. **Removed methods are refused by name, not dropped.** The liveness method was removed
+   in the newest revision, so a client on it gets a method error saying which revision
+   removed it, while a client on either older revision still gets its answer. Dropping the
+   method entirely would have broken the older clients; answering it to everyone would
+   have told the newest one we support something we do not.
+
+5. **Every result carries both blocks, and every tool declares both shapes.** The text
+   block is what a client that predates structured content reads; the structured block is
+   what a client validates against the declared output schema and what it can index. One
+   without the other leaves half the clients guessing. The same holds for a failure, which
+   stays a result rather than a protocol error, because a client that renders an exception
+   renders no answer at all. The declared shape per tool is what makes the pair checkable,
+   and the test calls every tool with the least a client would send and validates what
+   comes back.
+
+6. **The byte ceiling bounds the text block only.** A caller who sets a ceiling wants a
+   smaller answer, not a malformed one: the structured block stays whole, so it keeps
+   matching the schema, and the text block says how much was omitted and how to ask for
+   more. A tool that truncated the structured block would make the one representation a
+   client can validate fail validation.
+
+7. **The schema checker is in this repository.** The output schemas are here, so the thing
+   that reads them is here too: a dependency would be a second copy of rules that could
+   drift out of date without anyone noticing, and a tool that has to validate an answer
+   has to work on a machine where nothing was installed. The checker understands a small
+   set of keywords and throws on one it does not, because a keyword it ignored would turn
+   every schema using it into decoration — the check would pass, and the payload would not
+   match.
+
+## Consequences
+
+A client on any of the three revisions gets an answer in the shape it asked for, and one on
+the newest can cache the tool list for an hour instead of asking on every conversation. A
+client that validates gets a real failure message when a payload grows a field nobody
+wrote down, which is how the schemas here were corrected on the day they were written:
+five of them described a payload that does not exist in that shape.
+
+Nothing here adds a resource. Rules and decisions are readable through tools today, and
+publishing them as resources is the next half of the review's fix rather than a detail of
+this one.
+
+## Rejected
+
+- **Implementing the newest revision only.** It would have broken every client that
+  negotiates, and the specification's own guidance for `initialize` is to answer with what
+  the server speaks.
+- **Echoing whatever version a client asks for, as the old code did.** That was the
+  original defect: the echo was true for one revision and a guess for the rest.
+- **Answering the removed liveness method to everyone.** A client on the newest revision
+  would read a success as support for a method the protocol deleted.
+- **Truncating the structured block with the text.** The one representation a client can
+  check would fail the check.
+- **Taking a JSON Schema validator from npm.** Zero runtime dependencies is a hard
+  requirement, and the schemas being validated live in this file, so the rules and the
+  reader of the rules belong together.
+- **Declaring a resource capability with no resources behind it.** A capability is a
+  promise a client will wait on, so it is declared only when a method answers.

package/docs/decisions/ADR-069-the-conformance-lint-checks-the-published-specification.md

@@ -0,0 +1,90 @@
+# ADR-069 — The conformance lint checks the published specification
+
+Status: **accepted** · 2026-10-13 · filed as S44
+**Affects:** `graph lint`, `skills install`, `src/graph/spec.mjs`, `src/graph/speccheck.mjs`,
+`src/commands/graph.mjs`, `src/commands/skillsinstall.mjs`, `test/graphspec.test.mjs`
+
+## Context
+
+Review 0002 found that the Agent Skills specification sets out limits this package does not
+check, and that `graph lint` — the command whose whole job is to hold skills to their
+declarations — checks bytes and structure instead. Forty extra characters of description
+are not a formatting problem: a client that validates a skill at load time will refuse it,
+and the discoverer of that is whoever runs the client, not whoever wrote the file.
+
+So the specification was fetched and read rather than recalled. Two things fell out of
+reading it. The first is that the review's list was incomplete: it named the name, the
+description and the compatibility limits, and missed four rules — a name may not start or
+end with a hyphen, may not contain consecutive hyphens, and must equal the directory it
+lives in, and the main file is recommended to stay under five hundred lines. The second is
+that the specification is explicit about which of its rules are musts and which are
+recommendations, which is a distinction a lint has to keep.
+
+It also turns out most real descriptions use a folded block scalar, `description: >-` with
+indented lines under it. A reader that treated the arrow as the value measured a
+two-hundred-character description as two characters, and the first run of this lint produced
+that wrong answer on five real skills before the reader was rewritten.
+
+## Rulings
+
+1. **The lint checks the specification it names, and the flag refuses any other name.**
+   `--spec agentskills` is the only value that works, and a different one is a usage error
+   rather than an unnamed default. A lint against an unnamed set of rules cannot be argued
+   with, and the argument is the whole point of publishing the rules.
+
+2. **A must is an error and a recommendation is a warning.** Name, description and
+   compatibility limits, a name that disagrees with its directory, and a file not named
+   SKILL.md fail the exit code. Body length and line count warn, because the specification
+   words them as recommendations for progressive disclosure, and a lint that fails on a
+   recommendation teaches a reader to skip the lint — which costs it every rule it does
+   enforce.
+
+3. **The name rules live in one place, and `skills install` asks them too.** The
+   specification requires a name to equal its directory, and an install creates the
+   directory from the name. So an install is not the place to allow a name the lint would
+   reject: it is the last moment anybody can notice before a skill is deployed that no
+   client can address by the name inside it. The command refuses with the rule broken.
+
+4. **The frontmatter reader reads block scalars.** A folded or literal block is the ordinary
+   spelling of a long description, and a reader that misses one reports a conforming skill
+   as broken. This is the one rule in this file that is about the reader rather than the
+   skill, and it is here because the first version of this lint was confidently wrong about
+   five files.
+
+5. **The conformance pass is additive to the registry pass, not gated by it.** The registry
+   answers "does the bookkeeping match the files"; the specification answers "would a
+   client accept these files". A reader with no registry can still lint a skill directory,
+   so the two passes run side by side, and a path the first cannot read is a warning from
+   the second and never a second error for the same thing — one defect, one exit path.
+
+6. **Progressively disclosed fields that are not musts are reported as unknowns, not
+   rejected.** An experimental field and a vendor's extra key appear as warnings naming the
+   field. The specification says clients may add metadata, and a lint that failed on it
+   would fail on a skill built exactly the way the specification invites.
+
+## Consequences
+
+Thirty warnings and no errors across the skills this workspace declares, which is the
+outcome the review predicted. The warnings are real: seven bodies over the recommended
+size, one at six times it, and a set of vendor-specific frontmatter keys the specification
+does not define. None of those is a defect in the skills — they are the cost a reader pays
+per activation, which is what the recommendation exists to make visible.
+
+The naming rules now hold at install time as well as at lint time, so a skill can no longer
+be written to a directory its own name contradicts.
+
+## Rejected
+
+- **Recalling the limits instead of reading them.** The review's summary was missing four
+  of them, and the ones it missed are the ones that break an install.
+- **A byte-length check alone.** The specification counts characters and tokens, and the
+  body limit is a token recommendation with a line count beside it; a byte check answers a
+  different question.
+- **Failing the exit code on the body recommendations.** They are recommendations, and a
+  gate that fails on advice is a gate that gets skipped.
+- **A dependency on the upstream reference validator.** It would be a second copy of the
+  rules, maintained elsewhere, and this package ships no runtime dependencies.
+- **Rejecting an unknown frontmatter field.** The specification invites extra metadata, and
+  a lint that failed on it would refuse skills built to specification.
+- **Two copies of the name rules, one for the lint and one for the install.** The one
+  nobody linted would be the one that let an unaddressable skill through.

package/docs/decisions/ADR-070-the-json-payload-carries-its-own-version.md

@@ -0,0 +1,91 @@
+# ADR-070 — The JSON payload carries its own version
+
+Status: **accepted** · 2026-10-13 · filed as S51
+**Affects:** `src/output/index.mjs`, `src/commands/index.mjs`, `src/commands/mcp.mjs`,
+`src/commands/graph.mjs`, `src/commands/rules.mjs`, `src/commands/skills.mjs`,
+`src/commands/skillsinstall.mjs`, `src/commands/init.mjs`, `src/argv.mjs`,
+`src/commands/help.mjs`, `test/jsoncontract.test.mjs`
+
+## Context
+
+Review 0002 filed that `--json` output had no schema version and no compact form:
+`emitJson` was `JSON.stringify(value, null, 2)` and every payload was four columns of
+whitespace. Two consequences, both invisible until they mattered.
+
+The first is that a reader could not detect a shape change. An agent that parses `--json`
+gets a document that parses, and if a field is renamed the parse still succeeds and the
+next lookup returns `undefined`. A version in a README does not help: nobody reads the
+README, and it goes stale without failing anything. The version has to travel inside the
+payload, because the payload is the only thing a reader is guaranteed to see.
+
+The second is that indentation is paid for on every call. The reader of `--json` is
+`JSON.parse`, not an eye; the same document is a third larger for nothing. The one case
+where indentation is worth its bytes is a terminal, where a person is the reader.
+
+Writing the contract test found the two things the review missed. `doctor` did not use
+`emitJson` at all — it hand-rolled `emit(JSON.stringify(..., null, 2))` — and neither did
+`mcp --list`, `graph lint`, `rules list`, `skills index`, `skills find`, `skills show` or
+`skills install`, so seven surfaces answered `--json` in a shape no reader could rely on.
+And `fail()` wrote only to stderr, which means a command that failed under `--json`
+returned an empty stdout: the caller was told something went wrong and given no way to
+learn what. A failure is a result — the question was asked and the answer is "no, and here
+is why" — and it belongs where results go.
+
+One note on how this was found, because it is the argument for the test existing at all:
+the contract test itself passed a `mcp` entry whose argument list was silently dropped by
+an `Array.isArray` mistake, so it ran `mcp --json` with no `--list`, and the command served
+on stdio and waited forever. A contract that cannot fail loudly is not a contract.
+
+## Rulings
+
+1. **The version is in the payload, not in the documentation.**
+   `schemaVersion` is written into every object payload that does not already carry one.
+   Adding a field is not a bump; removing, renaming or retyping one is. A reader that
+   wants to know what changed reads the field, not a changelog.
+
+2. **Compact is the default and `--pretty` asks for indentation, with a terminal as the
+   exception.** A pipe gets one document on one line because its reader is a program; a TTY
+   gets indentation because its reader is a person. The flag exists to override the
+   terminal case, not the pipe.
+
+3. **One place decides the shape for every command.** `dispatch` sets the indent default
+   and the failure mode once, from the parsed flags. Threading either through twenty-five
+   call sites would mean twenty-five places to forget, and the one that forgot would be the
+   one a reader pipes into a script.
+
+4. **A failure under `--json` is a JSON document on stdout.** `ok: false`, the error, the
+   remedy and the exit code. Without this, a scripted caller has an empty document and a
+   non-zero exit and nothing else, which is the failure mode that makes an agent give up
+   rather than retry.
+
+5. **`emitJson` owns the byte ceiling too.** Every `emit(JSON.stringify(...))` call that
+   also passed `maxBytes` becomes an `emitJson(payload, { maxBytes })` call, so the
+   truncation announcement reads the same everywhere and no surface gets an unbounded
+   document by being spelled differently.
+
+6. **The contract test is generated from the command registry.** It iterates the commands
+   that emit JSON, runs each through the real binary, and asserts one line, no leading
+   whitespace, a parse, and the version. A command added to the registry is not
+   automatically in the test — the test asserts the list is still real, and the list is the
+   contract.
+
+## Consequences
+
+Every `--json` payload now begins with `schemaVersion`, and twelve commands no longer have
+a private idea of what `--json` means. `doctor --json` went from seventeen indented lines
+to one, and the failure of `skills install` in a bare directory now answers in the shape
+its caller asked for.
+
+What is not here: the README half of the review's fix — an exit-code table and a per-command
+JSON contract generated from the registry. The exit codes are already named in `EXIT`, and
+generating README prose from them is a documentation change that belongs to whoever owns
+the README, so it is noted in the tracker rather than done silently here.
+
+## Rejected
+
+- **A version in a comment or the changelog only.** It is exactly the artefact that goes
+  stale without failing anything.
+- **Threading `--pretty` through the call sites.** Twenty-five chances to forget, to fix a
+  problem that has one place to live.
+- **Keeping failures on stderr under `--json`.** It leaves a scripted caller with an empty
+  document and a number, which is a contract that cannot be acted on.

package/docs/decisions/ADR-071-a-rule-that-can-be-narrowed-is-written-narrow.md

@@ -0,0 +1,106 @@
+# ADR-071 — A rule that can be narrowed is written narrow
+
+Status: **accepted** · 2026-10-14 · filed as S50
+**Affects:** `src/projection/rules.mjs`, `src/projection/targets.mjs`,
+`src/projection/surfaces.mjs`, `src/projection/project.mjs`, `rules/stacks/*.md`,
+`test/scoped.test.mjs`, `test/project.test.mjs`, `test/surfaces.test.mjs`
+
+## Context
+
+Every per-rule file this tool ships was always-on, and so was every stack profile, because
+profiles had nowhere else to live: they reached a reader through the generated region in
+AGENTS.md and through nothing else. A repository on Cursor got the profile in both places,
+and a repository on opencode got it in one place, always, whether or not a Python file was
+ever open.
+
+Two vendors document how to make that conditional, and both were read rather than recalled.
+Cursor attaches a rule with `alwaysApply: false` and `globs` "when a matching file is in
+context", and separates patterns with commas. Antigravity takes `trigger: glob` with a
+comma-separated `globs`, requires patterns that start with `*` to be **quoted** so YAML does
+not read them as alias anchors, and **discards a rule with invalid frontmatter without a
+message**. It also documents a 24 KB per-file limit and a 20,000-token budget for always_on
+rules, past which rules are demoted to pointers — so an eager profile is not merely
+wasteful, it is a budget the reader spends on rules that did not apply.
+
+One row of the surface table is the reason this needed a ruling rather than a patch.
+Decision 3 — an always-on rule emits no scoping frontmatter — was settled on Claude Code's
+`paths:` key silently failing to lazy-load for quoted values and YAML sequences
+(anthropics/claude-code#13905, #17204, #19377), with the documented examples not valid YAML.
+That decision stands. This record says what happens on either side of it, and does not
+rewrite it.
+
+## Rulings
+
+1. **A profile leaves the region only when every selected surface can narrow it.**
+   `desiredRegion` asks whether all of them can; when one cannot, the profile stays in the
+   region and a note says which surface stopped it. The alternative — writing the profile
+   only as a scoped file for the three surfaces that can scope it — leaves a Claude Code
+   reader with no rule at all, and a rule nobody loads is worse than a rule that loads
+   eagerly.
+
+2. **Three surfaces can narrow, and the answer is per surface rather than per key.**
+   Cursor (`globs`), Antigravity (`trigger: glob` plus `globs`) and Copilot (`applyTo`)
+   can; Claude Code cannot, for the reason in decision 3; opencode cannot, because it has
+   no per-rule channel at all (`rule: null`). `canScope` names the answer, and the shipped
+   gate now probes the scoped frontmatter shape as well as the eager one, so a row that
+   emitted `globs` without documenting it would fail the gate rather than ship an inert
+   key.
+
+3. **Antigravity's patterns are quoted, and a scoped rule always carries a description.**
+   Unquoted `**/*.py` is an alias anchor and the whole rule is discarded silently. Cursor
+   documents no description plus no globs as manual `@`-mention only, so a scoped rule with
+   neither would never attach to anything — a rule that looks installed and is not.
+
+4. **A scope that matches everything is a defect, not a narrowing.** `**`, `**/*` and `*`
+   are what a surface applies when it is given no pattern, so a profile carrying one is
+   the eager profile wearing a costume. An empty list is the same thing spelled plainly.
+   Both are refused by `describeDefect`, where a profile's other frontmatter is checked.
+
+5. **A quoted pattern is read as the pattern.** `parseFrontmatter` did not strip quotes, so
+   a profile author quoting `"src/**/*.ts"` would have projected a glob matching nothing.
+   The reader now strips them, because the alternative is that the obvious spelling of a
+   glob silently does not work.
+
+6. **One construction, and the gate uses it.** `scopedTargets` delegates to `ruleTargets`
+   with the profile marked `alwaysApply: false`, and `checkTargets` calls the same function
+   `plan` does. A scoped file that was planned and written but never gated would show a
+   clean `check` over a stale reader — the asymmetry this module exists to prevent.
+
+7. **The region keeps a pointer section.** A profile that moved is named in AGENTS.md with
+   its patterns and the files it moved to. A reader who knows the profile was there and
+   cannot find it will otherwise conclude it was deleted, and the region's source list is
+   the provenance a review reads.
+
+8. **The shipped profiles carry the scope that selected them.** Eighteen of nineteen: node,
+   typescript, react-web, react-native, python, uv, rust, go, ruby, jvm, swift, dotnet,
+   dart, deno, elixir, android, cloudflare-workers, container. Each is anchored on the file
+   whose presence selected it, so a reader loads the profile exactly when the thing that
+   made it apply is in play. `connectiq` has no scope: it is selected by a tag no file
+   announces, and inventing an anchor for it would be a claim about a file this tool has
+   never seen.
+
+## Consequences
+
+A repository on Cursor, Copilot or Antigravity now receives its stack profiles as
+`.cursor/rules/python.mdc`, `.agents/rules/python.md` and
+`.github/instructions/python.instructions.md`, each carrying the patterns and no
+`alwaysApply: true`, with a pointer in the region replacing the profile text. A repository
+whose surfaces include opencode or Claude Code sees no change at all, and says why in a
+note when it asked for narrowing it could not have.
+
+A monorepo gets the same treatment per package, because package regions call the same
+`desiredRegion` (ADR-066).
+
+## Rejected
+
+- **Emitting `paths:` for Claude Code anyway.** Its parser defect is documented with issue
+  numbers and the failure is silent: the reader loads nothing and believes the rule is
+  installed.
+- **Narrowing on whichever surfaces can, and leaving the rest to find the profile
+  elsewhere.** It trades an eagerly loaded rule for a rule that is never loaded, which is
+  the same defect with a worse diagnosis.
+- **A catch-all default scope for a profile with none.** It would look like narrowing in a
+  diff and behave exactly like not narrowing.
+- **Reusing the mdc rule-file path for a profile file.** The name comes from `ruleName`,
+  which reads `.mdc` targets; a profile has none, and the first version of this wrote
+  `null.mdc` and then `python.md.mdc` before either was noticed.

package/docs/decisions/ADR-072-the-budget-is-a-declaration-beside-the-gates.md

@@ -0,0 +1,104 @@
+# ADR-072 — The budget is a declaration beside the gates, not a number inside the projection
+
+Status: **accepted** · 2026-10-14 · filed as S38
+**Affects:** `src/projection/manifest.mjs`, `src/measure/context.mjs`,
+`src/projection/project.mjs`, `src/commands/sync.mjs`, `simt tokens`, `simt-dev check`,
+`test/tokens.test.mjs`, `test/surfaces.test.mjs`
+
+## Context
+
+Review 0002 row S38 asks for a per-repository always-on budget: "for these 7 roots,
+generated always-on bytes are at most 30 KB". Plan 0003 spells the mechanism as R08, and
+the plan was read rather than recalled, which is how the two facts below were found.
+
+The first is that R08 as written presupposes R07. Its compiler "packs kernel lines by
+priority class" and `check` reports "each cut line" — and there are no kernel lines
+without R07's `projection.mode` and the per-line kernel frontmatter it introduces, whose own default stays
+`full` until R02 proves a narrow mode is not worse. With no kernel there is nothing to cut,
+so the packing half of R08 cannot be built honestly before the R01–R05 evaluation has been
+run. Building it anyway would mean inventing a kernel nobody measured.
+
+The second is where the number lives. R08 says `projection.budget.bytes`. In this tool
+`projection` is a generated key: `GENERATED_KEYS` names it, and `withGenerated()` replaces
+it with the tool's own `{ simtDevSha, version }` on every write. A budget written there
+would be deleted by the next `upgrade`, and — because `manifestDrift` compares only the
+generated keys — not reported as deleted. The repo would watch its budget disappear on a
+green gate. That is the same defect this package treats as unrecoverable everywhere else:
+content the repository chose must be preserved by the repair, not overwritten by it.
+
+So the part of R08 that is independent of the kernel ships now, and the part that is not
+does not.
+
+## Rulings
+
+1. **The budget is a repository declaration at the top level of the manifest, beside
+   `limits` and `gates`.** It is content the repo chose, so it survives `upgrade`, and the
+   plan's `projection.budget.bytes` spelling is superseded rather than edited in place. The
+   default is not a field either: it is the value whoever measures applies when the key is
+   absent, so `simt tokens` and the gate read one number from one place.
+
+2. **A repository that declares nothing is not reported as having declared the default.**
+   `buildManifest` omits the key entirely when the repo has none, which keeps
+   `budget.declared` an honest fact. Writing the default in would make every adopted repo
+   look like it had chosen the review's line — a reader told "declared: true" about a
+   number nobody wrote is being lied to about the only thing the number is for.
+
+3. **The default is 30,000 bytes and it is the review's figure, not this tool's
+   measurement.** It is written as 30,000 rather than 30 × 1024 because it is a ceiling and
+   the conservative reading of "at most 30 KB" is the one that trips first.
+
+4. **Over budget is reported, never enforced.** The finding names the bytes measured, the
+   bytes declared and what was not done: nothing was cut, because the projection is still
+   in full mode. A reader who sees an over-budget line must not conclude the projection
+   shrank, and a gate that failed here would fail on a measurement this tool has not
+   validated against a study.
+
+5. **`simt tokens` carries the finding it would raise, produced by the same function.**
+   One function words the fact, so the report and the gate cannot describe the same
+   overflow two ways.
+
+6. **The rows themselves are unchanged.** Which rules move behind skills is R01–R05's
+   finding, not this record's, and a budget that silently dropped rules would be enforcing
+   a decision nobody has made.
+
+7. **The meter is the definition of the number, and the gate quotes it.**
+   `simt-dev check` calls the same `measureRoot` the meter does rather than summing the
+   bytes of the targets it happens to compare. That was the other way round first, and it
+   was wrong: the meter also counts managed skills and `.mdc` files, so one repository had
+   two budgets and two different numbers for the same declaration. Two definitions of one
+   ceiling is the same defect as two projections of one fact, one layer up.
+
+8. **The gate raises the finding and does not block on it.** `budget` is in both
+   non-blocking sets, `check` and `sync` alike. Nothing was cut, so the projection is
+   exactly what the repository agreed to project; failing the run over a ceiling it wrote
+   down itself would train people to raise the ceiling. R08 says non-blocking for the same
+   reason, and this record agrees with it now that the finding has a shape to be.
+
+9. **The cost of ruling 7 is accepted rather than avoided.** `check` now reads what the
+   meter reads — the projected region, the rule files, the skills — on every run, where it
+   previously compared bytes it had already read. A cheaper gate would have to keep its own
+   notion of what counts, and this is the one place where the two are not allowed to differ.
+
+## Consequences
+
+S38's accept criterion is now checkable rather than asserted: a repository can declare the
+line it intends to carry, and `simt tokens` reports it against that line and says how far
+over it is. Three tests hold the two halves that were easy to get backwards — the budget
+survives an upgrade, a repository that declared nothing keeps `declared: false`, and the
+finding says that nothing was cut.
+
+What has not landed: the gate reporting the budget as a finding, and R08's packing. The
+first needs the number the gate is already comparing — the bytes of the region and the rule
+files it checks — so that `check` and `tokens` cannot report different totals for one
+repository; that is a wiring decision, not a measurement. The second needs R07.
+
+## Rejected
+
+- **The plan's `projection.budget.bytes`.** The generated block is replaced wholesale on
+  every upgrade, and nothing in the repair would notice.
+- **A default written into every manifest.** It would make every adopted repo look like it
+  had chosen a number it never chose.
+- **Cutting lines to fit the budget now.** There is no kernel to pack and no measurement
+  saying which lines a reader can lose.
+- **Failing the gate on an over-budget projection.** The number is this tool's own
+  estimate, and a gate that fails on its own estimate teaches a reader to ignore it.