simt-dev 0.2.0 → 0.2.2

package/docs/decisions/ADR-066-a-monorepo-projects-once-per-package.md

@@ -0,0 +1,115 @@
+# ADR-066 — A monorepo projects once per package
+
+Status: **accepted** · 2026-10-13 · filed as S41
+**Affects:** `init`, `sync`, `check`, `compare`, `hooks run`, `src/monorepo.mjs`,
+`src/projection/rules.mjs`, `src/projection/project.mjs`, `src/hooks/dispatcher.mjs`,
+the `gates.cwd` manifest field
+
+## Context
+
+A monorepo received exactly one projection: the root's `AGENTS.md`, fingerprinted from
+the root. Everything below the root was invisible to the detector, so a React
+application inside a node workspace was handed the node profile and nothing else, while
+a Workers service beside it was handed the same. Neither the repository's rules nor the
+tool's output said another package existed with different rules.
+
+The estate's own monorepos made this expensive rather than merely wrong. Fourteen
+repositories hold between them hundreds of packages, and one rule set per repository
+means every package is told the union of what the root can see and nothing about what it
+is. The profile that should have applied to a package is applied by nobody, so the rule
+that package needed was simply missing — not wrong, missing.
+
+Three shapes of answer were available, and the cheapest is the one that was not taken.
+Writing every package's full profile set into the root duplicates text the reader loads
+once per turn (review 0002 S38 measured that duplication at 72% of the workspace's
+always-on bytes). Writing the root's set into each package does the same and worse.
+Projecting the root once and each package once, with each package carrying only what the
+root does not, adds bytes proportional to the number of packages that actually differ,
+and nothing at all to the ones that do not.
+
+The harder half is that `check` is the gate. A projection the tool writes but does not
+check is a projection nobody is held to, and a monorepo that drifts in one package would
+report `current` while CI is green and the reader is wrong.
+
+## Rulings
+
+1. **A workspace is read from its declarations, never from a directory scan.** npm
+   workspaces, pnpm's package list, turbo's workspace list, Cargo members, a go.work use
+   list and Gradle includes are all read, because each one is a file that already states
+   which directories are members and why. Finding a marker file by walking the tree is
+   the alternative, and it is the one this repository's rules forbid: a heuristic that
+   cannot be explained by a declaration is a heuristic a reader has to reverse-engineer
+   from its output, and the only way to find out why a directory was or was not given
+   rules is to read this tool's source. A declaration this tool cannot read is a
+   directory it does not discover, which is an honest absence rather than a guess.
+
+2. **The root keeps the shared rules; a package carries its delta.** The root is
+   fingerprinted as before and renders the core plus every profile the root's own signals
+   select. A package is fingerprinted the same way, and renders only the profiles the
+   root did not already select. A reader opening the package file is therefore never
+   shown a rule the root already gave them, and a reader of the root file is never shown
+   a rule that belongs to one package. The duplication the workspace reader pays for is
+   one sentence of orientation per package, and the bytes it pays for scale with the
+   packages that differ rather than with the repository count.
+
+3. **An empty delta writes nothing.** Two node packages under one workspace select the
+   same profiles, so the delta is empty and there is no file. A file whose entire content
+   is a claim about rules it does not contain is always-on bytes spent on nothing, which
+   is the cost S38 exists to measure, and the reader is left looking for rules that are
+   not there.
+
+4. **A gate names its directory in a map, not in a new shape for the command.** The
+   manifest's gate commands stay name-to-command-line strings, and an added map gives
+   each gate a directory to run in. Re-reading a command string to discover where it runs
+   would mean the answer to "where does anything run" lives inside a value whose purpose
+   is something else, and a manifest written by an earlier release would have to be
+   rewritten to gain the capability. A directory that does not exist, or that resolves
+   outside the repository, fails the event with a message naming which of the two things
+   is wrong, because they are repaired by different edits. Containment is checked on the
+   resolved path rather than on the text: a relative traversal and a symlink both pass a
+   prefix test applied to a string.
+
+5. **`check` reports a bad directory before a commit, not at one.** The dispatcher fails
+   closed on the same condition, so a reader would otherwise find out by being unable to
+   commit — after writing a commit, which is the wrong order for the news. The same
+   applies to a directory entry naming a gate that is not declared at all: the entry is
+   inert, the reader believes the gate runs where it says, and nothing anywhere says
+   otherwise.
+
+6. **`compare` counts findings, not repositories.** One monorepo with three drifted
+   packages is one repository with three findings. A summary that said one problem would
+   understate the work by a factor of three, and a reader comparing two runs would see a
+   single count that moves by three when the underlying state changed by three. The
+   repository still counts once among repositories with problems, because that count is
+   about how much work a person has.
+
+## Consequences
+
+- A workspace whose members are declared in a form this tool does not read gets the root
+  projection only, exactly as it did before. That is a gap to close by adding a row to
+  the declaration table, not a behaviour to document.
+- Nested regions are checked, and their findings are printed with their paths. A reader
+  who edits a package file by hand is told which file, which is the same information the
+  root's own drift finding carries.
+- The package file is a generated region like any other: the markers, the source list and
+  the repair command all behave identically, so there is no second kind of generated file
+  for a reader to learn.
+
+## Rejected
+
+- **Scanning for marker files instead of reading declarations.** Rejected for ruling 1.
+  A marker file answers "is there a build here", which is not the question; a declaration
+  answers "is this a member of the workspace", which is.
+- **Folding every package's rules into the root region.** Rejected for ruling 2. It is
+  the smallest change to make and it makes every reader in the workspace carry every
+  package's rules, which is the cost S38 measured and S38's kernel exists to remove.
+- **A directory field on each declared command.** Rejected for ruling 4, for the reason
+  recorded there: it puts where a gate runs inside the value that says what it runs, and
+  it makes an old manifest unreadable rather than merely older.
+- **Skipping the directory check because the dispatcher already fails closed.**
+  Rejected for ruling 5. The dispatcher's refusal is correct but late; the reader who
+  learns about it from a failed commit has already done the work the commit would have
+  saved them.
+- **Refusing to project a monorepo at all until every package is understood.** Rejected:
+  a root-only projection is a strictly smaller claim than it was, and refusing to improve
+  it because the improvement is incomplete makes the reader worse off than the tool.

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.