@descent-vtt/spec-guard 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,153 @@ All notable changes to this project are documented here. Versions follow
 may change in a minor release — each such change is listed under **Changed**
 with the flag that restores the previous behaviour.
 
+## 0.9.0
+
+A project's policy can live in its `package.json`, and `spec-guard --watch`
+reports again as the tree changes, re-executing only the rules a change
+affected. [ADR-0014](docs/adr/0014-configuration-and-watch.md).
+
+### Added
+
+- **Options in `package.json`, under `"specGuard"`:** `specs`, `engine`,
+  `strict`, `allowMissingTargets`, `allowEmptyScope`, `ignoreStatus`,
+  `includeSpecs`, `defaultSkips`, `maxSnippets` and `concurrency`.
+  - Read from the root's `package.json` only, never a parent directory's.
+  - Validated before anything runs. An unknown key, an option that belongs to one
+    invocation (`format`, `verbose`, `watch`, ...), a string where a boolean goes
+    or a count out of range is exit 2, naming the file and the key. `--help` and
+    `--version` still work under a broken `package.json`.
+  - The command line wins: patterns replace `specs`, and every on/off option the
+    file can set gained its opposite - `--no-strict`,
+    `--no-allow-missing-targets`, `--no-allow-empty-scope`, `--no-ignore-status`,
+    `--no-include-specs` and `--default-skips`.
+  - A report that took anything from the file names it in a line above its
+    summary, with what the command line overrode; the JSON report carries
+    `config`.
+  - `query` applies the keys a query reads. The MCP server reads the file again
+    for every request, as it reads the specs.
+- **`spec-guard --watch`.** Reports, then reports again whenever something under
+  the root changes, until Ctrl+C, which exits 130.
+  - Saves are batched: 50 ms of quiet, or 500 ms after the first change. Enter
+    re-runs everything. A change no rule reads updates the status line only.
+  - Only the rules whose directive or inputs changed are re-executed. On this
+    repository a save in `src` re-executes 21 of 60 rules in a median of 21 ms -
+    over the 15 ms it was built to, as ADR-0014 reports - and a save elsewhere
+    takes 2-3 ms.
+  - One recursive `fs.watch` on the root, and no dependency.
+  - Refuses `--engine` - it scans in-process, where it sees what each rule reads -
+    and `--json`, `--format json|sarif`, `--print-baseline`, `--fail-fast` and
+    `--allow-empty`.
+  - A test changes trees at random and requires every report a session gives to
+    equal a fresh run's, however the change is reported, and six deliberately
+    broken sessions have to fail it.
+- **One door for every read** (`Io`, `nodeIo`, `readText`, `watchTree`), and the
+  session behind watch mode (`createSession`, `runWatch`, `createFactCache`,
+  `createMemo`) in the programmatic API. `runSpecGuard` is `planRun`, an
+  execution and `reportRun`, and those two are exported.
+  `createJavaScriptEngine(io, memo)` builds a scanner over a door, and
+  `createCachedEngine(engine, fallback)` names what it falls back to.
+- `scripts/bench-watch.mjs`, which measures a session on a copy of this
+  repository.
+
+### Changed
+
+- **API:** `defaultDirectoryReader` and `statOrNull` are gone for `nodeIo`.
+  `WalkOptions.readDirectory` is `WalkOptions.io`, `enumerateCandidates` takes an
+  `Io` as its third argument, and `createTreeIndex(root, io)` takes a whole door.
+  `Assertion.missingTargets` is gone: only execution ever wrote to it.
+- This repository keeps its specs in `package.json`, and its selfcheck, CI run
+  and SARIF upload run `spec-guard` without patterns.
+- **Mutation testing in CI runs in four parallel shards.** The full sweep took
+  42m39s against a 45-minute job limit, and a slower runner was cancelled on the
+  same source. Hosted runners vary by a fifth or more on identical work.
+  - Each shard mutates its own files, balanced on per-file minutes read from
+    sweep logs (`scripts/mutation-timeline.mjs`).
+  - A final job merges the reports (`scripts/mutation-shards.mjs`). It refuses a
+    missing shard, a file mutated twice or by the wrong shard, and shards that ran
+    different tests, then applies the 97% gate to the merged score.
+  - Every shard runs every test: Stryker's vitest runner now has `related: false`.
+  - A full sweep starts from no incremental file, and a branch's shard from only
+    its own part of main's. Stryker reports the verdicts an incremental file holds
+    for files a run does not mutate, and on the first sharded sweep every shard
+    reported every other shard's files with the previous sweep's verdicts. The
+    merge refused that sweep.
+  - No mutants were left out, the per-mutant timeout is unchanged, and the gate
+    is unchanged. [ADR-0003](docs/adr/0003-mutation-testing.md).
+
+### Fixed
+
+- **A binary file was a gap for every rule sharing its pass.** A plain run scans
+  every rule over one scope together, and kept one ledger for them: a binary file
+  holding one rule's symbol was reported against all of them with their matches
+  summed, so `--strict` failed rules over files that did not hold their symbol.
+  The count of files whose comments could not be classified leaked the same way.
+  Each rule now has its own.
+- **Two runs of one tree could list skipped files in different orders**, and past
+  the ledger's cap of 100, name different ones: files entered the ledger as their
+  reads finished. They now enter in walk order.
+- Executing one resolved assertion twice named each missing target twice. Nothing
+  did so before watch mode.
+- A test of the MCP server's durations that failed about one run in 53, on
+  floating-point error in the test.
+
+## 0.8.0
+
+An architecture document can now state conventions about names and layout: what
+the files in a directory are called, what every package holds, and which files
+come in pairs. [ADR-0013](docs/adr/0013-structure-assertions.md).
+
+### Added
+
+- **`@assert-structure`**, with exactly one of three claims per directive:
+  - `pattern="*.entity.ts, index.ts"` - every file in scope is named by one of
+    the patterns;
+  - `required="package.json, README.md"` - every directory holds each entry.
+    The directories are the targets, or with `dirs="*"` their children and with
+    `dirs="**"` every directory below them, empty ones included. An entry may be
+    a path, may end in a glob, and must be a directory when it ends in `/`;
+  - `partner="[name].test.[ext], tests/[dir]/test_[name].py"` - every file has
+    one of its partners. Three placeholders and no other grammar: `[name]` and
+    `[ext]` split the file name at its last dot, and `[dir]` is the file's
+    directory below its target.
+
+  Names are compared exactly from directory listings, never by looking a path
+  up, so `Readme.md` does not satisfy `README.md` on Windows or macOS any more
+  than it does on Linux. A scope with no files or no directories fails, as does
+  a partner template naming the file itself and a `required` target that is a
+  file. When a file has no partner because it *is* one, the report says so and
+  suggests the `exclude`. Takes `glob`, `exclude`, `max`, `allow-empty`,
+  `baseline` and `ratchet`. Spec files are in scope, and symbolic links are not
+  followed. All structure rules in a run share one walk per target and read
+  each directory once.
+- `spec-guard query` and the MCP server show what a structure rule asks of a
+  path: whether a file's name is allowed, the partners it needs, and - for a
+  file in a directory a `required` rule holds - that rule.
+- The JSON report carries `claim` on structure results. A match with `line: 0`
+  is a path rather than a place in one, and SARIF annotates a misnamed or
+  partnerless file at its first line, and a directory missing an entry at the
+  directive, with the directory in the message.
+- `checkStructure`, `createTreeIndex`, `expandPartner`, `partnerTemplateIssue`
+  and `requiredEntryIssue` are exported, with their types. `walkPaths` takes an
+  `onDirectory` callback.
+
+### Changed
+
+- **`executeAssertion` needs a `tree`** in its options: `createTreeIndex(root)`,
+  the run's directory listings, beside the `imports` and `hasFiles` caches it
+  already takes. Only code calling `executeAssertion` directly is affected;
+  `runSpecGuard` and the command line create it themselves.
+- The MCP server's instructions and the `get_architectural_rules` description
+  tell an agent that the rules for a path now include what it must be named and
+  the partner files it needs.
+- **Mutation score 98.63%** over 6,939 mutants, up from 0.7.0's 98.47%, with 92
+  survivors - one fewer than before the 676 mutants this release adds.
+  `structure.ts` is at 100%, and every other module has exactly the survivors it
+  had, less one in `glob.ts` that the new tests turned into a genuine hang. A
+  local sweep had reported four survivors in the new listing cache as killed; CI
+  found them, and they are tested. See
+  [ADR-0003](docs/adr/0003-mutation-testing.md).
+
 ## 0.7.0
 
 Two things an architecture document could not do before. It can state the shape

