mandrel 2.9.0 → 2.11.0

package/.agents/scripts/lib/audit-suite/selector.js

@@ -702,7 +702,7 @@ const SOURCE_CODE_EXTENSIONS = Object.freeze([
 const TEST_FILE_RE = new RegExp(String.raw`\.(test|spec)\.[cm]?[jt]sx?$`);
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const TEST_DIR_RE = new RegExp(
-  String.raw`(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)`,
+  '(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)',
 );
 // biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
 const CODE_EXT_RE = new RegExp(String.raw`\.[cm]?[jt]sx?$`);

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -117,6 +117,39 @@ export function resolveBundleSizeEnvOverrides(env) {
   return { acknowledged, overrides };
 }
 
+/**
+ * Pure helper: resolve the one-shot maintainability refresh/acknowledge flag
+ * (Story #4731). This is the env-parity sibling of
+ * `resolveBundleSizeEnvOverrides`: `MAINTAINABILITY_REFRESH=1` (or `true`,
+ * case-insensitive) tells `check-baselines --gate maintainability` to demote
+ * this run's head-vs-base maintainability regressions to `unchanged` for this
+ * invocation only. Floors still apply — an acknowledged run can still fail on
+ * an absolute floor breach (e.g. a row below `min` 70); only the
+ * ratchet-vs-base regression comparison is suspended.
+ *
+ * Unlike bundle-size, maintainability also has a **commit-tagged** trigger
+ * (a `baseline-refresh:`-tagged commit in the compared range that touches the
+ * maintainability baseline file) resolved in the evaluate phase — this env
+ * flag is the manual override the two share by shape. Neither is persisted:
+ * the next run without the flag / tag re-enforces the ratchet at full
+ * strength automatically.
+ *
+ * Accepted truthy values: `1`, `true` (case-insensitive). Anything else
+ * (including unset/empty) resolves to `acknowledged: false`.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ acknowledged: boolean, overrides: string[] }}
+ */
+export function resolveMaintainabilityRefreshOverrides(env) {
+  const raw = env?.MAINTAINABILITY_REFRESH;
+  const acknowledged =
+    typeof raw === 'string' && /^(1|true)$/i.test(raw.trim());
+  const overrides = acknowledged
+    ? [`acknowledged=true (MAINTAINABILITY_REFRESH=${raw})`]
+    : [];
+  return { acknowledged, overrides };
+}
+
 /**
  * Pure helper: resolve the effective MI tolerance by layering precedence:
  *   1. `CRAP_TOLERANCE` env-var (CI override — the baseline-refresh-

package/.agents/scripts/lib/baselines/preview-gates.js

@@ -263,6 +263,11 @@ export async function runCrapPreview({
   const requireCoverage = crap.requireCoverage !== false;
   const coveragePath = crap.coveragePath ?? 'coverage/coverage-final.json';
   const coverage = loadCoverage(path.resolve(cwd, coveragePath));
+  // Story #4731 (AC-3) — feed the CRAP regression compare the *configured*
+  // crap tolerance (env override → `gates.crap.tolerance` → framework default)
+  // so `compareCrap` demotes positive deltas at or under tolerance rather than
+  // failing on any positive delta; over-tolerance deltas still fail. This keeps
+  // the pre-commit/pre-push preview aligned with the authoritative gate.
   const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
     crap,
     process.env,

package/.agents/scripts/lib/config/gates/maintainability.schema.js

@@ -1,12 +1,21 @@
 /* node:coverage ignore file -- AJV schema declaration (data-as-code) */
 
-import { GATE_BASE, LIST_OR_EXTENDER_OF_STRINGS } from './shared.js';
+import {
+  GATE_BASE,
+  LIST_OR_EXTENDER_OF_STRINGS,
+  SAFE_STRING,
+} from './shared.js';
 
 export const MAINTAINABILITY_GATE = {
   type: 'object',
   properties: {
     ...GATE_BASE,
     targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
+    // Story #4731 — commit-subject substring that acknowledges a deliberate
+    // maintainability baseline refresh in the compared range. Mirrors the CRAP
+    // gate's `refreshTag`; a range commit carrying it that touches the baseline
+    // file demotes head-vs-base regressions (floors still enforced).
+    refreshTag: { ...SAFE_STRING, minLength: 1 },
     // Story #2165 — bounded timeout for `npm run maintainability:update`
     // spawned by the baseline-attribution refresh path. Mirrors
     // `coverage.timeoutMs` (Story #2142).

package/.agents/scripts/lib/config/quality.js

@@ -110,6 +110,13 @@ export const MAINTAINABILITY_GATE_DEFAULTS = Object.freeze({
   tolerance: DEFAULT_MI_TOLERANCE,
   floors: DEFAULT_MI_FLOORS,
   targetDirs: Object.freeze([]),
+  // Story #4731 — the commit-subject substring that acknowledges a deliberate
+  // maintainability baseline refresh in the compared range. Mirrors the CRAP
+  // gate's `refreshTag`; the evaluate phase demotes head-vs-base regressions
+  // (floors still enforced) when a range commit carrying this tag touches the
+  // baseline file. Kept identical to the CRAP default so one refresh commit
+  // can acknowledge both gates.
+  refreshTag: 'baseline-refresh:',
   // Story #2165 — bounded timeout (ms) for `npm run maintainability:update`
   // spawned by the baseline-attribution refresh path. Defaults to 60 s.
   refreshTimeoutMs: 60_000,
@@ -154,6 +161,7 @@ const MI_GATE_KEYS = new Set([
   'tolerance',
   'floors',
   'targetDirs',
+  'refreshTag',
   'refreshTimeoutMs',
   'ignoreGlobs',
 ]);
@@ -268,6 +276,7 @@ function resolveMaintainabilityQuality(userBlock, gateScoping) {
   if (userBlock == null || typeof userBlock !== 'object') {
     return {
       targetDirs: [...defaults.targetDirs],
+      refreshTag: defaults.refreshTag,
       refreshTimeoutMs: defaults.refreshTimeoutMs,
       ignoreGlobs: [...defaults.ignoreGlobs],
       defaultScope: scoping.defaultScope,
@@ -277,6 +286,10 @@ function resolveMaintainabilityQuality(userBlock, gateScoping) {
   warnUnknownKeys(userBlock, MI_GATE_KEYS, 'quality.gates.maintainability');
   const out = {
     targetDirs: resolveListValue(defaults.targetDirs, userBlock.targetDirs),
+    refreshTag:
+      typeof userBlock.refreshTag === 'string' && userBlock.refreshTag.length
+        ? userBlock.refreshTag
+        : defaults.refreshTag,
     refreshTimeoutMs: resolvePositiveIntegerMs(
       userBlock.refreshTimeoutMs,
       defaults.refreshTimeoutMs,

package/.agents/scripts/lib/config/temp-paths.js

@@ -52,6 +52,8 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { mkdtempSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 /**
@@ -114,6 +116,81 @@ export function _clearMainCheckoutRootCache() {
   _mainCheckoutRootCache.clear();
 }
 
+/**
+ * Environment variable naming an absolute per-process scratch tempRoot that
+ * every stream writer must land in during a test run (Story #4696).
+ *
+ * The shared test bootstrap (`lib/test-env.js`) sets this to a fresh
+ * `os.tmpdir()` directory before spawning the test runner, so any test that
+ * reaches a writer (`signals-writer`, the lifecycle `LedgerWriter`, etc.)
+ * *without* explicitly injecting an absolute tempRoot still resolves under
+ * scratch instead of the repo's real `temp/` tree. This is the single
+ * injection seam: because every path helper funnels a relative root through
+ * `anchorTempRoot`, one redirect here covers all writers regardless of how
+ * each one resolved its root.
+ */
+export const TEST_TEMP_ROOT_ENV = 'MANDREL_TEST_TEMP_ROOT';
+
+/**
+ * Resolve the absolute scratch tempRoot override, or `null` when none is
+ * configured. Only an **absolute** value is honoured — a relative override
+ * would re-anchor against the repo tree and defeat the isolation, so it is
+ * ignored (treated as unset). Module-internal: the behaviour is exercised
+ * through `anchorTempRoot`, so it is deliberately not exported (keeps the
+ * public seam to `anchorTempRoot` + `TEST_TEMP_ROOT_ENV`).
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string|null}
+ */
+function testScratchTempRoot(env = process.env) {
+  const override = env?.[TEST_TEMP_ROOT_ENV];
+  return typeof override === 'string' &&
+    override.length > 0 &&
+    path.isAbsolute(override)
+    ? override
+    : null;
+}
+
+/**
+ * Environment variable that opts a test-context process back into the real
+ * `temp/` tree (Story #4711). The `anchorTempRoot` test-context fallback
+ * refuses to anchor a relative root into the repo's telemetry tree when the
+ * process is a node:test context; a test that genuinely needs the real tree
+ * sets this to `'1'` on its own spawn — an explicit, greppable opt-out
+ * instead of a silent bypass.
+ */
+export const TEST_ALLOW_REAL_TEMP_ENV = 'MANDREL_TEST_ALLOW_REAL_TEMP';
+
+/**
+ * Per-process memo for the lazily-created test-context scratch dir, so every
+ * relative-root resolution in one test process converges on a single scratch
+ * tree (mirrors the `_mainCheckoutRootCache` pattern above).
+ */
+let _testContextScratchDir = null;
+
+/**
+ * Test-only: clear the test-context scratch memo so a suite can exercise the
+ * lazy-arming branch repeatedly in one process.
+ */
+export function _clearTestContextScratchCache() {
+  _testContextScratchDir = null;
+}
+
+/**
+ * Is this process a node:test context? True when the env carries
+ * `NODE_TEST_CONTEXT` (set by the node:test runner on every spawned test
+ * child, regardless of how the runner itself was launched) or when the
+ * process was started with the `--test` flag (a direct `node --test <file>`
+ * runner process, or in-process isolation modes).
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string[]} execArgv
+ * @returns {boolean}
+ */
+function inNodeTestContext(env, execArgv) {
+  return Boolean(env?.NODE_TEST_CONTEXT) || execArgv.includes('--test');
+}
+
 /**
  * Anchor a resolved `tempRoot` to the main checkout root when it is a
  * relative path (Story #3900). Absolute roots are returned verbatim; a
@@ -123,11 +200,54 @@ export function _clearMainCheckoutRootCache() {
  * root is returned unchanged so behaviour degrades to the prior
  * cwd-relative semantics rather than throwing.
  *
+ * Test isolation (Story #4696): when the scratch override
+ * (`MANDREL_TEST_TEMP_ROOT`) is set, a relative root is joined onto the
+ * scratch dir instead of the main checkout root, so a writer that reaches
+ * the default (or any relative) root under the test bootstrap lands in
+ * scratch and never pollutes the repo's real `temp/` telemetry tree. An
+ * absolute root injected by a well-behaved test still bypasses the redirect
+ * verbatim.
+ *
+ * Process-level arming (Story #4711): the wrapper-armed override above only
+ * covers processes spawned by `run-tests.js` — a direct `node --test <file>`
+ * run used to bypass it and append fixture records to the real tree. When no
+ * override is armed but the process *is* a node:test context (see
+ * `inNodeTestContext`), a per-process scratch dir is created lazily and the
+ * relative root anchors there instead. The scratch dir is memoized and — for
+ * the real `process.env` — written back to `MANDREL_TEST_TEMP_ROOT` so child
+ * processes the test spawns inherit the same scratch tree. Escape hatch: a
+ * test that genuinely needs the real tree sets
+ * `MANDREL_TEST_ALLOW_REAL_TEMP=1` (`TEST_ALLOW_REAL_TEMP_ENV`) to restore
+ * main-checkout anchoring; the `check-test-temp-hygiene` guard remains the
+ * backstop either way.
+ *
  * @param {string} tempRoot
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @param {{ mkdtemp?: typeof mkdtempSync, execArgv?: string[] }} [deps]
+ *   Injectable for tests.
  * @returns {string}
  */
-export function anchorTempRoot(tempRoot) {
+export function anchorTempRoot(tempRoot, env = process.env, deps = {}) {
   if (path.isAbsolute(tempRoot)) return tempRoot;
+  const scratch = testScratchTempRoot(env);
+  if (scratch) return path.join(scratch, tempRoot);
+  const execArgv = deps.execArgv ?? process.execArgv;
+  if (
+    inNodeTestContext(env, execArgv) &&
+    env?.[TEST_ALLOW_REAL_TEMP_ENV] !== '1'
+  ) {
+    if (_testContextScratchDir === null) {
+      const mkdtemp = deps.mkdtemp ?? mkdtempSync;
+      _testContextScratchDir = mkdtemp(
+        path.join(os.tmpdir(), 'mandrel-test-temp-'),
+      );
+      if (env === process.env) {
+        // Children spawned by this test process inherit the same scratch.
+        process.env[TEST_TEMP_ROOT_ENV] = _testContextScratchDir;
+      }
+    }
+    return path.join(_testContextScratchDir, tempRoot);
+  }
   const root = mainCheckoutRoot();
   return root ? path.join(root, tempRoot) : tempRoot;
 }

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -160,10 +160,19 @@ const SIGNALS_SCHEMA = {
  * behind-the-base PR up to date before giving the branch up as unwinnable,
  * rather than waiting out the budget behind a base it could have merged.
  * All keys default in the consumer when omitted (30s / 300s / 3600s / 3).
+ *
+ * `mode` selects the close-time merge posture (Story #4698). Default `sync`
+ * keeps the in-close foreground wait unchanged. `async` caps the per-invocation
+ * wait to a short probe window (~60s: catches instant merges and instantly-red
+ * required checks) and then returns the resumable `pending` terminal, so a
+ * slow-CI consumer no longer burns ~5 minutes of the host tool slot on a merge
+ * that lands after the wait would have expired anyway — the worker launches the
+ * `pending` envelope's `nextCommand` in the background instead.
  */
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   properties: {
+    mode: { type: 'string', enum: ['sync', 'async'] },
     intervalSeconds: { type: 'integer', minimum: 1 },
     maxWaitSeconds: { type: 'integer', minimum: 1 },
     maxBudgetSeconds: { type: 'integer', minimum: 1 },
@@ -280,6 +289,26 @@ const ACCEPTANCE_EVAL_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.review` — close-scope review tuning (Story #4699). `lensDiffFloor`
+ * is the changed-line floor below which the Story-scope local-lens pass skips
+ * lens materialization for a diff with zero sensitive-path hits (default 40
+ * via `lib/audit-suite/lens-diff-floor.js`; `0` disables the skip). The
+ * maker-blind code-review pass and all hard gates are untouched by the floor.
+ */
+const REVIEW_SCHEMA = {
+  type: 'object',
+  properties: {
+    lensDiffFloor: {
+      type: 'integer',
+      minimum: 0,
+      description:
+        'Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip. Hard gates and the maker-blind code-review pass are unaffected.',
+    },
+  },
+  additionalProperties: false,
+};
+
 /**
  * `delivery.feedbackLoop` — opt-out toggles consumed by the Epic finalize
  * listener's auto-file graduators (`lib/feedback-loop/*-graduator.js`, read
@@ -335,6 +364,7 @@ export const DELIVERY_SCHEMA = {
     quality: QUALITY_SCHEMA,
     mergeWatch: MERGE_WATCH_SCHEMA,
     codeReview: CODE_REVIEW_SCHEMA,
+    review: REVIEW_SCHEMA,
     refactorStage: REFACTOR_STAGE_SCHEMA,
     acceptanceEval: ACCEPTANCE_EVAL_SCHEMA,
     feedbackLoop: FEEDBACK_LOOP_SCHEMA,

package/.agents/scripts/lib/config-settings-schema.js

@@ -278,34 +278,30 @@ const PLANNING_SCHEMA = {
   properties: {
     riskHeuristics: LIST_OR_EXTENDER_OF_STRINGS,
     codebaseSnapshot: CODEBASE_SNAPSHOT_SCHEMA,
-    // Story #4683 — plan-time ceremony-lite complexity gate. Routes a trivial
-    // single-artifact seed onto a collapsed plan/deliver path while a
-    // multi-capability seed keeps the full ceremony. Deterministic and
-    // conservative (full on any doubt); the lite path never relaxes a
-    // non-negotiable (Story ticket, PR-to-main, repo gates, security baseline).
-    // Defaults live on DEFAULT_COMPLEXITY_GATE in
-    // `lib/orchestration/complexity-gate.js`.
+    // Story #4722 (superseding #4683's word-count gate) — shape-derived
+    // ceremony-lite routing. Complexity routes on the objective shape of the
+    // authored work (changes[] count, acceptance count, creates-vs-refactors
+    // mix, sensitive-path classes), never on seed word count: `maxSeedWords`
+    // was removed in the hard cutover and is rejected as an additional
+    // property. The lite path never relaxes a non-negotiable (Story ticket,
+    // PR-to-main, repo gates, security baseline). Defaults live on
+    // DEFAULT_COMPLEXITY_GATE in `lib/orchestration/complexity-gate.js`;
+    // shape ceilings are the framework constants STORY_SHAPE_CEILINGS.
     complexityGate: {
       type: 'object',
       description:
-        'Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.',
+        'Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.',
       properties: {
         enabled: {
           type: 'boolean',
           description:
-            'Master switch. When false, every seed takes the full plan/deliver ceremony. Default true.',
-        },
-        maxSeedWords: {
-          type: 'integer',
-          minimum: 0,
-          description:
-            'Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 60.',
+            'Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true.',
         },
         maxArtifacts: {
           type: 'integer',
           minimum: 0,
           description:
-            'Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1.',
+            'Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1.',
         },
       },
       additionalProperties: false,

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -0,0 +1,217 @@
+/**
+ * metrics-ledger.js — the narrow shared metrics-ledger boundary (Story #4712).
+ *
+ * Owns the one append-tail implementation for the plan-metrics ledger:
+ * path resolution, serialization, lazy directory creation, size-capped
+ * rotation, and the append itself. Every ledger writer — the plan-domain
+ * appenders in `../orchestration/plan-metrics.js` and the close-domain
+ * findings-yield entry point below — routes through
+ * {@link appendLedgerRecord}, so the open→append→rotate→close tail exists
+ * exactly once and cannot drift between call sites.
+ *
+ * The findings-yield entry point (Story #4699) lives here rather than in
+ * the plan-domain module so the story-close review spine
+ * (`../orchestration/story-close/phases/review-core.js`) depends on this
+ * narrow shared ledger module instead of plan-domain internals.
+ *
+ * Wire contract (unchanged by the #4712 re-home): record shapes, file
+ * locations (`temp/run-<id>/plan-metrics.json` / the standalone stream),
+ * and the rotation threshold are exactly what `plan-metrics.js` shipped —
+ * readers (`readPlanMetrics` / `summarizePlanMetrics`) stay plan-side and
+ * key kinded records on `kind`, never on absent fields.
+ *
+ * Robustness contract (mirrors `signals-writer.js`):
+ *   - **No buffering.** Each append opens, writes one line, closes.
+ *   - **Rotation.** When an append would push the ledger past
+ *     `maxBytes`, the current file is renamed to `<name>.1` (replacing any
+ *     prior rollover) and the append starts a fresh ledger.
+ *   - **Best-effort at the entry points.** {@link appendLedgerRecord}
+ *     itself throws on fs failure; each public appender catches, warns via
+ *     `Logger`, and returns `false` so metric capture can never fail the
+ *     wrapped plan phase or Story close.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  anchorTempRoot,
+  runArtifactPath,
+  tempRootFrom,
+} from '../config/temp-paths.js';
+import { Logger } from '../Logger.js';
+
+export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
+export const PLAN_METRICS_SCHEMA_VERSION = 1;
+
+/**
+ * Record kind for a per-close, per-lens findings-yield entry (Story #4699).
+ * One record per Story close whose review ran (or floor-skipped) at least
+ * one local lens:
+ *
+ * ```json
+ * { "v": 1, "kind": "findings-yield", "cli": "story-close-review",
+ *   "storyId": 4699, "epicId": null,
+ *   "lenses": [{ "lens": "audit-clean-code", "findings": 0,
+ *                "skippedByFloor": false }],
+ *   "diffFloor": { "skip": false, "reason": "at-or-above-floor",
+ *                  "floor": 40, "changedLineCount": 120 },
+ *   "at": "..." }
+ * ```
+ *
+ * The ledger only records — no roster behavior changes ride on it. Its
+ * purpose is evidentiary: a lens that stays at zero findings across N
+ * closes becomes droppable on measurement instead of assumption.
+ */
+const PLAN_METRICS_KIND_FINDINGS_YIELD = 'findings-yield';
+
+/**
+ * Rotation threshold. At ~200 bytes per record this is ~5000 invocations —
+ * far beyond any real plan run, so rotation only fires on pathological
+ * accumulation.
+ */
+export const MAX_LEDGER_BYTES = 1024 * 1024;
+
+/**
+ * Resolve the ledger path for an Epic (or the standalone stream when
+ * `epicId` is `null` — the `story-plan.js` / Epic-less healthcheck case).
+ *
+ * @param {number|null} epicId
+ * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).
+ * @returns {string}
+ */
+export function planMetricsPath(epicId, config) {
+  if (epicId === null || epicId === undefined) {
+    return path.join(
+      anchorTempRoot(tempRootFrom(config)),
+      'standalone',
+      PLAN_METRICS_BASENAME,
+    );
+  }
+  return runArtifactPath(epicId, PLAN_METRICS_BASENAME, config);
+}
+
+/**
+ * Rotate the ledger when appending `incomingBytes` would exceed
+ * `maxBytes`. Single-generation rollover: `plan-metrics.json` →
+ * `plan-metrics.json.1` (any prior `.1` is replaced).
+ *
+ * @param {string} filePath
+ * @param {number} incomingBytes
+ * @param {number} maxBytes
+ * @returns {Promise<boolean>} true when a rotation happened.
+ */
+async function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
+  let size = 0;
+  try {
+    size = (await fs.stat(filePath)).size;
+  } catch {
+    return false; // No existing ledger — nothing to rotate.
+  }
+  if (size + incomingBytes <= maxBytes) return false;
+  await fs.rename(filePath, `${filePath}.1`);
+  return true;
+}
+
+/**
+ * The single ledger append tail (Story #4712): serialize the record to one
+ * newline-terminated JSON line, create the ledger directory lazily, rotate
+ * when the byte cap would be exceeded, and append.
+ *
+ * Throws on any fs failure — the best-effort posture (warn + `false`,
+ * never throw) belongs to the public appenders that wrap this, because
+ * each labels its own failure mode.
+ *
+ * @param {object} record Fully-built ledger record (already validated).
+ * @param {{
+ *   epicId?: number|null,
+ *   config?: object,
+ *   maxBytes?: number,
+ * }} [opts] `maxBytes` is a test seam for the rotation threshold.
+ * @returns {Promise<void>}
+ */
+export async function appendLedgerRecord(record, opts = {}) {
+  const filePath = planMetricsPath(opts.epicId ?? null, opts.config);
+  const line = `${JSON.stringify(record)}\n`;
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await rotateIfNeeded(
+    filePath,
+    Buffer.byteLength(line),
+    opts.maxBytes ?? MAX_LEDGER_BYTES,
+  );
+  await fs.appendFile(filePath, line, 'utf8');
+}
+
+/**
+ * Append one findings-yield record (Story #4699). Called once per Story
+ * close by the review spine when the local-lens pass matched (or
+ * floor-skipped) at least one lens. Best-effort: returns `false` (after a
+ * `Logger.warn`) instead of throwing on any failure, so a ledger failure
+ * can never fail the close.
+ *
+ * @param {{
+ *   storyId: number,
+ *   lenses: Array<{ lens: string, findings?: number, skippedByFloor?: boolean }>,
+ *   cli?: string,
+ *   epicId?: number|null,
+ *   diffFloor?: object|null,
+ * }} entry
+ * @param {object} [config]
+ * @param {{ maxBytes?: number }} [opts] Test seam for the rotation threshold.
+ * @returns {Promise<boolean>} true when the line was written.
+ */
+export async function appendFindingsYield(entry, config, opts = {}) {
+  try {
+    if (!entry || typeof entry !== 'object') {
+      throw new TypeError('appendFindingsYield requires an entry object');
+    }
+    const storyId = Number(entry.storyId);
+    if (!Number.isInteger(storyId) || storyId <= 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a positive integer entry.storyId',
+      );
+    }
+    if (!Array.isArray(entry.lenses) || entry.lenses.length === 0) {
+      throw new TypeError(
+        'appendFindingsYield requires a non-empty entry.lenses array',
+      );
+    }
+    const epicId = entry.epicId ?? null;
+    const record = {
+      v: PLAN_METRICS_SCHEMA_VERSION,
+      kind: PLAN_METRICS_KIND_FINDINGS_YIELD,
+      cli:
+        typeof entry.cli === 'string' && entry.cli.length > 0
+          ? entry.cli
+          : 'story-close-review',
+      storyId,
+      epicId,
+      lenses: entry.lenses
+        .filter((l) => l && typeof l.lens === 'string' && l.lens.length > 0)
+        .map((l) => ({
+          lens: l.lens,
+          findings:
+            typeof l.findings === 'number' && Number.isFinite(l.findings)
+              ? l.findings
+              : 0,
+          skippedByFloor: l.skippedByFloor === true,
+        })),
+      diffFloor:
+        entry.diffFloor && typeof entry.diffFloor === 'object'
+          ? entry.diffFloor
+          : null,
+      at: new Date().toISOString(),
+    };
+    await appendLedgerRecord(record, {
+      epicId,
+      config,
+      maxBytes: opts.maxBytes,
+    });
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-metrics] findings-yield append failed (non-fatal): ${err?.message ?? err}`,
+    );
+    return false;
+  }
+}

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -68,6 +68,13 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   CLOSE_FAILED: 'close-failed',
   /** A bounded merge wait expired with the PR still in flight. */
   MERGE_WAIT_EXHAUSTED: 'merge-wait-exhausted',
+  /**
+   * A review/lens tool failed to *execute* (binary missing, unparseable
+   * output, materialization crash) — an operational degradation, not a code
+   * finding. Story #4699 routes these here so findings severity tiers
+   * reflect code findings only.
+   */
+  TOOL_DEGRADED: 'tool-degraded',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */