mandrel 2.60.0 → 2.62.0

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

@@ -1,200 +0,0 @@
-# Known Tooling Behavior
-
-This rule applies when you are about to trust the output of a gate, a
-baseline ratchet, or a local stand-in for a CI check — before pushing,
-before declaring a check green, and before diagnosing a red one.
-
-Each entry below records a **measured** behavior of this repository's own
-tooling: a place where a command's visible output does not mean what it
-looks like it means. Entries exist because each one has already cost a
-delivery cycle.
-
-## The entry bar
-
-- An entry states behavior that was **measured against this repo**, never
-  recalled and never assumed.
-- Every entry carries a **reproduction command** that was actually run. If
-  the command stops reproducing the behavior, **delete the entry** — do not
-  annotate it. A stale entry is worse than a missing one, because it is
-  trusted.
-- Entries describe the observable behavior and the safe move. They never
-  describe a way to bypass a gate, and recording a behavior here is not a
-  decision to keep it.
-
-## 1. `npm run lint` prints `Summary: 0 error(s)` and can still exit 1
-
-**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.
-
-**Reproduce.**
-
-```bash
-# a format-only diff is an error, not a warning
-printf 'export const x = {a:1,   b:2};\n' | npx biome check --stdin-file-path=probe.js
-echo "biome exit=$?"   # 1 — "The contents aren't fixed"
-
-# and markdownlint's Summary line is unconditional
-npm run lint 2>&1 | grep -c 'Summary: 0 error(s)'
-```
-
-**Safe move.** Trust the exit code, never the last line. When `npm run lint`
-exits non-zero and you cannot see why, re-run `npx biome ci .` on its own —
-`.agents/scripts/run-lint.js` lists every tool it fans out to. Fix formatting
-with `npm run format`; never reach for `--no-verify`.
-
-## 2. `check-baselines.js` is not the whole `baselines` check
-
-**Behavior.** `.agentrc.json` declares the `baselines` required check as
-`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 nine standalone
-commands** the script knows nothing about, so a locally green
-`check-baselines.js` is not evidence that the `baselines` check will pass.
-
-| Command CI's `baselines` job runs | Covered by `check-baselines.js` | Covered by `npm run lint` | Covered by `npm run verify` |
-| --- | --- | --- | --- |
-| `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 | **yes** |
-| `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** |
-
-One is still in **no** local aggregate command — `check-baseline-scope.js`,
-reachable only as its own npm script (`baselines:scope`) or a direct
-invocation. `check-workflow-citations.js` joined `verify` when Story #5340
-demoted it to a report; before that it was exempted because
-`tests/check-workflow-citations.test.js` re-ran its ratchet through the `test`
-step.
-
-**Two of the nine cannot fail this job any more** (Story #5340, ADR
-20260917-5340). `check-workflow-citations.js` prints a per-file provenance
-count and always exits 0 — it reads no baseline at all, and the one it used
-to ratchet against is deleted.
-`check-context-budget.js` fails on the `alwaysLoaded` tier alone: its
-`workflow` and `mandatoryRead` tiers are printed, and the per-file 8 KB
-agent-boot ceiling and the row-vs-tree drift gate are gone. A green run of
-either is therefore **not** evidence the numbers held — read the report. Both
-ratchets used to fail a *rise*, so a prose fix had to be paid for with an
-unrelated trim in the same commit; the always-loaded gate is the one that
-stays because every session and every subagent spawn re-pays that closure.
-
-`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` and `check-workflow-citations.js` additionally run in
-`.husky/pre-push`, as reports. A shrink in the always-loaded closure no longer
-reds anything either (Story #5313): it is reported, and the close's write-back
-seam commits the lower total on the Story branch.
-
-**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 'js'
-sed -n '/^const STEPS/,/^];/p' .agents/scripts/run-verify.js  # the steps verify covers
-```
-
-**Safe move.** `npm run verify` is the closest local mirror. Run
-`npm run baselines:scope && npm run baselines:prune -- --check` alongside it
-when the change 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 `!`
-
-**Behavior.** `check-dead-exports.js` runs twice with two separate
-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 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
-**zero** export rows and exits clean — a green that means "nothing was
-analyzed", not "nothing is dead".
-
-**Reproduce.**
-
-```bash
-node .agents/scripts/check-dead-exports.js              # default pass
-node .agents/scripts/check-dead-exports.js --production # strictly larger row set
-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 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.
-
-## 4. A green pre-push is only evidence the two scopes agreed because `--ref` outranks config
-
-**Behavior.** `.husky/pre-push` captures coverage and then scores it, both
-against a literal `origin/main`. The CRAP half of `quality-preview.js` is a
-function of complexity **and** coverage, so the preview is only reading its
-own tree if the artifact under it was captured over the same change set.
-Both steps resolve that set through **one** rule, stated once in
-`resolveChangedFilesRef` (`.agents/scripts/lib/changed-files.js`): the ref the
-caller named wins, and
-`delivery.quality.gates.crap.incrementalCoverage.baseRef` is the default for a
-caller that names none — the close-validation gate, which passes no `--ref`.
-Both `coverage-capture` paths and the preview's CRAP baseline join call it, so
-one hook invocation cannot resolve two refs.
-
-Before Story #5365 the configured value outranked the flag. The preview has
-no config ref to consult, so a consumer that set `baseRef` captured against
-one ref while the preview scored another, and the preview could read an
-artifact whose scope was not its own — the stale-artifact read the
-capture-before-preview ordering (Story #5356) exists to prevent, reopened by
-configuration rather than by editing the hook. **This repository sets no
-`baseRef`**, so the divergence was invisible here: a green local run proved
-nothing about a consumer's.
-
-**Reproduce.**
-
-```bash
-node -e "import('./.agents/scripts/lib/changed-files.js').then(({ resolveChangedFilesRef }) => { const crap = { incrementalCoverage: { baseRef: 'develop' } }; console.log(resolveChangedFilesRef({ crap, ref: 'origin/main' })); console.log(resolveChangedFilesRef({ crap, ref: null })); })"
-# → origin/main   (the hook's flag wins over a configured baseRef)
-# → develop       (config still answers a caller that named no ref)
-grep -n 'origin/main' .husky/pre-push   # the same literal on both steps
-```
-
-**Safe move.** Read a green pre-push as evidence about CRAP only when both
-hook steps still carry the same literal ref. Moving one means moving the
-other; adding another consumer of the change set means routing it through
-`resolveChangedFilesRef` rather than reading `baseRef` directly.

package/.agents/rules/orchestration-error-handling.md

@@ -1,61 +0,0 @@
-# Orchestration Error Handling
-
-This rule applies to contributors writing or modifying orchestration scripts
-under `.agents/scripts/*.js` and the helper modules under
-`.agents/scripts/lib/orchestration/**`. Most agent task work does not touch
-these files; consult this rule only when implementing or refactoring
-orchestrators themselves.
-
-## Throw, Never Fatal
-
-Orchestration scripts MUST surface unrecoverable failures with
-`throw new Error(<message>)` rather than `Logger.fatal(<message>)`. The
-`runAsCli` boundary catches the throw and maps it to `process.exit(1)`,
-preserving the message verbatim and staying robust under a mocked
-`process.exit`; `Logger.fatal` falls through silently when `process.exit` is
-stubbed, letting execution continue past the intended hard-stop.
-
-### Where it applies
-
-- `.agents/scripts/<orchestrator>.js` (top-level CLI entry points)
-- `.agents/scripts/lib/orchestration/**/*.js` (helper modules)
-
-Non-orchestration scripts (one-shot utilities, audit reporters, doc
-generators) may continue to use `Logger.fatal` where the lifetime guarantees
-are simpler.
-
-## Output Contract — compact digest + artifact path (Story #4708)
-
-An orchestration script's stdout rides resident in the invoking agent's
-transcript and is re-read as prompt-cache input on every later turn, so fat
-success output is a per-turn tax on the whole session — not a one-time cost.
-
-- **Budget.** A script's **default success-path stdout MUST stay under
-  ~2KB**. Error paths and opt-in verbose modes are exempt; the budget is
-  about what every routine invocation pays.
-- **Digest + artifact path.** When a script produces a large result (a full
-  envelope, a per-phase result object, a report), it MUST write the full
-  payload to an on-disk artifact (under `temp/`, or an operator-named
-  `--out` path) and emit a **compact machine-parseable digest** on stdout
-  that names the artifact path plus the handful of fields the caller acts
-  on. The shared helper
-  [`lib/observability/terse-result.js`](../scripts/lib/observability/terse-result.js)
-  (`emitTerseResult`, Story #4685) implements this for hot-path result
-  dumps; `plan-context.js --out` shows the envelope-capture variant.
-- **Compact JSON.** Machine-parsed stdout envelopes are `JSON.parse`d by
-  their drivers — emit them single-line (`JSON.stringify(x)`), never
-  pretty-printed (`null, 2` only adds resident bytes). Pretty output is
-  reserved for explicit opt-in flags (`--pretty`).
-- **Streamed child output counts too (Story #4736).** A script that pipes a
-  child process's stdout/stderr through to the caller is emitting that output
-  as its own. `single-story-close.js` streamed every close-validation gate —
-  the whole of `npm test` included — and blew the budget by ~25× on a *passing*
-  close. Capture it to an artifact instead
-  ([`single-story-close/gate-log.js`](../scripts/lib/orchestration/single-story-close/gate-log.js)),
-  emit the digest, and **replay the tail inline on failure** — the bound is a
-  success-path bound, and a red gate's evidence belongs in front of the caller.
-- **Escape hatch.** `MANDREL_RESULT_DETAIL=inline` restores inline full
-  detail for interactive debugging; scripts using `emitTerseResult` honor it
-  automatically. `AGENT_LOG_LEVEL=verbose` restores live gate streaming.
-- **stdout purity is unchanged.** Scripts whose stdout is a machine contract
-  (Story #2278) keep logs on stderr; the digest is the *only* stdout line.

package/.agents/rules/test-seams.md

@@ -1,59 +0,0 @@
-# Injectable Test Seams
-
-This rule applies when writing or modifying scripts under
-`.agents/scripts/lib/` that perform filesystem I/O or spawn child processes.
-
-## Motivation
-
-Functions that hard-bind `fs` or `spawnSync` at module scope cannot be unit-
-tested without side-effecting the real filesystem or spawning real processes.
-The injectable-seam pattern threads replaceable implementations through a
-default-param `deps` object so tests substitute stubs while production code
-continues to call the real Node built-ins with zero configuration change.
-
-## The Pattern
-
-Each function that performs I/O accepts an optional final parameter named
-`deps` (or named individual dep params such as `fsImpl`, `spawnImpl`) that
-defaults to the real implementation:
-
-```js
-import fs from 'node:fs';
-import { spawnSync as defaultSpawnSync } from 'node:child_process';
-
-export function ensureSomething(ctx, { fsImpl = fs, spawnImpl = defaultSpawnSync } = {}) {
-  if (fsImpl.existsSync(ctx.target)) return { action: 'already-present' };
-  fsImpl.writeFileSync(ctx.target, ctx.body, 'utf8');
-  return { action: 'created' };
-}
-```
-
-### Canonical In-Repo Reference
-
-`.agents/scripts/lib/bootstrap/project-bootstrap.js` (its exported step
-functions) is the established in-repo baseline for this pattern.
-
-## Rules
-
-1. **Default to the real impl.** The default value MUST be the real built-in so
-   callers (bootstrap CLI, integration tests) require no change.
-2. **One seam per I/O surface.** Filesystem access uses `fsImpl`; child-process
-   spawning uses `spawnImpl`. Do not bundle them into a single opaque deps
-   object unless the function is exclusively internal (not exported).
-3. **No module-level seam state.** Seam parameters live on individual functions,
-   not on a shared module-level variable. Module-level variables are reset only
-   on re-import, which makes parallel test isolation impossible.
-4. **Re-export the real impl when a helper wraps it.** If a private helper
-   (`readJsonIfExists`, `writeJson`) receives `fsImpl`, it must accept and
-   forward the seam — not re-acquire `fs` at call time.
-5. **Tests inject stubs via the parameter, never via module mocking.** Prefer
-   passing a plain object `{ existsSync: () => false, readFileSync: () => '' }`
-   over `mock.module()` / `jest.mock()` so tests remain isolated and
-   parallelizable.
-
-## Where It Applies
-
-- `.agents/scripts/lib/bootstrap/project-bootstrap.js` (primary consumer of
-  this rule — every exported step function).
-- Any new helper in `.agents/scripts/lib/` that touches the filesystem or
-  spawns a process.

package/.agents/schemas/baselines/lighthouse.schema.json

@@ -1,59 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://mandrel/.agents/schemas/baselines/lighthouse.schema.json",
-  "title": "LighthouseBaseline",
-  "description": "Per-kind baseline schema for the Lighthouse audit gate. Extends the shared baseline-envelope contract.",
-  "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
-  "type": "object",
-  "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["performance", "accessibility", "bestPractices", "seo"],
-        "additionalProperties": false,
-        "properties": {
-          "performance": { "type": "number", "minimum": 0, "maximum": 100 },
-          "accessibility": { "type": "number", "minimum": 0, "maximum": 100 },
-          "bestPractices": { "type": "number", "minimum": 0, "maximum": 100 },
-          "seo": { "type": "number", "minimum": 0, "maximum": 100 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["performance", "accessibility", "bestPractices", "seo"],
-          "additionalProperties": false,
-          "properties": {
-            "performance": { "type": "number", "minimum": 0, "maximum": 100 },
-            "accessibility": { "type": "number", "minimum": 0, "maximum": 100 },
-            "bestPractices": { "type": "number", "minimum": 0, "maximum": 100 },
-            "seo": { "type": "number", "minimum": 0, "maximum": 100 }
-          }
-        }
-      }
-    },
-    "rows": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": [
-          "route",
-          "performance",
-          "accessibility",
-          "bestPractices",
-          "seo"
-        ],
-        "additionalProperties": false,
-        "properties": {
-          "route": { "type": "string" },
-          "performance": { "type": "number", "minimum": 0, "maximum": 100 },
-          "accessibility": { "type": "number", "minimum": 0, "maximum": 100 },
-          "bestPractices": { "type": "number", "minimum": 0, "maximum": 100 },
-          "seo": { "type": "number", "minimum": 0, "maximum": 100 }
-        }
-      }
-    }
-  }
-}

package/.agents/schemas/baselines/lint.schema.json

@@ -1,47 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://mandrel/.agents/schemas/baselines/lint.schema.json",
-  "title": "LintBaseline",
-  "description": "Per-kind baseline schema for the lint gate. Extends the shared baseline-envelope contract.",
-  "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
-  "type": "object",
-  "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["errorCount", "warningCount"],
-        "additionalProperties": false,
-        "properties": {
-          "errorCount": { "type": "integer", "minimum": 0 },
-          "warningCount": { "type": "integer", "minimum": 0 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["errorCount", "warningCount"],
-          "additionalProperties": false,
-          "properties": {
-            "errorCount": { "type": "integer", "minimum": 0 },
-            "warningCount": { "type": "integer", "minimum": 0 }
-          }
-        }
-      }
-    },
-    "rows": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["path", "errorCount", "warningCount"],
-        "additionalProperties": false,
-        "properties": {
-          "path": { "type": "string" },
-          "errorCount": { "type": "integer", "minimum": 0 },
-          "warningCount": { "type": "integer", "minimum": 0 }
-        }
-      }
-    }
-  }
-}