mandrel 1.66.0 → 1.68.0

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -12,6 +12,16 @@
  * Tests inject a `spawnImpl` (or shape-compatible `execImpl`) to exercise
  * the gh-exec surface deterministically; production code defaults to
  * `child_process.spawn`.
+ *
+ * Story #4135 (Epic #4131, F11) — the envelope additionally carries a
+ * `recurringDefectClasses[]` array derived from the `friction::<class>`
+ * labels the retro routed-proposals composer stamps onto the meta issues it
+ * proposes. That closes the retro→planner loop: a recurring defect class
+ * caught by review/deliver is filed as a `meta::*` + `friction::<class>`
+ * issue, and the next `/plan` Phase 0 surfaces the class (with a recurrence
+ * count across the open feedback issues) to the decompose-author guidance so
+ * the planning floor ratchets up. The derivation is no-op-safe: issues with
+ * no `friction::*` label contribute nothing and the array is empty.
  */
 
 import { META_LABELS } from '../label-constants.js';
@@ -19,6 +29,66 @@ import { runChild } from './graduator-core.js';
 
 const DEFAULT_LIMIT = 50;
 
+/** Prefix stamped on routed-proposal issue labels by the retro composer. */
+const FRICTION_LABEL_PREFIX = 'friction::';
+
+/**
+ * Pure: derive recurring-defect-class signals from a list of normalized
+ * issues by counting `friction::<class>` labels across them (Story #4135).
+ *
+ * Each fetched meta issue may carry one `friction::<class>` label (stamped by
+ * the retro routed-proposals composer when it proposed the issue). A class
+ * that appears across **multiple** open feedback issues is recurring across
+ * Epics — exactly the signal F11 surfaces to the planner. The count is the
+ * number of distinct open issues carrying the class; the `issues[]` array
+ * lists their numbers so the planner can cross-reference.
+ *
+ * Determinism: classes are sorted by descending recurrence count, ties
+ * broken by class name ASC, so a given input always yields a stable order.
+ *
+ * No-op-safe: issues without a `friction::*` label contribute nothing; an
+ * empty / non-array input yields `[]`.
+ *
+ * @param {Array<{ number: number, labels?: string[] }>} issues
+ * @returns {Array<{ class: string, count: number, issues: number[] }>}
+ */
+export function extractRecurringDefectClasses(issues) {
+  if (!Array.isArray(issues)) return [];
+  /** @type {Map<string, Set<number>>} */
+  const byClass = new Map();
+  for (const issue of issues) {
+    if (!issue || typeof issue !== 'object') continue;
+    const number = typeof issue.number === 'number' ? issue.number : null;
+    const labels = Array.isArray(issue.labels) ? issue.labels : [];
+    for (const label of labels) {
+      if (
+        typeof label !== 'string' ||
+        !label.startsWith(FRICTION_LABEL_PREFIX)
+      ) {
+        continue;
+      }
+      const cls = label.slice(FRICTION_LABEL_PREFIX.length).trim();
+      if (cls.length === 0) continue;
+      let set = byClass.get(cls);
+      if (!set) {
+        set = new Set();
+        byClass.set(cls, set);
+      }
+      if (number !== null) set.add(number);
+    }
+  }
+  const out = [];
+  for (const [cls, set] of byClass) {
+    out.push({
+      class: cls,
+      count: set.size,
+      issues: [...set].sort((a, b) => a - b),
+    });
+  }
+  out.sort((a, b) => b.count - a.count || a.class.localeCompare(b.class));
+  return out;
+}
+
 /**
  * Spawn the given gh CLI with the supplied args and resolve to
  * `{ code, stdout, stderr, spawnError }`. Delegates to the shared
@@ -157,6 +227,7 @@ async function fetchByLabel({ owner, repo, label, ghPath, limit, spawnImpl }) {
  * @returns {Promise<{
  *   frameworkGaps: object[],
  *   consumerImprovements: object[],
+ *   recurringDefectClasses: Array<{ class: string, count: number, issues: number[] }>,
  *   fetchedAt: string,
  *   errors: string[],
  * }>}
@@ -180,6 +251,7 @@ export async function fetchPriorFeedback({
   const envelope = {
     frameworkGaps: [],
     consumerImprovements: [],
+    recurringDefectClasses: [],
     fetchedAt: new Date().toISOString(),
     errors,
   };
@@ -223,6 +295,16 @@ export async function fetchPriorFeedback({
     envelope.consumerImprovements.push(issue);
   }
 
+  // Story #4135 (Epic #4131, F11) — close the retro→planner loop: derive the
+  // recurring defect classes from the `friction::<class>` labels carried by
+  // the deduped feedback issues, so the next /plan Phase 0 surfaces them to
+  // the decompose-author guidance. No-op-safe when no issue carries a
+  // `friction::*` label (empty array, no behavioural change).
+  envelope.recurringDefectClasses = extractRecurringDefectClasses([
+    ...envelope.frameworkGaps,
+    ...envelope.consumerImprovements,
+  ]);
+
   return envelope;
 }
 

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/authoring-context.js

@@ -21,11 +21,13 @@ import { fetchPriorFeedback } from '../../../feedback-loop/prior-feedback-fetche
 import { Logger } from '../../../Logger.js';
 import { buildDocsContext } from '../../doc-reader.js';
 import { applyBudget } from '../../planning-context-budget.js';
+import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
 import {
   ACCEPTANCE_SPEC_SYSTEM_PROMPT,
   PRD_SYSTEM_PROMPT,
   TECH_SPEC_SYSTEM_PROMPT,
 } from './prompts.js';
+import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
  * Resolve the per-project memory directory used by the memory-freshness
@@ -146,24 +148,47 @@ export async function buildAuthoringContext(
       recentCommitWindow:
         settings?.planning?.codebaseSnapshot?.recentCommitWindow,
     });
-    // Story #3959 — when the skinny-tier cap drops files, the degradation
-    // used to be silent (only `truncated: true` on the envelope). Surface
-    // an operator-visible warning naming the dropped count and the two
-    // remedies so the spec author knows the snapshot is partial and can
-    // either opt into the richer `medium` tier or narrow `include`.
-    if (codebaseSnapshot?.truncated) {
-      const dropped = Math.max(
-        0,
-        (codebaseSnapshot.fileCount ?? 0) -
-          (codebaseSnapshot.files?.length ?? 0),
-      );
-      Logger.warn(
-        `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
-          `${codebaseSnapshot.fileCount} matched file(s) dropped from the ` +
-          `skinny-tier view. The spec-author context is partial. To restore ` +
-          `full grounding, set planning.codebaseSnapshot.tier: "medium" ` +
-          `and/or narrow planning.codebaseSnapshot.include in .agentrc.json.`,
-      );
+    // Story #4139 (F10) — ground the spec author in the files it will cite.
+    // Two signals are attached to the snapshot envelope so the author (which
+    // consumes the JSON, not stderr) cannot miss them:
+    //   1. `grounding.truncation` — the structured, in-envelope form of the
+    //      Story #3959 dropped-file warning. The skinny-tier cap used to drop
+    //      the majority of matched files with only a stderr `Logger.warn` and
+    //      a bare `truncated: true` flag; the author never learned the
+    //      snapshot was partial (a real run dropped "377 of 627 files").
+    //   2. `grounding.citedButAbsent` — path-shaped references in the Epic
+    //      body (the prose the author grounds *from*) that are absent from
+    //      the snapshot's file set and not phrased as net-new, so cited-but-
+    //      absent surfaces are visible *during* authoring rather than only
+    //      after the post-author freshness gate (Story #2635).
+    // The grounding consults only the snapshot's file set and the Epic body —
+    // no new filesystem or git probes — so the context stays bounded for cost.
+    if (codebaseSnapshot) {
+      const grounding = buildAuthoringGrounding({
+        snapshot: codebaseSnapshot,
+        prose: epic.body ?? '',
+        collectReferences,
+        hasNewFileCue,
+      });
+      codebaseSnapshot.grounding = grounding;
+      if (grounding.truncation) {
+        const { dropped, matched, tier } = grounding.truncation;
+        Logger.warn(
+          `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
+            `${matched} matched file(s) dropped from the ${tier}-tier view. ` +
+            `The spec-author context is partial. To restore full grounding, ` +
+            `set planning.codebaseSnapshot.tier: "medium" and/or narrow ` +
+            `planning.codebaseSnapshot.include in .agentrc.json.`,
+        );
+      }
+      if (grounding.citedButAbsent.length > 0) {
+        Logger.warn(
+          `[epic-plan-spec] ${grounding.citedButAbsent.length} path(s) cited ` +
+            `in the Epic body are absent from the codebase snapshot: ` +
+            `${grounding.citedButAbsent.join(', ')}. The spec author will ` +
+            `flag these as drift unless they are net-new.`,
+        );
+      }
     }
   } catch (err) {
     Logger.warn(`[epic-plan-spec] codebase snapshot skipped: ${err.message}`);

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/run-spec-phase.js

@@ -7,6 +7,7 @@
  */
 
 import path from 'node:path';