package/README.md

@@ -422,6 +422,99 @@ reading `tsconfig.json`, which is the resolver
 [ADR-0011](docs/adr/0011-layers-and-cycles.md) declines to become, for the
 reasons it gives.
 
+### `@assert-structure` - what files are called, and what comes with them
+
+Architecture documents state conventions over sets of files rather than naming
+files one by one. Each directive makes exactly one of three claims:
+
+```md
+<!-- @assert-structure target="src/domain" exclude="*.test.ts" pattern="*.entity.ts, index.ts" -->
+<!-- @assert-structure target="packages" dirs="*" required="package.json, README.md" -->
+<!-- @assert-structure target="src/handlers" exclude="*.test.ts" partner="[name].test.ts" -->
+```
+
+- **`pattern`** - every file in scope is named by one of the patterns. They are
+  globs, read like `glob=`: without a `/` against the file name, with one
+  against the path from the root.
+- **`required`** - every directory holds every entry. Without `dirs` the
+  directories are the targets; `dirs="*"` means their immediate children and
+  `dirs="**"` every directory below them. An entry may be a path
+  (`src/index.ts`), may end in a glob (`*.csproj`), and must be a directory
+  when it ends in `/`.
+- **`partner`** - every file has a partner, named by a template.
+
+Each failure names the file or directory, since there is no line to point at:
+
+```text
+✖ docs/architecture.md:3  @assert-structure
+    files in src/domain must be named *.entity.ts or index.ts (excluding *.test.ts)
+    expected no misnamed files, found 1
+      src/domain/helpers.ts  matches none of *.entity.ts, index.ts
+
+✖ docs/architecture.md:4  @assert-structure
+    directories matching * under packages must contain package.json, README.md
+    expected no directories missing an entry, found 2
+      packages/billing  missing README.md
+      packages/web  missing package.json, README.md
+
+✖ docs/architecture.md:5  @assert-structure
+    files in src/handlers must each have a partner [name].test.ts (excluding *.test.ts)
+    expected no files without a partner, found 1
+      src/handlers/refund.ts  has no partner src/handlers/refund.test.ts
+```
+
+A partner template has three placeholders and nothing else - no regular
+expressions, no conditionals - so a reader can expand one by eye:
+
+| Placeholder | For `src/api/user.handler.ts`, `target="src"` |
+| --- | --- |
+| `[name]` | `user.handler` - the file name up to its last dot |
+| `[ext]` | `ts` - what follows that dot |
+| `[dir]` | `api` - the file's directory below the target, empty at the top |
+
+A template without a `/` names a file beside it. One with a `/` is a path from
+the root, which is how a mirrored test tree is written:
+`partner="tests/[dir]/test_[name].py"`. A comma-separated list gives
+alternatives, any one of which will do.
+
+The partners themselves are in scope unless `exclude` says otherwise. Forgetting
+to exclude them is loud rather than silent, and says what probably happened:
+
+```text
+      src/handlers/order.test.ts  has no partner src/handlers/order.test.test.ts (it is the partner of src/handlers/order.ts - exclude it?)
+```
+
+Some things fail rather than pass, because each is a rule that would otherwise
+check nothing:
+- a scope holding no files, or selecting no directories (`allow-empty` as
+  everywhere else);
+- a template that names the file itself (`partner="[name].[ext]"`);
+- a `required` target that is a file.
+
+**Names are compared exactly, on every platform.** Whether `README.md` exists is
+decided by reading its directory, never by asking the filesystem for the path.
+That lookup finds `Readme.md` on Windows and macOS and does not find it on Linux,
+and the same rule would pass on a laptop and fail in CI.
+
+A structure rule reads names, never contents. It walks with the run's usual
+skips, follows no symbolic link, and counts the spec files - which every other
+rule leaves out, and which a naming rule about `docs/adr` is about. `max`,
+`baseline` and `ratchet` work as they do on `@assert-absence`, and a baseline
+lists files or directories. `spec-guard query` shows what a rule asks of a file
+that does not exist yet:
+
+```text
+src/handlers/invoice.ts (does not exist yet)
+  1 rule from 1 document
+
+  Architecture  (docs/architecture.md)
+    :5 @assert-structure  files in src/handlers must each have a partner [name].test.ts (excluding *.test.ts)
+      partner: src/handlers/invoice.test.ts
+```
+
+[ADR-0013](docs/adr/0013-structure-assertions.md) has the design and what it
+costs.
+
 ### `@assert-present` - this file exists
 
 ```md
@@ -435,23 +528,27 @@ Passes when every listed path exists relative to `--root`. Directories count.
 
 | Attribute | Applies to | Meaning |
 | --- | --- | --- |
-| `target` | absence, count | Comma-separated paths to search, relative to `--root`. Default `.` |
+| `target` | all but present | Comma-separated paths, relative to `--root`. Default `.` |
 | `symbol` | absence, count | The literal string to search for (or a regex with `regex="true"`) |
 | `file` | present | Comma-separated paths that must exist |
-| `expected` | absence, count | Upper bound for absence; exact count for count |
-| `min` / `max` | count (`max` also on absence) | Inclusive bounds |
-| `glob` | absence, count | Include-only file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
-| `exclude` | absence, count | Paths to leave out, gitignore-style: `src/config/**`, `tests`, `*.test.ts` |
+| `expected` | all but present | Exact count for count; an upper bound everywhere else |
+| `min` / `max` | count (`max` on all but present) | Inclusive bounds |
+| `glob` | absence, count, structure | Include-only file filters, e.g. `*.ts,*.tsx` (ripgrep `-g` semantics) |
+| `exclude` | all but present | Paths to leave out, gitignore-style: `src/config/**`, `tests`, `*.test.ts` |
 | `regex` | absence, count | Treat `symbol` as a regular expression |
 | `word` | absence, count | Require word boundaries, so `Primary` does not match `PrimaryButton` |
 | `ignore-case` | absence, count | Case-insensitive matching |
 | `comments` | absence, count | `ignore` (default) or `include` for matches inside comments |
 | `module` | import-absence, import-count | Which dependency, matched like `exclude` |
 | `order` | layers | The layers, from the one everything may depend on to the one that may depend on everything |
+| `pattern` | structure | The names every file in scope must match one of |
+| `required` | structure | The entries every chosen directory must hold; a trailing `/` means a directory |
+| `dirs` | structure, with `required` | Which directories below each target: `*` for children, `**` for all |
+| `partner` | structure | Partner templates, any one of which must exist: `[name].test.[ext]` |
 | `types` | import assertions, layers, cycles | `include` (default) or `ignore` for `import type` |
-| `allow-empty` | absence, count, import assertions, layers, cycles | Tolerate a scope that holds no files, or a layer that matches none. Off by default - see below |
-| `baseline` | absence, import-absence, layers | Known violations that do not count: `path` or `path:count` |
-| `ratchet` | absence, import-absence, layers | `two-sided` (default) or `one-way` - see below |
+| `allow-empty` | all but present | Tolerate a scope that holds no files, a layer that matches none, or no chosen directories. Off by default - see below |
+| `baseline` | absence, import-absence, layers, structure | Known violations that do not count: `path` or `path:count` |
+| `ratchet` | absence, import-absence, layers, structure | `two-sided` (default) or `one-way` - see below |
 | `reason` | all | Human-readable justification, printed on failure |
 
 Unknown attributes are an error, not a shrug: `expct="1"` fails the run instead
@@ -661,6 +758,7 @@ sources they follow, and what is deliberately not implemented.
 
 ```bash
 spec-guard [patterns...] [options]     # execute the directives
+spec-guard --watch [patterns...]       # execute them again whenever the tree changes
 spec-guard query <paths...> [options]  # the rules in force for files or directories
 spec-guard mcp [options]               # serve the rules over MCP on stdio
 ```
@@ -670,17 +768,18 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 | `-r, --root <path>` | Codebase root that assertions resolve against (default: cwd) |
 | `--spec <pattern>` | A spec glob or path, repeatable. `query` and `mcp` take their specs only from here |
 | `-v, --verbose` | Print passing assertions too |
+| `--watch` | Report, then report again as the tree changes, until Ctrl+C |
 | `--fail-fast` | Stop at the first failing assertion |
 | `--json` | Machine-readable report on stdout (same as `--format json`) |
 | `--format <human\|json\|sarif>` | Output format. `sarif` uploads to GitHub code scanning |
 | `--engine <auto\|rg\|js>` | Search engine (default `auto`: scanner for small trees, ripgrep for big ones) |
-| `--strict` | Treat analysis that could not be completed as a failure |
-| `--allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
-| `--allow-empty-scope` | Warn instead of failing when an assertion inspects no files |
+| `--strict` / `--no-strict` | Treat analysis that could not be completed as a failure |
+| `--allow-missing-targets` / `--no-allow-missing-targets` | Warn instead of failing when a `target` path does not exist |
+| `--allow-empty-scope` / `--no-allow-empty-scope` | Warn instead of failing when an assertion inspects no files |
 | `--print-baseline` | Print the `baseline="..."` that would exempt today's violations, and exit |
-| `--no-default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
-| `--ignore-status` | Execute directives in draft, proposed and superseded documents too |
-| `--include-specs` | Also count matches inside the spec files themselves |
+| `--no-default-skips` / `--default-skips` | Search `.git`, `.hg`, `.svn` and `node_modules` too |
+| `--ignore-status` / `--no-ignore-status` | Execute directives in draft, proposed and superseded documents too |
+| `--include-specs` / `--no-include-specs` | Also count matches inside the spec files themselves |
 | `--max-snippets <n>` | Failure snippets per assertion (default 5) |
 | `--concurrency <n>` | Search passes in flight at once (default 8) |
 | `--allow-empty` | Exit 0 when no spec file matched the patterns (about the run, not an assertion) |
@@ -688,6 +787,93 @@ spec-guard mcp [options]               # serve the rules over MCP on stdio
 
 Patterns are expanded by spec-guard itself, so quoted globs behave identically
 on Windows, macOS and Linux. A directory expands to the Markdown files in it.
+The second form of each on/off option exists to override a configuration.
+
+### Configuration
+
+The options that are a project's policy can live in `package.json`, under
+`"specGuard"`, so CI, a pre-commit hook and the MCP server an agent starts all
+hold the same rules the same way:
+
+```json
+{
+  "specGuard": {
+    "specs": ["docs/**/*.md", "README.md"],
+    "strict": true
+  }
+}
+```
+
+| Key | Command line | Value |
+| --- | --- | --- |
+| `specs` | patterns, `--spec` | a non-empty array of globs |
+| `engine` | `--engine` | `"auto"`, `"rg"` or `"js"` |
+| `strict`, `allowMissingTargets`, `allowEmptyScope`, `ignoreStatus`, `includeSpecs`, `defaultSkips` | the flag of that name | `true` or `false` |
+| `maxSnippets` | `--max-snippets` | an integer, 0 or more |
+| `concurrency` | `--concurrency` | an integer, 1 or more |
+
+- **Only the root's `package.json`** is read: the `--root` directory, or the
+  working directory. Nothing is inherited from a parent directory.
+- **The command line wins, both ways.** Patterns replace `specs`, and
+  `--no-strict` beats `"strict": true`.
+- **A malformed configuration is exit 2, before anything runs**, naming the file
+  and the key: an unknown key, `"true"` where `true` goes, or an option that
+  belongs to one invocation, such as `format` or `verbose`.
+- **Every report says what it took from the file**: a line above the summary
+  such as `options from package.json: specs, strict`, and a `config` field in
+  JSON. An
+  option nobody can see should never decide a result.
+- `query` applies what a query reads, and the MCP server reads the file again
+  for every request.
+
+### Watch mode
+
+```bash
+spec-guard --watch
+```
+
+Prints the report, then prints it again whenever something under the root
+changes, until Ctrl+C. Saves are batched: a batch starts after 50 ms without a
+new change, or 500 ms after its first. On a terminal the screen is redrawn;
+otherwise each report is appended under the time. A change that no rule reads
+updates the status line and nothing else:
+
+```text
+watching 15 specs · 1 change · 21 of 60 rules re-executed · 21 ms · Enter re-runs everything, Ctrl+C stops
+```
+
+A session re-executes only the rules whose directive or inputs changed. Every
+filesystem read goes through one module, so the session can record which rule
+read what. A watcher's event only evicts what it may have changed, and the
+evicted facts are read again and compared, so noise costs one directory read,
+and a renamed directory's contents need no events of their own. Work that is a
+pure function of a file's bytes - tokenizing, comment masking, scanning - is
+remembered by the bytes' hash. Each of those is a way to report a tree that no
+longer exists, so a test changes trees at random and requires every report a
+session gives to equal a fresh run's, with six deliberately broken sessions
+that it has to catch. [ADR-0014](docs/adr/0014-configuration-and-watch.md) has
+the design, the measurements and the limits.
+
+On this repository, from a change to the report, in the quietest of four runs
+(a plain warm run took 69 ms in it):
+
+| Edit | Rules re-executed | Median |
+| --- | --- | --- |
+| a file in `src` | 21 of 60 | 21 ms |
+| a test file | 1 of 60 | 3.3 ms |
+| a file no rule reads | 0 | 2.0 ms |
+| an ADR's prose | 0 | 2.4 ms |
+
+The 15 ms this was built to is missed for a save in `src`, which re-executes the
+two layer rules and every text rule over `src`; ADR-0014 says where the time
+goes.
+
+`--watch` scans in-process, where it can see what each rule reads, so it refuses
+`--engine`, and `--json`, `--format json|sarif`, `--print-baseline`,
+`--fail-fast` and `--allow-empty`, which each describe a single run. It exits
+130 when stopped, since a session is neither a pass nor a failure. What it
+cannot see: a change the operating system never reports, a change behind a
+symbolic link, and anything outside the root. CI stays the authority.
 
 ### Exit codes
 
@@ -695,7 +881,8 @@ on Windows, macOS and Linux. A directory expands to the Markdown files in it.
 | --- | --- |
 | `0` | Every assertion held |
 | `1` | An assertion failed, or a directive was malformed |
-| `2` | spec-guard could not run: bad usage, no spec files matched, `--engine rg` with no ripgrep |
+| `2` | spec-guard could not run: bad usage, a malformed configuration, no spec files matched, `--engine rg` with no ripgrep, a watch that could not start |
+| `130` | A `--watch` session was stopped |
 
 ## CI integration
 
@@ -757,9 +944,10 @@ spec-guard's claims are about a whole repository - "this symbol appears nowhere
 in `src`" - and a language server is handed one buffer at a time. Answering a
 repository-wide question on every keystroke means rescanning the tree on every
 keystroke; the alternative is answering a smaller question and calling it the
-same one. The CLI does a full run of this repository in about 130 ms, so a
-pre-commit hook or a watch loop already closes the feedback gap without a
-daemon, an extension per editor, or a protocol version matrix.
+same one. `--watch` re-evaluates this repository in milliseconds after a save
+by re-executing only what the save affected, and a pre-commit hook closes the
+rest of the gap, without a daemon, an extension per editor, or a protocol
+version matrix.
 
 ## How it works
 
@@ -1002,7 +1190,7 @@ npm install
 npm run build      # tsc -> dist/
 npm test           # vitest
 npm run test:coverage
-npm run test:mutation  # stryker (~16 min in CI; over two hours locally)
+npm run test:mutation  # stryker (four parallel jobs in CI; hours locally)
 npm run lint       # tsc --noEmit
 npm run selfcheck  # run spec-guard on its own docs
 ```
