mandrel 2.30.0 → 2.32.0

package/.agents/docs/execution-reference.md

@@ -11,11 +11,11 @@ links here from the sections that used to inline this content.
 
 ## Friction telemetry
 
-Reference mechanics behind the friction-telemetry MUST in
-[`instructions.md` § 1.H](../instructions.md). The always-loaded core keeps the
-MUST, the command, and the when-to-fire triggers; the detail below is consulted
-only when reasoning about **where** a friction record lands and **how** it is
-validated.
+Reference mechanics behind the optional friction-telemetry tool pointed at
+from [`instructions.md` § 1.H](../instructions.md). Capture is a **tool, not a
+mandate** — reach for `diagnose-friction.js` when a wrapped command's failure
+shape is worth attributing; the detail below is consulted only when reasoning
+about **where** a friction record lands and **how** it is validated.
 
 - **Canonical record + schema validation**: `diagnose-friction.js` appends one
   `kind: friction` record, validated write-time against
@@ -62,10 +62,10 @@ Unrecognized `AGENT_LOG_LEVEL` values fall back to `info`. There is no
 `debug` level alias.
 
 This is a diagnostic knob: set it when you need quieter script embedding
-(`silent`) or a deeper trace (`verbose`). The friction-telemetry MUST it sits
-under — capture friction as a local NDJSON signal via `diagnose-friction.js` —
-stays in [`instructions.md` § 1.H](../instructions.md); its record-landing and
-schema mechanics are in [§ Friction telemetry](#friction-telemetry) above.
+(`silent`) or a deeper trace (`verbose`). This table is the SSOT for the
+levels; the optional friction-capture tool it sits beside is pointed at from
+[`instructions.md` § 1.H](../instructions.md), and that tool's record-landing
+and schema mechanics are in [§ Friction telemetry](#friction-telemetry) above.
 
 ---
 
@@ -85,11 +85,10 @@ over-ceiling envelope or an over-budget Story count.
 > before shipping the raw seed anyway. The schema now **rejects**
 > `planning.context`, so a config carrying it fails loudly rather than silently
 > capping nothing. The ceiling below is the replacement and the only live bound
-> on planner-context size. Separately, `elideEnvelope` in
-> `lib/orchestration/context-envelope.js` — which this section used to credit
-> with limiting hydrated prompt size — has no production caller either (it is
-> carried in `baselines/dead-exports-production.json`). Only `estimateTokens`
-> from that module is live.
+> on planner-context size. Separately, the `ContextEnvelope` SDK this section
+> used to credit with limiting hydrated prompt size had no production caller
+> and was deleted in Story #5005; only its `estimateTokens` helper survived,
+> re-homed in `lib/orchestration/spec-spill.js`.
 
 ### Planner-context envelope (`/plan`)
 

package/.agents/docs/quality-gates.md

@@ -172,15 +172,20 @@ baseline still trips the gate.
   run on push; use `npm run verify` locally before a PR. CI enforces the
   authoritative full gate set on every PR.
 - **CI** (`.github/workflows/ci.yml`): the `validate` job runs
-  **Lint and Format** (`npm run lint`), a **Maintainability Check**
-  (`npm run maintainability:check` → `check-baselines.js --gate
-  maintainability`, diff-scoped on PRs via
-  `delivery.quality.gateScoping`, full scope on push-to-main via
-  `BASELINE_SCOPE=full`), and **Run Tests with Coverage**
+  **Lint and Format** (`npm run lint`) and **Run Tests with Coverage**
   (`npm run test:coverage`), uploading the `test-results` and
   `coverage-final` artifacts. A separate required **baselines** job runs
   the unified `node .agents/scripts/check-baselines.js --format text`,
-  which enforces floors across every configured gate.
+  which enforces floors across every configured gate and is the only
+  baseline gate on the per-change path. (Story #5004 removed a
+  `Maintainability Check` step from `validate` that re-ran
+  `check-baselines.js --gate maintainability` at the same scope; a later
+  correction pass revisited its record of what the step's
+  `BASELINE_SCOPE=full` branch did — see `docs/ci-contract.md`.)
+- **Nightly** (`.github/workflows/baseline-drift.yml`): the only
+  automated **full-scope re-score**. See
+  [`check-baseline-drift.js`](#check-baseline-driftjs--the-scheduled-full-scope-re-score)
+  below.
 
 ### Opt-out
 
@@ -248,16 +253,27 @@ the `delivery.acceptanceEval` field reference is in
 > Baseline envelope, axes, and component model: see the
 > [Baseline reference](#baseline-reference) section below.
 
-The lint baseline engine enforces zero-deterioration during Story
-delivery. Integrations fail if new lint warnings are introduced, and the
-baseline automatically tightens when the codebase improves.
+The `lint` baseline kind enforces zero-deterioration during Story
+delivery: `check-baselines.js --gate lint` fails if new lint warnings are
+introduced, and the baseline tightens when the codebase improves.
 
 The canonical baseline file lives at `baselines/lint.json` (override via
-`delivery.quality.gates.lint.baselinePath`). Refresh with:
-
-```bash
-node .agents/scripts/lint-baseline.js capture
-```
+`delivery.quality.gates.lint.baselinePath`).
+
+**There is no framework capture CLI.** Story #5004 retired the
+`lint-baseline.js` shell that used to write this file: it spawned a
+configured lint command and parsed the linter's JSON, a shape only
+ESLint-style output satisfies, and this repo's own `npm run lint`
+(Biome + markdownlint fan-out) never produced it, so the gate was
+configured-but-unfed. A consumer that wants the kind writes
+`baselines/lint.json` from its own linter in the envelope shape documented
+under [Baseline reference](#baseline-reference); a consumer that does not is
+unaffected, because an absent baseline leaves the gate unconfigured.
+
+> **Upgrading?** The `project.commands.lintBaseline` key that fed the retired
+> shell is gone from the config schema, which is `additionalProperties: false`
+> — a `.agentrc.json` still carrying it now **fails validation** rather than
+> being silently ignored. Delete the key.
 
 Refresh commits should use a `baseline-refresh:` subject + non-empty body so
 the operator can spot baseline edits in review — same convention as the CRAP
@@ -320,6 +336,58 @@ its `new-method count over c=<flag>` column.
 
 ---
 
+## Gherkin corpus gate (opt-in)
+
+`check-gherkin-corpus.js` is a static gate over a project's `.feature` corpus.
+It runs inside `npm run lint` — the same required check as the arch-cycle
+ratchet — and it enforces two things:
+
+- **must-compile.** Every in-scope `.feature` is parsed with the real
+  `@cucumber/gherkin` parser and a failure is reported at `file:line:column`.
+  Re-implementing acceptance is the defect the gate exists to prevent: a
+  hand-rolled reader skips what it does not recognise, so a corpus that cannot
+  generate reads clean.
+- **must-bind.** Every active scenario's steps are resolved against the step
+  definitions of **its own scope only**. A file that fails must-compile is
+  excluded from must-bind — a broken file parses as an arbitrary subset of
+  itself, and linting the remainder buries the one actionable finding.
+
+The gate is **opt-in**: with no `qa.gherkinLint` block in `.agentrc.json` it
+reports that it is not configured and exits 0, even when `.feature` files
+exist on disk. An upgrade must never redden the lint of a corpus the consumer
+never asked the framework to police. This repository does not configure it.
+
+```jsonc
+"qa": {
+  "gherkinLint": {
+    "scopes": {
+      "web": {
+        "featureRoots": ["apps/web/tests/features"],
+        "stepRoots": ["apps/web/tests/steps"]
+      }
+    },
+    "exemptionTags": ["@skip"],
+    "stepWaivers": []
+  }
+}
+```
+
+Inside the opt-in the gate fails **closed**. An unresolvable
+`@cucumber/gherkin`, or a scope resolving zero step definitions, exits 1
+naming the cause and the remedy — reporting every step as unbound would be the
+same blackout in a different costume. The parser is an optional peer
+dependency resolved from the consumer project's own module chain, so a
+consumer with no BDD tier gains nothing; install it with
+`npm install --save-dev @cucumber/gherkin` when enabling the gate.
+
+Two escapes exist because the step index is a source scan (heuristic) while
+the parser is exact: `exemptionTags` (default `["@skip"]`) drops a scenario
+from must-bind, and `stepWaivers` drops one exact step text. Neither is an
+escape from must-compile — a parse error in an exempt scenario's file still
+fails the run.
+
+---
+
 ## CRAP gate — Consumer onboarding
 
 > Baseline envelope, axes, and component model: see the
@@ -556,9 +624,110 @@ tolerance, **in either direction**. A row that silently improved is equally
 strong evidence the baseline no longer describes the tree.
 
 Exit codes: `0` no drift (or every kind skipped), `1` drift detected, `2` the
-check could not run. It is designed to be wired as a scheduled CI job;
-scheduling it is deliberately consumer-side work, and nothing in this
-repository runs it automatically.
+check could not run.
+
+**`--require-scored`.** "Every kind skipped" mapping to `0` is a
+fail-open trap for the scheduled use this CLI was built for. Measured: with no
+`coverage/coverage-final.json` on disk, `check-baseline-drift.js --gate crap`
+prints `✅ No baseline drift detected` and exits `0` — a nightly job wired that
+way is green and inert. Pass `--require-scored` and any skipped kind exits `2`
+instead, naming the kind and the skip reason. Use it in every scheduled
+invocation.
+
+This repository schedules the maintainability kind in
+`.github/workflows/baseline-drift.yml` (framework repo only — that path is not
+part of the materialized `.agents/` payload) — nightly at 05:43 UTC plus
+`workflow_dispatch`; it files or updates one
+`meta::baseline-drift` issue with the report, closes it when the tree comes
+back clean, and fails the run. A consumer materializing `.agents/` still owns
+its own schedule.
+
+`crap` is deliberately **not** in that job. Its drift identity is
+`path::method@startLine`, so anything that shifts a method's line re-keys its
+row: measured on this tree with a real coverage artifact, 82 rows drifted but
+1438 were reported added and 898 removed — and 853 of those removals are the
+same `path::method` reappearing at a different line. The added/removed axis is
+re-keying churn, not drift, and the remedy the report prints
+(`npm run crap:update -- --full-scope`) additionally re-measures, pulling in
+near-empty coverage entries minted by CLI-spawning tests. Fixing the identity
+is a prerequisite to scheduling the kind.
+
+### `check-baseline-scope.js` — is this baseline still measuring the tree?
+
+Drift detection assumes the row set is right and asks whether its numbers
+moved. The prior question went unasked: **does this baseline still describe
+the tree at all?** A ratchet is perfectly capable of being green while
+measuring almost nothing — a row can point at a file deleted months ago, and
+an in-scope file can carry no row whatsoever, and every gate above stays
+green.
+
+The scope gate asserts the row set in **both directions**, recomputing each
+kind's in-scope file set from the gate's own configuration —
+`.c8rc.cjs` `include`/`exclude` for coverage,
+`delivery.quality.gates.<kind>.{targetDirs,ignoreGlobs}` for the rest —
+through the same helpers the refresh scorers use, so the gate and the
+producers cannot disagree about scope:
+
+```bash
+npm run baselines:scope                                  # every kind
+node .agents/scripts/check-baseline-scope.js --kind coverage --json
+node .agents/scripts/check-baseline-scope.js --strict     # skip attribution
+```
+
+Two design constraints are worth knowing before reading a report:
+
+- **Only dense kinds assert `missing`.** `coverage` and `maintainability`
+  emit one row per in-scope file, so a file with no row is a real hole. `crap`
+  (per-method, coverage-gated), `duplication` (rows only where clones exist),
+  `lint` and `mutation` are sparse by construction — asserting `missing`
+  against them yields hundreds of phantom findings on a healthy tree, so they
+  assert `extra` only. `lighthouse` (`route`) and `bundle-size` (`bundle`) are
+  not file-keyed and are excluded from both.
+- **A PR is blocked only for divergence it created.** Whole-tree equality
+  would red every open PR the moment anyone lands an in-scope file, so the
+  gate blocks on divergence attributable to `merge-base(base, HEAD)..HEAD` and
+  warns about the inherited remainder. It fails towards **strict** — every
+  finding fatal — when no base resolves, when HEAD is not ahead of it, or when
+  the change set edits a baseline or the config defining its scope.
+
+Exit codes: `0` no fatal divergence, `1` fatal divergence, `2` the check could
+not run. It runs in the required `baselines` CI job.
+
+### `prune-baseline-orphans.js` — the cheap remedy that makes the gate fair
+
+A hard gate is only defensible while clearing it costs a command. Re-deriving
+a whole baseline to express a *deletion* spends a coverage run or a full-tree
+MI pass, which is exactly why stale rows accumulate. The pruner is that
+deletion, done as arithmetic:
+
+```bash
+npm run baselines:prune                                   # write the prune
+node .agents/scripts/prune-baseline-orphans.js --check     # report only, exit 1
+```
+
+It removes exactly two provably-inert row classes across every file-keyed
+baseline — a row whose file is **absent** from disk, and a row for a file now
+**out-of-scope** under the gate's own `targetDirs`/`ignoreGlobs` — and it is
+**measurement-free by contract**: it never adds a row, never restamps
+`generatedAt` (a fresh stamp over rows nobody re-measured is the precise
+failure an age check exists to catch), and recomputes `rollup` through the
+kind's own arithmetic so the pruned envelope still validates against its
+schema. An unreadable scope config degrades to orphan-only pruning rather than
+reading unknown scope as empty scope, which would hand it the whole baseline.
+
+A **missing** row is the one thing the pruner will not fix: a file added
+without being measured needs its producer (`npm run coverage:update`,
+`npm run maintainability:update`), because inventing a row would be claiming a
+measurement nobody took.
+
+**CI does not run the pruner in either mode.** `--check` exits 1 on any stale
+row without asking which change set introduced it, so pairing it with
+`check-baseline-scope.js` in the required job cancelled that gate's merge-base
+attribution: a row inherited from `main` — say one PR deletes a file while a
+second, branched earlier, re-adds its row through a baseline refresh — reds
+every open PR on divergence its author did not create and cannot fix from
+their branch. The scope gate reports that row as an inherited warning; the
+pruner is the remedy an operator (or agent) runs with the branch in hand.
 
 ---
 
@@ -651,10 +820,13 @@ Cross-references:
   configuration surface that backs the gates.
 - [`.agents/README.md`](../README.md) — consumer onboarding.
 
-> The `mutation` gate ships **dormant** (built-but-unwired, intentionally
-> opt-in). The former `update-mutation-baseline.js` refresh CLI was retired
-> with the rest of the zero-consumer script surface (#4482); the
-> `lib/mutation/` snapshot machinery remains for a future activation.
+> `mutation` is a **registered baseline kind with no shipped runner**. The
+> envelope, schema, and floor config below describe a `baselines/mutation.json`
+> the framework can read and ratchet, but nothing in Mandrel invokes Stryker or
+> writes that file: the `update-mutation-baseline.js` refresh CLI was retired
+> in #4482 and the `lib/mutation/` snapshot machinery in #5008. Activating the
+> gate means shipping a runner first — treat the kind as a reserved slot, not a
+> dormant feature.
 
 ### Envelope
 
@@ -911,8 +1083,8 @@ Refresh paths:
   `baselines/crap.json`.
 - `node .agents/scripts/update-maintainability-baseline.js` — rewrites
   `baselines/maintainability.json`.
-- `node .agents/scripts/lint-baseline.js capture` — rewrites
-  `baselines/lint.json`.
+- `baselines/lint.json` has no framework refresh CLI — see
+  [Lint baseline ratchet](#lint-baseline-ratchet).
 
 After a kernel bump, regenerate every baseline whose `kernelVersion`
 drifted, then commit the refreshed files. The writer guarantees

package/.agents/instructions.md

@@ -77,11 +77,8 @@ present, else the **Tech Stack** section of `docs/architecture.md`.
 
 ### H. Observability & Friction Telemetry
 
-You MUST log operational friction (repeated tool errors, unrecoverable
-command failures, self-corrected ambiguity, automatable boilerplate):
-`node .agents/scripts/diagnose-friction.js --story [STORY_ID] --cmd <cmd> <args...>`
-— a **local NDJSON signal** (not posted to the ticket). Schema and the
-`AGENT_LOG_LEVEL` table:
+Optional: `diagnose-friction.js` wraps a command and records its failure
+shape as a local NDJSON signal —
 [`docs/execution-reference.md`](docs/execution-reference.md#friction-telemetry).
 
 ### I. Anti-Thrashing Protocol

package/.agents/rules/ci-remediation.md

@@ -51,6 +51,7 @@ the two options above. Name the verdict you reached in the `friction` comment.
 | **defect-in-diff** | The failure reproduces on the branch and not on an unmodified `main` | Option 1 — fix at source |
 | **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — file `meta::framework-gap`; remediate here only if it blocks this delivery |
 | **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — file `meta::framework-gap` **and** escalate to the operator |
+| **unreproducible-tier** | The tier cannot be exercised in this sandbox at all, proven by an attempted attach (see below) | Option 2 — file `meta::framework-gap` **and** escalate on first encounter |
 
 ### The `capacity` verdict
 
@@ -82,10 +83,46 @@ the operator, who owns the runner pool. Do not sit in a retry loop waiting for
 capacity to return.
 
 **Rerunning a failed job to reach green stays forbidden under every verdict,
-`capacity` included.** The verdict changes who owns the fix and where it is
+`capacity` and `unreproducible-tier` included.** The verdict changes who owns the fix and where it is
 filed; it never licenses a re-run, and it is not a route to a green bar. A
 capacity-blocked delivery ends `agent::blocked` — not merged.
 
+### The `unreproducible-tier` verdict
+
+A check can fail on a tier the sandbox cannot run at all — most often a
+browser suite whose Playwright `webServer` block supervises a dev server the
+local process manager daemonizes, which aborts the run with
+`Process from config.webServer exited early` before any test executes. The
+failure is a property of the sandbox's ability to *host* the suite, not of the
+diff.
+
+This is the same structural hole the `capacity` verdict was added to fill, one
+step earlier in the loop. Without it the honest reading is `flaky`, which routes
+to Option 1 — and fix-at-source requires reproducing the failure, which is the
+one thing that cannot be done. The agent then spends the full timebox
+rediscovering that before escalating anyway, and any fix it does author is
+written blind against a tier it never ran.
+
+**Unreproducible must be proven, not inferred.** "The suite did not run for me"
+is not the verdict — it is the symptom every misconfiguration produces. Cite
+both:
+
+- **The attempted attach.** Work the attach-don't-boot seam in the
+  [`playwright`](../skills/stack/qa/playwright/SKILL.md) skill — boot the server
+  out-of-band, point the suite at the running origin, set `reuseExistingServer`
+  — and name which step failed and how. A tier that runs once attached was never
+  unreproducible.
+- **The observed signature.** The verbatim line the runner aborted on, so a
+  later reader can tell a lifetime-ownership mismatch from a genuine boot
+  failure in the app under test.
+
+Absent both readings the verdict is unavailable and the failure routes as it did
+before. On the verdict: file the `meta::framework-gap` issue with the run link,
+the failure signature, and the attach attempt; flip the Story to
+`agent::blocked` with a `friction` comment naming the verdict; and hand back to
+the operator, who owns the sandbox. Do not author a fix for a tier you could not
+run — a blind fix to a suite nobody exercised is how the gap compounds.
+
 ## Verifier
 
 The check is resolved only when it is **green with zero reruns of the failed
@@ -131,3 +168,9 @@ operator under **any** of:
   signature) and escalate on the first encounter rather than burning iterations
   trying to code around it. A proven-capacity failure is this case: reach the
   `capacity` verdict above and escalate on the first encounter.
+- **Unrunnable tier → escalate immediately.** A tier the sandbox cannot host at
+  all is this case too: work the attach seam once, reach the
+  `unreproducible-tier` verdict above with its two readings, and escalate on the
+  **first encounter**. The 30-minute timebox is a ceiling here, never a budget
+  to spend — every minute past the failed attach buys nothing, because no
+  iteration can make an unhostable suite run.

package/.agents/rules/git-conventions-reference.md

@@ -43,6 +43,33 @@ Practical guidance when authoring a contract change:
   can detect "I cannot read this artifact"); they are **not** an
   invitation to keep multiple readers alive in the same release.
 
+### Declaring the break so consumers see it
+
+A hard cutover is only honest if the consumer can find out about it. Prose in
+a commit body does not qualify: release-please recognizes exactly two signals,
+a `!` before the colon in the subject and a `BREAKING CHANGE:` footer, and
+sees nothing else. Story #5004 removed `project.commands.lintBaseline` from a
+schema block that is `additionalProperties: false` — a config that used to be
+silently ignored now fails validation — described it in three body paragraphs,
+and shipped with neither signal. It reached `main` as `docs:` and would have
+been absent from the release notes entirely.
+
+So a contract change MUST declare itself in one of two places, and close
+(`normalize-pr-title.js`) propagates either to the squash subject and PR body:
+
+1. **A commit footer** — a `BREAKING CHANGE:` (or `BREAKING-CHANGE:`) line in
+   the body of whichever commit does the breaking. This is the default; write
+   it as you write the commit. The keyword is uppercase and starts its own
+   line, per Conventional Commits.
+2. **A Story-body declaration** — the same footer as its own line in the Story
+   issue, naturally at the end of `## Spec`. Use this when the break is known
+   at plan time, or when it spans several commits and no single one owns it.
+
+Close reads both, marks the PR title `<type>!: …`, and appends the collected
+note to the PR body as a footer. Consumers whose on-disk state needs changing
+should also get a step in `lib/migrations/` — see that directory's README;
+`2.32.0-retire-lint-baseline-command.js` is the step #5004 should have shipped.
+
 ## Push Validation — the known false-negative signature
 
 The core rule is: **never bypass hooks** (`--no-verify`, `--no-gpg-sign`, or
@@ -125,33 +152,6 @@ different hazards:
   (`git -C <main-repo> checkout -- <files>`), then re-run `/deliver <storyId>`.
   Never `git reset --hard` or `git checkout --force` to clear the way.
 
-## Documentation Freshness Gate
-
-The `validate-docs-freshness.js` gate (run during `/deliver`) asks a
-falsifiable question of every doc in `delivery.docsFreshness.paths` +
-`project.docsContextFiles`: **was this doc actually updated for the Epic?**
-A doc passes on either of two conditions, but they are not
-interchangeable:
-
-- **Living docs are satisfied by being rewritten, not annotated.** For
-  any non-changelog doc (architecture, decisions, README, guides, …) the
-  gate passes **only** when an Epic-referencing commit touched the file —
-  a commit whose message references `#<epicId>` and changes the doc.
-  Rewrite the doc as part of the Epic's work; do not sprinkle `#<epicId>`
-  into its prose to satisfy the check. An appended `#<epicId>` annotation
-  alone **fails** the gate for these files, and the failure message names
-  the file and the rewrite-not-append contract.
-- **`#<epicId>` body annotations pass only for changelog files.** A
-  changelog-class file (basename matches `/changelog/i`, e.g.
-  `docs/CHANGELOG.md`) may pass on a body annotation, because an appended
-  release note keyed to the Epic is the legitimate, expected update there.
-  This is the single sanctioned annotation path; every other doc must use
-  the rewrite path above.
-
-This restriction exists to remove the perverse incentive by which the
-gate would otherwise reward manufacturing fake provenance — appending
-Epic-ID history into living docs purely to clear the check.
-
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so

package/.agents/rules/git-conventions.md

@@ -5,8 +5,8 @@ core**: branch shapes, the Conventional-Commit subject contract, issue
 references, and the non-negotiable push/hygiene MUSTs. Deeper mechanics —
 the hard-cutover contract policy, the full push-validation procedure and
 the push-hook false-negative signature, checkout-hygiene scope rules,
-shared-checkout merge contention, the documentation-freshness gate, and
-the `meta::*` labels — live in the on-demand
+shared-checkout merge contention, and the `meta::*` labels — live in the
+on-demand
 [`git-conventions-reference.md`](git-conventions-reference.md); read it
 **before** doing the matching work.
 
@@ -32,6 +32,8 @@ subject referencing the Story via `(refs #<storyId>)` — see
   It does **not** run on squash-merge titles edited in the GitHub UI —
   author the PR title in conventional form so the squash commit parses
   for release-please.
+- Consumer-breaking changes MUST carry a `BREAKING CHANGE:` footer
+  (breaking commit or Story body); prose never reaches release-please.
 
 ## Push Validation & Reliability (MUSTs)
 

package/.agents/rules/known-tooling-behavior.md

@@ -23,13 +23,14 @@ delivery cycle.
 
 ## 1. `npm run lint` prints `Summary: 0 error(s)` and can still exit 1
 
-**Behavior.** `npm run lint` is `run-lint.js`, which spawns six tools
-concurrently with inherited stdio and exits with the first non-zero code.
-`Summary: 0 error(s)` is **markdownlint-cli2's own verdict**, not the
-aggregate — it is printed whether or not Biome, the lifecycle lint, the
-workflow-CLI lint, the label-vocabulary lint, or the arch-cycle ratchet
-failed. Because the tools run in parallel, that line can land anywhere in
-the output, including last, so the tail of a failing run reads green.
+**Behavior.** `npm run lint` is `run-lint.js`, which spawns eight tools
+concurrently with inherited stdio and exits with the first non-zero code —
+Biome, markdownlint-cli2, the lifecycle lint, the workflow-CLI lint, the
+label-vocabulary lint, the workflow-timeout gate, the arch-cycle ratchet, and
+the Gherkin corpus gate. `Summary: 0 error(s)` is **markdownlint-cli2's own
+verdict**, not the aggregate — it is printed whether or not any of the other
+seven failed. Because the tools run in parallel, that line can land anywhere
+in the output, including last, so the tail of a failing run reads green.
 Biome's format diagnostics are `error`-severity, so a file that only needs
 reformatting fails the check while emitting no lint rule name at all.
 
@@ -55,34 +56,53 @@ with `npm run format`; never reach for `--no-verify`.
 `node .agents/scripts/check-baselines.js`, but that script only runs the
 gates configured under `delivery.quality.gates` — currently **crap,
 maintainability, and duplication**. CI's job named `baselines` in
-`.github/workflows/ci.yml` runs that script **and then five standalone
-ratchets** the script knows nothing about, so a locally green
+`.github/workflows/ci.yml` runs that script **and then nine standalone
+commands** the script knows nothing about, so a locally green
 `check-baselines.js` is not evidence that the `baselines` check will pass.
 
-| Ratchet CI's `baselines` job runs | Covered by `check-baselines.js` | Covered by `npm run lint` | Covered by `npm run verify` |
+| Command CI's `baselines` job runs | Covered by `check-baselines.js` | Covered by `npm run lint` | Covered by `npm run verify` |
 | --- | --- | --- | --- |
-| `.agents/scripts/check-arch-cycles.js` | no | **yes** | via `lint` |
-| `.agents/scripts/check-dead-exports.js` | no | no | **yes** |
-| `.agents/scripts/check-dead-exports.js --production` | no | no | **yes** |
-| `.agents/scripts/check-context-budget.js` | no | no | **yes** |
-| `.agents/scripts/check-workflow-citations.js` | no | no | **no** |
-
-`check-workflow-citations.js` is currently in **no** local aggregate command
-— it is reachable only as `npm run check:workflow-citations` or a direct
-invocation.
+| `check-arch-cycles.js` | no | **yes** | via `lint` |
+| `check-dead-exports.js` | no | no | **yes** |
+| `check-dead-exports.js --production` | no | no | **yes** |
+| `check-context-budget.js` | no | no | **yes** |
+| `check-workflow-citations.js` | no | no | **no** |
+| `check-cyclomatic.js` | no | no | **yes** |
+| `check-schema-references.js` | no | no | **yes** |
+| `check-knip-entries.js` | no | no | **yes** |
+| `check-baseline-scope.js` | no | no | **no** |
+
+Two are still in **no** local aggregate command —
+`check-workflow-citations.js` and `check-baseline-scope.js`. Each is reachable
+only as its own npm script (`check:workflow-citations`, `baselines:scope`) or a
+direct invocation.
+
+`prune-baseline-orphans.js --check` left this table in v2.32.0: it no longer
+runs in CI in any mode. It reports the same absent / out-of-scope rows as
+`check-baseline-scope.js` but without merge-base attribution, so holding it in
+the required job made the scope gate's inherited-divergence warning
+unreachable — a stale row on `main` red every open PR regardless of who landed
+it. It stays the operator's remedy, via `npm run baselines:prune`.
+
+`check-context-budget.js` additionally runs in `.husky/pre-push`. It is
+zero-tolerance in **both** directions — a change that *shrinks* the
+always-loaded doc closure reds it exactly as growth does, and the remedy is a
+committed baseline refresh, not a smaller diff.
 
 **Reproduce.**
 
 ```bash
 node .agents/scripts/check-baselines.js --format text   # names the 3 gates it ran
-sed -n '/name: baselines/,/windows-smoke/p' .github/workflows/ci.yml | grep 'check-'
-grep "label: '" .agents/scripts/run-verify.js            # the 7 steps verify covers
+sed -n '/name: baselines/,/windows-smoke/p' .github/workflows/ci.yml | grep 'js'
+grep "label: '" .agents/scripts/run-verify.js            # the 9 steps verify covers
 ```
 
-**Safe move.** `npm run verify` is the closest local mirror; run
-`node .agents/scripts/check-workflow-citations.js` alongside it when the
-change touches workflow prose under `.agents/workflows/`. Reproducing only
-the `.agentrc.json` command before a push is a false green.
+**Safe move.** `npm run verify` is the closest local mirror. Run
+`node .agents/scripts/check-workflow-citations.js` alongside it when the change
+touches workflow prose under `.agents/workflows/`, and
+`npm run baselines:scope && npm run baselines:prune -- --check` when it adds,
+deletes or moves files inside a scored `targetDirs` root. Reproducing only the
+`.agentrc.json` command before a push is a false green.
 
 ## 3. The two dead-export passes disagree, and the production pass is silent without `!`
 
@@ -90,10 +110,21 @@ the `.agentrc.json` command before a push is a false green.
 baselines. The default pass treats `tests/**` as knip entry points, so an
 export whose only importer is a test still reads as *used*; the
 `--production` pass discounts test importers and therefore sees a much
-larger surface — `baselines/dead-exports.json` carries 165 rows against
-`baselines/dead-exports-production.json`'s 667. A new export that is only
+larger surface — `baselines/dead-exports.json` carries 130 rows against
+`baselines/dead-exports-production.json`'s 695. A new export that is only
 imported by its test passes the default pass and fails the production one.
 
+Rows come in two shapes. `{ file, symbol: '<name>' }` is one unused export;
+`{ file, symbol: '*' }` is **whole-file death** — a module nothing imports.
+Knip reports such a module once, under its `files` category, and suppresses
+that module's per-export rows, so a file losing its last importer *shrinks*
+the export row set. Reading only `exports` therefore scored losing a whole
+module as an improvement; the `*` rows exist so it reads as the regression
+it is. `knip.json` lists the `.agents/scripts` CLIs as explicit entry paths
+for the same reason: a blanket `.agents/scripts/*.js!` glob declared every
+top-level CLI reachable by construction, so no uninvoked one could ever
+surface. Adding a CLI means adding its entry line.
+
 The production pass depends entirely on the `!` suffix on the `entry` and
 `project` patterns in `knip.json`: `!` marks a pattern as
 production-relevant. Strip the suffixes and `knip --production` reports
@@ -109,6 +140,11 @@ grep -c '!"' knip.json                                  # the production markers
 ```
 
 **Safe move.** Run both passes before pushing. When an export is genuinely
-test-only, keep it and refresh the production baseline deliberately —
-`.agents/rules/test-seams.md` governs which seams are sanctioned. Never
-remove the `!` suffixes from `knip.json` to quieten the production pass.
+test-only, keep it and refresh both baselines deliberately with `npm run
+dead-exports:update` — `.agents/scripts/update-dead-exports-baseline.js`,
+which rewrites the rows knip currently reports and fails closed rather than
+persisting an empty snapshot from a knip run that never worked. Never
+hand-edit `baselines/dead-exports*.json`: a hand-written row set is the one
+input no gate re-derives. `.agents/rules/test-seams.md` governs which seams
+are sanctioned. Never remove the `!` suffixes from `knip.json` to quieten the
+production pass.