mandrel 2.22.0 → 2.24.0

package/.agents/docs/configuration.md

@@ -291,6 +291,7 @@ top-level keys are validation errors.
 | `feedbackLoop` | No | `object` | — | Nested configuration block. |
 | `feedbackLoop.auditResultsAutoFile` | No | `boolean` | `true` | When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story. |
 | `feedbackLoop.retroProposals` | No | `boolean` | `true` | When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas. |
+| `feedbackLoop.frictionWindowDays` | No | `integer` | `30` | How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30. |
 | `auditToStories` | No | `object` | — | Nested configuration block. |
 | `auditToStories.severityFloor` | No | `"critical"` \| `"high"` \| `"medium"` \| `"low"` \| `"all"` | `"high"` | Minimum severity a finding must meet to be proposed as a Story on an unattended `/audit-to-stories --auto` sweep (Story #4626). Default high. |
 | `auditToStories.autoComment` | No | `boolean` | `true` | When true (default), `/audit-to-stories --auto` posts a re-detected comment on an already-open matched Issue instead of silently skipping it. |

package/.agents/schemas/agentrc.schema.json

@@ -1430,6 +1430,12 @@
               "type": "boolean",
               "default": true,
               "description": "When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas."
+            },
+            "frictionWindowDays": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 30,
+              "description": "How many days back the run-scope friction recurrence window reaches (Story #4850). The window spans every surviving per-Story signal stream rather than the triggering run's own Stories, so that a defect firing once per Story can reach the actionable threshold; this bounds it by age so a defect fixed weeks ago stops re-routing. Rows older than the bound — and rows carrying no readable timestamp — are excluded and counted on the roll-up step result. Default 30."
             }
           },
           "additionalProperties": false

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -87,7 +87,8 @@
         "statusResync",
         "refCleanup",
         "baseFastForward",
-        "tempPurge"
+        "tempPurge",
+        "leaseRelease"
       ],
       "properties": {
         "followUps": { "type": "boolean" },
@@ -98,6 +99,10 @@
           "type": "boolean",
           "description": "Story #4794 — the merged Story's spent temp artifacts (gate transcripts, validation evidence) were purged under delivery.tempRetention. A disabled policy reports true: the operator turned the purge off, so doing nothing IS the correct outcome. Only a real failure — an unreadable temp root, an undeletable artifact — reports false, and like every tail step that degrades the report, never the land."
         },
+        "leaseRelease": {
+          "type": "boolean",
+          "description": "Story #4860 — the operator's assignee-lease on the Story was released now that the merge is confirmed. The close deliberately no longer releases it at PR creation, so the ticket stays assigned for the whole time its PR is open; every non-merged ending (merge.unlanded block, exhausted wait budget, --no-wait-merge, --no-auto-merge) retains the claim and never reaches this step. A no-op release — the operator is no longer the recorded owner, as on a re-run or a belated manual confirm — reports true: an already-unassigned ticket is the desired end state. Only a throw reports false, and like every tail step that degrades the report, never the land."
+        },
         "details": {
           "type": "object",
           "description": "Per-step diagnostic detail — the reason a false step reported false.",

package/.agents/scripts/deliver-light.js

@@ -61,10 +61,10 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
-import { computeChangeSet } from './lib/orchestration/change-set.js';
+import { resolveBackstopOutcome } from './lib/orchestration/light-backstop.js';
+import { recordGateRefusal } from './lib/orchestration/light-escalation.js';
 import {
   buildReceiptStoryTicket,
-  checkLightDiffBackstop,
   deriveLightSuitability,
   resolveLightGateOutcome,
 } from './lib/orchestration/light-suitability.js';
@@ -121,7 +121,11 @@ Gate options:
                      envelope and ENDS the session (no prompt, no fallback).
 
 Backstop options:
-  --backstop         Re-check the ACTUAL diff after implementation.
+  --backstop         Re-check the ACTUAL diff after implementation. Bounds the
+                     change's IMPLEMENTATION half by magnitude (changed lines +
+                     file sprawl); test/doc/baseline companions are exempt from
+                     the counts but still matched for sensitive paths. A block
+                     emits a nextCommand recycling the receipt through /plan.
   --story <id>       Story issue number whose story-<id> branch to diff.
 
   --pretty           Pretty-print the JSON envelope.
@@ -130,8 +134,6 @@ Backstop options:
 
 /** Exit code when the gate did not resolve to proceed-light. */
 const EXIT_NOT_PROCEED = 2;