@@ -1017,10 +1205,13 @@ prebuilt binary and is never a runtime dependency.
 
 Coverage says a line ran. It does not say an assertion would notice if the line
 behaved differently. This repository measures the difference: line coverage is
-**100%**, and **97.65%** of 4,299 mutants are killed in CI, with no file below
-95%. The second number is the one worth reading - and it is the ceiling, not a
-way-point: every surviving mutant has been checked individually and the 101 that
-are left produce byte-identical output.
+**100%**, and **98.84%** of 7,763 mutants are killed in CI, with 87 survivors and
+no file below 95%. The second number is the one worth reading, and what was done
+about the survivors matters more than the score. At 0.5.1 every surviving mutant
+was checked individually, and the 101 left then produced byte-identical output.
+Each release since has replayed the survivors its own code added before it
+shipped: they were killed, deleted as dead code, or shown equivalent and
+recorded in [ADR-0003](docs/adr/0003-mutation-testing.md) with the evidence.
 
 That gap is the point. The first run scored 77.23%, and the weakest file was the
 reporter at 65.48% - not because it lacked tests, but because its tests were
@@ -1061,13 +1252,19 @@ quoted above; a full sweep is also what publishes the cache the branches start
 from, so an incremental verdict can never be built on another incremental
 verdict.
 
