mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/orchestration/retro/phases/compose-body.js

@@ -26,6 +26,37 @@ export function normalizeInterventionCount(value) {
   return Math.trunc(value);
 }
 
+/**
+ * Pure: does `routedProposals` carry at least one actionable item (a
+ * framework- or consumer-routed `gh issue create` proposal)? Story #4417 —
+ * the compact retro shape (and therefore the `automerge-verdict`
+ * `cleanSprint: true` flag it drives) MUST be suppressed whenever an
+ * actionable proposal exists, regardless of `forceFull` or the
+ * comment-derived counts: the clean-sprint verdict is an auto-merge input
+ * and must never read "clean" while actionable friction sits in the routed
+ * proposals. Discarded (single-occurrence) items do NOT count — they are
+ * the retro's explicit "nothing to file" bucket.
+ *
+ * @param {{ framework?: object[], consumer?: object[] } | null | undefined} routedProposals
+ * @returns {boolean}
+ */
+export function hasActionableProposals(routedProposals) {
+  if (
+    !routedProposals ||
+    typeof routedProposals !== 'object' ||
+    Array.isArray(routedProposals)
+  ) {
+    return false;
+  }
+  const framework = Array.isArray(routedProposals.framework)
+    ? routedProposals.framework
+    : [];
+  const consumer = Array.isArray(routedProposals.consumer)
+    ? routedProposals.consumer
+    : [];
+  return framework.length > 0 || consumer.length > 0;
+}
+
 /**
  * Pure: derive the recurring-defect-class signal from the routed-proposal
  * sections (Story #4135 / Epic #4131, F11).
@@ -125,7 +156,15 @@ export function composeRetroBody(input) {
   } = input;
 
   const interventions = normalizeInterventionCount(counts?.interventions);
-  const compact = !forceFull && isCleanManifest({ ...counts, interventions });
+  // Story #4417 — the compact shape requires BOTH a clean manifest AND zero
+  // actionable routed proposals. The routed proposals and the counts are
+  // derived from the same unified signals scan (gather-signals.js), so this
+  // guard closes the window where the comment-derived counts read "clean"
+  // while the ndjson-derived routed proposals hold an actionable item.
+  const compact =
+    !forceFull &&
+    isCleanManifest({ ...counts, interventions }) &&
+    !hasActionableProposals(routedProposals);
   const heading = `## 🪞 Sprint Retrospective — Epic #${epicId}: ${epicTitle}`;
   const generatedLine = `_Generated ${timestamp}_`;
   const scorecardRows = [
@@ -214,12 +253,11 @@ export function composeRetroBody(input) {
     legacyActionItems.length > 0 ? legacyActionItems.join('\n') : '_None._';
 
   // Story #2558 — routed-proposals mode. When routedProposals is supplied
-  // AND any of the four buckets is non-empty, render the four explicit
+  // AND any of the three buckets is non-empty, render the three explicit
   // sections in deterministic order ABOVE the retro-complete marker:
   //   1. Proposed issues — consumer repo
   //   2. Proposed issues — framework repo
-  //   3. Proposed memory updates
-  //   4. One-off / discarded
+  //   3. One-off / discarded
   // Otherwise the legacy "Action Items for Next Epic" section renders.
   const routedSectionsBlock = renderRoutedSections(routedProposals);
 
@@ -419,7 +457,10 @@ function shellEscape(s) {
  * Render the body lines (everything below a section heading and its trailing
  * blank) for a "proposed issues" bucket — the consumer and framework sections
  * share this shape. Empty buckets collapse to a single `_None._`; populated
- * buckets emit one fenced `gh issue create` stanza per item.
+ * buckets emit, per item, either the **filed issue reference** (when the
+ * retro auto-filer already filed it — Story #4418, stamped as
+ * `item.filedIssue`) or the paste-ready fenced `gh issue create` stanza (the
+ * toggle-OFF / filing-skipped fallback).
  *
  * @param {object[]} items
  * @returns {string[]}
@@ -430,32 +471,21 @@ function renderIssueBucket(items) {
   for (const item of items) {
     lines.push(`- **${item.title ?? item.category}**`);
     lines.push('');
-    lines.push('```sh');
-    lines.push(String(item.command ?? ''));
-    lines.push('```');
+    if (item.filedIssue && item.filedIssue.url) {
+      const ref = Number.isInteger(item.filedIssue.number)
+        ? `#${item.filedIssue.number}`
+        : 'issue';
+      lines.push(`  Filed: [${ref}](${item.filedIssue.url})`);
+    } else {
+      lines.push('```sh');
+      lines.push(String(item.command ?? ''));
+      lines.push('```');
+    }
     lines.push('');
   }
   return lines;
 }
 
-/**
- * Render the body lines for the "proposed memory updates" bucket — a plain
- * instruction prelude followed by one bullet per insight, or `_None._` when
- * empty. Deliberately NOT YAML frontmatter (asserted by the routed-sections
- * contract test).
- *
- * @param {object[]} items
- * @returns {string[]}
- */
-function renderMemoryBucket(items) {
-  if (items.length === 0) return ['_None._'];
-  return [
-    'update your memory with the following insights:',
-    '',
-    ...items.map((m) => `- ${m.insight}`),
-  ];
-}
-
 /**
  * Render the body lines for the "one-off / discarded" bucket — one bullet per
  * discarded class naming its occurrence count and source, or `_None._`.
@@ -472,12 +502,16 @@ function renderDiscardedBucket(items) {
 }
 
 /**
- * Descriptor table for the four routed-proposal sections, in deterministic
- * emit order (consumer → framework → memory → discarded). Each descriptor
- * pairs a heading, the `routedProposals` field it reads, and a body renderer.
+ * Descriptor table for the three routed-proposal sections, in deterministic
+ * emit order (consumer → framework → discarded). Each descriptor pairs a
+ * heading, the `routedProposals` field it reads, and a body renderer.
  * {@link renderRoutedSections} walks the table once, so reordering or adding a
  * section is a data edit here rather than another copy-pasted emit block.
  *
+ * The former "Proposed memory updates" section was deleted in the Epic
+ * #4406 signal-contract cutover — no writer ever produced the memory-pane
+ * records it rendered.
+ *
  * @type {Array<{ heading: string, field: string, renderBucket: (items: object[]) => string[] }>}
  */
 const ROUTED_SECTIONS = [
@@ -491,11 +525,6 @@ const ROUTED_SECTIONS = [
     field: 'framework',
     renderBucket: renderIssueBucket,
   },
-  {
-    heading: '### Proposed memory updates',
-    field: 'memory',
-    renderBucket: renderMemoryBucket,
-  },
   {
     heading: '### One-off / discarded',
     field: 'discarded',

package/.agents/scripts/lib/orchestration/retro/phases/gather-signals.js

@@ -10,8 +10,12 @@
  */
 
 import { TYPE_LABELS } from '../../../label-constants.js';
-import { forEachLine } from '../../../observability/signals-writer.js';
+import {
+  forEachEpicLine,
+  forEachLine,
+} from '../../../observability/signals-writer.js';
 import { concurrentMap } from '../../../util/concurrent-map.js';
+import { read as readEpicRunState } from '../../epic-run-state-store.js';
 import { composeRoutedProposals } from '../../retro-proposals.js';
 import { parseFencedJsonComment } from '../../structured-comment-parser.js';
 import { findStructuredComment } from '../../ticketing.js';
@@ -38,6 +42,15 @@ const SIGNALS_READ_CONCURRENCY = 8;
 // zero-descendant walk is suspicious.
 const EPIC_BODY_REFERENCE = /#\d+/;
 
+/**
+ * Fallback category stamped on a snapshot-derived blocked event that
+ * carries no `category` of its own. A non-empty category is what promotes
+ * the event to an actionable routed proposal in `composeRoutedProposals`,
+ * so a category-less `agent::blocked` record must still resolve to a
+ * concrete bucket rather than being silently dropped.
+ */
+const BLOCKED_EVENT_FALLBACK_CATEGORY = 'agent-blocked';
+
 /**
  * Pure: aggregate `frictionByCategory` payloads into a single integer.
  */
@@ -50,6 +63,83 @@ function sumFriction(byCategory) {
   return total;
 }
 
+/**
+ * Fold one parsed `signals.ndjson` record into the routed-signal
+ * accumulator. Shared by the per-Story and per-Epic scans so both streams
+ * contribute to the SAME unified counts that feed the routed proposals AND
+ * the compact/full retro decision. Reads the canonical envelope: top-level
+ * `category` and the string `source` classifier tag (Epic #4406). Non-object
+ * records and records without a `category` contribute nothing.
+ *
+ * @param {unknown} parsed
+ * @param {Array<{ category: string, source: 'framework'|'consumer' }>} routedSignals
+ */
+function accumulateSignalRecord(parsed, routedSignals) {
+  if (parsed === null || typeof parsed !== 'object') return;
+  const record = /** @type {Record<string, unknown>} */ (parsed);
+  const category = typeof record.category === 'string' ? record.category : null;
+  if (!category) return;
+  const source = record.source === 'framework' ? 'framework' : 'consumer';
+  routedSignals.push({ category, source });
+}
+
+/**
+ * Read the `epic-run-state` snapshot and project every Story still recorded
+ * as `blocked` into an `unresolvedBlockedEvents` entry for
+ * `composeRoutedProposals`. Each event carries a **non-empty** category —
+ * the snapshot record's own `category` when present, otherwise the
+ * `agent-blocked` fallback — so it force-promotes an actionable proposal
+ * even when no friction signal shares its category. Best-effort: a read
+ * failure or shapeless snapshot degrades to an empty array (observability
+ * MUST NOT take down the retro path).
+ *
+ * @param {{
+ *   epicId: number,
+ *   provider: object,
+ *   logger?: { warn?: Function },
+ *   readFn: typeof readEpicRunState,
+ * }} args
+ * @returns {Promise<Array<{ ticketId?: number, category: string, source: 'framework'|'consumer' }>>}
+ */
+async function readUnresolvedBlockedEvents({
+  epicId,
+  provider,
+  logger,
+  readFn,
+}) {
+  let snapshot;
+  try {
+    snapshot = await readFn({ provider, epicId });
+  } catch (err) {
+    logger?.warn?.(
+      `[retro-runner] Failed to read epic-run-state for blocked events (continuing): ${
+        err?.message ?? err
+      }`,
+    );
+    return [];
+  }
+  const storiesMap =
+    snapshot && typeof snapshot.stories === 'object' && snapshot.stories
+      ? snapshot.stories
+      : {};
+  const events = [];
+  for (const [key, record] of Object.entries(storiesMap)) {
+    if (!record || typeof record !== 'object' || record.status !== 'blocked') {
+      continue;
+    }
+    const rawCategory =
+      typeof record.category === 'string' ? record.category.trim() : '';
+    const category =
+      rawCategory.length > 0 ? rawCategory : BLOCKED_EVENT_FALLBACK_CATEGORY;
+    const source = record.source === 'framework' ? 'framework' : 'consumer';
+    const ticketId = Number(key);
+    const event = { category, source };
+    if (Number.isInteger(ticketId) && ticketId > 0) event.ticketId = ticketId;
+    events.push(event);
+  }
+  return events;
+}
+
 /**
  * Walk every descendant ticket of `epicId` once. Returns the flat list with
  * each ticket's labels + body + state — the consumer derives its own
@@ -154,6 +244,8 @@ export async function gatherRetroSignals({
   frameworkRepo,
   consumerRepo,
   forEachLineFn = forEachLine,
+  forEachEpicLineFn = forEachEpicLine,
+  epicRunStateReadFn = readEpicRunState,
   composeRoutedProposalsFn = composeRoutedProposals,
 }) {
   const descendants = await collectDescendants(provider, epicId);
@@ -232,54 +324,35 @@ export async function gatherRetroSignals({
     };
   }
 
-  const counts = {
-    friction: frictionFromSummaries,
-    parked: parkedFollowOns.parked.length,
-    recuts: parkedFollowOns.recuts.length,
-    hitl,
-  };
-
-  // Story #2558 — read per-Story `signals.ndjson` streams (already
-  // source-tagged by Story #2553's writer) and compose the four routed
-  // proposal sections (framework / consumer / memory / discarded). Read
-  // failures degrade silently — observability MUST NOT take down the
-  // retro path. Empty streams yield empty arrays so the composer
-  // remains backward-compatible.
+  // Story #4417 — the compact/full retro decision, the automerge-verdict
+  // cleanSprint flag, and the routed proposals must all read from ONE
+  // signals scan. We fold the per-Story `signals.ndjson` streams AND the
+  // per-Epic `signals.ndjson` stream (the `appendEpicSignal` wave-lifecycle
+  // writers, e.g. lifecycle-emit) into a single `routedSignals`
+  // accumulation; `counts.friction` then derives from that same scan so a
+  // retro can never read "clean" from the comment substrate while
+  // actionable friction sits unrendered in the ndjson substrate.
+  //
+  // Story #2558 — the streams are source-tagged by the writer's
+  // `tagSignalSource`; `accumulateSignalRecord` reads the canonical
+  // envelope (top-level `category` + string `source`, Epic #4406). Read
+  // failures degrade silently — observability MUST NOT take down the retro.
   //
-  // Story #3347 — the per-Story reads previously ran one-at-a-time in a
-  // sequential `for` loop, serializing N disk reads. They now fan out via
-  // `concurrentMap` with a bounded cap (`SIGNALS_READ_CONCURRENCY`). Each
-  // Story accumulates into its own local arrays; `concurrentMap` preserves
-  // input order so we concatenate the per-Story results in `stories` order.
-  // That keeps `routedSignals` / `memorablePatterns` — and therefore the
-  // composed `routedProposals` — byte-for-byte identical to the prior
-  // serial behaviour, independent of which read settles first.
+  // Story #3347 — the per-Story reads fan out via `concurrentMap` with a
+  // bounded cap (`SIGNALS_READ_CONCURRENCY`); `concurrentMap` preserves
+  // input order so we concatenate the per-Story `routedSignals` in
+  // `stories` order, keeping the composed `routedProposals` deterministic.
   const perStorySignals = await concurrentMap(
     stories,
     async (story) => {
       const sid = Number(story.id ?? story.number);
       if (!Number.isInteger(sid) || sid <= 0) {
-        return { routedSignals: [], memorablePatterns: [] };
+        return { routedSignals: [] };
       }
       const localRoutedSignals = [];
-      const localMemorablePatterns = [];
       try {
         await forEachLineFn(epicId, sid, (parsed) => {
-          if (parsed === null || typeof parsed !== 'object') return;
-          const record = /** @type {Record<string, unknown>} */ (parsed);
-          const category =
-            typeof record.category === 'string' ? record.category : null;
-          const source =
-            record.source === 'framework' ? 'framework' : 'consumer';
-          if (category) {
-            localRoutedSignals.push({ category, source });
-          }
-          if (record.memorable === true && typeof record.insight === 'string') {
-            localMemorablePatterns.push({
-              category: category ?? 'general',
-              insight: record.insight,
-            });
-          }
+          accumulateSignalRecord(parsed, localRoutedSignals);
         });
       } catch (err) {
         logger?.warn?.(
@@ -288,24 +361,60 @@ export async function gatherRetroSignals({
           }`,
         );
       }
-      return {
-        routedSignals: localRoutedSignals,
-        memorablePatterns: localMemorablePatterns,
-      };
+      return { routedSignals: localRoutedSignals };
     },
     { concurrency: SIGNALS_READ_CONCURRENCY },
   );
   const routedSignals = [];
-  const memorablePatterns = [];
   for (const perStory of perStorySignals) {
     routedSignals.push(...perStory.routedSignals);
-    memorablePatterns.push(...perStory.memorablePatterns);
   }
 
-  // Resolve repos. Caller overrides win; otherwise default the consumer
-  // repo to the project's own `github.owner/repo` (best-effort: the
-  // provider may expose it, but we don't depend on it — empty string
-  // disables that pane in the routed proposals).
+  // Story #4417 — fold in the per-Epic `signals.ndjson` stream
+  // (`appendEpicSignal` wave-lifecycle writers, e.g. lifecycle-emit) so the
+  // unified scan is not blind to Epic-scoped friction that never lands on
+  // an individual Story stream.
+  try {
+    await forEachEpicLineFn(epicId, (parsed) => {
+      accumulateSignalRecord(parsed, routedSignals);
+    });
+  } catch (err) {
+    logger?.warn?.(
+      `[retro-runner] forEachEpicLine failed for epic #${epicId} (continuing): ${
+        err?.message ?? err
+      }`,
+    );
+  }
+
+  const counts = {
+    // `friction` derives from the unified ndjson scan (every categorized
+    // signal across the per-Story and per-Epic streams) PLUS the legacy
+    // story-perf-summary totals, so a non-empty ndjson substrate forces the
+    // full retro even when no `story-perf-summary` comment was posted.
+    friction: frictionFromSummaries + routedSignals.length,
+    parked: parkedFollowOns.parked.length,
+    recuts: parkedFollowOns.recuts.length,
+    hitl,
+  };
+
+  // Story #4417 — project unresolved `agent::blocked` Stories from the
+  // epic-run-state snapshot into force-flag events for the routed-proposal
+  // composer. This replaces the formerly hardwired empty array: a blocked
+  // Story now force-promotes an actionable proposal even absent a matching
+  // friction category (its category falls back to `agent-blocked`).
+  const unresolvedBlockedEvents = await readUnresolvedBlockedEvents({
+    epicId,
+    provider,
+    logger,
+    readFn: epicRunStateReadFn,
+  });
+
+  // Resolve repos. The framework repo falls back to the Mandrel mirror
+  // constant (a known, stable default). The consumer repo does NOT fall
+  // back to the framework repo: when the caller resolves no consumer repo
+  // from `config.github`, the consumer proposal pane is DISABLED loudly
+  // (Story #4417) rather than silently routing consumer-tagged friction at
+  // the framework mirror.
   const resolvedFrameworkRepo =
     typeof frameworkRepo === 'string' && frameworkRepo.length > 0
       ? frameworkRepo
@@ -313,15 +422,21 @@ export async function gatherRetroSignals({
   const resolvedConsumerRepo =
     typeof consumerRepo === 'string' && consumerRepo.length > 0
       ? consumerRepo
-      : resolvedFrameworkRepo; // when caller omits, fall back to the framework repo so the command renders without an empty `--repo` flag.
+      : '';
+  if (resolvedConsumerRepo.length === 0) {
+    logger?.warn?.(
+      '[retro-runner] No consumer repo resolved from config.github — the ' +
+        'consumer proposal pane is DISABLED for this retro. Set ' +
+        'github.owner / github.repo to route consumer-tagged friction.',
+    );
+  }
 
   const routedProposals = composeRoutedProposalsFn({
     epicId,
     frameworkRepo: resolvedFrameworkRepo,
     consumerRepo: resolvedConsumerRepo,
     signals: routedSignals,
-    unresolvedBlockedEvents: [],
-    memorablePatterns,
+    unresolvedBlockedEvents,
   });
 
   return {

package/.agents/scripts/lib/orchestration/retro/phases/post-and-mirror.js

@@ -14,6 +14,7 @@ import nodeFs from 'node:fs';
 import path from 'node:path';
 
 import { epicRetroMirrorPath } from '../../../config/temp-paths.js';
+import { fileRetroProposals as defaultFileRetroProposals } from '../../../feedback-loop/retro-proposals-graduator.js';
 import { upsertStructuredComment } from '../../ticketing.js';
 import { appendChecksSection, collectRetroFindings } from './checks.js';
 import {
@@ -37,9 +38,15 @@ export async function composeAndPostRetro({
   bus,
   now,
   manualInterventions,
+  frameworkRepo,
+  consumerRepo,
+  config = null,
   gatherFn = defaultGatherRetroSignals,
   composeFn = defaultComposeRetroBody,
   upsertFn = upsertStructuredComment,
+  fileRetroProposalsFn = defaultFileRetroProposals,
+  ghPath,
+  spawnImpl,
   runChecksFn,
   assembleStateFn,
   cwd,
@@ -48,7 +55,47 @@ export async function composeAndPostRetro({
   onMirrorWritten,
   perfThresholds = null,
 }) {
-  const signals = await gatherFn({ epicId, provider, logger });
+  const signals = await gatherFn({
+    epicId,
+    provider,
+    logger,
+    frameworkRepo,
+    consumerRepo,
+  });
+
+  // Story #4418 — auto-file the retro's actionable routed proposals BEFORE
+  // the body composes, so the rendered retro sections list the real filed
+  // issue numbers instead of paste-ready `gh` command stanzas. Runs behind
+  // the `delivery.feedbackLoop.retroProposals` toggle (default ON); when
+  // OFF (or when filing is skipped / fails) the proposals pass through
+  // unenriched and the composer falls back to the command stanzas. Never
+  // throws — a filing failure degrades gracefully.
+  const { routedProposals: filedRoutedProposals, summary: filingSummary } =
+    await fileRetroProposalsFn({
+      epicId,
+      provider,
+      config,
+      frameworkRepo,
+      consumerRepo,
+      routedProposals: signals.routedProposals,
+      ghPath,
+      spawnImpl,
+      cwd,
+      logger,
+    });
+  // Surface (never throw on) per-proposal filing failures. Dropping
+  // `summary.errors` silently made a failed `gh issue create` — e.g. a
+  // `friction::<category>` label that doesn't exist in the target repo —
+  // invisible except as an unenriched command stanza in the retro body.
+  if (Array.isArray(filingSummary?.errors) && filingSummary.errors.length) {
+    for (const err of filingSummary.errors) {
+      logger?.warn?.(
+        `[retro] proposal auto-file error (degrading to command stanza): ${
+          typeof err === 'string' ? err : JSON.stringify(err)
+        }`,
+      );
+    }
+  }
 
   // Best-effort fetch of the Epic title for the heading.
   let epicTitle;
@@ -69,7 +116,7 @@ export async function composeAndPostRetro({
     storyPerfSummaries: signals.storyPerfSummaries,
     epicPerfReport: signals.epicPerfReport,
     parkedFollowOns: signals.parkedFollowOns,
-    routedProposals: signals.routedProposals,
+    routedProposals: filedRoutedProposals,
     timestamp,
     forceFull,
     perfThresholds,