-/** Exit code when the diff backstop blocked the land. */
-const EXIT_BACKSTOP_BLOCKED = 3;
 
 /**
  * Split a comma-separated path list into trimmed, non-empty entries.
@@ -292,33 +294,6 @@ export function buildNextCommands(storyId) {
   };
 }
 
-/**
- * Run the diff backstop against a Story branch's actual change set.
- *
- * @param {{
- *   storyId: number,
- *   baseRef?: string,
- *   cwd?: string,
- *   computeFn?: typeof computeChangeSet,
- *   injectedRules?: object,
- * }} args
- * @returns {ReturnType<typeof checkLightDiffBackstop>}
- */
-export function runDiffBackstop({
-  storyId,
-  baseRef = 'main',
-  cwd = process.cwd(),
-  computeFn = computeChangeSet,
-  injectedRules,
-} = {}) {
-  const { files } = computeFn({
-    baseRef,
-    headRef: `story-${storyId}`,
-    cwd,
-  });
-  return checkLightDiffBackstop({ changedFiles: files, injectedRules });
-}
-
 /**
  * Was a non-blank `--operator-proceed-light` supplied? The gate core decides
  * whether it *applies*; this only asks whether the operator typed one, so the
@@ -348,27 +323,28 @@ function emit(envelope, pretty) {
 }
 
 /**
- * Backstop mode — re-check the actual diff.
+ * Backstop mode — re-check the actual diff. The decision lives in
+ * {@link module:lib/orchestration/light-backstop}; this branches and prints.
  *
- * @param {{ story?: string, pretty: boolean }} values
+ * @param {object} values Parsed CLI values.
+ * @param {{ resolveFn?: typeof resolveBackstopOutcome }} [deps]
  * @returns {Promise<number>}
  */
