mandrel 1.87.0 → 1.89.0

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,

package/.agents/scripts/lib/orchestration/retro-proposals.js

@@ -1,12 +1,14 @@
 /**
  * lib/orchestration/retro-proposals.js — pure composer that turns
- * aggregated source-tagged friction signals into four routed proposal
- * sections (framework, consumer, memory, discarded).
+ * aggregated source-tagged friction signals into three routed proposal
+ * sections (framework, consumer, discarded).
  *
  * Epic #2547 / Story #2558 / Tech Spec #2550. Consumes per-Story signals
- * already source-tagged by `signals-writer.appendSignal` (Story #2553) and
- * yields a four-way split that the retro composer renders above the
- * `<!-- retro-complete: ... -->` marker.
+ * already source-tagged by `signals-writer.appendSignal` and yields a
+ * three-way split that the retro composer renders above the
+ * `<!-- retro-complete: ... -->` marker. The former "memory updates"
+ * pane was deleted in the Epic #4406 signal-contract cutover (it had no
+ * producer — no writer ever emitted the record it rendered).
  *
  * Heuristic:
  *   - **Actionable** (renders as a pre-drafted `gh issue create` shell
@@ -14,14 +16,8 @@
  *     Epic, OR an `agent::blocked` event whose root cause was not
  *     resolved by Epic close (the caller supplies these as
  *     `unresolvedBlockedEvents`).
- *   - **Memorable** (renders as a plain bulleted instruction line under
- *     "update your memory with the following insights"): a pattern
- *     observed in retro signals supplied via `memorablePatterns`. We do
- *     **not** emit memory frontmatter — the section is a free-text
- *     instruction block.
  *   - **Discarded**: a friction category with exactly 1 occurrence and
- *     no follow-on signal (no companion `agent::blocked`, not in
- *     `memorablePatterns`).
+ *     no follow-on signal (no companion `agent::blocked`).
  *
  * Routing:
  *   - Each actionable item is routed to `framework` or `consumer` based
@@ -45,17 +41,12 @@
  * @property {string} [category]
  * @property {string} [summary]
  *
- * @typedef {Object} MemorablePattern
- * @property {string} category
- * @property {string} insight   The instruction line text (rendered as a bullet).
- *
  * @typedef {Object} RoutedProposalsInput
  * @property {number}                epicId
  * @property {string}                frameworkRepo   `"<owner>/<repo>"`.
  * @property {string}                consumerRepo    `"<owner>/<repo>"`.
  * @property {FrictionSignal[]}      [signals]
  * @property {BlockedEvent[]}        [unresolvedBlockedEvents]
- * @property {MemorablePattern[]}    [memorablePatterns]
  *
  * @typedef {Object} RoutedItem
  * @property {string} category
@@ -65,10 +56,6 @@
  * @property {string} body
  * @property {string} command       The pre-drafted `gh issue create` line.
  *
- * @typedef {Object} MemoryItem
- * @property {string} category
- * @property {string} insight
- *
  * @typedef {Object} DiscardedItem
  * @property {string} category
  * @property {number} occurrences
@@ -77,7 +64,6 @@
  * @typedef {Object} RoutedProposals
  * @property {RoutedItem[]}     framework
  * @property {RoutedItem[]}     consumer
- * @property {MemoryItem[]}     memory
  * @property {DiscardedItem[]}  discarded
  */
 
@@ -88,7 +74,7 @@
  * @returns {RoutedProposals}
  */
 function emptyResult() {
-  return { framework: [], consumer: [], memory: [], discarded: [] };
+  return { framework: [], consumer: [], discarded: [] };
 }
 
 /**
@@ -250,7 +236,6 @@ function buildRoutedItem({
  *   consumerRepo: string,
  *   signals: FrictionSignal[],
  *   unresolvedBlockedEvents: BlockedEvent[],
- *   memorablePatterns: MemorablePattern[],
  * } | null}
  */
 function normaliseInput(input) {
@@ -269,9 +254,6 @@ function normaliseInput(input) {
     unresolvedBlockedEvents: Array.isArray(record.unresolvedBlockedEvents)
       ? record.unresolvedBlockedEvents
       : [],
-    memorablePatterns: Array.isArray(record.memorablePatterns)
-      ? record.memorablePatterns
-      : [],
   };
 }
 
