mandrel 2.5.0 → 2.6.0

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

@@ -45,7 +45,7 @@
 import crypto from 'node:crypto';
 
 import { Logger } from '../Logger.js';
-import { appendSignal } from './signals-writer.js';
+import { appendSignal, forEachLine } from './signals-writer.js';
 
 /**
  * The friction categories this module emits.
@@ -202,19 +202,150 @@ export async function emitBlockRecoveredFriction({
 }
 
 /**
- * Pure predicate: is this signal a recovery-marked `story-blocked` record?
+ * Emit the recovery counterpart of a `close-failed` record when a Story's
+ * close ultimately lands (Story #4649).
+ *
+ * A close that fails once — CI/lease contention, a transient GitHub fault —
+ * and succeeds on a later attempt still fired a `close-failed` record at the
+ * failed terminal, which the composer counts exactly like a close that never
+ * recovered. This is the `close-failed` analogue of
+ * {@link emitBlockRecoveredFriction}: same `recovered: true` discriminator,
+ * same category (a distinct bucket would itself aggregate into a routable
+ * proposal, re-introducing the noise).
+ *
+ * **Why this is not emitted from `frictionForTerminal`.** A `landed` terminal
+ * envelope is emitted at the very END of close — *after* the post-land tail
+ * has already gathered the signal stream and filed its follow-ups. A marker
+ * written there would arrive too late to net anything out of the run that
+ * produced it. So the emit hangs off `runPostLandTail`, which is the single
+ * shared land point (reached from both the in-close land and the standalone
+ * `single-story-confirm-merge.js` resume) and runs BEFORE follow-up capture.
+ *
+ * **Conditional on an actual failure.** The marker is appended only when the
+ * Story's stream already carries an un-recovered `close-failed`. Emitting
+ * unconditionally on every land would write a `close-failed` row for Stories
+ * whose close never failed — a category-mislabelled record — and, because the
+ * netting is per `(category, storyId)` over the cumulative stream, that
+ * spurious marker would suppress the Story's `close-failed` bucket outright,
+ * making the category un-routable at story scope for a Story that never had
+ * a close failure at all.
+ *
+ * What this guard does NOT do is bound the netting once a *legitimate* marker
+ * exists. The netting inherits the Story #4622 coarsening — per
+ * `(category, storyId)` across the whole stream, not 1:1 pairing — so a
+ * later, genuinely un-landed `close-failed` for a Story that already
+ * recovered once is still netted away, and does not even reach `discarded`.
+ * Reaching that needs a re-close after a land (a confirm-merge resume, or a
+ * close after a revert). Deliberate, inherited, and called out here rather
+ * than papered over: an aggregate is a routing heuristic, not an incident
+ * ledger.
+ *
+ * Best-effort; never throws. A read failure yields no marker (the failure
+ * stays counted) rather than a speculative write.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {object} [args.config]
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export async function emitCloseRecoveredFriction({ storyId, config } = {}) {
+  const sid = positiveIntOrNull(storyId);
+  if (sid === null) return false;
+
+  let failed = false;
+  let recovered = false;
+  try {
+    await forEachLine(
+      null,
+      sid,
+      (parsed) => {
+        if (!parsed || typeof parsed !== 'object') return;
+        if (parsed.category !== RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED) {
+          return;
+        }
+        if (isRecoveredSignal(parsed)) recovered = true;
+        else failed = true;
+      },
+      config,
+    );
+  } catch (err) {
+    Logger.warn(
+      `[runtime-friction] close-recovery probe failed for Story #${sid}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return false;
+  }
+  // Nothing to cancel, or already cancelled — a second marker would be noise.
+  if (!failed || recovered) return false;
+
+  return emitRuntimeFriction({
+    storyId: sid,
+    category: RUNTIME_FRICTION_CATEGORIES.CLOSE_FAILED,
+    tool: 'runPostLandTail',
+    details: { recovered: true },
+    config,
+  });
+}
+
+/**
+ * Normalize one raw signals-stream row into the shape the retro composer
+ * consumes, or `null` when the row carries no usable category.
+ *
+ * Single-homed because BOTH production gathers need it identically —
+ * `gatherStoryFrictionSignals` (story scope) and `executeFollowUpRollup`
+ * (run scope) — and the bug this exists to prevent is precisely the two of
+ * them drifting: they each independently flattened rows to
+ * `{ category, source }`, dropping the `storyId` / `details` the composer's
+ * recovery-netting keys on, which left that netting unreachable on real data
+ * while its unit tests stayed green (Story #4649).
+ *
+ * The row's own `storyId` wins over `fallbackStoryId` so a stream carrying
+ * foreign rows attributes each one correctly; the fallback covers records
+ * written before the field existed.
+ *
+ * @param {unknown} parsed          One parsed NDJSON row.
+ * @param {number}  fallbackStoryId Stream owner, used when the row has none.
+ * @returns {{ category: string, source: 'framework'|'consumer', storyId: number, details: object }|null}
+ */
+export function normalizeGatheredSignal(parsed, fallbackStoryId) {
+  if (!parsed || typeof parsed !== 'object') return null;
+  const category =
+    typeof parsed.category === 'string' ? parsed.category.trim() : '';
+  if (!category) return null;
+  const recordStoryId = Number(parsed.storyId);
+  return {
+    category,
+    source: parsed.source === 'framework' ? 'framework' : 'consumer',
+    storyId: Number.isInteger(recordStoryId) ? recordStoryId : fallbackStoryId,
+    details:
+      parsed.details && typeof parsed.details === 'object'
+        ? parsed.details
+        : {},
+  };
+}
+
+/**
+ * Pure predicate: is this signal a recovery marker for its own category?
  * Shared with the retro composer so the "recovered" discriminator is read
- * from one place. A record is a recovery marker when its category is
- * `story-blocked` and `details.recovered === true`.
+ * from one place.
+ *
+ * **Category-agnostic by design (Story #4649).** The predicate used to hard-
+ * code `story-blocked`, which meant every new category needing recovery
+ * semantics had to re-implement the netting. A record is a recovery marker
+ * when it carries a usable `category` and `details.recovered === true`; the
+ * composer nets per `(category, storyId)`, so a marker can only ever cancel
+ * records in its OWN bucket.
  *
  * @param {object} signal
  * @returns {boolean}
  */
