mandrel 1.87.0 → 1.89.0

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -0,0 +1,218 @@
+// .agents/scripts/lib/orchestration/merge-block-class.js
+/**
+ * merge-block-class.js — Story #4426 (Epic #4425, slice 1: foundation).
+ *
+ * Shared block-class classifier consumed by BOTH delivery paths — the
+ * epic-path must-land terminal step and the standalone
+ * `single-story-close` must-land terminal step (the not-yet-landed
+ * follow-on Stories under Epic #4425) — so a headless delivery run that
+ * finishes its work without a confirmed merge is attributable to exactly
+ * one of four classes from the SAME decision logic, instead of each path
+ * inventing its own ad hoc diagnosis.
+ *
+ * Block classes (Epic #4425 Goal):
+ *   - `checks-pending-timeout`           The watch/poll budget was
+ *                                         exhausted while required checks
+ *                                         were still pending/running — not
+ *                                         a hard block, the run simply ran
+ *                                         out of time.
+ *   - `branch-protection-human-required` GitHub reports the PR needs a
+ *                                         human action: a required review
+ *                                         that hasn't been granted, or a
+ *                                         branch-protection rule the
+ *                                         automation cannot satisfy on its
+ *                                         own.
+ *   - `arm-failure`                      The arm call itself (`gh pr merge
+ *                                         --auto` or equivalent) failed for
+ *                                         a reason that is NOT branch
+ *                                         protection — auth, rate limit, an
+ *                                         already-merged race, a network
+ *                                         error.
+ *   - `api-race-other`                   Fallback for anything that does
+ *                                         not cleanly fit the above three —
+ *                                         a transient GraphQL/API error, an
+ *                                         ambiguous probe result, or a
+ *                                         genuinely novel condition.
+ *
+ * Pure function, no I/O: callers pass in the already-observed
+ * arm-result / PR-probe / budget signals (from `AutomergeArmer`,
+ * `MergeWatcher`, a raw `gh pr view` read, or the standalone
+ * `single-story-confirm-merge.js` poll) and get back a
+ * `{ blockClass, reason }` verdict ready to hand to `emitMergeUnlanded`
+ * (`emit-merge-unlanded.js`).
+ */
+
+/**
+ * The four block classes named in the Epic #4425 Goal. Order is the
+ * evaluation priority documented on `classifyMergeBlock` below, NOT an
+ * arbitrary listing — earlier entries are checked first when a real input
+ * happens to satisfy more than one heuristic.
+ */
+export const BLOCK_CLASSES = Object.freeze([
+  'checks-pending-timeout',
+  'branch-protection-human-required',
+  'arm-failure',
+  'api-race-other',
+]);
+
+const BLOCK_CLASS_SET = new Set(BLOCK_CLASSES);
+
+/**
+ * @param {string} value
+ * @returns {boolean} `true` iff `value` is one of the four canonical
+ *   block classes.
+ */
+export function isValidBlockClass(value) {
+  return BLOCK_CLASS_SET.has(value);
+}
+
+/**
+ * Substrings that identify a branch-protection / human-review rejection
+ * surfaced through an arm call's stderr or reason text. Matched
+ * case-insensitively against the whole string.
+ */
+const BRANCH_PROTECTION_MARKERS = Object.freeze([
+  'review',
+  'required_status_checks',
+  'protected branch',
+  'branch protection',
+  'approval',
+]);
+
+function textIncludesAny(text, markers) {
+  const lower = String(text ?? '').toLowerCase();
+  return markers.some((marker) => lower.includes(marker));
+}
+
+/**
+ * Build the `api-race-other` fallback reason from whatever signal is
+ * available, so the emitted event still carries a specific-as-possible
+ * explanation rather than a bare "unknown".
+ */
+function describeApiRaceFallback(prProbe, budget) {
+  if (prProbe?.error) {
+    return `PR probe error: ${prProbe.error}`;
+  }
+  if (budget && budget.exhausted === true) {
+    return `watch budget exhausted with an unrecognised checks status (${prProbe?.checksStatus ?? 'unknown'})`;
+  }
+  return 'no definitive block signal observed; classified as a transient API race or other condition';
+}
+
+/**
+ * Classify why a delivery run finished without a confirmed merge.
+ *
+ * Evaluation order (first match wins):
+ *   1. Arm failure — the arm call itself did not succeed. A failed arm
+ *      means there is no "armed but stuck" PR left to probe, so this is
+ *      checked before any PR-probe or budget signal. A branch-protection
+ *      rejection surfaced AT arm time still routes to
+ *      `branch-protection-human-required` rather than the generic
+ *      `arm-failure`.
+ *   2. Budget exhaustion while checks were still in flight —
+ *      `checks-pending-timeout`. Evaluated BEFORE the human-required
+ *      probe signals because on a protected branch GitHub reports
+ *      `mergeStateStatus: 'BLOCKED'` for the entire time required checks
+ *      are still running — a slow-CI timeout would otherwise always
+ *      misclassify as `branch-protection-human-required` and the
+ *      headless once-only budget extension could never engage.
+ *   3. PR-probe human-required signals — `reviewDecision` reporting a
+ *      required review, or `mergeStateStatus: 'BLOCKED'` with checks NOT
+ *      in flight (green/failed checks + BLOCKED = a genuinely human
+ *      gate, e.g. a missing approval).
+ *   4. Fallback — `api-race-other`.
+ *
+ * @param {object} input
+ * @param {object} [input.armResult] Outcome of the arm call.
+ * @param {boolean} [input.armResult.armed] `false` when the arm call
+ *   itself failed (a non-zero `gh pr merge` exit, or arming was refused
+ *   up-front).
+ * @param {string} [input.armResult.reason] Free-form failure detail (e.g.
+ *   `gh` stderr) — inspected for branch-protection markers.
+ * @param {string} [input.armResult.error] Alternate free-form failure
+ *   detail field, checked when `reason` is absent.
+ * @param {object} [input.prProbe] Latest `gh pr view` read.
+ * @param {string} [input.prProbe.reviewDecision] GitHub review decision
+ *   (`REVIEW_REQUIRED`, `APPROVED`, …).
+ * @param {string} [input.prProbe.mergeStateStatus] GitHub merge-state
+ *   status (`BLOCKED`, `BEHIND`, `CLEAN`, …).
+ * @param {string} [input.prProbe.checksStatus] Aggregate required-check
+ *   status observed on the last probe (`success` | `pending` |
+ *   `still-running` | `failure` | `unknown`).
+ * @param {string} [input.prProbe.error] Set when the probe call itself
+ *   errored (network / API failure reading the PR).
+ * @param {object} [input.budget] Poll-budget accounting.
+ * @param {boolean} [input.budget.exhausted] `true` once the watch loop hit
+ *   its budget without observing a confirmed merge.
+ * @param {number} [input.budget.elapsedSeconds] Elapsed watch time in
+ *   seconds, folded into the `reason` text.
+ * @returns {{ blockClass: string, reason: string }}
+ */
+export function classifyMergeBlock(input) {
+  const { armResult, prProbe, budget } = input ?? {};
+
+  // 1. Arm call failure.
+  if (armResult && armResult.armed === false) {
+    const detail = armResult.reason ?? armResult.error ?? '';
+    if (textIncludesAny(detail, BRANCH_PROTECTION_MARKERS)) {
+      return {
+        blockClass: 'branch-protection-human-required',
+        reason:
+          detail ||
+          'arm call rejected: branch protection requires a human action',
+      };
+    }
+    return {
+      blockClass: 'arm-failure',
+      reason: detail || 'arm call failed for an unspecified reason',
+    };
+  }
+
+  // Positive in-flight evidence from the latest probe. Only `pending` /
+  // `still-running` count — `unknown` (empty rollup: a checks-less repo
+  // or a probe race) routes to the api-race re-arm below, and
+  // `undefined` (no probe at all) keeps its budget-timeout mapping in
+  // step 2 without suppressing the step-3 human-required verdict.
+  const checksStatus = prProbe?.checksStatus;
+  const checksPendingEvidence =
+    checksStatus === 'pending' || checksStatus === 'still-running';
+
+  // 2. Budget exhausted while checks were still in flight. Ordered
+  // before the human-required probe signals: `mergeStateStatus:
+  // 'BLOCKED'` is the steady state on a protected branch while required
+  // checks run, so a slow-CI timeout must not read as human-required —
+  // it must consume the headless once-only budget extension instead.
+  if (
+    budget &&
+    budget.exhausted === true &&
+    (checksPendingEvidence || checksStatus === undefined)
+  ) {
+    return {
+      blockClass: 'checks-pending-timeout',
+      reason: `watch budget exhausted after ${budget.elapsedSeconds ?? 'an unknown number of'} seconds with required checks still pending`,
+    };
+  }
+
+  // 3. PR-probe human-required signals. A BLOCKED merge state counts
+  // only without positive checks-in-flight evidence —
+  // BLOCKED-with-settled-checks is a genuinely human gate (e.g. a
+  // missing required approval), whereas BLOCKED-while-checks-run is the
+  // protected-branch steady state.
+  if (prProbe) {
+    if (
+      prProbe.reviewDecision === 'REVIEW_REQUIRED' ||
+      (prProbe.mergeStateStatus === 'BLOCKED' && !checksPendingEvidence)
+    ) {
+      return {
+        blockClass: 'branch-protection-human-required',
+        reason: `PR requires human action (reviewDecision=${prProbe.reviewDecision ?? 'n/a'}, mergeStateStatus=${prProbe.mergeStateStatus ?? 'n/a'})`,
+      };
+    }
+  }
+
+  // 4. Fallback.
+  return {
+    blockClass: 'api-race-other',
+    reason: describeApiRaceFallback(prProbe, budget),
+  };
+}

package/.agents/scripts/lib/orchestration/plan-review-routing.js

@@ -24,7 +24,7 @@ const AUTO_PROCEED_MESSAGE =
   'Planning risk is low — auto-proceeding to Phase 8 decomposition after spec validation. Context tickets remain open until Epic delivery finalizes.';
 
 const REVIEW_REQUIRED_MESSAGE =
-  'Planning risk requires operator review — STOP before Phase 8. Review the PRD, Tech Spec, and Acceptance Spec on GitHub and confirm in this session before decomposition.';
+  'Planning risk requires operator review — STOP before Phase 8. Review the Tech Spec sections and the Acceptance Table — both managed sections of the Epic body — on GitHub and confirm in this session before decomposition.';
 
 const FORCE_REVIEW_MESSAGE =
   'Operator override — forcing review stop before Phase 8 despite low planning risk.';

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -119,12 +119,12 @@ async function emitReapFailureFriction({
       storyId: Number(storyId),
       signal: {
         kind: 'friction',
-        timestamp: new Date().toISOString(),
+        ts: new Date().toISOString(),
         epicId: Number(epicId),
         storyId: Number(storyId),
         category: 'reap-failure',
-        source: { tool: 'story-close.js' },
-        details: `Worktree reap failed: ${reason}`,
+        emitter: { tool: 'story-close.js' },
+        details: { message: `Worktree reap failed: ${reason}` },
         epicBranch,
         worktreePath: wtPath,
         reason,

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',