@@ -280,11 +262,9 @@ function normaliseInput(input) {
  * signals.
  *
  * Pure — no I/O, no time-dependent state, no provider calls. Returns an
- * object with four arrays:
+ * object with three arrays:
  *   - `framework`: actionable items routed to the framework repo.
  *   - `consumer`: actionable items routed to the consumer repo.
- *   - `memory`: bulleted instruction lines for the operator's memory
- *     surface (NOT memory frontmatter).
  *   - `discarded`: single-occurrence friction with no follow-on signal.
  *
  * @param {RoutedProposalsInput} input
@@ -299,28 +279,10 @@ export function composeRoutedProposals(input) {
     consumerRepo,
     signals,
     unresolvedBlockedEvents,
-    memorablePatterns,
   } = normalised;
 
   const byCategory = aggregateByCategory(signals);
 
-  // Memory: every supplied pattern with a non-empty insight, sorted by
-  // category. Memorable categories are *also* tracked so a 1-occurrence
-  // friction that's memorable is NOT discarded — it's already covered by
-  // the memory section.
-  const memorableCategories = new Set();
-  /** @type {MemoryItem[]} */
-  const memory = [];
-  for (const m of memorablePatterns) {
-    if (m === null || typeof m !== 'object') continue;
-    const category = asString(m.category);
-    const insight = asString(m.insight);
-    if (category.length === 0 || insight.length === 0) continue;
-    memorableCategories.add(category);
-    memory.push({ category, insight });
-  }
-  memory.sort((a, b) => a.category.localeCompare(b.category));
-
   // Unresolved agent::blocked events always promote their category to
   // actionable — even if the friction count is < 2. The event itself
   // doesn't count as a friction occurrence; we treat it as a force-flag.
@@ -362,12 +324,7 @@ export function composeRoutedProposals(input) {
       else consumer.push(item);
       continue;
     }
-    // total === 1 AND no force flag.
-    if (memorableCategories.has(category)) {
-      // Memorable single-occurrence frictions are covered by the memory
-      // section; do not also discard them.
-      continue;
-    }
+    // total === 1 AND no force flag → discarded.
     discarded.push({ category, occurrences: total, source });
   }
 
@@ -391,5 +348,5 @@ export function composeRoutedProposals(input) {
   consumer.sort((a, b) => a.category.localeCompare(b.category));
   discarded.sort((a, b) => a.category.localeCompare(b.category));
 
-  return { framework, consumer, memory, discarded };
+  return { framework, consumer, discarded };
 }

package/.agents/scripts/lib/orchestration/retro-runner.js

@@ -95,6 +95,9 @@ export { gatherRetroSignals } from './retro/phases/gather-signals.js';
  *   bus?: object|null,
  *   now?: () => number,
  *   manualInterventions?: number,
+ *   frameworkRepo?: string,
+ *   consumerRepo?: string,
+ *   config?: object|null,
  *   gatherFn?: typeof gatherRetroSignals,
  *   composeFn?: typeof composeRetroBody,
  *   upsertFn?: typeof upsertStructuredComment,
@@ -122,6 +125,9 @@ export async function runRetro(opts = {}) {
     bus,
     now = Date.now,
     manualInterventions = 0,
+    frameworkRepo,
+    consumerRepo,
+    config = null,
     gatherFn = gatherRetroSignals,
     composeFn = composeRetroBody,
     upsertFn = upsertStructuredComment,
@@ -159,6 +165,9 @@ export async function runRetro(opts = {}) {
       bus,
       now,
       manualInterventions,
+      frameworkRepo,
+      consumerRepo,
+      config,
       gatherFn,
       composeFn,
       upsertFn,

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js

@@ -94,6 +94,7 @@ export function buildStoryReviewCrossRefBody({
  *   prNumber: number|null,
  *   provider: object,
  *   runCodeReviewFn: Function,
+ *   runLocalLensReviewFn?: Function,
  *   progress: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -103,6 +104,7 @@ export function buildStoryReviewCrossRefBody({
  *   posted?: boolean,
  *   postedCommentId?: number|null,
  *   crossRefPosted?: boolean,
+ *   localLensReview?: object,
  * }>}
  */
 export async function runStoryScopeReview({
@@ -114,6 +116,7 @@ export async function runStoryScopeReview({
   prNumber,
   provider,
   runCodeReviewFn,
+  runLocalLensReviewFn,
   progress,
 }) {
   if (prNumber == null) {
@@ -138,6 +141,10 @@ export async function runStoryScopeReview({
     progress,
     progressTag: 'REVIEW',
     runCodeReviewFn,
+    // Forward the seam only when the caller injects it; otherwise
+    // `runStoryReviewCore` uses its default local-lens pass. `undefined`
+    // deep-merges to the default via the destructuring default there.
+    ...(runLocalLensReviewFn ? { runLocalLensReviewFn } : {}),
   });
 
   const sev = result.severity ?? {
@@ -186,5 +193,6 @@ export async function runStoryScopeReview({
     posted: result.posted,
     postedCommentId: result.postedCommentId ?? null,
     crossRefPosted,
+    localLensReview: result.localLensReview,
   };
 }