-The full sweep was 6m54s at 2,118 mutants, 15m51s at 3,493, and is 17m at
-4,299. That growth is why the tiers exist: a check that gets quietly more
-expensive every release is a check somebody eventually proposes lowering.
+The full sweep was 6m54s at 2,118 mutants, 15m51s at 3,493, and 42m39s at 7,763.
+That growth is why the tiers exist: a check that gets quietly more expensive
+every release is a check somebody eventually proposes lowering. It is also why
+both tiers now run in four parallel shards. One runner
+could no longer finish the full sweep reliably inside the job's limit, and the
+answer was to split the sweep rather than raise the limit or drop mutants.
+Each shard mutates its own files against every test, and a final job merges the
+reports. The merge refuses anything that is not exactly one sweep, and applies
+the 97% gate to the merged score with the same library Stryker's gate uses.
 
 Run it locally with `npm run test:mutation` if you like, but do not calibrate
 anything on the result: on the Windows machine this was developed on the same
-suite takes over two hours against 21 minutes hosted, and it scores *higher*,
+suite takes hours against 43 minutes of hosted time, and it scores *higher*,
 because far more mutants hang there and Stryker counts a hang as a kill. Linux
 CI is the measurement.
 

package/dist/cli.d.ts

@@ -7,7 +7,10 @@
  *   2 - spec-guard could not run (bad usage, no spec files, missing engine)
  */
 import type { Readable } from 'node:stream';
