mandrel 1.91.0 → 1.92.0

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/persist.js

@@ -240,13 +240,17 @@ export async function runDecomposePhase(
  * @param {typeof defaultRunPlanHealthcheck} args.runHealthcheckFn
  * @returns {Promise<{ ok: boolean, waived?: boolean, reason?: string|null }>}
  */
-function enforceFanOutGate(findings, allowLargeFanOut) {
+export function enforceFanOutGate(
+  findings,
+  allowLargeFanOut,
+  tag = 'epic-plan-decompose',
+) {
   const fanOut = (findings ?? []).filter((f) => f.kind === 'fan-out-warning');
   if (fanOut.length === 0) return;
   if (allowLargeFanOut) {
     for (const f of fanOut) {
       Logger.warn(
-        `[epic-plan-decompose] Persisting a large-fan-out deletion: ` +
+        `[${tag}] Persisting a large-fan-out deletion: ` +
           `Task "${f.taskSlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
           `call site(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.`,
       );
@@ -260,7 +264,7 @@ function enforceFanOutGate(findings, allowLargeFanOut) {
     )
     .join('\n');
   throw new Error(
-    `[epic-plan-decompose] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
+    `[${tag}] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
       `Split each deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
       `or rerun --allow-large-fan-out after confirming the deletion is intentional.`,
   );
@@ -284,24 +288,30 @@ function enforceFanOutGate(findings, allowLargeFanOut) {
  *
  * @param {object[]} findings
  */
-function surfaceSoftConflictFindings(findings) {
+export function surfaceSoftConflictFindings(
+  findings,
+  tag = 'epic-plan-decompose',
+) {
   const soft = (findings ?? []).filter(
     (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
   );
   if (soft.length === 0) return;
   Logger.warn(
-    `[epic-plan-decompose] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+    `[${tag}] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
   );
   for (const finding of soft) {
-    Logger.warn(
-      `[epic-plan-decompose] soft conflict: ${renderHardConflictError(finding)}`,
-    );
+    Logger.warn(`[${tag}] soft conflict: ${renderHardConflictError(finding)}`);
   }
 }
 
-async function runHealthcheckGate({ epicId, epic, runHealthcheckFn }) {
+export async function runHealthcheckGate({
+  epicId,
+  epic,
+  runHealthcheckFn,
+  tag = 'epic-plan-decompose',
+}) {
   Logger.info(
-    `[epic-plan-decompose] Running post-plan readiness healthcheck for Epic #${epicId}...`,
+    `[${tag}] Running post-plan readiness healthcheck for Epic #${epicId}...`,
   );
   let result;
   try {
@@ -321,13 +331,13 @@ async function runHealthcheckGate({ epicId, epic, runHealthcheckFn }) {
   const waived = labels.includes(PLANNING_HEALTHCHECK_WAIVED);
   if (waived) {
     Logger.warn(
-      `[epic-plan-decompose] Healthcheck failed for Epic #${epicId} but '${PLANNING_HEALTHCHECK_WAIVED}' is applied — proceeding with agent::ready handoff. Reason: ${result?.reason ?? '(no reason reported)'}`,
+      `[${tag}] Healthcheck failed for Epic #${epicId} but '${PLANNING_HEALTHCHECK_WAIVED}' is applied — proceeding with agent::ready handoff. Reason: ${result?.reason ?? '(no reason reported)'}`,
     );
     return { ok: false, waived: true, reason: result?.reason ?? null };
   }
 
   throw new Error(
-    `[epic-plan-decompose] Refusing agent::ready handoff for Epic #${epicId}: ` +
+    `[${tag}] Refusing agent::ready handoff for Epic #${epicId}: ` +
       `post-plan healthcheck failed (${result?.reason ?? '(no reason reported)'}). ` +
       `Resolve the failing check(s), or apply the '${PLANNING_HEALTHCHECK_WAIVED}' ` +
       `label to the Epic to override and rerun the persist phase.`,

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

@@ -113,7 +113,12 @@ export async function buildAuthoringContext(
   settings = {},
   opts = {},
 ) {
-  const epic = await provider.getEpic(epicId);
+  // Epic #4474 (M3 PR2): `opts.epic` is an optional prefetched Epic object
+  // so a caller that already holds the issue (the folded `plan-context.js`
+  // envelope build, which also needs the raw body for clarity scoring and
+  // re-plan detection) does not pay a second provider fetch. Absent, the
+  // fetch behaviour is unchanged.
+  const epic = opts.epic ?? (await provider.getEpic(epicId));
   if (!epic) {
     throw new Error(`Epic #${epicId} not found.`);
   }

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-diff.js

@@ -568,7 +568,20 @@ export function diff({ spec, state, ghState } = {}) {
 
   for (const entity of flattenSpec(spec)) {
     seenSpecSlugs.add(entity.slug);
-    const mapped = mapping[entity.slug];
+    // Epic #4474 (PR3) — a mapping entry without a numeric `issueNumber`
+    // is a partial-failure tombstone: the apply's state writer projects an
+    // entry per spec slug, but only completed creations carry a number
+    // (`buildState` seeds new slugs with `issueNumber: null`). Treating
+    // such an entry as "mapped" made a `--resume` after a rate-limit crash
+    // silently skip every failed creation (no Create emitted; the content
+    // hash matches, so no Update either — a lossy resume). A numberless
+    // entry is therefore unmapped here → Create. No duplicate risk: any
+    // live same-title issue was already reseeded onto the slug (with its
+    // number) by `reseedMappingFromGh` before the diff runs.
+    const mappedEntry = mapping[entity.slug];
+    const mapped = Number.isInteger(mappedEntry?.issueNumber)
+      ? mappedEntry
+      : undefined;
 
     if (!mapped) {
       plan.creates.push(
@@ -630,9 +643,12 @@ export function diff({ spec, state, ghState } = {}) {
     }
   }
 
-  // Closes — anything in mapping not seen in spec.
+  // Closes — anything in mapping not seen in spec. A numberless
+  // partial-failure tombstone (see above) has no live issue to close;
+  // dropping it from the spec simply drops the entry.
   for (const [slug, mapped] of Object.entries(mapping)) {
     if (seenSpecSlugs.has(slug)) continue;
+    if (!Number.isInteger(mapped?.issueNumber)) continue;
     plan.closes.push(
       closeOp({
         slug,

package/.agents/scripts/{lifecycle-diff.js → lib/orchestration/lifecycle/ledger-diff.js}

@@ -1,35 +1,22 @@
-#!/usr/bin/env node
-/* node:coverage ignore file */
-
 /**
- * lifecycle-diff.js — assertion modes over a lifecycle ledger file for
- * the repeatability invariants. The structural-`diff` helpers below are
- * exported for unit tests that pin the diff contract.
+ * ledger-diff.js — structural-diff and ordering-assertion helpers over a
+ * lifecycle ledger (`temp/epic-<id>/lifecycle.ndjson`) for the
+ * repeatability invariants.
  *
- * Usage:
- *   node .agents/scripts/lifecycle-diff.js --assert <mode> <ledger>
- *       — `mode` is one of:
- *           merge-gate-ordering   — epic.merge.armed must be preceded
- *                                   by epic.merge.ready (same seqId
- *                                   chain; armed.seqId > ready.seqId).
- *           reconcile-ordering    — pr.created must be preceded by
- *                                   acceptance.reconcile.ok.
- *       — exits 0 on pass; exits 1 with a structured message on fail.
+ * Relocated from the retired `.agents/scripts/lifecycle-diff.js` CLI
+ * (#4482): the assertion helpers are the live surface — they pin the
+ * cross-listener ordering contracts in the lifecycle invariant tests —
+ * while the CLI wrapper had no workflow, script, or CI consumer.
  *
  * Invariants are derived from Tech Spec #2189 § Repeatability Acceptance
  * Criteria.
  */
 
-import { readFileSync } from 'node:fs';
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-
 /**
  * Parse an NDJSON lifecycle ledger into an array of records. Blank
  * lines tolerated; malformed JSON throws with line number. Duplicated
- * from `lib/orchestration/lifecycle/trace-logger.js` to avoid coupling
- * the CLI to the listener surface.
+ * from `trace-logger.js` to keep the diff surface decoupled from the
+ * listener surface.
  */
 export function parseLedgerText(text) {
   const out = [];
@@ -41,7 +28,7 @@ export function parseLedgerText(text) {
       out.push(JSON.parse(line));
     } catch (_err) {
       throw new Error(
-        `lifecycle-diff: malformed JSON in ledger on line ${i + 1}: ${line.slice(0, 80)}`,
+        `ledger-diff: malformed JSON in ledger on line ${i + 1}: ${line.slice(0, 80)}`,
       );
     }
   }
@@ -151,56 +138,3 @@ export function assertReconcileOrdering(records) {
   }
   return { ok: true };
 }
-
-const ASSERTIONS = new Map([
-  ['merge-gate-ordering', assertMergeGateOrdering],
-  ['reconcile-ordering', assertReconcileOrdering],
-]);
-
-function loadLedger(p) {
-  return parseLedgerText(readFileSync(p, 'utf8'));
-}
-
-async function main() {
-  const { values, positionals } = parseArgs({
-    options: {
-      assert: { type: 'string' },
-    },
-    allowPositionals: true,
-    args: process.argv.slice(2),
-  });
-
-  // --assert <mode> <ledger>
-  if (!values.assert) {
-    process.stderr.write('Usage: lifecycle-diff --assert <mode> <ledger>\n');
-    return 2;
-  }
-  if (positionals.length !== 1) {
-    process.stderr.write(
-      'lifecycle-diff --assert <mode> requires exactly one positional ledger path\n',
-    );
-    return 2;
-  }
-  const assertion = ASSERTIONS.get(values.assert);
-  if (!assertion) {
-    process.stderr.write(
-      `lifecycle-diff: unknown --assert mode "${values.assert}". Valid: ${[...ASSERTIONS.keys()].join(', ')}\n`,
-    );
-    return 2;
-  }
-  const records = loadLedger(positionals[0]);
-  const result = assertion(records);
-  if (result.ok) {
-    process.stdout.write(`[lifecycle-diff] PASS ${values.assert}\n`);
-    return 0;
-  }
-  process.stderr.write(
-    `[lifecycle-diff] FAIL ${values.assert}: ${result.reason}\n`,
-  );
-  return 1;
-}
-
-await runAsCli(import.meta.url, main, {
-  source: 'lifecycle-diff',
-  propagateExitCode: true,
-});

package/.agents/scripts/lib/orchestration/lifecycle/listeners/acceptance-reconciler.js

@@ -199,7 +199,7 @@ export class AcceptanceReconciler {
       ? epicIdFromPayload
       : this.epicId;
 
-    // 1. Start emit. The downstream lifecycle-diff `reconcile-ordering`
+    // 1. Start emit. The downstream ledger-diff `reconcile-ordering`
     //    assert checks for `acceptance.reconcile.ok` before `pr.created`,
     //    but operators want to see the `.start` marker in the trace too.
     try {