-async function runBackstopMode(values) {
+async function runBackstopMode(values, deps = {}) {
+  const { resolveFn = resolveBackstopOutcome } = deps;
   const storyId = Number.parseInt(String(values.story ?? ''), 10);
   if (!Number.isInteger(storyId) || storyId <= 0) {
     process.stderr.write(HELP);
     throw new Error('[deliver-light] --backstop requires --story <id>');
   }
-  const result = runDiffBackstop({ storyId });
-  emit({ mode: 'backstop', storyId, ...result }, values.pretty);
-  if (result.blocked) {
-    Logger.warn(
-      `[deliver-light] diff backstop BLOCKED Story #${storyId}: ${result.reasons.join('; ')}`,
-    );
-    return EXIT_BACKSTOP_BLOCKED;
-  }
-  Logger.info(`[deliver-light] diff backstop clean for Story #${storyId}.`);
-  return 0;
+  const { result, nextCommand, exitCode, message } = await resolveFn({
+    storyId,
+  });
+  const extra = nextCommand === null ? {} : { nextCommand };
+  emit({ mode: 'backstop', storyId, ...result, ...extra }, values.pretty);
+  if (result.blocked) Logger.warn(message);
+  else Logger.info(message);
+  return exitCode;
 }
 
 /**
@@ -407,6 +383,7 @@ export async function runGateMode(values, deps = {}) {
     createReceiptFn = createLightReceipt,
     emitFn = emit,
     emitTerminalFn = emitTerminalEnvelope,
+    recordRefusalFn = recordGateRefusal,
   } = deps;
 
   if (!values.prompt || String(values.prompt).trim() === '') {
@@ -457,6 +434,7 @@ export async function runGateMode(values, deps = {}) {
       { mode: 'gate', action: gate.action, outcome: gate.outcome },
       values.pretty,
     );
+    await recordRefusalFn({ gate, amends: values.amends });
     Logger.warn(
       `[deliver-light] gate did not proceed light (${gate.action}): ${gate.outcome.reasons.join('; ')}`,
     );

package/.agents/scripts/diagnose-friction.js

@@ -31,6 +31,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
+import { constants as osConstants } from 'node:os';
 import { getLimits, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
@@ -97,6 +98,72 @@ function classifyFrictionCategory(errorOutput) {
   return { category: matched.category, remediation: matched.remediation };
 }
 
+/**
+ * `spawnSync`'s own `timeout` option kills the child with `SIGTERM`, so a
+ * SIGTERM observed here almost always means the interceptor's configured
+ * `executionTimeoutMs` bound fired. Any other signal — a `SIGKILL` from the
+ * OOM killer, an operator `kill -9` — originated outside this process.
+ *
+ * @type {string}
+ */
+const INTERCEPTOR_TIMEOUT_SIGNAL = 'SIGTERM';
+
+/** Shell convention for "the process died by signal N": exit `128 + N`. */
+const SIGNAL_EXIT_BASE = 128;
+
+/**
+ * Describe a child that never exited normally — `status === null`, Node's
+ * documented representation of "did not exit normally". The raw status must
+ * never reach `process.exit`, because `process.exit(null)` exits **0**: the
+ * interceptor would report success for a command it just watched get killed
+ * (Story #4851).
+ *
+ * Which signal fired is the diagnostic value: SIGTERM points at the
+ * interceptor's own bound, anything else at the host. Recording that plus the
+ * bound itself is what makes the row actionable to a consumer who cannot edit
+ * the materialized framework tree.
+ *
+ * Deliberately module-local and pure — exporting it for tests would fail the
+ * `--production` dead-exports ratchet, and folding it into `main` would spend
+ * the file's per-file maintainability-delta headroom. The CLI contract is the
+ * seam the unit tests drive.
+ *
+ * @param {{signal: (string|null), error?: {message?: string}}} result A
+ *   `spawnSync` result whose `status` is `null`.
+ * @param {number} executionTimeoutMs The resolved interceptor bound, in ms.
+ * @returns {{category: string, remediation: string, details: object,
+ *   preview: string, exitCode: number}}
+ */
+function describeAbnormalExit(result, executionTimeoutMs) {
+  const signal = typeof result.signal === 'string' ? result.signal : null;
+  if (signal === null) {
+    return {
+      category: FRICTION_DEFAULT.category,
+      remediation: FRICTION_DEFAULT.remediation,
+      details: {
+        killedBySignal: null,
+        killOrigin: 'spawn-failure',
+        executionTimeoutMs,
+      },
+      preview: `Command did not exit normally and reported no signal: ${result.error?.message ?? 'spawn produced no exit status'}.`,
+      exitCode: 1,
+    };
+  }
+
+  const timedOut = signal === INTERCEPTOR_TIMEOUT_SIGNAL;
+  const killOrigin = timedOut ? 'interceptor-timeout' : 'external';
+  const signum = osConstants.signals[signal];
+  return {
+    category: timedOut ? 'Execution Timeout' : 'Execution Killed',
+    remediation: timedOut
+      ? ` - ${signal} matches the interceptor's own executionTimeoutMs bound (${executionTimeoutMs}ms), so the command was almost certainly cut off rather than broken. Split it into smaller steps, or raise the bound.`
+      : ` - ${signal} originated outside the interceptor — the executionTimeoutMs bound (${executionTimeoutMs}ms) did not fire, so suspect an OOM kill or a hard kill from the host. Reduce the command's memory footprint or give the host more headroom.`,
+    details: { killedBySignal: signal, killOrigin, executionTimeoutMs },
+    preview: `Command terminated by signal ${signal} (${killOrigin}); executionTimeoutMs=${executionTimeoutMs}.`,
+    exitCode: Number.isInteger(signum) ? SIGNAL_EXIT_BASE + signum : 1,
+  };
+}
+
 function toIntOrNull(value) {
   if (value == null) return null;
   const n = Number.parseInt(String(value), 10);
@@ -121,6 +188,7 @@ function buildFrictionSignal({
   category,
   commandStr,
   errorPreview,
+  terminationDetails = null,
 }) {
   return {
     kind: 'friction',
@@ -133,11 +201,14 @@ function buildFrictionSignal({
     // and always null.
     taskId: null,
     category,
+    // `emitter.command` is what `classifySignalSource` step 1 scans, so the
+    // command-scan stays authoritative for `source`: a consumer command killed
+    // by its own host remains consumer-actionable (Story #4851).
     emitter: {
       tool: 'diagnose-friction.js',
       command: commandStr,
     },
-    details: { errorPreview },
+    details: { errorPreview, ...(terminationDetails ?? {}) },
   };
 }
 
@@ -176,10 +247,22 @@ export async function main(args = process.argv.slice(2)) {
   if (result.stderr) process.stderr.write(result.stderr);
 
   if (result.status !== 0) {
+    // A `null` status means the child never exited normally; the cause lives in
+    // `result.signal`, not in the status.
+    const abnormal =
+      result.status === null
+        ? describeAbnormalExit(result, executionTimeoutMs)
+        : null;
+    // With both streams empty an abnormal termination names its signal; the
+    // `Unknown exit code` fallback is therefore reachable only with a real
+    // numeric status, never as `Unknown exit code null`.
+    const noOutputFallback = abnormal
+      ? abnormal.preview
+      : `Unknown exit code ${result.status}`;
     const errorOutput = (
       result.stderr ||
       result.stdout ||
-      `Unknown exit code ${result.status}`
+      noOutputFallback
     ).trim();
     const errorPreview = errorOutput.substring(0, 500);
 
@@ -188,7 +271,12 @@ export async function main(args = process.argv.slice(2)) {
       'Command failed. Appending friction signal to NDJSON stream...',
     );
 
-    const { category, remediation } = classifyFrictionCategory(errorOutput);
+    // An abnormal termination classifies itself: the marker scan reads output
+    // the kill may have truncated (or never produced), so it cannot name the
+    // signal.
+    const classified = classifyFrictionCategory(errorOutput);
+    const category = abnormal?.category ?? classified.category;
+    const remediation = abnormal?.remediation ?? classified.remediation;
 
     const { storyId: resolvedStoryId, epicId: resolvedEpicId } =
       resolveContextIds({ storyId, epicId }, config);
@@ -199,6 +287,7 @@ export async function main(args = process.argv.slice(2)) {
       category,
       commandStr,
       errorPreview,
+      terminationDetails: abnormal?.details ?? null,
     });
 
     // Story #2874 — accept story-only context (no parent Epic). When
@@ -236,7 +325,9 @@ export async function main(args = process.argv.slice(2)) {
     Logger.error(remediation);
     Logger.error('----------------------------------------\n');
 
-    process.exit(result.status);
+    // Never `process.exit(result.status)` on a null status — that exits 0 and
+    // reports success for a killed command.
+    process.exit(abnormal?.exitCode ?? result.status);
   } else {
     process.exit(0);
   }

package/.agents/scripts/lib/audit-suite/lens-diff-floor.js

@@ -28,6 +28,7 @@
  */
 
 import { gitSpawn } from '../git-utils.js';
+import { readNumstatRows } from '../orchestration/diff-magnitude.js';
 import { selectSensitivePathClasses } from './selector.js';
 
 /**
@@ -58,6 +59,12 @@ export function resolveLensDiffFloor(config) {
  * Count the changed lines (additions + deletions) in the
  * `baseRef...headRef` diff via `git diff --numstat`.
  *
+ * The read and the parse are shared with the light path's magnitude backstop
+ * ({@link module:lib/orchestration/diff-magnitude.readNumstatRows}) so the two
+ * cannot disagree about how a diff is measured. This one keeps a whole-diff
+ * total: the lens floor asks "is this diff small", not "is its implementation
+ * half small", so it deliberately does **not** apply the companion exemption.
+ *
  * Total — never throws. Returns `null` (the neutral "count unknown" signal
  * the floor fails open on) for any git failure or unparseable output, and
  * `0` for a genuinely empty diff. Binary rows (`-\t-\tpath`) contribute 0
@@ -77,31 +84,9 @@ export function countChangedLines({
   cwd = process.cwd(),
   gitSpawnFn = gitSpawn,
 } = {}) {
-  if (typeof baseRef !== 'string' || baseRef.length === 0) return null;
-  if (typeof headRef !== 'string' || headRef.length === 0) return null;
-  try {
-    const result = gitSpawnFn(
-      cwd,
-      'diff',
-      '--numstat',
-      `${baseRef}...${headRef}`,
-    );
-    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
-      return null;
-    }
-    let total = 0;
-    for (const line of result.stdout.split('\n')) {
-      const trimmedEnd = line.replace(/\s+$/, '');
-      if (trimmedEnd.length === 0) continue;
-      const match = /^(\d+|-)\t(\d+|-)\t/.exec(trimmedEnd);
-      if (!match) return null; // Unexpected format — the count is not trustworthy.
-      if (match[1] !== '-') total += Number(match[1]);
-      if (match[2] !== '-') total += Number(match[2]);
-    }
-    return total;
-  } catch {
-    return null;
-  }
+  const rows = readNumstatRows({ baseRef, headRef, cwd, gitSpawnFn });
+  if (rows === null) return null;
+  return rows.reduce((total, row) => total + row.additions + row.deletions, 0);
 }
 
 /**

package/.agents/scripts/lib/baselines/kinds/maintainability.js

@@ -30,10 +30,25 @@ export const name = 'maintainability';
 export const keyField = 'path';
 
 /**
- * Files the maintainability scorer cannot measure because `typhonjs-escomplex`
- * (the upstream kernel) parse-fails on syntax the runtime supports but the
- * library has never been updated for. Each entry must carry a one-line reason
- * so a future engine bump can audit the list and drop the exclusion.
+ * Files the maintainability scorer cannot measure because the upstream kernel
+ * throws on them. Each entry must carry a one-line reason so a future engine
+ * bump can audit the list and drop the exclusion.
+ *
+ * **This list is empty, and the goal is to keep it that way.** It previously
+ * held seven paths, all attributed to escomplex "choking on modern
+ * destructuring / regex-property patterns". That diagnosis was wrong. The real
+ * defect is that `typhonjs-escomplex`'s code generator is written against
+ * ESTree while its own parser emits Babel, so a regex literal in a loop head,
+ * an `await` in a loop head, a `?.`, a dynamic `import()`, or an object spread
+ * in a default parameter aborted the whole file's analysis. That is now
+ * repaired at the kernel boundary by `lib/escomplex-ast-compat.js`, which makes
+ * all four surviving entries scorable — and the audit incidentally showed the
+ * other three had been pointing at deleted files, because nothing audits an
+ * allowlist whose only effect is to suppress output.
+ *
+ * Before adding a path here, check whether `escomplex-ast-compat.js` can handle
+ * the construct instead. An entry here is a file nobody measures; a handler
+ * there gets it measured for every consumer.
  *
  * Story #2467 / Task #2494 — the prior behaviour stored these files with
  * `mi: 0` in `baselines/maintainability.json`, which corrupted the global
@@ -44,34 +59,7 @@ export const keyField = 'path';
  *
  * Canonicalised POSIX repo-relative paths.
  */
-export const MAINTAINABILITY_EXCLUSIONS = Object.freeze(
-  new Set([
-    // escomplex: "Cannot read properties of undefined (reading 'pattern')" —
-    // chokes on modern destructuring / regex-property patterns used in the
-    // reconciler's spec walker.
-    '.agents/scripts/acceptance-spec-reconciler.js',
-    // escomplex: same "pattern" parse failure as acceptance-spec-reconciler;
-    // both files share the lifecycle-lint regex-driven scan helpers.
-    '.agents/scripts/check-lifecycle-lint.js',
-    // escomplex: "this[node.callee.type] is not a function" — the cyclomatic
-    // visitor lacks a handler for one of the quality-watch CLI's call shapes.
-    '.agents/scripts/quality-watch.js',
-    // escomplex: "Cannot read properties of undefined (reading 'pattern')" —
-    // the audit-to-stories parser reuses the same regex-property scan
-    // patterns as acceptance-spec-reconciler.
-    '.agents/scripts/lib/audit-to-stories/parse-audit-md.js',
-    // escomplex: same "pattern" parse failure family — the BDD scanner walks
-    // source trees with regex visitors that hit the upstream destructuring
-    // bug.
-    '.agents/scripts/lib/bdd-scenario-scanner.js',
-    // escomplex: same "pattern" parse failure — the wave-runner tick uses
-    // the regex-property destructuring escomplex chokes on.
-    '.agents/scripts/lib/wave-runner/tick.js',
-    // escomplex: same "pattern" parse failure — exercises the same
-    // destructuring shape in a test fixture.
-    'tests/scripts/story-close-merge-subject.test.js',
-  ]),
-);
+export const MAINTAINABILITY_EXCLUSIONS = Object.freeze(new Set());
 
 /**
  * Filter parse-unscorable files out of a rows array. Used by the scorer

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

@@ -322,12 +322,20 @@ const REVIEW_SCHEMA = {
  * issues via the graduator pre-parsed-findings seam, and the rendered retro
  * sections list the filed issue numbers instead of paste-ready `gh` command
  * stanzas; set it to `false` to fall back to the command stanzas.
+ *
+ * `frictionWindowDays` (Story #4850) bounds the run-scope friction recurrence
+ * window by row age. The window deliberately spans every surviving signal
+ * stream rather than the triggering run's own Stories — that is what lets a
+ * once-per-Story systemic defect reach the ≥ 2 actionable threshold — which
+ * left it unbounded in time, so a defect fixed weeks ago kept re-routing. An
+ * integer ≥ 1; unset means 30 days.
  */
 const FEEDBACK_LOOP_SCHEMA = {
   type: 'object',
   properties: {
     auditResultsAutoFile: { type: 'boolean' },
     retroProposals: { type: 'boolean' },
+    frictionWindowDays: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };