simt-dev 0.2.1__tar.gz → 0.3.0__tar.gz

{simt_dev-0.2.1 → simt_dev-0.3.0}/.gitignore

@@ -7,4 +7,10 @@
 git.config
 
 .pybuild/
-dist/
+dist/
+
+# Local index, evidence ledger and benchmark run outputs (plan 0003 §4).
+# Task descriptors in .simt-dev/bench/tasks/*.json are committed; runs are not.
+.simt-dev/index.sqlite
+.simt-dev/ledger.jsonl
+.simt-dev/bench/runs/

{simt_dev-0.2.1 → simt_dev-0.3.0}/CHANGELOG.md

@@ -6,6 +6,242 @@ All notable changes to this package are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-10-17
+
+### The rules and the decisions are readable as MCP resources
+
+A client that wants to browse this tool's rules and rulings had no way to: every answer came back from a tool call with an argument in it. They are addressable now, as one URI per rule and one per decision record, with the byte size each will cost stated up front — the one number a client cannot get without spending the read.
+
+Both resource revisions of the specification were read rather than recalled, and they disagree about the behaviour that decides whether a client retries or gives up: a missing resource is `-32602` on the newest revision and `-32002` on the two older ones, and neither lets a server answer with an empty body. A decision record is redacted on the way out, because a resource travels further than the CLI did (ADR-074).
+
+### A plan is resumed one slice at a time
+
+`simt plan next` returns the next ready slice and only its section. `simt plan done` rewrites that one row, and previews the change unless `--yes` is given. The directories and the table format come from the `plans` key in `simt.json` when a repository sets one; otherwise the tracker template delivered with the tool is used, which reads `docs/plans` and `docs/reviews` (ADR-081, ADR-082). `init` keeps a manifest key it does not write, which is what lets `plans` survive a re-init.
+
+### The rules are enforced at the tool call
+
+Three rules that text does not hold — a `git push`, a `--no-verify`, an edit inside a generated region — are now a decision before the tool call. `simt agent-hooks install` writes one policy into the harnesses that read a hooks file, and keeps every key it does not own. `simt agent-hook` is the entry point those harnesses call (ADR-079).
+
+### A line the repository already proves does not ship
+
+A rule line may say when the repository already proves it. `simt sync` drops that line, and `--explain` names the line and the fact, so a removal is visible rather than silent (ADR-078).
+
+### The region leads with this repository's commands
+
+The projected region opens with the commands this repository actually runs, derived from its committed gates and runner, in both the full projection and kernel mode (ADR-077).
+
+### A change to what an agent reads can be measured
+
+`simt bench mine`, `run`, `report`, `ablate` and `probes` measure a change to projected context against tasks taken from this repository's own history. A change that cannot be run says `unmeasured` in its record rather than implying a result (ADR-076).
+
+### What each reader loads, and a transcript split
+
+`simt harness loaders` reports what each reader loads at session start, in bytes, and what its size cap drops. DeepSeek is one of those readers. `simt tokens --session` splits a local Claude Code or Codex transcript into rules, file reads and tool output.
+
+### A name this tool owns is not reported as a repository
+
+`simt rules why` keeps this tool's own names (`simt-priority`, `simt-hooks`, and the rest) and still redacts a repository the reader cannot open (ADR-080).
+
+## [0.2.2] — 2026-10-14
+
+### A repository can ask for a smaller projection
+
+`simt tokens` measured the cost and `check` now holds the line the repository draws: `budget.bytes`
+in `simt.json` is how many always-on bytes that repository has agreed to carry, and both the meter and
+the gate report the overflow with the two numbers in them. It sits beside `gates` rather than inside
+`projection`, because that key belongs to this tool and an upgrade replaces it.
+
+`mode: kernel` is the other half. It keeps the rules a reader cannot do without — the ones a hard
+constraint or a command depends on — and defers the rest behind a `## Deferred rules` section that
+names each one and the command that shows it. A Python fixture projects 16% smaller. `full` is still
+the default, because nobody has measured yet whether the smaller projection loses compliance, and a
+tool that made that trade silently would be deciding it on the reader's behalf (ADR-073).
+
+### A repository can declare how many always-on bytes it is willing to carry
+
+`simt tokens` has reported that number since the meter landed, against a constant nobody
+could argue with. A repository can now say what it will carry — `budget: { bytes: N }`
+beside `limits` and `gates` in the manifest — and both `simt tokens` and `simt-dev check`
+measure against that line. One declaration, one meter, one function that words the finding.
+
+The declaration is deliberately *not* inside `projection`, which is the one block this tool
+owns and `upgrade` is allowed to replace: a number written there would be deleted silently
+on the next upgrade and never reported as drift. And a repository that declares nothing is
+reported as declaring nothing, rather than being quietly handed the default as though it
+had chosen it.
+
+Over budget is reported and never fails the gate. Nothing was cut — the projection is
+still full mode, every rule loaded as written — so the honest thing to say is "you are
+over your line", not to fail a repository over a ceiling it wrote down itself. Which rules
+move behind skills stays with the evaluation that has to decide it (ADR-072).
+
+### A repository can declare the always-on bytes it intends to carry
+
+`simt tokens` measured the number; it could not be held to one. A manifest now carries
+`budget.bytes` — a declaration beside `limits` and `gates`, not inside `projection`,
+because that block is regenerated on every upgrade and nothing in the repair would notice
+its budget disappearing. A repository that declares nothing is measured against the
+review's 30 KB and reports `declared: false` rather than looking like it chose it.
+
+Over budget is reported, never enforced, and the report says what was not done: nothing
+was cut, because the projection is still in full mode. Which rules move behind skills is a
+measurement that has not been taken yet, and a budget that quietly dropped rules would be
+enforcing a decision nobody made (ADR-072).
+
+### A stack profile loads only when a matching file is in play
+
+A stack profile used to be always-on everywhere, because profiles reached a reader through
+the generated region in AGENTS.md and through nothing else. A profile can now declare
+`simt-scope`, and a repository on Cursor, Copilot or Antigravity gets it as a file the
+surface attaches on patterns: `.cursor/rules/python.mdc` with `globs` and
+`alwaysApply: false`, an Antigravity rule with `trigger: glob`, a Copilot
+`.instructions.md` with `applyTo`. AGENTS.md keeps one line naming the profile, the
+patterns and the file it moved to — a profile that vanishes from the region reads as one
+that was deleted.
+
+The narrowing happens only when every selected surface can do it. Claude Code's `paths:`
+key is documented and silently fails to lazy-load for quoted values, and opencode has no
+per-rule channel at all, so a repository carrying either keeps its profiles in the region
+and is told which surface stopped it. A rule that never loads is worse than a rule that
+loads eagerly.
+
+Reading the two vendors' docs changed the shape of this: Antigravity requires patterns
+starting with `*` to be quoted or YAML reads them as an alias anchor and the rule is
+discarded with no message, and it documents a 20,000-token budget for always_on rules past
+which they are demoted to pointers — so eager profiles cost the reader a real budget. A
+`simt-scope` that matches everything is now refused, since that is the same behaviour with
+a narrowing-looking spelling (ADR-071).
+
+### Every `--json` payload says which version it is
+
+An agent that parses `--json` had no way to notice that a field had moved: the parse
+succeeds, the lookup returns `undefined`, and the answer is quietly wrong. Every payload now
+opens with `schemaVersion`, and a version in a comment is not a version, so it travels in
+the document every reader is guaranteed to see.
+
+The same document is now one line rather than four columns of whitespace, because the reader
+of `--json` is a program and it pays for every byte. `--pretty` asks for the other form, and
+a terminal gets it without being asked, because there the reader is a person.
+
+Writing the contract test found two things the review that asked for this missed. Eight
+commands — `doctor`, `mcp --list`, `graph lint`, `rules list`, and the `skills` ones — had a
+private `emit(JSON.stringify(..., null, 2))` instead of the shared helper, so `--json` meant
+something different depending on which command you asked. And a command that *failed* under
+`--json` wrote only to stderr, so a scripted caller got an empty document and a non-zero
+exit and no way to learn what went wrong. It now answers in the shape it was asked in (ADR-070).
+
+### `graph lint` now checks skills against the published specification
+
+The Agent Skills specification sets limits nobody here was checking: a name of lowercase
+letters, digits and single hyphens that equals the directory it lives in; a description
+under 1,024 characters; a compatibility note under 500; a body recommended under 5,000
+tokens because an agent loads all of it once the skill activates. `graph lint --spec
+agentskills` checks every skill against those, and the specification was fetched rather
+than recalled — reading it turned up four rules the review that asked for this did not
+list, including the one that breaks installs.
+
+What the specification calls a must fails the exit code; what it calls a recommendation
+warns. A lint that fails on advice is a lint that gets skipped. `skills install` now asks
+the same name rules, since the directory is created from the name and an unaddressable
+skill would be the last thing anyone notices.
+
+### The MCP surface speaks three protocol revisions, and answers in the shape each asks for
+
+The server was pinned to one revision and returned pretty JSON in a text block, so a
+client could read the answer but could not validate it, could not cache it, and could not
+tell a read-only tool from one that writes. All three published revisions were read rather
+than guessed at, and each is answered in its own shape: the newest drops the handshake for
+a version carried on every request, adds a discovery method servers must implement,
+requires a result-type field and a cache lifetime on list results, and deleted the liveness
+method — which older clients still get, and newest clients are told is gone by name.
+
+Every tool now declares what it returns and says it is a reader, and every call returns
+the answer in both shapes: the text block for a client that predates structured content,
+the structured block for one that validates against the declared schema. The byte ceiling
+bounds the text only, so the block a client can check still checks. The schema checker
+that makes this testable lives in the package rather than in a dependency.
+
+### Which harnesses a repository is set up for is now answerable
+
+`simt-dev harness detect` looks at the configuration directories that exist and says
+which harnesses this repository — and, with `--user`, its reader — is set up for. It
+claims presence and nothing else: a directory found is not a claim about what its owner
+reads, because the tool cannot answer that without a vendor document, and a guess here
+would be the reader's problem the first time it was wrong. A harness that reads
+AGENTS.md is served by the standard surface whatever else it reads, and every surface row
+now records that in three values rather than two, because "reads AGENTS.md" and "is
+covered for this harness" are not the same sentence — Copilot's CLI reads it and its
+editor, code review and cloud agent do not.
+
+No new harness rows ship with it. The candidates are recorded as directory names, which
+claim presence and not coverage; a row still requires the vendor document it cites, and
+one that reads nothing has to be added on purpose.
+
+### A monorepo gets rules for each of its packages
+
+One repository, one projection: every package under the root was given the root's rules,
+so a React application inside a node workspace was handed the node profile and nothing
+else, and the profile that should have applied to it was applied by nobody. The rule that
+package needed was not wrong — it was missing.
+
+Packages are now discovered from the declarations that already list them (npm and pnpm
+workspaces, turbo, Cargo members, `go.work`, Gradle includes) rather than by walking the
+tree, because a declaration states which directories are members and a marker file only
+says there is a build here. The root keeps what every package shares; each package that
+selects something new gets a generated region carrying exactly its own delta, and a
+package that selects nothing new gets no file at all. `check` reports every package
+region and fails on any one of them, and `compare` counts the drifted regions rather than
+the repositories that hold them.
+
+A gate can also name the directory it runs in, which is what a monorepo with no root test
+script needs: `gates.cwd` maps a gate to a directory, a directory that does not exist or
+resolves outside the repository fails the event and is reported by `check` before the
+commit rather than at it, and a directory named for a gate that is not declared is
+reported as the inert entry it is.
+
+### One rule set, shared by the repositories that agreed on it
+
+Several repositories want the same rules and each kept its own copy, so a policy change
+was several edits that could be several-minus-one, and the repository that missed it
+carried instructions nobody there wrote. A pack is that shared set: `packs` in the manifest
+declares it, the bytes live in the repository, and a digest of them is recorded so nobody
+has to trust that the two agree.
+
+A pack's rules are selected by the same matcher as any profile and appear in the region's
+source list under the pack's own directory. Precedence is the repository, then a pack it
+declares, then what the tool ships, and every replacement is reported rather than silent.
+
+A pack that disagrees with its pin still projects — the gate blocks and prints both
+digests, because dropping it would let the repair delete the rules it is reporting. One
+that is missing blocks with a remedy that restores it, and one with no digest is reported
+without failing anything, since its rules render correctly. `compare` lists every pack and
+the digest it is pinned to, so a repository behind a shared change is visible before
+anyone follows stale instructions. Nothing is fetched: the bytes are in the repository,
+which is what makes the rendered region reproducible from what the reader has (ADR-065).
+
+### `simt tokens` counts what a reader loads
+
+Review 0002 filed the estate's always-on context at 90 KB per turn, 72% of it a paragraph
+an earlier repository had already loaded — a number produced by reading seven
+repositories by hand, which ages the moment a rule is edited and cannot be re-derived by
+the reader who has to act on it.
+
+`simt tokens` is that reading, as a command. It reports the bytes this tool wrote per
+channel (region, rule files, skill metadata), an approximate token figure, and — with
+`--repos` — the same figure across a workspace, with every repeated paragraph attributed
+to the first root that carries it. A region that ends past a harness's read limit is
+reported with its byte offset, using the same numbers the existing check uses.
+
+Three choices keep the figure honest, and all three are recorded in ADR-064: the meter
+counts what the projection wrote and reports hand-written bytes beside it rather than
+folding them into the budget; a region is the span between its two markers, so the blank
+line a person left above the marker is billed to nobody; and an over-budget repository is
+reported rather than failed, because a meter that went red would train people to ignore
+the number.
+
+S38 stays open — this is the instrument. Whether the estate gets under 30 KB is R07's
+kernel, R08's budget field and R11's dedupe, measured with this.
+
 ## [0.2.1] — 2026-10-13
 
 ### `init` writes in place; the backup tag and adopt branch are opt-in
@@ -327,6 +563,9 @@ never ran `simt hooks install` again will find nothing until the dependency is r
 and `simt hooks install --yes` is re-run. That is a real upgrade step and it is called out
 here rather than discovered.
 
+[0.3.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.3.0
+[0.2.2]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.2
+[0.2.1]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.1
 [0.2.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.2.0
 [0.1.1]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.1.1
 [0.1.0]: https://github.com/QuazarMedia/simt-dev/releases/tag/v0.1.0

{simt_dev-0.2.1 → simt_dev-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simt-dev
-Version: 0.2.1
+Version: 0.3.0
 Summary: 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.
 Project-URL: Homepage, https://github.com/QuazarMedia/simt-dev
 Project-URL: Repository, https://github.com/QuazarMedia/simt-dev

simt_dev-0.3.0/bin/simt-dev.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// simt-dev - developer and agent tooling for the SIMT ecosystem.
+//
+// POSIX only (ADR-012). package.json declares os: [darwin, linux], so npm refuses
+// the install elsewhere rather than letting a hook fail obscurely.
+
+import { parse } from '../src/argv.mjs';
+import { EXIT, fail, jsonFailMode, jsonIndentDefault } from '../src/output/index.mjs';
+
+try {
+  const argv = process.argv.slice(2);
+  const parsed = parse(argv);
+  if (!parsed.ok) {
+    process.exit(parsed.code);
+  }
+  const { flags, positional } = parsed.value;
+
+  // No arguments at all is a usage error, not a silent help dump: an agent that
+  // ran the wrong thing should be told so rather than handed 40 lines of prose.
+  if (positional.length === 0 && !flags.help && !flags.version) {
+    process.exit(fail('no command given', EXIT.USAGE));
+  }
+
+  jsonIndentDefault(flags.pretty === true);
+  jsonFailMode(flags.json === true);
+
+  // The one command that runs on somebody else's hot path, and therefore the one that
+  // does not load the registry. `agent-hook` is called before every tool call an agent
+  // makes, so its latency is a product requirement rather than a nicety (plan 0003
+  // R15), and the registry's imports - detection, projection, the bench corpus - cost
+  // tens of milliseconds before the command itself starts. Measured on the machine
+  // this was written on: 127.7 ms through the registry against 91.5 ms with only this
+  // module's imports, where the bare runtime is 86.9 ms of it.
+  //
+  // Only the exact spelling the renderers write takes this path. Anything else -
+  // including `agent-hook --help` - loads the registry, so help stays the one list of
+  // every command and this shortcut cannot become a second, thinner command surface.
+  if (positional[0] === 'agent-hook' && !flags.help && !flags.version) {
+    const { agentHookCommand } = await import('../src/commands/agenthook.mjs');
+    process.exit((await agentHookCommand(positional.slice(1), flags)) ?? EXIT.OK);
+  }
+
+  const { dispatch } = await import('../src/commands/index.mjs');
+  process.exit((await dispatch(argv)) ?? EXIT.OK);
+} catch (error) {
+  process.exit(fail(error?.message ?? String(error), EXIT.FAIL));
+}

simt_dev-0.3.0/docs/decisions/ADR-064-the-context-meter-counts-what-the-tool-wrote.md

@@ -0,0 +1,107 @@
+# ADR-064 — The context meter counts what the tool wrote, and says what it did not
+
+Status: **accepted** · 2026-10-13 · filed after review 0002 S38
+
+**Affects:** the `tokens` command, the new context meter in `src/measure/context.mjs`, and
+the structure field `readLimitFindings` now returns.
+
+## Context
+
+Review 0002 S38 measured the estate by hand and filed a number: 90,042 bytes of always-on
+context per turn across seven workspace roots, of which 64,738 bytes — 72% — were a
+paragraph an earlier root had already loaded. It also found a repository whose region
+ended past the 32,768 bytes Codex reads before it stops.
+
+Two things are wrong with a finding that arrives as a hand count. The count ages: the
+moment a rule is edited, the number is a description of a version nobody has any more.
+And it cannot be re-derived by the reader who has to act on it — it was produced by
+reading seven repositories, which is the work the tool exists to do.
+
+Plan 0003 R06 asks for the same measurement as a command, with an acceptance criterion
+that names the figures it must reproduce: the 90,042 bytes, the 64,738 redundant, and a
+repository beyond Codex's limit. Reproducing a hand count is only possible if the meter
+counts what the hand counted — which means settling what "always-on" means before
+writing the code, because every choice here changes the number the criterion will be
+checked against.
+
+The answer is the hardest question in the command, and it is not "bytes".
+
+## Rulings
+
+1. **The meter counts what this tool wrote, and reports hand-written bytes beside it
+   rather than folding them in.** The budget being defended is the projection's: a
+   repository's own 40 KB of prose in AGENTS.md is an authoring decision the tool did not
+   make and cannot shrink. Billing it to a projection budget would make the budget
+   unachievable for reasons outside the projection, which is how a budget stops being
+   read. So every channel reports `generatedBytes` and `readerBytes` separately, and the
+   headline figure is the generated one.
+
+2. **A token count is an approximation, and it is labelled as one every time it is
+   printed.** Four bytes per token, stated in the payload and in the text, with a `~`
+   in front of the number. Nobody has measured this corpus, and a figure that looks exact
+   invites the reader to spend it as though it were.
+
+3. **A region is the span between its two markers, and nothing outside it counts as
+   generated — not even the blank line above the marker.** This is the defect the first
+   test run caught: subtracting the hand-written prefix from the file billed the
+   projection for a newline a person typed. In a command whose whole claim is that it
+   counts exactly, that byte is the whole argument.
+
+4. **Redundancy is byte-exact, blank-line-paragraph by blank-line-paragraph, measured
+   across roots in sorted path order.** That is the method review 0002 used by hand, and
+   it is reproducible: the same corpus measured twice gives the same figure, which is
+   what lets the number appear in a commit message. Order is therefore load-bearing —
+   `discover` sorts, and the first root to carry a paragraph owns it. Reordering the walk
+   would move bytes between roots, so nothing downstream re-sorts them.
+
+5. **The budget is reported, not enforced, and the command exits 0 for it.** A
+   repository over budget is a fact about the repository. A meter that went red for it
+   would train people to ignore the number it exists to print. Enforcement is R08's
+   business, and it is a manifest field rather than a constant so a repository can argue
+   with its own budget.
+
+6. **A pointer is counted once, as the file it points at.** One reader, one copy of the
+   text; enumerating the target as well would double every rule the projection replaced
+   with a pointer, which is precisely the saving the pointer was made for.
+
+7. **MCP `tools/list` bytes are reported once, outside every repository total.** The
+   same tool list is loaded whatever the repository, so summing it into each root would
+   multiply one number by the number of roots and call the result a workspace cost.
+
+8. **The flag is `--repos`, not `--workspace`.** Plan 0003 R06 wrote `--workspace`, but
+   `--workspace <path>` has been a value flag since plan 0002, where it names a
+   directory of skill sources. One flag cannot mean two things depending on which
+   command read it — that is the silent-ignore defect the argument parser's own header
+   refuses — so the new one is `--repos`, and it says what it measures: every repository
+   under the root, in sorted order.
+
+9. **No MCP tool exposes this yet.** The byte counts are already in the payload, but a
+   tool that returns a per-repository context cost is a second public surface to keep
+   honest. It arrives when there is a second caller for the logic to be wrong in.
+
+## Consequences
+
+- `simt tokens` answers "what does a turn pay for this repository", and
+  `simt tokens --repos` answers "what does a turn pay for the workspace". Both print
+  bytes and a labelled approximation; `--json` carries the same figures, because two
+  renderings of one question must not be able to disagree (ADR-050).
+- The command refuses two shapes of path — a directory holding repositories when
+  `--repos` was not passed, and a directory holding none — with remedies that are
+  commands rather than locations.
+- `readLimitFindings` grew structured fields (`reader`, `limitBytes`, `endByte`,
+  `overBy`) beside its prose, so the meter and the check that already reported the
+  Codex limit are reading the same numbers rather than each re-deriving them.
+- S38 stays open. What landed is the instrument. The 30 KB figure it wants needs R07's
+  kernel, R08's budget field, R11's dedupe, and R01–R05's evaluation of whether moving
+  the process rules behind skills costs compliance — and this meter's job is to report
+  whether that work succeeded.
+
+## Rejected
+
+- **Failing the run when a repository is over budget.** The measurement would become
+  something people route around, and the number would go with it.
+- **Treating a pointer as free rather than counted once.** Its target is still loaded;
+  calling that zero is the sort of accounting that makes a report unfalsifiable.
+- **`--workspace` for the new flag, on the grounds that the plan says so.** The plan
+  wrote that before `--workspace` was a value flag for something else, and a plan is a
+  record of an intention, not a reason to ship two meanings for one name.

simt_dev-0.3.0/docs/decisions/ADR-065-a-pack-is-one-shared-rule-set-pinned-by-digest.md

@@ -0,0 +1,97 @@
+# ADR-065 — A pack is one shared rule set, vendored into the repository and pinned by digest
+
+Status: **accepted** · 2026-10-13 · filed as S39
+**Affects:** `src/packs.mjs`, `src/projection/rules.mjs` (`loadRules`, `select`), `src/projection/manifest.mjs` (`packs` field), `src/commands/sync.mjs` (`check`), `src/compare/row.mjs` (`packs`, `problems`), `test/packs.test.mjs`
+
+## Context
+
+S39 found estate product policy shipping as if it were universal: a profile that named
+one company's domain layer, a rule file that named its Firebase environment variables, and
+a `gender` sentinel in a map profile. Fourteen repositories shared one set of those rules
+and each carried its own copy, so a policy change was fourteen edits that could be thirteen.
+
+Two answers were available. The first is a remote: a pack published somewhere, a `source`
+in the manifest, and the renderer fetching it. The second is a directory in the repository
+holding the bytes, with a digest recorded so nobody has to trust that the two agree.
+
+The remote is the one that reads better in a design document and is worse for the reader
+this tool is for. A region rendered from a fetched pack is a region whose bytes depend on
+something the receiving repository does not contain: a reader who clones the repo, deletes
+their network, and runs the gate gets a different answer, and a reviewer approving a diff
+is approving text they cannot produce from what is in front of them. That is the single
+failure this repository exists to prevent, and a shared-rules feature is exactly where it
+would arrive.
+
+The vendored answer has one obvious weakness: updating a pack is a commit in every
+repository that declares it, not one push somewhere. That is the cost of the property
+above, and it is the right trade — a rule a reader cannot account for is worth less than a
+rule that is one merge behind.
+
+ADR-061 already settled half of P4. A pack may have carried the skill registry, and the
+review's fix line says it should; ADR-061 ruled the registry to be workspace data that the
+package no longer ships. A second source for it would reopen that ruling by accident, from
+a feature that is not about skills at all.
+
+## Rulings
+
+1. **A pack's bytes live in the adopting repository, and the manifest records a digest of
+   them.** The manifest gains a `packs` list of `{name, source, version, digest}`; the
+   directory the tool reads is a fixed one, and `source` and `version` record where the
+   bytes came from for a human and for a future fetch. Nothing in a projection reads a
+   path outside the repository it is rendering into.
+
+2. **Precedence is ranked, not special-cased: the repository's own profile, then a pack it
+   declares, then what the tool ships.** The ranking is one table read by the selector, so
+   the precedence and the order the files are collected in cannot disagree. A replacement
+   is reported in the existing `shadowed` list, because a profile that silently replaced
+   another leaves a reader unable to tell which of two texts they are being held to.
+
+3. **A pack that is present but disagrees with its pin still projects.** What is
+   questioned is the pin, and the gate blocks and prints both digests. Dropping the pack
+   instead would let the remedy the finding names — `sync` — delete every rule the pack
+   carries, which is the opposite of what a reader who ran it meant. A pack that is absent
+   has nothing to project and blocks with a remedy that restores it; a pack with no digest
+   is reported and does not block, because its rules render correctly and only the record of
+   which bytes they were is missing.
+
+4. **A pack carries rule files, not a skill registry.** A profile it ships is selected by
+   the same matcher as any other and appears in the region's source list under its pack's
+   directory. A registry inside a pack is read by nothing, and that is the ruling rather
+   than an oversight: ADR-061 makes the registry workspace data, and a second source for
+   it needs its own decision about which of two registries answers.
+
+5. **`compare` reports every pack and the digest it is pinned to, per repository.** The
+   pinned digest, not the computed one — it answers "which bytes was this declared at", and
+   a row reporting the new digest would hide the mismatch from anything reading the JSON.
+   A pack that cannot be used is a problem on the row; one that is merely unpinned is a
+   note, which is the same division the gate draws.
+
+6. **`packs` is repository-owned content, not a generated field.** Which packs a repository
+   uses is its decision, so a re-init must not empty it, and the drift check does not
+   compare it. What is compared is the directory's digest against the pin.
+
+## Consequences
+
+- A group of repositories sharing one rule set declares the same pack and vendors the same
+  bytes; a policy change is a commit per repository, and the digest is what makes an
+  unmerged one visible before a reader follows stale instructions.
+- Nothing fetches anything. A pack cannot be pulled by name, cannot be published by this
+  tool, and cannot be refreshed by `upgrade`. That is the deliberate half of the answer,
+  and it leaves the fetch as a later ruling rather than a missing feature.
+- The rule provenance digest does not cover pack bytes, so `projection.simtDevSha` still
+  answers "what did the tool render" and the pack digest answers "which bytes were these".
+  Two answers to two questions, both in the manifest.
+
+## Rejected
+
+- **Fetching a pack from a remote during projection.** It makes the rendered bytes depend
+  on something the receiving repository does not carry, and it puts the network inside a
+  command whose defining property is that it is deterministic and offline.
+- **Refusing to project a pack whose digest does not match.** The remedy would delete the
+  rules it reports, so the tool would cause the damage it exists to report.
+- **One flag per pack state**, so a reader could choose what blocks the gate. Three flags
+  for one directory's worth of state is a configuration surface nobody will read twice, and
+  the division that matters — does the region account for its rules — has one defensible
+  answer.
+- **A pack carrying the skill registry**, which proposal P4 asked for before ADR-061
+  settled where the registry comes from.

simt_dev-0.3.0/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.