mandrel 1.91.0 → 1.93.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/lib/orchestration/file-assumptions.js

@@ -15,7 +15,13 @@
  *
  * Rules (one error per mismatched path):
  *   - `creates`            + path **exists**  → error (Story would clobber).
- *   - `refactors-existing` + path **absent** → error (no target to refactor).
+ *   - `refactors-existing` (via `changes`) + path **absent** →
+ *     auto-normalized to `creates` with a logged warning (#4496 fix 5):
+ *     a refactor declaration against a base-untracked path is
+ *     deterministically a create, so rejecting it only forces a
+ *     reject→amend→re-persist cycle for a mechanical rewrite. Genuine
+ *     mismatches keep failing — a `references`-sourced `refactors-existing`
+ *     on an absent path is a missing read dependency and stays an error.
  *   - `exists`             + path **absent** → error (read dependency missing).
  *   - `deletes`            + path **absent** → error (nothing to delete).
  *
@@ -185,6 +191,18 @@ function renderMismatch({
   return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path already exists at the base branch.`;
 }
 
+/**
+ * Render an auto-normalization (#4496 fix 5) into a stable warning string.
+ * Kept pure and exported through the report so callers log a
+ * self-explanatory line rather than re-deriving the rationale.
+ *
+ * @param {{ slug: string, source: string, path: string, assumption: string }} normalization
+ * @returns {string}
+ */
+function renderNormalization({ slug, source, path, assumption }) {
+  return `"${slug}" → body.${source} declares assumption="${assumption}" for ${path} but the path is untracked at the base branch — auto-normalized to "creates" (a refactor of a base-untracked path is deterministically a create). Declare assumption="creates" in the plan to silence this warning.`;
+}
+
 /**
  * Index, across every Story, which Stories declare a `creates` (and which
  * declare a `deletes`) for each `changes`-sourced path. The maps drive the
@@ -251,8 +269,11 @@ function predecessorMutator(index, path, predecessors) {
  *
  *   {
  *     errors:    string[]   // one entry per mismatch, batched per Story
- *     warnings:  string[]   // legacy/no-assumption deprecation nudges
+ *     warnings:  string[]   // legacy/no-assumption deprecation nudges +
+ *                           // auto-normalization notices (#4496 fix 5)
  *     mismatches: object[]  // structured payload for downstream tooling
+ *     normalizations: object[] // `refactors-existing`→`creates`
+ *                           // auto-normalizations on base-untracked paths
  *   }
  *
  * Under the 2-tier hierarchy the Story is the implementation unit, so the
@@ -283,6 +304,7 @@ export function validateStoryFileAssumptions(opts) {
   const errors = [];
   const warnings = [];
   const mismatches = [];
+  const normalizations = [];
   const probeCache = new Map();
 
   // Wave-aware setup (Story #3960): transitive predecessor sets over the
@@ -350,6 +372,14 @@ export function validateStoryFileAssumptions(opts) {
         predecessorCreator,
       });
       if (mismatch !== null) {
+        // Auto-normalization (#4496 fix 5): a deterministic
+        // `refactors-existing`→`creates` rewrite is a warning, never a
+        // rejection — genuine mismatches keep flowing to `errors`.
+        if (mismatch.normalizedTo === 'creates') {
+          normalizations.push(mismatch);
+          warnings.push(renderNormalization(mismatch));
+          continue;
+        }
         mismatches.push(mismatch);
         errors.push(renderMismatch(mismatch));
         continue;
@@ -384,7 +414,7 @@ export function validateStoryFileAssumptions(opts) {
       }
     }
   }
-  return { errors, warnings, mismatches };
+  return { errors, warnings, mismatches, normalizations };
 }
 
 /**
@@ -468,12 +498,43 @@ function checkAssumption({
       }
       return null;
     case 'refactors-existing':
+      // Validate against the simulated tree: a predecessor `creates` makes
+      // an otherwise-absent base path present, so `refactors-existing`
+      // against it is no longer a false-positive mismatch (Story #3960).
+      if (!simulatedExists) {
+        // Auto-normalization (#4496 fix 5): a `changes`-sourced refactor
+        // declaration on a path untracked at the base branch (and not
+        // produced by any predecessor) is deterministically a create —
+        // downgrade to a normalization warning instead of rejecting. Two
+        // genuine mismatches stay hard errors: a `references`-sourced entry
+        // (a read dependency this Story does not author cannot be "created"
+        // here), and a base-TRACKED path a predecessor deletes (the absence
+        // is a plan-shape conflict, not an untracked-path misdeclaration).
+        if (source === 'changes' && !baseExists) {
+          return {
+            slug,
+            source,
+            path,
+            assumption,
+            expected: 'creates',
+            actual: 'absent',
+            normalizedTo: 'creates',
+          };
+        }
+        return {
+          slug,
+          source,
+          path,
+          assumption,
+          expected: 'present',
+          actual: 'absent',
+        };
+      }
+      return null;
     case 'exists':
     case 'deletes':
-      // Validate against the simulated tree: a predecessor `creates` makes
-      // an otherwise-absent base path present, so `refactors-existing` /
-      // `exists` / `deletes` against it is no longer a false-positive
-      // mismatch (Story #3960).
+      // Same simulated-tree overlay as above (Story #3960); an absent path
+      // remains a genuine mismatch for both assumptions.
       if (!simulatedExists) {
         return {
           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 {