+import { verifyBddRunnerPendingTag } from '../../../bdd-runner-detect.js';
 import { Logger } from '../../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../../label-constants.js';
 import { cleanupPhaseTempFiles } from '../../../plan-phase-cleanup.js';
@@ -45,12 +46,20 @@ function buildRiskVerdictCommentBody({ epicId, riskVerdict, planningRisk }) {
     verdict: riskVerdict,
     planningRisk,
   };
+  // Story #4145 — when the disposition was forced to not-applicable because
+  // no BDD runner exists, make the waiver operator-visible in the rendered
+  // comment (not just the fenced JSON record) so a reviewer sees why an
+  // otherwise-required AC table was waived.
+  const waiverNote = planningRisk.acceptanceWaivedReason
+    ? ['', `> ⚠️ **Acceptance waived** — ${planningRisk.acceptanceWaivedReason}`]
+    : [];
   return [
     `### 🧭 Planning Risk Verdict — ${planningRisk.overallLevel} · ${planningRisk.gateDecision}`,
     '',
     riskVerdict.summary,
     '',
     ...axisTable,
+    ...waiverNote,
     '',
     '```json',
     JSON.stringify(record, null, 2),
@@ -99,7 +108,29 @@ export async function runSpecPhase(
       '[epic-plan-spec] risk verdict is required — author risk-verdict.json via the epic-plan-spec-author Skill and pass it with --risk-verdict.',
     );
   }
