mandrel 1.90.0 → 1.92.0

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -19,9 +19,12 @@
  * Delivery Slicing section, an unparseable "Independent?" cell — resolves to
  * `dispatch: true`. This gate can only ever *save* a dispatch when it is
  * confident the critic has nothing to do; it never disables the critic's
- * ability to catch a real divergence. Phase 8.4 (reachability critic), 8.5
- * (pre-mortem critic), and the deterministic ticket validator are
- * unconditional — this precondition governs only the 8.3 dispatch.
+ * ability to catch a real divergence. Since Epic #4474 PR6 this precondition
+ * is one input to the risk/size-conditional dispatch layer
+ * (`plan-critic-conditions.js`): reachability (8.4) is a deterministic
+ * persist-side check (`plan-reachability.js`) and the pre-mortem critic
+ * (8.5) is risk/size-gated; the deterministic ticket validator remains
+ * unconditional.
  *
  * Pure, synchronous, no I/O — callers own reading `tickets.json` and the
  * Epic body off disk / the GitHub API.
@@ -146,10 +149,14 @@ function isBddScaffoldStory(story) {
  *   top-level `slug` / `depends_on` / `body` (serialized string).
  * @param {string} input.epicBody - The Epic body carrying the folded Tech
  *   Spec sections (`## Delivery Slicing` onward).
- * @returns {{ dispatch: boolean, reasons: string[] }} `dispatch: false` only
- *   when the draft matches the Delivery Slicing table 1:1 in count and
- *   dependency shape; `dispatch: true` (with `reasons`) otherwise, including
- *   every fail-open case.
+ * @returns {{ dispatch: boolean, cause: 'match'|'divergence'|'fail-open', reasons: string[] }}
+ *   `dispatch: false` only when the draft matches the Delivery Slicing table
+ *   1:1 in count and dependency shape; `dispatch: true` (with `reasons`)
+ *   otherwise, including every fail-open case. `cause` distinguishes a
+ *   **confirmed** divergence (count or dependency-shape mismatch) from the
+ *   fail-open ambiguity (missing/unparseable table) — the #4474 PR6
+ *   conditional-dispatch layer treats only the former as a firing condition
+ *   on small drafts.
  */
 export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (!Array.isArray(draftStories)) {
@@ -162,6 +169,7 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (!slicing) {
     return {
       dispatch: true,
+      cause: 'fail-open',
       reasons: [
         'Delivery Slicing section is missing or unparseable — fail-open to the critic.',
       ],
@@ -175,6 +183,7 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   if (slicedStories.length !== slicing.length) {
     return {
       dispatch: true,
+      cause: 'divergence',
       reasons: [
         `Story count diverges from Delivery Slicing: ${slicing.length} proposed slice(s) vs ${slicedStories.length} non-scaffold draft Story(ies).`,
       ],
@@ -201,11 +210,12 @@ export function evaluateConsolidationPrecondition({ draftStories, epicBody }) {
   }
 
   if (reasons.length > 0) {
-    return { dispatch: true, reasons };
+    return { dispatch: true, cause: 'divergence', reasons };
   }
 
   return {
     dispatch: false,
+    cause: 'match',
     reasons: [
       `Draft matches Delivery Slicing 1:1 in count and dependency shape (${slicing.length} slice(s)) — skipping the 8.3 consolidation dispatch.`,
     ],

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -9,9 +9,8 @@
  * file I/O decisions, or process.exit(). All I/O choices are delegated
  * to the caller.
  *
- * Consumers:
- *   - `.agents/scripts/hydrate-context.js`   — the only supported CLI wrapper
- *     (imports hydrateContext; `--emit prompt` writes the raw hydrated prompt)
+ * Consumers import `hydrateContext` from this module directly — the former
+ * `hydrate-context.js` CLI wrapper was retired (#4482) with no live consumer.
  *
  * @see .agents/scripts/lib/ITicketingProvider.js
  */
@@ -153,7 +152,7 @@ function getVersion() {
  * @param {string} body
  * @returns {Record<string, number>}
  */
-export function parseHierarchy(body) {
+function parseHierarchy(body) {
   const result = {};
   if (!body) return result;
 

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -15,7 +15,7 @@
  *
  * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
  * generate-and-write export so the planner-context surface
- * (`epic-plan-spec.js` / `authoring-context.js`) can produce a session docs
+ * (`plan-context.js` / `authoring-context.js`) can produce a session docs
  * digest without duplicating the mkdir+writeFile plumbing
  * `epic-deliver-prepare.js` already owns for the delivery-children digest.
  */
@@ -146,7 +146,7 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
  * write) when there is nothing to digest. This is the single shared
  * generate-and-persist export both digest producers call: the per-Epic
  * delivery-children digest (`epic-deliver-prepare.js`) and the planner-
- * context digest (`epic-plan-spec.js` → `authoring-context.js`, Story
+ * context digest (`plan-context.js` → `authoring-context.js`, Story
  * #4433). Callers own path construction (temp-root layout, epic id, etc.)
  * so both surfaces can keep — or deliberately share — their own convention;
  * this function only owns "build digest, ensure parent dir, write file".

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

@@ -104,6 +104,10 @@ export function validateTickets(tickets, config, opts = {}) {
   const validated = validateAndNormalizeTickets(tickets, {
     baseBranchRef,
     conflictPolicy,
+    // Thread the repo cwd into the AC-freshness / file-assumption git
+    // probes (#4474 PR7) — without it they silently ran against
+    // process.cwd(), which is only the repo root by coincidence.
+    cwd: opts.cwd,
   });
   validateTaskBodies(validated);
   return validated;

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 {

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

@@ -82,6 +82,7 @@ import {
   openOrLocatePr as defaultOpenOrLocatePr,
 } from '../../finalize/open-or-locate-pr.js';
 import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/post-handoff-comment.js';
+import { probeRemoteBranch as defaultProbeRemoteBranch } from '../../remote-verifier.js';
 
 /**
  * Build the production default `runFinalizeFn` that composes the
@@ -103,12 +104,22 @@ import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/
  * contract is identical and `markPrReady` is a no-op on an already-ready
  * PR, so replay stays idempotent.
  *
+ * Issue #4483 — deterministic land-or-block backstop. Before opening (or
+ * readying) the PR, finalize asserts the delivery branch `epic/<id>`
+ * actually exists on origin. A delivery that was never pushed — e.g. an
+ * agent that built the Epic inline on local `main` and skipped the
+ * orchestration — MUST surface as an explicit
+ * `delivery-branch-missing-on-origin` blocker (which keeps the Epic at
+ * `agent::blocked`), never a declared success. The probe is bounded
+ * (timeout + SIGKILL) so a hung remote degrades to a blocker too.
+ *
  * @param {{
  *   provider?: object|null,
  *   earlyPr?: boolean,
  *   openOrLocatePrFn?: typeof defaultOpenOrLocatePr,
  *   markPrReadyFn?: typeof defaultMarkPrReady,
  *   postHandoffCommentFn?: typeof defaultPostHandoffComment,
+ *   probeRemoteBranchFn?: typeof defaultProbeRemoteBranch,
  * }} deps
  */
 export function composeBusOwnedFinalize(deps = {}) {
@@ -116,6 +127,8 @@ export function composeBusOwnedFinalize(deps = {}) {
   const markPrReadyFn = deps.markPrReadyFn ?? defaultMarkPrReady;
   const postHandoffCommentFn =
     deps.postHandoffCommentFn ?? defaultPostHandoffComment;
+  const probeRemoteBranchFn =
+    deps.probeRemoteBranchFn ?? defaultProbeRemoteBranch;
   const provider = deps.provider ?? null;
   const earlyPr = deps.earlyPr !== false;
 
@@ -128,6 +141,25 @@ export function composeBusOwnedFinalize(deps = {}) {
         },
       };
     }
+
+    // Issue #4483 backstop — the delivery branch MUST be on origin before
+    // finalize declares any success. A never-pushed branch is the silent
+    // local-main failure shape; block explicitly with the probe detail.
+    let branchProbe;
+    try {
+      branchProbe = probeRemoteBranchFn({ branch: `epic/${epicId}`, cwd });
+    } catch (err) {
+      branchProbe = { exists: false, detail: err?.message ?? String(err) };
+    }
+    if (!branchProbe.exists) {
+      return {
+        blocker: {
+          reason: 'delivery-branch-missing-on-origin',
+          detail: `epic/${epicId} is not on origin — the delivery was never pushed; refusing to finalize (issue #4483). Probe: ${branchProbe.detail}`,
+        },
+      };
+    }
+
     let openResult;
     try {
       openResult = await openOrLocatePrFn({