mandrel 2.59.0 → 2.61.0

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

@@ -1,150 +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 | **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 '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/`, 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 `!`
-
-**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.

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 }
-        }
-      }
-    }
-  }
-}

package/.agents/schemas/model-attribution.schema.json

@@ -1,53 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/model-attribution.schema.json",
-  "title": "ModelAttribution",
-  "description": "Payload of the <!-- structured:model-attribution --> comment upserted onto a Task ticket at the moment it transitions to agent::executing (Story #2813). One entry per Task. Story- and Epic-level breakdowns are derived at query time from the child Tasks' attribution comments — there is no Story/Epic-scope emission.",
-  "x-mandrel-uncompiled": {
-    "reason": "Deliberate: this document is the SSOT for the shape, but no AJV instance compiles it. The framework does not pull AJV into the structured-comment path — that path uses hand-rolled shape guards — so the runtime gate below mirrors this document by hand. Keep the two in step: an edit here is only real once the validator enforces it. Declared in-file per Story #4938 so a reader is never left inferring authority from the file's mere existence.",
-    "runtimeGate": ".agents/scripts/lib/orchestration/model-attribution.js#validateModelAttributionPayload"
-  },
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["kind", "ticketId", "model", "source", "recordedAt"],
-  "properties": {
-    "kind": { "type": "string", "const": "model-attribution" },
-    "ticketId": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "GitHub Issue number of the Task this attribution is recorded on."
-    },
-    "model": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id"],
-      "properties": {
-        "id": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Canonical model identifier (e.g. 'claude-opus-4-7', 'claude-sonnet-4-6'), or the sentinel 'unknown' when neither SDK metadata nor a runtime env var supplied an identity."
-        },
-        "family": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Coarse model family label for rollup grouping (e.g. 'Opus', 'Sonnet', 'Haiku'). Optional; derived from the id when present."
-        }
-      }
-    },
-    "source": {
-      "type": "string",
-      "enum": ["sdk-metadata", "env", "unknown"],
-      "description": "Provenance of the model identification, in fallback order: 'sdk-metadata' (resolved from the SDK response), 'env' (resolved from a runtime env var), 'unknown' (neither was available)."
-    },
-    "recordedAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO-8601 timestamp at which the attribution was recorded."
-    },
-    "sdkMetadata": {
-      "type": "object",
-      "description": "Opaque pass-through fields lifted from the SDK response metadata when available (e.g. response id, usage hints). Never required; never relied upon by the rollup helper.",
-      "additionalProperties": true
-    }
-  }
-}