mandrel 1.92.0 → 1.94.0

package/.agents/scripts/lib/orchestration/deliver-route.js

@@ -0,0 +1,173 @@
+/**
+ * lib/orchestration/deliver-route.js — the deliver-side reader for the
+ * plan-time single-delivery seam (Epic #4475, M4-A).
+ *
+ * The plan path already ships the seam inert (Epic #4474): the risk verdict's
+ * `deliveryShape`, the `delivery::single` label, and the
+ * `epic-plan-state.decompose = { ticketCount: 0, shape: "single" }`
+ * checkpoint. Nothing on the deliver side read them — until this module. It
+ * folds those two markers (plus the global kill-switch) into a single
+ * delivery-route verdict for `/deliver`.
+ *
+ * Pure and total — inputs in, verdict out. No GitHub calls, no I/O, no
+ * throws. It mirrors how `review-depth.js#resolveDepth` and
+ * `epic-audit-prepare.js` read `planningRisk` / `decompose` off the
+ * `epic-plan-state` checkpoint: the caller fetches the Epic labels + the
+ * checkpoint, then hands both here.
+ *
+ * ── Routing precedence (highest wins) ──────────────────────────────────
+ *   1. Kill-switch. `delivery.routing.singleDelivery === false` forces
+ *      `fan-out` for EVERY Epic, even a single-labelled one — the instant
+ *      global revert (`lib/config/delivery-routing.js`). Overrides all.
+ *   2. Single marker. The `delivery::single` label (primary) OR
+ *      `checkpoint.decompose.shape === "single"` (secondary) → `single`.
+ *   3. Wide-DAG advisory. A fan-out-shaped Epic whose ready-width > 1 is
+ *      genuine parallelism → `fan-out`. Deliver-time width only ADVISES —
+ *      it never reroutes a single-marked Epic (that would orphan a Story
+ *      tree that does not exist; re-route = re-plan).
+ *   4. Legacy / no marker → `fan-out` (safe backward-compat: a legacy Epic
+ *      has an authored Story tree the fan-out engine consumes).
+ *
+ * BEHAVIOR-PRESERVING in M4-A: the router consumes a `single` verdict via a
+ * stub that continues at `deliver-epic.md` (fan-out), so no `/deliver`
+ * observably changes until M4-B lands `deliver-epic-single.md`.
+ *
+ * @typedef {'single'|'fan-out'} DeliveryRoute
+ */
+
+import { getDeliveryRouting } from '../config/delivery-routing.js';
+
+/** The canonical single-delivery routing marker label. */
+export const DELIVERY_SINGLE_LABEL = 'delivery::single';
+
+/**
+ * True when the Epic carries the `delivery::single` routing label. Tolerant
+ * of the two label shapes callers hold: an array of label-name strings, or an
+ * array of `{ name }` objects (the GitHub REST label shape).
+ *
+ * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
+ * @returns {boolean}
+ */
+function hasSingleLabel(epic) {
+  const labels = Array.isArray(epic?.labels) ? epic.labels : [];
+  return labels.some((l) => {
+    const name = typeof l === 'string' ? l : l?.name;
+    return name === DELIVERY_SINGLE_LABEL;
+  });
+}
+
+/**
+ * True when the plan-state checkpoint's `decompose.shape` is the deliberate
+ * single shape. `plan-persist.js` writes `decompose = { ticketCount: 0,
+ * shape: "single" }` for a spec-only plan; every other value (including a
+ * legacy checkpoint with no `shape` field) is not-single.
+ *
+ * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
+ * @returns {boolean}
+ */
+function hasSingleDecomposeShape(checkpoint) {
+  return checkpoint?.decompose?.shape === 'single';
+}
+
+/**
+ * Resolve the delivery route for one Epic from its labels, its plan-state
+ * checkpoint, and the resolved config. See the module header for the full
+ * precedence. Pure — never throws; malformed / absent inputs degrade to the
+ * safe `fan-out` default.
+ *
+ * @param {{ labels?: Array<string | { name?: string }> } | null | undefined} epic
+ *   The Epic ticket snapshot (only `labels` is read here).
+ * @param {{ decompose?: { shape?: string } } | null | undefined} checkpoint
+ *   The `epic-plan-state` structured comment, parsed (or `null` on a legacy
+ *   Epic that predates the checkpoint — treated as no marker).
+ * @param {object | null | undefined} config
+ *   The resolved config; `delivery.routing.singleDelivery` is the kill-switch.
+ * @returns {{ route: DeliveryRoute, reason: string, singleDeliveryEnabled: boolean }}
+ */
+export function resolveEpicDeliveryRoute(epic, checkpoint, config) {
+  const { singleDelivery } = getDeliveryRouting(config);
+
+  // 1. Kill-switch — overrides all. A `false` value forces fan-out even for
+  //    an Epic the planner marked single (the instant global revert).
+  if (singleDelivery === false) {
+    return {
+      route: 'fan-out',
+      reason:
+        'kill-switch: delivery.routing.singleDelivery=false forces fan-out for every Epic',
+      singleDeliveryEnabled: false,
+    };
+  }
+
+  // 2. Single marker — label (primary) OR checkpoint decompose shape
+  //    (secondary). Either alone routes single.
+  const labelled = hasSingleLabel(epic);
+  const shaped = hasSingleDecomposeShape(checkpoint);
+  if (labelled || shaped) {
+    const via =
+      labelled && shaped
+        ? `${DELIVERY_SINGLE_LABEL} label + decompose.shape="single"`
+        : labelled
+          ? `${DELIVERY_SINGLE_LABEL} label`
+          : 'decompose.shape="single"';
+    return {
+      route: 'single',
+      reason: `single marker present (${via})`,
+      singleDeliveryEnabled: true,
+    };
+  }
+
+  // 3/4. No single marker → fan-out (a wide DAG or a legacy Story tree; the
+  //      deliver-time width only advises and never reroutes here).
+  return {
+    route: 'fan-out',
+    reason: 'no single marker — fan-out (legacy Story tree or wide DAG)',
+    singleDeliveryEnabled: true,
+  };
+}
+
+/**
+ * Compute the ready-width of a delivery plan — the count of work units that
+ * could dispatch on the first beat. It is the mechanical parallelism signal
+ * the planner uses at plan time to mark a genuinely-wide Epic `fan-out`, and
+ * that `/deliver` may surface as an advisory at deliver time (it never
+ * reroutes — see the module header).
+ *
+ * Accepts either input shape the framework already produces:
+ *   - Delivery-Slicing rows — `[{ independent: boolean }, …]` from
+ *     `parseDeliverySlicingTable`. A serial chain (every row
+ *     `Independent: No`, or a lone independent slice) has width 1; two or
+ *     more independent slices yield a width equal to that independent count
+ *     (> 1) — genuine parallelism.
+ *   - A wave DAG — `[[…], […], …]` (the array-of-waves `state.waves` shape
+ *     `runBuildWaveDagPhase` produces). The width is the largest wave — the
+ *     most Stories ready to dispatch on a single beat.
+ *
+ * Pure and total: an empty / malformed / unrecognized input degrades to
+ * width 1 (the safe "not wide" signal). Never throws.
+ *
+ * @param {Array<{ independent?: boolean }> | Array<Array<unknown>> | null | undefined} deliverySlicingRowsOrDag
+ * @returns {number} an integer ≥ 1.
+ */
+export function computeReadyWidth(deliverySlicingRowsOrDag) {
+  const input = deliverySlicingRowsOrDag;
+  if (!Array.isArray(input) || input.length === 0) return 1;
+
+  // Wave-DAG shape: an array whose entries are themselves arrays.
+  if (input.every((entry) => Array.isArray(entry))) {
+    let widest = 1;
+    for (const wave of input) {
+      if (wave.length > widest) widest = wave.length;
+    }
+    return widest;
+  }
+
+  // Delivery-Slicing rows: entries are `{ independent }` records.
+  const independentCount = input.reduce(
+    (acc, row) =>
+      row && typeof row === 'object' && row.independent === true
+        ? acc + 1
+        : acc,
+    0,
+  );
+  return independentCount >= 2 ? independentCount : 1;
+}

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