-  const planningRisk = deriveRiskEnvelope(riskVerdict);
+
+  // Story #4145 — probe the project's BDD runner. When none is detected
+  // (`fallback === true`, e.g. a node:test repo with no tests/features/**),
+  // the acceptance disposition is forced to not-applicable inside
+  // deriveRiskEnvelope: an authored AC table could never be reconciled by
+  // `@epic-<id>-ac-*` feature tags, so /deliver finalize would otherwise
+  // abort and require a manual `acceptance::n-a`. The probe is static and
+  // best-effort — a detection failure degrades to "runner present" (no
+  // forced waiver), preserving the BDD-repo path, and never blocks Phase 7.
+  let bddRunner = null;
+  try {
+    bddRunner = await verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT });
+  } catch (err) {
+    Logger.warn(
+      `[epic-plan-spec] BDD runner probe skipped (${err.message}); acceptance disposition derived from risk axes only.`,
+    );
+  }
+  const planningRisk = deriveRiskEnvelope(riskVerdict, { bddRunner });
+  if (planningRisk.acceptanceWaivedReason) {
+    Logger.info(
+      `[epic-plan-spec] Acceptance disposition forced to not-applicable for Epic #${epicId}: ${planningRisk.acceptanceWaivedReason}`,
+    );
+  }
 
   const epic = await provider.getEpic(epicId);
   if (!epic) {

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/spec-authoring-grounding.js

@@ -0,0 +1,147 @@
+/**
+ * phases/spec-authoring-grounding.js — F10 spec-authoring code-grounding.
+ *
+ * Story #4139 (Epic #4131). `/plan` Phase 7 authors the PRD + Tech Spec
+ * from the Epic body, the scraped project docs, and the
+ * `codebaseSnapshot` structural view of the consumer repo. Two failure
+ * modes made that grounding silently partial:
+ *
+ *   1. The skinny-tier snapshot caps its file list at `MAX_FILES_SKINNY`
+ *      and sets `truncated: true` — but the only operator-visible signal
+ *      was a stderr `Logger.warn` (Story #3959). The spec author consumes
+ *      the JSON envelope, not stderr, so it never learned the snapshot
+ *      was partial. A run that dropped "377 of 627 files" looked complete
+ *      to the author.
+ *
+ *   2. When the Epic body cites a code path that is **absent** from the
+ *      snapshot's file set, nothing surfaced the gap *during* authoring.
+ *      The post-author spec-freshness gate (Story #2635) catches stale
+ *      citations only after the Tech Spec is written — one phase too late
+ *      to ground the author's choices.
+ *
+ * `buildAuthoringGrounding` derives a small, bounded `grounding` block that
+ * is attached to the `codebaseSnapshot` envelope so the author (and the
+ * operator inspecting the run) see both signals before the spec is written:
+ *
+ *   - `truncation` — non-null when the snapshot dropped files. Carries the
+ *     dropped count, the matched/shown totals, and the two remedies. This
+ *     is the structured, in-envelope form of the Story #3959 stderr warning.
+ *   - `citedButAbsent` — path-shaped references pulled from the authoring
+ *     prose (the Epic body) that are **not** present in the snapshot's file
+ *     set and are not phrased as net-new. Bounded to `MAX_CITED_ABSENT`
+ *     entries so a pathological Epic body cannot blow the envelope budget.
+ *
+ * The grounding is targeted (the prose the author is grounding *from* and
+ * the files the snapshot already carries), not a whole-repo dump — the
+ * snapshot file set is the only source consulted, so this adds no new
+ * filesystem or git probes.
+ */
+
+/**
+ * Hard cap on the `citedButAbsent` list so an Epic body that mentions a
+ * very large number of paths cannot inflate the authoring envelope. The
+ * cap is generous relative to a realistic Epic citation count; when it is
+ * hit, `citedButAbsentTruncated: true` flags the elision so the signal is
+ * not silently dropped (the very failure mode this Story fixes).
+ */
+export const MAX_CITED_ABSENT = 40;
+
+/**
+ * Build the operator-visible truncation signal from a snapshot envelope.
+ * Returns `null` when the snapshot is absent or was not truncated.
+ *
+ * @param {object|null} snapshot - The `codebaseSnapshot` envelope.
+ * @returns {{ dropped: number, matched: number, shown: number, tier: string, remedies: string[] } | null}
+ */
+export function buildTruncationSignal(snapshot) {
+  if (!snapshot || snapshot.truncated !== true) return null;
+  const matched = Number.isInteger(snapshot.fileCount) ? snapshot.fileCount : 0;
+  const shown = Array.isArray(snapshot.files) ? snapshot.files.length : 0;
+  const dropped = Math.max(0, matched - shown);
+  return {
+    dropped,
+    matched,
+    shown,
+    tier: typeof snapshot.tier === 'string' ? snapshot.tier : 'skinny',
+    remedies: [
+      'Set planning.codebaseSnapshot.tier: "medium" in .agentrc.json to restore full grounding.',
+      'Narrow planning.codebaseSnapshot.include in .agentrc.json so the cited surfaces survive the cap.',
+    ],
+  };
+}
+
+/**
+ * Surface path-shaped references from the authoring prose that are absent
+ * from the snapshot's file set. Reuses the spec-freshness path extractor so
+ * the citation shapes recognised here match the post-author freshness gate
+ * exactly — a path the author cites in prose is detected the same way before
+ * and after authoring.
+ *
+ * A reference is reported only when it is **not** present in `snapshotFiles`
+ * **and** the surrounding prose does not phrase it as net-new (the same
+ * cue heuristic the freshness gate uses to demote intentional new-file
+ * mentions). Results are deduped by path, sorted, and bounded to
+ * `MAX_CITED_ABSENT`.
+ *
+ * @param {string} prose - The authoring prose (typically the Epic body).
+ * @param {string[]} snapshotFiles - The snapshot's `files` array.
+ * @param {object} deps
+ * @param {Function} deps.collectReferences - (body) => Array<{ path, index, matchLength }>.
+ * @param {Function} deps.hasNewFileCue - (body, index, matchLength) => boolean.
+ * @returns {{ paths: string[], truncated: boolean }}
+ */
+export function findCitedButAbsent(prose, snapshotFiles, deps) {
+  const { collectReferences, hasNewFileCue } = deps;
+  if (typeof prose !== 'string' || prose.length === 0) {
+    return { paths: [], truncated: false };
+  }
+  const present = new Set(
+    (Array.isArray(snapshotFiles) ? snapshotFiles : []).map((f) =>
+      String(f).replace(/\\/g, '/'),
+    ),
+  );
+  const absent = new Set();
+  for (const { path, index, matchLength } of collectReferences(prose)) {
+    const normalised = path.replace(/\\/g, '/');
+    if (present.has(normalised)) continue;
+    if (hasNewFileCue(prose, index, matchLength)) continue;
+    absent.add(normalised);
+  }
+  const sorted = [...absent].sort();
+  return {
+    paths: sorted.slice(0, MAX_CITED_ABSENT),
+    truncated: sorted.length > MAX_CITED_ABSENT,
+  };
+}
+
+/**
+ * Build the full `grounding` block attached to the `codebaseSnapshot`
+ * envelope. Pure with respect to its inputs (no filesystem or git probes):
+ * the snapshot file set is the sole grounding source, keeping the context
+ * bounded for cost.
+ *
+ * @param {object} opts
+ * @param {object|null} opts.snapshot - The `codebaseSnapshot` envelope.
+ * @param {string} opts.prose - The authoring prose (Epic body) to scan.
+ * @param {Function} opts.collectReferences - spec-freshness path extractor.
+ * @param {Function} opts.hasNewFileCue - spec-freshness net-new cue check.
+ * @returns {{ truncation: object|null, citedButAbsent: string[], citedButAbsentTruncated: boolean }}
+ */
+export function buildAuthoringGrounding({
+  snapshot,
+  prose,
+  collectReferences,
+  hasNewFileCue,
+}) {
+  const truncation = buildTruncationSignal(snapshot);
+  const { paths, truncated } = findCitedButAbsent(
+    prose,
+    snapshot?.files ?? [],
+    { collectReferences, hasNewFileCue },
+  );
+  return {
+    truncation,
+    citedButAbsent: paths,
+    citedButAbsentTruncated: truncated,
+  };
+}

package/.agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js

@@ -358,10 +358,15 @@ export async function pollUntilTerminal({
  * @param {number} opts.maxPolls           Hard cap on total poll iterations.
  * @param {number} opts.maxUpdates         Cap on `gh pr update-branch` recovery calls.
  * @param {number} opts.pollIntervalMs     Delay between poll ticks.
- * @param {Function} opts.ghPrChecksFn
- * @param {Function} opts.ghPrViewFn
- * @param {Function} opts.ghPrUpdateBranchFn
- * @param {Function} opts.sleepFn
+ * @param {Function} [opts.ghPrChecksFn]   `gh pr checks` invoker. Defaults
+ *   to the real `gh pr checks` spawn so the CLI path (which injects no
+ *   port) works; tests override it with a stub. Story #4144.
+ * @param {Function} [opts.ghPrViewFn]     `gh pr view` invoker. Defaults
+ *   to the real spawn; tests override.
+ * @param {Function} [opts.ghPrUpdateBranchFn] `gh pr update-branch`
+ *   invoker. Defaults to the real spawn; tests override.
+ * @param {Function} [opts.sleepFn]        Poll-tick delay. Defaults to a
+ *   real `setTimeout`-backed sleep; tests override with a no-op.
  * @param {{ info?: Function, warn?: Function, debug?: Function }} opts.logger
  * @param {{status:number,stdout:string,stderr:string}} [opts.firstProbe]
  *   Optional already-issued `gh pr checks` result. When the caller (the
@@ -388,10 +393,10 @@ export async function watchPrToTerminal({
   maxPolls,
   maxUpdates,
   pollIntervalMs,
-  ghPrChecksFn,
-  ghPrViewFn,
-  ghPrUpdateBranchFn,
-  sleepFn,
+  ghPrChecksFn = ghPrChecks,
+  ghPrViewFn = ghPrView,
+  ghPrUpdateBranchFn = ghPrUpdateBranch,
+  sleepFn = defaultSleep,
   logger,
   firstProbe,
 }) {

package/.agents/scripts/lib/orchestration/planning-risk.js

@@ -37,6 +37,18 @@
  * @property {boolean} requiresReview
  * @property {AcceptanceDisposition} acceptanceDisposition
  * @property {GateDecision} gateDecision
+ * @property {string} [acceptanceWaivedReason] Present only when the
+ *   acceptance disposition was forced to `not-applicable` by a non-axis
+ *   signal (currently: no BDD runner detected). An operator-visible
+ *   rationale so the override is never silent (Story #4145).
+ */
+
+/**
+ * @typedef {Object} BddRunnerProbe
+ * @property {string|null} runner
+ * @property {boolean} fallback `true` when no supported BDD runner was
+ *   detected in the project (`verifyBddRunnerPendingTag`).
+ * @property {string} [reason]
  */
 
 const LEVEL_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
@@ -129,27 +141,54 @@ function resolveRequiresReview(overallLevel, axes) {
  * (`epic-plan-spec.js`), never here, so a malformed verdict fails closed
  * before this function runs.
  *
+ * **No-BDD-runner waiver (Story #4145).** The acceptance disposition the risk
+ * axes derive presumes a BDD runner exists to satisfy an authored AC table.
+ * When `opts.bddRunner.fallback === true` (no supported runner detected — e.g.
+ * a `node:test` repo with no `tests/features/**`), an authored AC table can
+ * never be reconciled by `@epic-<id>-ac-*` feature tags, so `/deliver`
+ * finalize would abort. In that case the disposition is **forced** to
+ * `not-applicable` regardless of the risk axes, and `acceptanceWaivedReason`
+ * records the override so it is operator-visible, not silent. The
+ * `requiresReview` / `gateDecision` outputs are unaffected — a high-risk
+ * Epic still routes to review; only the acceptance-spec requirement is
+ * waived. Repos that ship a BDD runner (`fallback !== true`) are unaffected.
+ *
  * @param {RiskVerdict} [verdict]
+ * @param {{ bddRunner?: BddRunnerProbe|null }} [opts]
  * @returns {PlanningRiskEnvelope}
  */
-export function deriveRiskEnvelope(verdict = {}) {
+export function deriveRiskEnvelope(verdict = {}, { bddRunner = null } = {}) {
   const axes = (Array.isArray(verdict.axes) ? verdict.axes : []).map(
     ({ axis, level, rationale }) => ({ axis, level, rationale }),
   );
 
   const overallLevel = resolveOverallLevel(axes);
-  const acceptanceDisposition = resolveAcceptanceDisposition(
-    axes,
-    overallLevel,
-  );
+  const axisDisposition = resolveAcceptanceDisposition(axes, overallLevel);
   const requiresReview = resolveRequiresReview(overallLevel, axes);
   const gateDecision = requiresReview ? 'review-required' : 'auto-proceed';
 
-  return {
+  const noBddRunner = bddRunner?.fallback === true;
+  // Force the waiver only when the axes would otherwise have required (or
+  // recommended) an AC table; if the disposition is already not-applicable
+  // there is nothing to override and no waiver rationale to surface.
+  const forceWaiver = noBddRunner && axisDisposition !== 'not-applicable';
+  const acceptanceDisposition = forceWaiver
+    ? 'not-applicable'
+    : axisDisposition;
+
+  /** @type {PlanningRiskEnvelope} */
+  const envelope = {
     axes,
     overallLevel,
     requiresReview,
     acceptanceDisposition,
     gateDecision,
   };
+  if (forceWaiver) {
+    envelope.acceptanceWaivedReason =
+      `no BDD runner detected (${bddRunner?.reason ?? 'no-bdd-runner-detected'}) — ` +
+      `an authored acceptance-spec AC table cannot be reconciled by feature tags, ` +
+      `so the acceptance disposition is waived to not-applicable (was ${axisDisposition}).`;
+  }
+  return envelope;
 }

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

@@ -26,6 +26,69 @@ export function normalizeInterventionCount(value) {
   return Math.trunc(value);
 }
 
+/**
+ * Pure: derive the recurring-defect-class signal from the routed-proposal
+ * sections (Story #4135 / Epic #4131, F11).
+ *
+ * The routed-proposals composer (`retro-proposals.js`) already split the
+ * Epic's source-tagged friction into `framework` / `consumer` actionable
+ * items — a category lands there only when it recurred ≥2 times across the
+ * Epic OR was force-flagged by an unresolved `agent::blocked` event. Those
+ * are exactly the **recurring classes** of review/deliver-caught issues F11
+ * tracks, so we lift them verbatim rather than re-deriving a parallel
+ * threshold. Each entry carries the `friction::<category>` label the
+ * composer stamps onto its `gh issue create` command — that label is the
+ * join key the `/plan` Phase 0 prior-feedback fetcher reads back to surface
+ * recurring classes to the planner.
+ *
+ * Determinism: the two actionable arrays are already sorted by `category`
+ * ASC by the composer; we concatenate framework-then-consumer and re-sort by
+ * `category` so the merged signal is stable regardless of which source
+ * contributed a class.
+ *
+ * No-op-safe: a null / non-object / shapeless `routedProposals` (or one with
+ * empty actionable arrays) yields `[]` — the common clean-sprint case.
+ *
+ * @param {{ framework?: object[], consumer?: object[] } | null | undefined} routedProposals
+ * @returns {Array<{ category: string, occurrences: number, source: 'framework'|'consumer', label: string }>}
+ */
+export function deriveDefectClasses(routedProposals) {
+  if (
+    !routedProposals ||
+    typeof routedProposals !== 'object' ||
+    Array.isArray(routedProposals)
+  ) {
+    return [];
+  }
+  const framework = Array.isArray(routedProposals.framework)
+    ? routedProposals.framework
+    : [];
+  const consumer = Array.isArray(routedProposals.consumer)
+    ? routedProposals.consumer
+    : [];
+
+  const out = [];
+  for (const item of [...framework, ...consumer]) {
+    if (!item || typeof item !== 'object') continue;
+    const category =
+      typeof item.category === 'string' ? item.category.trim() : '';
+    if (category.length === 0) continue;
+    const occurrences =
+      typeof item.occurrences === 'number' && Number.isFinite(item.occurrences)
+        ? item.occurrences
+        : 0;
+    const source = item.source === 'framework' ? 'framework' : 'consumer';
+    out.push({
+      category,
+      occurrences,
+      source,
+      label: `friction::${category}`,
+    });
+  }
+  out.sort((a, b) => a.category.localeCompare(b.category));
+  return out;
+}
+
 /**
  * Pure: compose the retro markdown body. Exported for tests so they can
  * verify the body shape without round-tripping through a stub provider.

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

@@ -18,6 +18,7 @@ import { upsertStructuredComment } from '../../ticketing.js';
 import { appendChecksSection, collectRetroFindings } from './checks.js';
 import {
   composeRetroBody as defaultComposeRetroBody,
+  deriveDefectClasses,
   normalizeInterventionCount,
 } from './compose-body.js';
 import { gatherRetroSignals as defaultGatherRetroSignals } from './gather-signals.js';
@@ -74,6 +75,15 @@ export async function composeAndPostRetro({
     perfThresholds,
   });
 
+  // Story #4135 (Epic #4131, F11) — derive the recurring-defect-class signal
+  // from the same routed proposals the body composer consumed. The signal is
+  // surfaced on the runRetro envelope (`defectClasses`) so callers/tests can
+  // observe the recurring classes the routed-proposal `gh issue create`
+  // commands stamp with `friction::<class>` labels — the join key the
+  // `/plan` Phase 0 fetcher reads back. No-op-safe: a clean sprint (no
+  // routed proposals) yields `[]`.
+  const defectClasses = deriveDefectClasses(signals.routedProposals);
+
   const findings = await collectRetroFindings({
     runChecksFn,
     assembleStateFn,
@@ -128,6 +138,7 @@ export async function composeAndPostRetro({
     scorecard,
     body: bodyWithChecks,
     findings,
+    defectClasses,
     commentId: result?.commentId,
   };
 }

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

@@ -18,10 +18,23 @@
  * existing import sites stay unchanged.
  *
  * Public API:
- *   - `runRetro({ epicId, provider, logger })` → `{ posted, compact, scorecard, body }`.
+ *   - `runRetro({ epicId, provider, logger })` → `{ posted, compact, scorecard, body, defectClasses }`.
  *   - `composeRetroBody(input)` (pure, exported for tests).
  *   - `gatherRetroSignals({ epicId, provider })` (exported for tests).
  *   - `appendChecksSection(body, findings)` (pure, exported for tests).
+ *   - `deriveDefectClasses(routedProposals)` (pure, exported for tests).
+ *
+ * Story #4135 (Epic #4131, F11) — the runner now derives a
+ * **recurring-defect-class signal** from the routed-proposal actionable
+ * items (categories that recurred ≥2 times across review/deliver-caught
+ * friction, or a force-flagged `agent::blocked` category). The derived
+ * classes ride on the `runRetro` envelope as `defectClasses[]` and are
+ * stamped onto the proposed `gh issue create` commands as `friction::<class>`
+ * labels (the routed-proposals composer already emits that label), which is
+ * the durable substrate the `/plan` Phase 0 prior-feedback fetcher reads
+ * back to surface recurring classes to the planner. The derivation is
+ * **no-op-safe**: absent or empty routed proposals yield an empty array and
+ * no behavioural change to the existing retro/post path.
  *
  * Behaviour:
  *   - Reads child Stories' `story-perf-summary` comments to aggregate
@@ -50,7 +63,10 @@ import { upsertStructuredComment } from './ticketing.js';
 
 // Re-export phase-level helpers so existing import sites stay unchanged.
 export { appendChecksSection } from './retro/phases/checks.js';
-export { composeRetroBody } from './retro/phases/compose-body.js';
+export {
+  composeRetroBody,
+  deriveDefectClasses,
+} from './retro/phases/compose-body.js';
 export { gatherRetroSignals } from './retro/phases/gather-signals.js';
 
 /**
@@ -92,6 +108,7 @@ export { gatherRetroSignals } from './retro/phases/gather-signals.js';
  *   scorecard: object,
  *   body: string,
  *   findings: object[],
+ *   defectClasses: Array<{ category: string, occurrences: number, source: 'framework'|'consumer', label: string }>,
  *   commentId?: number,
  * }>}
  */