mandrel 1.94.0 → 2.1.0

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

@@ -1,140 +0,0 @@
-/**
- * ledger-diff.js — structural-diff and ordering-assertion helpers over a
- * lifecycle ledger (`temp/epic-<id>/lifecycle.ndjson`) for the
- * repeatability invariants.
- *
- * 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.
- */
-
-/**
- * Parse an NDJSON lifecycle ledger into an array of records. Blank
- * lines tolerated; malformed JSON throws with line number. Duplicated
- * from `trace-logger.js` to keep the diff surface decoupled from the
- * listener surface.
- */
-export function parseLedgerText(text) {
-  const out = [];
-  const lines = String(text || '').split('\n');
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (line.length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch (_err) {
-      throw new Error(
-        `ledger-diff: malformed JSON in ledger on line ${i + 1}: ${line.slice(0, 80)}`,
-      );
-    }
-  }
-  return out;
-}
-
-/**
- * Project a single record into a comparison key. `ts` and `seqId` are
- * intentionally elided; the rest of the record is included so that the
- * structural shape (event order, payload contents, listener attribution
- * on failed records) is the diff surface.
- *
- * Exported for unit tests that pin the diff contract.
- */
-export function projectRecord(rec) {
-  if (!rec || typeof rec !== 'object') return rec;
-  const { ts: _ts, seqId: _seqId, ...rest } = rec;
-  return rest;
-}
-
-/**
- * Structural diff of two ledger arrays. Returns an array of mismatch
- * descriptors (empty when identical modulo `ts`/`seqId`).
- */
-export function diff(ledgerA, ledgerB) {
-  const a = ledgerA.map(projectRecord);
-  const b = ledgerB.map(projectRecord);
-  const out = [];
-  const max = Math.max(a.length, b.length);
-  for (let i = 0; i < max; i += 1) {
-    const left = a[i];
-    const right = b[i];
-    const leftJson = JSON.stringify(left);
-    const rightJson = JSON.stringify(right);
-    if (leftJson !== rightJson) {
-      out.push({ index: i, left: left ?? null, right: right ?? null });
-    }
-  }
-  return out;
-}
-
-/**
- * Assert: epic.merge.armed must be preceded by epic.merge.ready
- * (same run). Returns `{ ok: true }` or `{ ok: false, reason }`.
- */
-export function assertMergeGateOrdering(records) {
-  let sawReady = false;
-  let sawReadySeq = null;
-  for (const rec of records) {
-    if (rec.kind !== 'emitted') continue;
-    if (rec.event === 'epic.merge.ready') {
-      sawReady = true;
-      sawReadySeq = rec.seqId;
-    } else if (rec.event === 'epic.merge.armed') {
-      if (!sawReady) {
-        return {
-          ok: false,
-          reason: `epic.merge.armed at seqId=${rec.seqId} without preceding epic.merge.ready`,
-        };
-      }
-      if (sawReadySeq != null && rec.seqId <= sawReadySeq) {
-        return {
-          ok: false,
-          reason: `epic.merge.armed seqId=${rec.seqId} must be > epic.merge.ready seqId=${sawReadySeq}`,
-        };
-      }
-    }
-  }
-  return { ok: true };
-}
-
-/**
- * Assert: pr.created must be preceded by either acceptance.reconcile.ok
- * or acceptance.reconcile.waived in the same run. Story #2893 split the
- * waiver path out of `.skipped` so the Finalizer now subscribes to both
- * `.ok` and `.waived`; either is a valid predecessor for pr.created.
- * A reconcile.skipped (empty-spec only after #2893) or reconcile.failed
- * before pr.created remains a violation.
- */
-export function assertReconcileOrdering(records) {
-  let sawReconcileGate = false;
-  let sawReconcileGateSeq = null;
-  let sawReconcileGateEvent = null;
-  for (const rec of records) {
-    if (rec.kind !== 'emitted') continue;
-    if (
-      rec.event === 'acceptance.reconcile.ok' ||
-      rec.event === 'acceptance.reconcile.waived'
-    ) {
-      sawReconcileGate = true;
-      sawReconcileGateSeq = rec.seqId;
-      sawReconcileGateEvent = rec.event;
-    } else if (rec.event === 'pr.created') {
-      if (!sawReconcileGate) {
-        return {
-          ok: false,
-          reason: `pr.created at seqId=${rec.seqId} without preceding acceptance.reconcile.ok or acceptance.reconcile.waived`,
-        };
-      }
-      if (sawReconcileGateSeq != null && rec.seqId <= sawReconcileGateSeq) {
-        return {
-          ok: false,
-          reason: `pr.created seqId=${rec.seqId} must be > ${sawReconcileGateEvent} seqId=${sawReconcileGateSeq}`,
-        };
-      }
-    }
-  }
-  return { ok: true };
-}

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

@@ -1,465 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/listeners/acceptance-reconciler.js
-/**
- * AcceptanceReconciler — lifecycle listener that gates Finalize on the
- * close-time acceptance-spec reconciliation. Story #2253 (Epic #2172):
- * the reconciliation moves *ahead* of the push + `gh pr create` call so
- * that AC coverage gaps block PR creation (review High-2).
- *
- * Subscribes to:
- *   - `epic.close.end` → emit `acceptance.reconcile.start`, run the
- *     `reconcileAcceptanceSpec` helper, emit one of
- *     `acceptance.reconcile.ok | .waived | .skipped | .failed`, and on
- *     `.failed` also emit `epic.blocked` so the LabelTransitioner /
- *     StructuredCommentPoster / NotifyDispatcher trio fire the blocker
- *     side effects exactly as a `story.blocked` cascade would.
- *
- * The Finalizer listener subscribes ONLY to `acceptance.reconcile.ok`,
- * so this listener is the authoritative safety gate ahead of any push
- * or PR-create work. The legacy `epic-deliver-finalize.js` shim still
- * exists for backwards compatibility, but its in-line reconciliation
- * call is replaced by the event-driven path.
- *
- * Idempotency contract (Acceptance Spec AC-10):
- *   - Per-instance `Set<string>` of `${event}:${seqId}` keys. A repeat
- *     `(event, seqId)` short-circuits without re-running reconciliation
- *     and emits no events.
- *   - The reconciler helper's only write is the section-scoped
- *     disposition record inside the Epic body's ## Acceptance Table
- *     region (Story #4324) — itself idempotent — so the seqId guard is
- *     the only defence the listener needs.
- *
- * Side-effect firewall: the listener owns the reconciliation call and
- * the four outcome emits. It does NOT mutate labels, post comments, or
- * call `notify` directly — those are downstream listener concerns.
- */
-
-import { reconcileAcceptanceSpec as defaultReconcileAcceptanceSpec } from '../../../../acceptance-spec-reconciler.js';
-import { DELIVERY_SINGLE_LABEL } from '../../deliver-route.js';
-import { read as readEpicRunState } from '../../epic-run-state-store.js';
-
-/**
- * Default single-delivery resolver (Epic #4475, M4-B, design §2c). Decides
- * whether the Epic under reconciliation is the single-delivery shape — the
- * signal that flips a `waived` reconcile into a hard failure (the back gate
- * of the non-waivable epic-level acceptance contract). Two sources, primary
- * first:
- *
- *   1. `epic-run-state.deliveryShape === 'single'` — the durable checkpoint
- *      the single-delivery prepare writes.
- *   2. The `delivery::single` label on the Epic ticket — the plan-time marker.
- *
- * Best-effort + fail-open-to-fan-out: any probe failure (null provider in a
- * unit fixture, a GitHub read error) degrades to `false` (treat as fan-out),
- * so the defence-in-depth back gate never *invents* a block — the front gate
- * (prepare refusing `acceptance::n-a`) is the primary guard. Tests inject
- * `resolveSingleFn` directly to bypass the probes.
- *
- * @param {{ provider?: object|null, epicId: number, config?: object|null }} args
- * @returns {Promise<boolean>}
- */
-export async function defaultResolveSingle({ provider, epicId }) {
-  if (!provider) return false;
-  try {
-    const checkpoint = await readEpicRunState({ provider, epicId });
-    if (checkpoint?.deliveryShape === 'single') return true;
-  } catch {
-    // Fall through to the label probe.
-  }
-  try {
-    const epic = await provider.getTicket(epicId);
-    const labels = Array.isArray(epic?.labels) ? epic.labels : [];
-    return labels.some(
-      (l) => (typeof l === 'string' ? l : l?.name) === DELIVERY_SINGLE_LABEL,
-    );
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Classify a `reconcileAcceptanceSpec` result envelope into the typed
- * outcome event the listener should emit. Pure function — exported so
- * unit tests can drive every branch without a bus instance.
- *
- * The reconciler exposes a four-value `status` discriminant:
- *   - `'waived'`     → the Epic carries `acceptance::n-a` (or no linked
- *                       spec under `--skip-when-waived`). Emit
- *                       `acceptance.reconcile.waived` with reason
- *                       `'waiver'`. Story #2893 split this out from
- *                       `.skipped` so the Finalizer can subscribe to
- *                       `.waived` and route waived Epics through to PR
- *                       creation, while empty-spec Epics still
- *                       terminate without a PR via `.skipped`.
- *                       **Non-waivable under single delivery (Epic #4475,
- *                       M4-B, design §2c):** when `opts.single` is true the
- *                       epic-level reconcile is the ONLY acceptance gate
- *                       left, so a `waived` status is treated as a hard
- *                       `failed` (reason `single-delivery-non-waivable`)
- *                       instead of passing through — the back gate that
- *                       forecloses the cohort's dilution (waived reconcile
- *                       as the sole gate). The front gate (prepare refusing
- *                       `acceptance::n-a`) already blocks this at seed time;
- *                       this is defence in depth.
- *   - `'empty-spec'` → the linked spec exists but declares zero AC IDs.
- *                       Treated as "no work to do"; emit `.skipped` with
- *                       reason `'empty-spec'` so operators see the
- *                       outcome explicitly (no silent skip).
- *   - `'ok'`         → the spec has AC IDs and every one is covered by
- *                       a non-pending scenario. Emit `.ok`.
- *   - `'gap'`        → at least one AC is pending or missing. Emit
- *                       `.failed` carrying a compact reason summary;
- *                       the listener then emits `epic.blocked` to flip
- *                       the Epic ticket.
- *
- * @param {object|undefined|null} result reconciler envelope.
- * @param {{ single?: boolean }} [opts] `single: true` flips a `waived` status
- *   into a hard `failed` (the non-waivable epic reconcile back gate).
- * @returns {{ outcome: 'ok'|'waived'|'skipped'|'failed', reason?: string }}
- */
-export function classifyReconcileResult(result, opts = {}) {
-  const single = opts?.single === true;
-  if (!result || typeof result !== 'object') {
-    return { outcome: 'failed', reason: 'reconciler-no-result' };
-  }
-  const status = result.status;
-  if (status === 'waived') {
-    if (single) {
-      return {
-        outcome: 'failed',
-        reason: 'single-delivery-non-waivable',
-      };
-    }
-    return { outcome: 'waived', reason: 'waiver' };
-  }
-  if (status === 'empty-spec') {
-    return { outcome: 'skipped', reason: 'empty-spec' };
-  }
-  if (status === 'ok') {
-    return { outcome: 'ok' };
-  }
-  if (status === 'gap') {
-    const missing = Array.isArray(result.missing) ? result.missing : [];
-    const pending = Array.isArray(result.pending) ? result.pending : [];
-    const parts = [];
-    if (missing.length > 0) parts.push(`missing=${missing.join(',')}`);
-    if (pending.length > 0) parts.push(`pending=${pending.join(',')}`);
-    const reason =
-      parts.length > 0 ? `gap:${parts.join(';')}` : 'gap:unspecified';
-    return { outcome: 'failed', reason };
-  }
-  // Unknown status — fail closed so the operator sees the surprise.
-  return { outcome: 'failed', reason: `unknown-status:${String(status)}` };
-}
-
-/**
- * AcceptanceReconciler — instantiate one per Epic run and call
- * `register()` to wire it onto the bus. Stateless w.r.t. the system
- * under orchestration; per-run state is the `(event, seqId)`
- * idempotency cache + the classification log.
- */
-export class AcceptanceReconciler {
-  /**
-   * @param {object} opts
-   * @param {object} opts.bus Lifecycle bus instance (must expose
-   *   `on()` and `emit()`).
-   * @param {number} opts.epicId Epic ticket id.
-   * @param {string} [opts.cwd] Working directory passed through to the
-   *   reconciler helper. Defaults to `process.cwd()`.
-   * @param {object} [opts.provider] Ticketing provider — injected into
-   *   the reconciler call so the lifecycle bus does not need to
-   *   construct one itself.
-   * @param {object} [opts.config] Resolved orchestration config —
-   *   injected for the same reason.
-   * @param {Function} [opts.reconcileAcceptanceSpecFn] Override of the
-   *   helper for tests; defaults to the production export.
-   * @param {Function} [opts.resolveSingleFn] Override of the single-delivery
-   *   resolver for tests (Epic #4475, M4-B); defaults to `defaultResolveSingle`
-   *   (checkpoint `deliveryShape` → `delivery::single` label).
-   * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
-   */
-  constructor(opts = {}) {
-    if (
-      !opts.bus ||
-      typeof opts.bus.on !== 'function' ||
-      typeof opts.bus.emit !== 'function'
-    ) {
-      throw new TypeError(
-        'AcceptanceReconciler requires a bus with on() and emit()',
-      );
-    }
-    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
-      throw new TypeError('AcceptanceReconciler requires a numeric epicId');
-    }
-    this.bus = opts.bus;
-    this.epicId = opts.epicId;
-    this.cwd = opts.cwd ?? process.cwd();
-    this.provider = opts.provider ?? null;
-    this.config = opts.config ?? null;
-    this.reconcileAcceptanceSpecFn =
-      opts.reconcileAcceptanceSpecFn ?? defaultReconcileAcceptanceSpec;
-    this.resolveSingleFn = opts.resolveSingleFn ?? defaultResolveSingle;
-    this.logger = opts.logger ?? console;
-    /** @type {Set<string>} `${event}:${seqId}` keys we've handled. */
-    this._seen = new Set();
-    /**
-     * Classification log — mirrors the BlockerHandler "no silent skip"
-     * surface so tests can confirm every `epic.close.end` we observed
-     * was classified into exactly one outcome.
-     *
-     * @type {Array<{ event: string, seqId: number, outcome: string, reason?: string }>}
-     */
-    this.classifications = [];
-    this.events = Object.freeze(['epic.close.end']);
-  }
-
-  /**
-   * Register this listener on the bus. Returns an array of unsubscribe
-   * functions (one per event) for test teardown.
-   */
-  register() {
-    return this.events.map((event) =>
-      this.bus.on(event, async (ctx) => this.handle(ctx)),
-    );
-  }
-
-  /**
-   * Bus listener body. The bus passes `{ event, seqId, payload }`. The
-   * listener:
-   *   1. Idempotently short-circuits a repeat `(event, seqId)`.
-   *   2. Emits `acceptance.reconcile.start`.
-   *   3. Runs `reconcileAcceptanceSpec` with injected provider/config.
-   *   4. Emits exactly one of `.ok` / `.skipped` / `.failed`.
-   *   5. On `.failed`, additionally emits `epic.blocked` so the
-   *      downstream listener trio (label flip + structured comment +
-   *      notify) fires the operator-visible blocker side effects.
-   *
-   * The listener does NOT throw on reconciler failures: the bus's
-   * `onFailed` boundary already persists the originating
-   * `epic.close.end` record; surfacing a throw here would short-circuit
-   * other `epic.close.end` listeners (e.g. trace logger) and is not
-   * needed for correctness — the `acceptance.reconcile.failed` +
-   * `epic.blocked` emits are the cascade contract.
-   *
-   * @param {{ event: string, seqId: number, payload: object }} ctx
-   */
-  async handle({ event, seqId, payload }) {
-    const key = `${event}:${seqId}`;
-    if (this._seen.has(key)) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'skipped',
-        reason: 'duplicate-seqId',
-      });
-      this.logger.debug?.(
-        `[AcceptanceReconciler] skip duplicate ${key} (idempotent)`,
-      );
-      return;
-    }
-    this._seen.add(key);
-
-    const epicIdFromPayload = Number(payload?.epicId);
-    const epicId = Number.isInteger(epicIdFromPayload)
-      ? epicIdFromPayload
-      : this.epicId;
-
-    // 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 {
-      await this.bus.emit('acceptance.reconcile.start', { epicId });
-    } catch (err) {
-      // Schema validation against a known-good payload should never
-      // throw; if it does, surface and bail — there's no point running
-      // the reconciler when we cannot announce its outcome.
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'failed',
-        reason: `start-emit-failed:${err?.message ?? err}`,
-      });
-      this.logger.warn?.(
-        `[AcceptanceReconciler] acceptance.reconcile.start emit failed: ${err?.message ?? err}`,
-      );
-      return;
-    }
-
-    // 2. Run the reconciler. The helper itself throws on hard errors
-    //    (no linked spec + no waiver, etc.); convert those into
-    //    `.failed` emits rather than re-propagating, so the cascade
-    //    contract holds even when the spec is malformed.
-    let result;
-    let thrown = null;
-    try {
-      result = await this.reconcileAcceptanceSpecFn({
-        epicId,
-        cwd: this.cwd,
-        injectedProvider: this.provider ?? undefined,
-        injectedConfig: this.config ?? undefined,
-        loggerImpl: this.logger,
-        // Honour `acceptance::n-a` — the helper already returns
-        // `status: 'waived'` for that label, but `skipWhenWaived: true`
-        // additionally tolerates a missing acceptance-table section under
-        // the waiver (we want the same forgiving stance the inline
-        // finalize call had).
-        skipWhenWaived: true,
-        // Close time is the one place the verification outcome is
-        // recorded into the Epic body's ## Acceptance Table section
-        // (section-scoped write, Story #4324).
-        writeDispositions: true,
-      });
-    } catch (err) {
-      thrown = err;
-    }
-
-    const baseRead = thrown == null && result != null;
-
-    if (thrown != null) {
-      const reason = `reconcile-threw:${thrown?.message ?? thrown}`;
-      await this._emitFailure({ event, seqId, baseRead, reason });
-      return;
-    }
-
-    // Resolve the delivery shape before classifying: under single delivery a
-    // `waived` reconcile is non-waivable (design §2c). Best-effort — a probe
-    // failure degrades to `false` (fan-out pass-through), never inventing a
-    // block.
-    let single = false;
-    try {
-      single = await this.resolveSingleFn({
-        provider: this.provider,
-        epicId,
-        config: this.config,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] single-delivery probe failed (treating as fan-out): ${err?.message ?? err}`,
-      );
-    }
-
-    const classification = classifyReconcileResult(result, { single });
-    if (classification.outcome === 'ok') {
-      await this._emitOk({ event, seqId, baseRead });
-      return;
-    }
-    if (classification.outcome === 'waived') {
-      await this._emitWaived({
-        event,
-        seqId,
-        baseRead,
-        reason: classification.reason ?? 'waiver',
-      });
-      return;
-    }
-    if (classification.outcome === 'skipped') {
-      await this._emitSkipped({
-        event,
-        seqId,
-        baseRead,
-        reason: classification.reason ?? 'skipped',
-      });
-      return;
-    }
-    await this._emitFailure({
-      event,
-      seqId,
-      baseRead,
-      reason: classification.reason ?? 'gap',
-    });
-  }
-
-  /**
-   * Emit `acceptance.reconcile.ok` and record the classification.
-   * Helper carved out so each branch in `handle()` reads as a single
-   * decision.
-   */
-  async _emitOk({ event, seqId, baseRead }) {
-    this.classifications.push({ event, seqId, outcome: 'ok' });
-    try {
-      await this.bus.emit('acceptance.reconcile.ok', { baseRead });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] acceptance.reconcile.ok emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Emit `acceptance.reconcile.waived` for the `acceptance::n-a` path.
-   * Story #2893 split this out of `.skipped` so the Finalizer can
-   * subscribe to `.waived` and route waived Epics through to PR
-   * creation. The schema pins `reason` to `'waiver'`.
-   */
-  async _emitWaived({ event, seqId, baseRead, reason }) {
-    this.classifications.push({ event, seqId, outcome: 'waived', reason });
-    try {
-      await this.bus.emit('acceptance.reconcile.waived', {
-        baseRead,
-        reason,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] acceptance.reconcile.waived emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Emit `acceptance.reconcile.skipped` carrying a typed `reason`. The
-   * schema requires `reason` to be non-empty so callers always pass one
-   * (no silent skip).
-   */
-  async _emitSkipped({ event, seqId, baseRead, reason }) {
-    this.classifications.push({ event, seqId, outcome: 'skipped', reason });
-    try {
-      await this.bus.emit('acceptance.reconcile.skipped', {
-        baseRead,
-        reason,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] acceptance.reconcile.skipped emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Emit `acceptance.reconcile.failed` and then `epic.blocked`, in that
-   * order. The `epic.blocked` emit drives the LabelTransitioner /
-   * StructuredCommentPoster / NotifyDispatcher trio so the operator
-   * sees the blocker label flip + structured comment + webhook,
-   * exactly as a `story.blocked` cascade would.
-   *
-   * Failures inside the `epic.blocked` emit are swallowed (the
-   * `.failed` record is already on the ledger; double-throwing here
-   * would mask the original reason).
-   */
-  async _emitFailure({ event, seqId, baseRead, reason }) {
-    this.classifications.push({ event, seqId, outcome: 'failed', reason });
-    try {
-      await this.bus.emit('acceptance.reconcile.failed', {
-        baseRead,
-        reason,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] acceptance.reconcile.failed emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-    try {
-      await this.bus.emit('epic.blocked', {
-        reason: `acceptance-reconcile:${reason}`,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[AcceptanceReconciler] epic.blocked emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /** Test helper — wipe the idempotency cache. */
-  reset() {
-    this._seen.clear();
-    this.classifications = [];
-  }
-}