@@ -41,7 +41,7 @@ import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
  * @param {{ github?: { owner?: string, repo?: string }|null }} opts
  * @returns {string|null}
  */
-export function resolveMemoryDir({ github } = {}) {
+function resolveMemoryDir({ github } = {}) {
   if (
     typeof process.env.MANDREL_MEMORY_DIR === 'string' &&
     process.env.MANDREL_MEMORY_DIR.length > 0

package/.agents/scripts/lib/orchestration/epic-run-state-store.js

@@ -326,6 +326,239 @@ export async function recordStoryStatus({
   });
 }
 
+/**
+ * Terminal / in-progress per-slice statuses persisted on a single-delivery
+ * checkpoint. The single-delivery analogue of `STORY_STATUSES` — a spec-only
+ * plan authors no Story tickets, so the leaf work unit is a `## Delivery
+ * Slicing` slice walked in-session on `epic/<id>` (Epic #4475). The design's
+ * durable contract is `{pending, done}`; `blocked`/`failed` mirror the story
+ * map so the M4-B executor can record a stalled slice without a schema bump.
+ */
+export const SLICE_STATUSES = Object.freeze([
+  'pending',
+  'done',
+  'blocked',
+  'failed',
+]);
+
+/**
+ * Build the initial per-slice status map from parsed `## Delivery Slicing`
+ * rows (`parseDeliverySlicingTable` output — `[{ slice, independent }]`).
+ * Every slice seeds at `status: 'pending'`, keyed by a **stable, position-
+ * derived** id `slice-<n>` (1-based) so a re-run over the same table
+ * round-trips its keys. The slice's human label is carried through as `title`
+ * for the operator rollup. Pure — exported for unit tests.
+ *
+ * @param {Array<{ slice?: string, independent?: boolean } | string>} slices
+ * @returns {Record<string, { status: string, title?: string }>}
+ */
+export function buildSliceStatusMap(slices) {
+  const out = {};
+  const rows = Array.isArray(slices) ? slices : [];
+  rows.forEach((entry, i) => {
+    const sliceId = `slice-${i + 1}`;
+    const record = { status: 'pending' };
+    const title =
+      typeof entry === 'string'
+        ? entry
+        : entry && typeof entry === 'object' && typeof entry.slice === 'string'
+          ? entry.slice
+          : undefined;
+    if (title) record.title = title;
+    out[sliceId] = record;
+  });
+  return out;
+}
+
+/**
+ * Merge a freshly-seeded slice status map onto a persisted one. Every slice
+ * present in either map appears in the result; when a slice exists in the
+ * prior map its recorded `status` wins (recorded progress — a `done` slice
+ * whose work already sits on `epic/<id>` — is never lost), while its `title`
+ * is refreshed from the incoming seed. Slices present only in the incoming
+ * seed are added at `pending`. Pure — exported for unit tests.
+ *
+ * @param {Record<string, object>|undefined} prior
+ * @param {Record<string, object>} incoming
+ * @returns {Record<string, object>}
+ */
+export function mergeSliceStatuses(prior, incoming) {
+  const priorMap = prior && typeof prior === 'object' ? prior : {};
+  const seedMap = incoming && typeof incoming === 'object' ? incoming : {};
+  const out = {};
+  for (const key of new Set([
+    ...Object.keys(priorMap),
+    ...Object.keys(seedMap),
+  ])) {
+    const priorEntry = priorMap[key];
+    const seedEntry = seedMap[key];
+    if (priorEntry && typeof priorEntry === 'object') {
+      const merged = { ...priorEntry };
+      if (seedEntry && typeof seedEntry.title === 'string') {
+        merged.title = seedEntry.title;
+      }
+      out[key] = merged;
+    } else {
+      out[key] = seedEntry;
+    }
+  }
+  return out;
+}
+
+/**
+ * Initialize (or resume) the single-delivery checkpoint for an Epic. The
+ * single-delivery analogue of `initialize` (Story #4155's per-Story map),
+ * writing the slice-map shape the M4-B executor walks:
+ *
+ * ```json
+ * {
+ *   "epicId": 4475,
+ *   "deliveryShape": "single",
+ *   "slices": { "slice-1": { "status": "pending", "title": "…" } },
+ *   "concurrencyCap": 1,
+ *   "storyCount": 0
+ * }
+ * ```
+ *
+ * Idempotent + resume-preserving: on a re-run an existing single checkpoint
+ * has its slice map **merged** (every already-`done` slice keeps its status
+ * so the executor skips it — the work already sits on `epic/<id>`), while
+ * newly-authored slices seed at `pending`. `startedAt` is preserved. A
+ * checkpoint written for the fan-out shape is NOT reinterpreted here — the
+ * caller (`epic-deliver-prepare.js --single`) owns route selection.
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   epicId: number,
+ *   slices: Array<{ slice?: string, independent?: boolean } | string>,
+ *   concurrencyCap?: number,
+ * }} opts
+ * @returns {Promise<object>} the persisted (or preserved) state
+ */
+export async function initializeSingle({
+  provider,
+  epicId,
+  slices,
+  concurrencyCap = 1,
+} = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  const seededSlices = buildSliceStatusMap(slices);
+  const storyCount = 0;
+  const existing = await read({ provider, epicId });
+  if (existing && existing.deliveryShape === 'single') {
+    const mergedSlices = mergeSliceStatuses(existing.slices, seededSlices);
+    if (
+      existing.concurrencyCap === concurrencyCap &&
+      sliceMapsEqual(existing.slices, mergedSlices)
+    ) {
+      return existing;
+    }
+    return write({
+      provider,
+      epicId,
+      state: {
+        ...existing,
+        deliveryShape: 'single',
+        concurrencyCap,
+        storyCount,
+        slices: mergedSlices,
+      },
+    });
+  }
+  return write({
+    provider,
+    epicId,
+    state: {
+      epicId,
+      startedAt: new Date().toISOString(),
+      deliveryShape: 'single',
+      concurrencyCap,
+      storyCount,
+      phase: 'prepare',
+      slices: seededSlices,
+      manualInterventions: [],
+    },
+  });
+}
+
+/**
+ * Record a per-slice terminal (or in-progress) status on a single-delivery
+ * checkpoint. The single-delivery analogue of `recordStoryStatus`: the M4-B
+ * executor calls this after each Delivery-Slicing slice commits to
+ * `epic/<id>`, flipping `slices[sliceId].status` `pending → done` so a resumed
+ * run skips the already-landed slice. Reads the current state first, splices
+ * the single slice's record into the `slices` map, and re-writes; other slices
+ * and all run-level fields are preserved verbatim. Tolerant of a
+ * legacy/absent `slices` map (treated as empty).
+ *
+ * @param {{
+ *   provider: import('../ITicketingProvider.js').ITicketingProvider,
+ *   epicId: number,
+ *   sliceId: string,
+ *   status: string,
+ *   title?: string,
+ * }} opts
+ * @returns {Promise<object>} the persisted state
+ */
+export async function recordSliceStatus({
+  provider,
+  epicId,
+  sliceId,
+  status,
+  title,
+} = {}) {
+  assertProvider(provider);
+  assertEpicId(epicId);
+  if (typeof sliceId !== 'string' || sliceId.length === 0) {
+    throw new TypeError(
+      'recordSliceStatus: sliceId must be a non-empty string',
+    );
+  }
+  if (!SLICE_STATUSES.includes(status)) {
+    throw new RangeError(
+      `recordSliceStatus: status "${status}" must be one of: ${SLICE_STATUSES.join(', ')}`,
+    );
+  }
+  const existing = (await read({ provider, epicId })) ?? {};
+  const slices =
+    existing.slices && typeof existing.slices === 'object'
+      ? { ...existing.slices }
+      : {};
+  const prior = slices[sliceId] ?? {};
+  const record = { ...prior, status };
+  if (typeof title === 'string' && title) record.title = title;
+  slices[sliceId] = record;
+  return write({
+    provider,
+    epicId,
+    state: { ...existing, slices },
+  });
+}
+
+/**
+ * Structural equality on two slice status maps — same key set and, per key,
+ * the same `status` and `title`. Used by `initializeSingle` to decide whether
+ * an idempotent re-prepare needs a rewrite. Pure.
+ *
+ * @param {Record<string, object>|undefined} a
+ * @param {Record<string, object>|undefined} b
+ * @returns {boolean}
+ */
+function sliceMapsEqual(a, b) {
+  const left = a && typeof a === 'object' ? a : {};
+  const right = b && typeof b === 'object' ? b : {};
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  for (const key of keys) {
+    const l = left[key] ?? {};
+    const r = right[key];
+    if (!r) return false;
+    if (l.status !== r.status || l.title !== r.title) return false;
+  }
+  return true;
+}
+
 /**
  * Append a manual-intervention record to the checkpoint. Out-of-band
  * recovery steps the host LLM performs during a delivery — `AskUserQuestion`

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,