+import { type ConfigKey, type ProjectConfig } from './config.js';
+import { watchTree } from './io.js';
 import type { EnginePreference } from './engine.js';
+import type { ConfigUse } from './types.js';
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_ERROR = 2;
@@ -17,8 +20,17 @@ export interface CliIO {
     env: NodeJS.ProcessEnv;
     cwd: string;
     isTTY: boolean;
-    /** Where `spec-guard mcp` reads its messages. Only that command reads input. */
+    /**
+     * Where `spec-guard mcp` reads its messages, and where a watch session hears
+     * Enter. Nothing else reads input.
+     */
     stdin?: Readable;
+    /** Writes to stdout as it is, with no newline added: a watch session redraws. */
+    write?: (text: string) => void;
+    /** Starts a recursive watch on a directory; a test passes one it drives itself. */
+    watch?: typeof watchTree;
+    /** Registers what Ctrl+C and SIGTERM do, and returns how to unregister it. */
+    onInterrupt?: (handler: () => void) => () => void;
 }
 /** What the command line asked for: a run, a query, or a server. */
 export type Command = 'check' | 'query' | 'mcp';
@@ -47,8 +59,18 @@ export interface CliOptions {
     maxSnippets: number;
     concurrency: number;
     color?: boolean;
+    /** Re-run as the tree changes, until stopped. ADR-0014. */
+    watch: boolean;
     help: boolean;
     version: boolean;
+    /**
+     * The configurable options the command line set, either way.
+     *
+     * A configuration fills in only what is not here, so a flag always wins - and
+     * `--strict` given alongside `"strict": true` is still reported as the command
+     * line's doing, not the file's.
+     */
+    fromCommandLine: Set<ConfigKey>;
 }
 export declare class UsageError extends Error {
 }
@@ -60,9 +82,22 @@ export declare class UsageError extends Error {
  * fallback nobody knows still works.
  */
 export declare function version(manifest?: string): string;
-export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]     execute the directives in the specs\n  spec-guard query <paths...> [options]  list the rules in force for files or directories\n  spec-guard mcp [options]               serve the rules to an AI agent over MCP on stdio\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted. query and\n  mcp take theirs from --spec.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)\n      --spec <pattern>    A spec glob or path; repeatable (default: \"docs/**/*.md\")\n  -v, --verbose           Print passing assertions too\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report (same as --format json)\n      --format <name>     human | json | sarif  (sarif uploads to GitHub code scanning)\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n      --strict            Treat analysis that could not be completed as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --allow-empty-scope Tolerate assertions whose scope holds no files (they fail by default)\n      --print-baseline    Print the baseline=\"...\" that would exempt today's violations, and exit\n      --no-default-skips  Search .git, .hg, .svn and node_modules too\n      --ignore-status     Execute directives in draft, proposed and superseded documents too\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel (default: 8)\n      --allow-empty       Exit 0 when no spec files matched (about the run, not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR is honoured)\n  -h, --help              Show this help\n      --version           Print the version\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n  <!-- @assert-import-cycle target=\"src/\" types=\"ignore\" -->\n  <!-- @assert-layers target=\"src/\" order=\"domain, application, infrastructure\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n  An assertion whose scope holds no files fails; add allow-empty=\"true\" to allow it.\n  A document whose status is draft, proposed, rejected, deprecated or superseded\n  is reported and not executed; --ignore-status runs it anyway.\n\nquery answers from the specs alone, without reading the codebase, so it works\nfor a file that does not exist yet. mcp offers the same answer, and a check,\nas the tools get_architectural_rules and check_architecture.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run";
+export declare const HELP = "spec-guard - Executable architecture assertions for Markdown specs & ADRs\n\nUsage\n  spec-guard [patterns...] [options]     execute the directives in the specs\n  spec-guard query <paths...> [options]  list the rules in force for files or directories\n  spec-guard mcp [options]               serve the rules to an AI agent over MCP on stdio\n\nPatterns\n  Globs or paths to the Markdown specs to execute. A directory expands to the\n  Markdown files inside it. Defaults to \"docs/**/*.md\" when omitted. query and\n  mcp take theirs from --spec.\n\nOptions\n  -r, --root <path>       Codebase root that assertions are resolved against (default: cwd)\n      --spec <pattern>    A spec glob or path; repeatable (default: \"docs/**/*.md\")\n  -v, --verbose           Print passing assertions too\n      --watch             Run again as the tree changes, until Ctrl+C (human output only)\n      --fail-fast         Stop at the first failing assertion\n      --json              Emit a machine-readable JSON report (same as --format json)\n      --format <name>     human | json | sarif  (sarif uploads to GitHub code scanning)\n      --engine <name>     auto | rg | js  (default: auto - scanner for small trees, ripgrep for big ones)\n      --strict            Treat analysis that could not be completed as a failure\n      --allow-missing-targets\n                          Tolerate target paths that do not exist (they fail by default)\n      --allow-empty-scope Tolerate assertions whose scope holds no files (they fail by default)\n      --print-baseline    Print the baseline=\"...\" that would exempt today's violations, and exit\n      --no-default-skips  Search .git, .hg, .svn and node_modules too\n      --ignore-status     Execute directives in draft, proposed and superseded documents too\n      --include-specs     Also count matches inside the spec files themselves\n      --max-snippets <n>  Failure snippets per assertion (default: 5)\n      --concurrency <n>   Assertions executed in parallel (default: 8)\n      --allow-empty       Exit 0 when no spec files matched (about the run, not an assertion)\n      --color/--no-color  Force colour on or off (NO_COLOR is honoured)\n  -h, --help              Show this help\n      --version           Print the version\n\nConfiguration\n  package.json in the root can hold specs, engine, strict, allowMissingTargets,\n  allowEmptyScope, ignoreStatus, includeSpecs, defaultSkips, maxSnippets and\n  concurrency under \"specGuard\". A flag wins over the file, and every on/off\n  option there also takes its opposite (--no-strict, --default-skips, ...).\n\nDirectives\n  <!-- @assert-absence target=\"src/\" symbol=\"LegacyGateway\" exclude=\"src/legacy/**\" -->\n  <!-- @assert-count   target=\"src/\" symbol=\"SessionManager\" expected=\"1\" -->\n  <!-- @assert-present file=\"SECURITY.md\" -->\n  <!-- @assert-import-cycle target=\"src/\" types=\"ignore\" -->\n  <!-- @assert-layers target=\"src/\" order=\"domain, application, infrastructure\" -->\n  <!-- @assert-structure target=\"src/\" exclude=\"*.test.ts\" partner=\"[name].test.ts\" -->\n\n  Matches inside comments do not count; add comments=\"include\" to count them.\n  An assertion whose scope holds no files fails; add allow-empty=\"true\" to allow it.\n  A document whose status is draft, proposed, rejected, deprecated or superseded\n  is reported and not executed; --ignore-status runs it anyway.\n\nquery answers from the specs alone, without reading the codebase, so it works\nfor a file that does not exist yet. mcp offers the same answer, and a check,\nas the tools get_architectural_rules and check_architecture.\n\nExit codes\n  0 all assertions passed   1 an assertion failed   2 spec-guard could not run\n  130 a --watch session was stopped";
 /** Minimal, dependency-free argv parser. Supports `--flag value` and `--flag=value`. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
+/**
+ * Fills in what the command line left unset from a configuration, and says what
+ * it took.
+ *
+ * A key the command does not read is neither applied nor overridden: `strict`
+ * is written for the runs, and a query that ignores it has not been told
+ * anything about strictness. A watch session scans in-process, so `engine` is
+ * not one of its keys either. Returns nothing when the configuration had
+ * nothing to say to this command, so a report says nothing about it.
+ */
+export declare function applyConfig(options: CliOptions, config: ProjectConfig, file?: string): ConfigUse | undefined;
+/** The process's own streams, signals and filesystem watcher. */
+export declare function defaultIO(): CliIO;
 /** Runs the CLI and resolves to the process exit code. */
 export declare function main(argv?: readonly string[], io?: CliIO): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEhD,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,SAAoB,GAAG,MAAM,CAQ5D;AAED,eAAO,MAAM,IAAI,opGAoD8D,CAAC;AA2DhF,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAqJ1E;AAoED,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAqD,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpH,OAAO,EAAoB,SAAS,EAAE,MAAM,SAAS,CAAC;AAMtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,SAAS,CAAC;IACzB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CACnD;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEhD,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,gBAAgB,CAAC;IACzB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;CACjC;AAED,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,SAAoB,GAAG,MAAM,CAQ5D;AAED,eAAO,MAAM,IAAI,gsHA6DmB,CAAC;AAsErC,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAsL1E;AAuCD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,SAAiB,GAAG,SAAS,GAAG,SAAS,CAepH;AA+BD,iEAAiE;AACjE,wBAAgB,SAAS,IAAI,KAAK,CAqBjC;AA+GD,0DAA0D;AAC1D,wBAAsB,IAAI,CAAC,IAAI,GAAE,SAAS,MAAM,EAA0B,EAAE,EAAE,GAAE,KAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpH"}