-export function isRecoveredBlockSignal(signal) {
+export function isRecoveredSignal(signal) {
   return (
     signal !== null &&
     typeof signal === 'object' &&
-    signal.category === RUNTIME_FRICTION_CATEGORIES.STORY_BLOCKED &&
+    typeof signal.category === 'string' &&
+    signal.category.trim() !== '' &&
     signal.details !== null &&
     typeof signal.details === 'object' &&
     signal.details.recovered === true

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -19,10 +19,10 @@ import { selectAudits } from '../audit-suite/index.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
-import { forEachLine } from '../observability/signals-writer.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
   buildFollowUpsCommentBody,
+  gatherRunFrictionSignals,
   resolveFollowUpRepos,
 } from './story-follow-ups.js';
 import { upsertStructuredComment } from './ticketing.js';
@@ -551,24 +551,10 @@ async function executeFollowUpRollup({
   config,
   cwd,
 }) {
-  const signals = [];
-  for (const raw of stories) {
-    const sid = Number(raw);
-    if (!Number.isInteger(sid) || sid <= 0) continue;
-    await forEachLine(
-      null,
-      sid,
-      (parsed) => {
-        if (!parsed || typeof parsed !== 'object') return;
-        const category =
-          typeof parsed.category === 'string' ? parsed.category.trim() : '';
-        if (!category) return;
-        const source = parsed.source === 'framework' ? 'framework' : 'consumer';
-        signals.push({ category, source });
-      },
-      config,
-    );
-  }
+  // Shared with the story-scoped gather (Story #4649): `storyId` + `details`
+  // are what the composer's recovery-netting keys on, and two hand-rolled
+  // copies of this loop are how they got dropped in the first place.
+  const signals = await gatherRunFrictionSignals(stories, config);
   const repos = resolveFollowUpRepos(config);
   const primaryId = Number(stories[0]);
   const proposals = composeRoutedProposals({

package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js

@@ -33,6 +33,7 @@ import path from 'node:path';
 
 import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
 import { Logger } from '../../../Logger.js';
+import { emitCloseRecoveredFriction as defaultEmitCloseRecoveredFriction } from '../../../observability/runtime-friction.js';
 import { acquireLockWithWait as defaultAcquireLockWithWait } from '../../../single-story-sweep/sweep-lock.js';
 import {
   executeFastForward as defaultExecuteFastForward,
@@ -250,6 +251,7 @@ async function stepBaseFastForward({
  * @param {object} [args.config]
  * @param {(tag: string, msg: string) => void} [args.progress]
  * @param {Function} [args.captureStoryFollowUpsFn] Test seam.
+ * @param {Function} [args.emitCloseRecoveredFrictionFn] Test seam.
  * @param {Function} [args.reassertStatusColumnFn]  Test seam.
  * @param {Function} [args.gitSpawnFn]              Test seam.
  * @param {Function} [args.planFastForwardFn]       Test seam.
@@ -266,6 +268,7 @@ export async function runPostLandTail({
   config,
   progress,
   captureStoryFollowUpsFn = defaultCaptureStoryFollowUps,
+  emitCloseRecoveredFrictionFn = defaultEmitCloseRecoveredFriction,
   reassertStatusColumnFn = defaultReassertStatusColumn,
   gitSpawnFn = defaultGitSpawn,
   planFastForwardFn = defaultPlanFastForward,
@@ -274,6 +277,14 @@ export async function runPostLandTail({
 }) {
   progress?.('POST-LAND', `🧾 Running land tail for Story #${storyId}...`);
 
+  // Story #4649 — the close landed, so any earlier `close-failed` for this
+  // Story was transient. Emit the recovery marker BEFORE follow-up capture
+  // reads the stream: the `landed` terminal envelope is emitted after this
+  // whole tail, so a marker written there would arrive too late to net
+  // anything out of the very run that produced the failure. Best-effort and
+  // never throws, exactly like every other tail step.
+  await emitCloseRecoveredFrictionFn({ storyId, config });
+
   const followUps = await step(
     () =>
       stepFollowUps({

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -12,8 +12,12 @@
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
 import { Logger } from '../Logger.js';
+import { normalizeGatheredSignal } from '../observability/runtime-friction.js';
 import { forEachLine } from '../observability/signals-writer.js';
-import { composeRoutedProposals } from './retro-proposals.js';
+import {
+  composeRoutedProposals,
+  deriveUnresolvedBlockedEvents,
+} from './retro-proposals.js';
 import { upsertStructuredComment } from './ticketing.js';
 
 export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
@@ -46,9 +50,23 @@ export function resolveFollowUpRepos(config) {
 }
 
 /**
+ * Gather the Story's friction signals for the composer.
+ *
+ * **`storyId` and `details` are load-bearing (Story #4649).** This function
+ * used to flatten every record to `{ category, source }`, which silently
+ * dropped exactly the two fields `netOutRecoveredIncidents` keys on — so the
+ * Story #4622 recovery-netting could never fire on real data, and every
+ * transient friction event survived to be auto-filed. The composer's unit
+ * tests passed throughout, because they fed it synthetic signals carrying
+ * both fields that no production path ever produced. Preserve them.
+ *
+ * The record's own `storyId` is preferred over the argument so a stream that
+ * carries foreign rows attributes each one correctly; the argument is the
+ * fallback for records written before the field existed.
+ *
  * @param {number} storyId
  * @param {object} [config]
- * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer' }>>}
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
  */
 export async function gatherStoryFrictionSignals(storyId, config) {
   const signals = [];
@@ -56,22 +74,40 @@ export async function gatherStoryFrictionSignals(storyId, config) {
     null,
     storyId,
     (parsed) => {
-      if (!parsed || typeof parsed !== 'object') return;
-      const kind = parsed.kind;
-      if (kind !== 'friction' && kind !== undefined) {
-        // Prefer friction records; also accept category-bearing rows.
-      }
-      const category =
-        typeof parsed.category === 'string' ? parsed.category.trim() : '';
-      if (!category) return;
-      const source = parsed.source === 'framework' ? 'framework' : 'consumer';
-      signals.push({ category, source });
+      const signal = normalizeGatheredSignal(parsed, storyId);
+      if (signal) signals.push(signal);
     },
     config,
   );
   return signals;
 }
 
+/**
+ * Gather friction signals across every Story in a run, for the run-scoped
+ * roll-up.
+ *
+ * Homed beside {@link gatherStoryFrictionSignals} on purpose: the two used to
+ * be independent copies of the same loop in two modules, and they drifted in
+ * exactly the way that made the recovery-netting unreachable (Story #4649).
+ * One reader, one normalizer, no second place to forget a field.
+ *
+ * Unusable ids are skipped rather than throwing — a roll-up must not fail the
+ * epilogue over one malformed entry.
+ *
+ * @param {Array<number|string>} storyIds
+ * @param {object} [config]
+ * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
+ */
+export async function gatherRunFrictionSignals(storyIds, config) {
+  const signals = [];
+  for (const raw of Array.isArray(storyIds) ? storyIds : []) {
+    const sid = Number(raw);
+    if (!Number.isInteger(sid) || sid <= 0) continue;
+    signals.push(...(await gatherStoryFrictionSignals(sid, config)));
+  }
+  return signals;
+}
+
 /**
  * Render the empty-roll-up line.
  *
@@ -250,7 +286,11 @@ export async function captureStoryFollowUps({
       frameworkRepo: repos.frameworkRepo,
       consumerRepo: repos.consumerRepo,
       signals,
-      unresolvedBlockedEvents: [],
+      // Derived, not hardcoded `[]` (Story #4649). This is the escape hatch
+      // the retired story-scope threshold carve-out was standing in for: a
+      // Story still parked at `agent::blocked` files at a single occurrence,
+      // while one that blocked and self-resolved nets out entirely.
+      unresolvedBlockedEvents: deriveUnresolvedBlockedEvents(signals),
     });
     const graduated = await graduateRetroProposals({
       epicId: sid,

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.6.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.5.0...mandrel-v2.6.0) (2026-07-20)
+
+
+### Fixed
+
+* **retro:** generalize friction recovery-netting, preserve signal fields on gather, and retire the story-scope singleton auto-file ([#4649](https://github.com/dsj1984/mandrel/issues/4649)) ([#4650](https://github.com/dsj1984/mandrel/issues/4650)) ([bdb8250](https://github.com/dsj1984/mandrel/commit/bdb82507d188bfe53bbd47fea7b18b2c3160439c))
+
 ## [2.5.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.4.0...mandrel-v2.5.0) (2026-07-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",