@bridge_gpt/mcp-server 0.2.9 → 0.2.12

package/build/conductor/epic-reconcile.js

@@ -1,6 +1,6 @@
 /**
  * Deterministic observed→desired reconciliation for the Epic Supervisor
- * (BAPI-408).
+ * (BAPI-408, BAPI-436).
  *
  * Executes five steps in order:
  *   1. Fold terminal signals into Postgres via CAS
@@ -9,10 +9,15 @@
  *   4. Action approved merges via C6 delegation
  *   5. Schedule post-action wait hooks
  *
+ * Dispatch is purely merge-gated (BAPI-436): dependents are dispatched only
+ * after their predecessor reaches "done", which requires a merge.succeeded
+ * signal. gate.met and run.stopped fold to the intermediate "ready_for_review"
+ * state — dependents do NOT dispatch on these signals.
+ *
  * All durable mutations go through injected seams so the logic is testable
  * without real network, ledger, or terminal access.
  */
-import { computeReadySet } from "./epic-state.js";
+import { computeReadySet, decideRemediation, DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS } from "./epic-state.js";
 import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
 // ---------------------------------------------------------------------------
 // reconcileEpic
@@ -21,7 +26,7 @@ import { extractMergeActionIdentityFromGateEvent } from "./merge-ledger.js";
  * Execute the deterministic observed→desired reconciliation pass. All I/O is
  * behind injected seams; the ready-set is computed by pure code (no LLM).
  */
-export async function reconcileEpic(access, observed, plan, deps) {
+export async function reconcileEpic(access, observed, plan, deps, supervisorConfig) {
     const result = {
         signals_folded: 0,
         dispatched: 0,
@@ -43,6 +48,22 @@ export async function reconcileEpic(access, observed, plan, deps) {
         if (casResult.ok) {
             result.signals_folded += 1;
             deps.log(`[epic-reconcile] folded ${signal.signal_type} for ${signal.ticket_key} → ${signal.next_status}`);
+            // BAPI-442: fire teardown + Jira transition strictly after merge.succeeded
+            // CAS → done. Both are fail-open: errors are logged and never abort the pass.
+            if (signal.signal_type === "merge.succeeded") {
+                if (supervisorConfig?.teardown_enabled && deps.teardownSeam) {
+                    await deps.teardownSeam(observed.epic_key, signal.ticket_key).catch((e) => {
+                        const safeMsg = e instanceof Error ? e.constructor.name : "teardown error";
+                        deps.log(`[epic-reconcile] teardown error for ${signal.ticket_key}: ${safeMsg}`);
+                    });
+                }
+                if (deps.jiraTransitionSeam) {
+                    await deps.jiraTransitionSeam(observed.epic_key, signal.ticket_key).catch((e) => {
+                        const safeMsg = e instanceof Error ? e.constructor.name : "jira error";
+                        deps.log(`[epic-reconcile] jira-transition error for ${signal.ticket_key}: ${safeMsg}`);
+                    });
+                }
+            }
         }
         else {
             // CAS conflict: another tick already advanced this ticket — non-fatal
@@ -61,8 +82,29 @@ export async function reconcileEpic(access, observed, plan, deps) {
     }
     // Step 2: Compute the ready-set (pure — never calls LLM)
     const readySet = computeReadySet(plan, observed.ticket_statuses);
-    // Step 3: Dispatch each ready ticket idempotently
+    // Step 3: Dispatch each ready ticket idempotently.
+    //
+    // BAPI-445 — pre-implementation spec re-review sequencing gate (Phase 1). When
+    // `auto_rereview_enabled` is on and the review seam is wired, a `planned` ready
+    // ticket must first pass a spec re-review: this loop advances it
+    // planned → reviewing, spawns the review run under a `:review` dispatch role,
+    // correlates its run_id, and STOPS — implementation does NOT dispatch in the
+    // same tick (honouring the product directive: "wait for review to complete
+    // before implementation begins"). The reviewing → ready (or → blocked) fold
+    // happens on a later tick once the review completes/votes; only THEN does this
+    // loop dispatch implementation. Gating only on `planned` (not `ready`) is
+    // deliberate: a `ready` ticket already passed review (reviewing → ready) or the
+    // flag is off, so re-gating it would loop forever.
     for (const ticketKey of readySet) {
+        const currentStatus = observed.ticket_statuses.get(ticketKey) ?? "planned";
+        if (supervisorConfig?.auto_rereview_enabled &&
+            deps.dispatchReviewSeam &&
+            currentStatus === "planned") {
+            await enterSpecReview(observed, deps, result, escalate, ticketKey);
+            // Either the review was dispatched, or a benign race/failure was logged;
+            // in every case implementation must NOT dispatch this tick.
+            continue;
+        }
         let claimResult;
         try {
             claimResult = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version);
@@ -118,6 +160,202 @@ export async function reconcileEpic(access, observed, plan, deps) {
             result.warnings.push(`correlate-failed for ${ticketKey}: ${safeMsg}`);
         }
     }
+    // Step 3.2: Reviewing recovery (BAPI-445 Phase 1 re-entry). computeReadySet
+    // never surfaces a `reviewing` ticket (it is mid-flight, not ready), so a
+    // ticket whose spec-review run died before completing would be stranded
+    // forever without this pass. Iterate `reviewing` tickets explicitly (mirroring
+    // how the remediation pass iterates `blocked` tickets): if the review run is
+    // dead and the dedicated review-attempt cap is not yet exhausted, reclaim an
+    // attempt-scoped `:review` dispatch key and re-dispatch the review; once the
+    // cap is exhausted, escalate. This uses its OWN attempt counter — it never
+    // touches the BAPI-441 remediation budget.
+    if (supervisorConfig?.auto_rereview_enabled &&
+        deps.dispatchReviewSeam &&
+        deps.readReviewWorkerLiveness) {
+        const dispatchReviewSeam = deps.dispatchReviewSeam;
+        const readReviewWorkerLiveness = deps.readReviewWorkerLiveness;
+        const maxReviewAttempts = supervisorConfig.max_spec_review_attempts ?? DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS;
+        for (const [ticketKey, status] of observed.ticket_statuses) {
+            if (status !== "reviewing")
+                continue;
+            try {
+                const liveness = await readReviewWorkerLiveness(observed.epic_key, ticketKey);
+                if (liveness.alive)
+                    continue; // review still running — wait across ticks
+                const priorAttempts = deps.countReviewAttempts
+                    ? deps.countReviewAttempts(ticketKey)
+                    : 0;
+                if (priorAttempts >= maxReviewAttempts) {
+                    await escalate(observed.epic_key, `spec-review-liveness-exhausted:${ticketKey}`);
+                    deps.log(`[epic-reconcile] spec-review liveness exhausted for ${ticketKey} ` +
+                        `(attempts=${priorAttempts} max=${maxReviewAttempts}) → escalate`);
+                    continue;
+                }
+                // Reclaim a fresh attempt-scoped review dispatch key. `priorAttempts`
+                // (>= 1 once the initial review dispatched) doubles as the next attempt
+                // index, so the key differs from every prior review run's key.
+                const attempt = priorAttempts;
+                let claim;
+                try {
+                    claim = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version, "review", attempt);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "claim error";
+                    result.warnings.push(`review-reclaim-error for ${ticketKey}: ${safeMsg}`);
+                    continue;
+                }
+                if (!claim.ok) {
+                    result.warnings.push(`review-dispatch-key lease-held for ${ticketKey}`);
+                    continue;
+                }
+                if (claim.kind !== "claimed") {
+                    if (claim.kind === "already-exists" && claim.dispatch.run_id === null) {
+                        result.warnings.push(`review-dispatch-orphan: ${ticketKey} has pending review dispatch key with no run_id`);
+                        await escalate(observed.epic_key, `dispatch-orphan:${ticketKey}`);
+                    }
+                    continue;
+                }
+                const dispatchKey = claim.dispatch.dispatch_key;
+                let runId;
+                try {
+                    runId = await dispatchReviewSeam(observed.epic_key, ticketKey, attempt);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "dispatch error";
+                    result.warnings.push(`review-redispatch-failed for ${ticketKey}: ${safeMsg}`);
+                    continue;
+                }
+                try {
+                    await deps.correlateRunId(dispatchKey, runId);
+                    deps.log(`[epic-reconcile] re-dispatched spec re-review for ${ticketKey} ` +
+                        `run_id=${runId} attempt=${attempt}`);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "correlate error";
+                    result.warnings.push(`review-correlate-failed for ${ticketKey}: ${safeMsg}`);
+                }
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.constructor.name : "reviewing recovery error";
+                result.warnings.push(`reviewing-recovery-error for ${ticketKey}: ${safeMsg}`);
+            }
+        }
+    }
+    // Step 3.4: Spec-review verdict gate (BAPI-445 Phase 2). A ticket blocked by a
+    // changes-requested SPEC review is a spec problem, not a code bug: escalate it
+    //
+    // NOTE: this block is reachable only once the verdict EMISSION primitive
+    // (`emitSpecReviewVerdict` in spec-review-producer.ts) is wired into the
+    // review-ticket completion flow so a `spec_review.changes_requested` event is
+    // folded to `blocked` with this reason. Until that Phase 2 integration lands,
+    // no ticket carries the `spec_review.changes_requested` blocked reason and this
+    // pass is a no-op. That is FAIL-SAFE: a completed review with no verdict does
+    // NOT advance `reviewing → ready` (epic-state filters review-run incidental
+    // terminals), so implementation never proceeds without an explicit pass —
+    // a stranded `reviewing` ticket is escalated by the recovery branch above.
+    // once for operator attention and EXCLUDE it from the BAPI-441 remediation pass
+    // below so it never spends the implementation remediation budget (no nudge, no
+    // redispatch, no budget counter increment). Runs independently of the
+    // remediation seams so a spec rejection is always surfaced.
+    const specRejectedTickets = new Set();
+    for (const [ticketKey, status] of observed.ticket_statuses) {
+        if (status !== "blocked")
+            continue;
+        if (observed.ticket_blocked_reasons?.get(ticketKey) !== "spec_review.changes_requested") {
+            continue;
+        }
+        specRejectedTickets.add(ticketKey);
+        await escalate(observed.epic_key, `spec-review-rejected:${ticketKey}`);
+        deps.log(`[epic-reconcile] spec-review changes-requested for ${ticketKey} → escalate ` +
+            `(remediation budget bypassed)`);
+    }
+    // Step 3.5: Remediation pass (BAPI-441) — re-act on blocked tickets under
+    // budget. Keyed off the folded "blocked" status + per-ticket counters, NOT a
+    // computeReadySet change (the ready-set still returns only planned tickets).
+    // Skipped entirely unless the remediation seams + supervisorConfig are wired.
+    const remediationWired = supervisorConfig !== undefined &&
+        deps.readWorkerLiveness !== undefined &&
+        deps.remediateCas !== undefined &&
+        deps.sendNudge !== undefined &&
+        deps.resumeDispatch !== undefined;
+    if (remediationWired) {
+        const cfg = supervisorConfig;
+        const readWorkerLiveness = deps.readWorkerLiveness;
+        const sendNudge = deps.sendNudge;
+        const resumeDispatch = deps.resumeDispatch;
+        const remediateCas = deps.remediateCas;
+        for (const [ticketKey, status] of observed.ticket_statuses) {
+            if (status !== "blocked")
+                continue;
+            // BAPI-445: a spec-review rejection was already escalated in Step 3.4 and
+            // must never enter the implementation remediation budget. Skip it here.
+            if (specRejectedTickets.has(ticketKey))
+                continue;
+            // Per-ticket try/catch so a single ticket's failure never aborts the pass.
+            try {
+                const counters = observed.ticket_remediation_counters?.get(ticketKey) ?? {
+                    attempts: 0,
+                    no_progress: 0,
+                };
+                const liveness = await readWorkerLiveness(observed.epic_key, ticketKey);
+                const decision = decideRemediation(counters.attempts, counters.no_progress, liveness.alive, cfg);
+                if (decision === "escalate") {
+                    await escalate(observed.epic_key, `remediation-budget-exhausted:${ticketKey}`);
+                    deps.log(`[epic-reconcile] remediation escalate ${ticketKey} ` +
+                        `(attempts=${counters.attempts} no_progress=${counters.no_progress})`);
+                    continue;
+                }
+                // The attempt being recorded is the next one (1-based).
+                const attempt = counters.attempts + 1;
+                const attemptKind = decision;
+                // The folding reason frames the nudge (message type + digest). Default to
+                // the review path when the ledger no longer carries the blocking event.
+                // spec_review.changes_requested is impossible here (skipped above) but
+                // narrow explicitly so the remediation seams keep their tight reason type.
+                const blockedReason = observed.ticket_blocked_reasons?.get(ticketKey);
+                const reason = blockedReason === "ci.failed" ? "ci.failed" : "review.changes_requested";
+                // A nudge needs a worker to address it to. The liveness scan already
+                // resolved the worker id from the same heartbeat that proved the worker
+                // alive; if it is missing we cannot relay, so skip BEFORE recording an
+                // attempt — otherwise the CAS would burn a budget unit with nothing sent.
+                if (decision === "nudge" && !liveness.workerId) {
+                    result.warnings.push(`remediation nudge skipped for ${ticketKey}: alive worker has no worker_id`);
+                    continue;
+                }
+                // Record the attempt durably FIRST. The remediate endpoint builds the
+                // (backend-redacted) review digest for a nudge and returns it, and is
+                // idempotent (a 409 replay returns conflict, not throw). An unexpected
+                // remediate failure is absorbed as a per-ticket warning so the rest of
+                // the pass still runs (crash-replay safe).
+                let casOutcome;
+                try {
+                    casOutcome = await remediateCas(observed.epic_key, ticketKey, attemptKind, reason);
+                }
+                catch (err) {
+                    const safeMsg = err instanceof Error ? err.constructor.name : "remediate error";
+                    result.warnings.push(`remediate-cas-failed for ${ticketKey} (${attemptKind}): ${safeMsg}`);
+                    continue;
+                }
+                if (casOutcome.conflict) {
+                    // Idempotency replay: the attempt was already recorded (and acted on)
+                    // on a prior tick. Do not re-act — the crash-replay self-heals here.
+                    result.warnings.push(`remediation replay swallowed for ${ticketKey} (${attemptKind})`);
+                    continue;
+                }
+                if (decision === "nudge") {
+                    await sendNudge(observed.epic_key, ticketKey, attempt, casOutcome.reviewDigest, casOutcome.truncated, reason, liveness.workerId);
+                }
+                else {
+                    await resumeDispatch(observed.epic_key, ticketKey, attempt);
+                }
+                deps.log(`[epic-reconcile] remediation ${decision} ${ticketKey} attempt=${attempt}`);
+            }
+            catch (err) {
+                const safeMsg = err instanceof Error ? err.constructor.name : "remediation error";
+                result.warnings.push(`remediation-error for ${ticketKey}: ${safeMsg}`);
+            }
+        }
+    }
     // Step 4: Action approved merges via C6 delegation
     for (const event of observed.pending_merge_events) {
         const identity = extractMergeActionIdentityFromGateEvent(event);
@@ -137,3 +375,79 @@ export async function reconcileEpic(access, observed, plan, deps) {
     // Step 5: Post-action waits are scheduled inline above per-dispatch
     return result;
 }
+// ---------------------------------------------------------------------------
+// enterSpecReview (BAPI-445 Phase 1 — planned → reviewing + spawn review run)
+// ---------------------------------------------------------------------------
+/**
+ * Advance a `planned` ready ticket into the pre-implementation spec re-review:
+ * CAS planned → reviewing, claim the `:review` dispatch key, spawn the review
+ * run, and correlate its run_id. Every failure is absorbed as a per-ticket
+ * warning so the rest of the reconcile pass still runs.
+ *
+ * Deliberately does NOT mutate the local `observed.ticket_statuses` map: the CAS
+ * is durable in Postgres (the NEXT tick's snapshot shows `reviewing`), and
+ * leaving the local status as `planned` keeps the same-tick reviewing-recovery
+ * pass from mistaking this freshly-spawned review for a stranded one and
+ * double-dispatching it.
+ */
+async function enterSpecReview(observed, deps, result, escalate, ticketKey) {
+    const dispatchReviewSeam = deps.dispatchReviewSeam;
+    if (!dispatchReviewSeam)
+        return; // caller-guarded; defensive
+    // CAS planned → reviewing (durable). Idempotency: if another tick already
+    // advanced the ticket, the CAS conflicts and we bail benignly.
+    const rowVersion = observed.ticket_row_versions.get(ticketKey) ?? 0;
+    let cas;
+    try {
+        cas = await deps.casTicketStatus(observed.epic_key, ticketKey, rowVersion, "reviewing", observed.plan_version);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "cas error";
+        result.warnings.push(`review-cas-error for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    if (!cas.ok) {
+        result.warnings.push(`review-cas-conflict advancing ${ticketKey} → reviewing`);
+        return;
+    }
+    // Claim the :review dispatch key (attempt 0), then spawn + correlate.
+    let claim;
+    try {
+        claim = await deps.claimDispatchKey(observed.epic_key, ticketKey, observed.plan_version, "review", 0);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "claim error";
+        result.warnings.push(`review-claim-error for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    if (!claim.ok) {
+        result.warnings.push(`review-dispatch-key lease-held for ${ticketKey}`);
+        return;
+    }
+    if (claim.kind !== "claimed") {
+        if (claim.kind === "already-exists" && claim.dispatch.run_id === null) {
+            result.warnings.push(`review-dispatch-orphan: ${ticketKey} has pending review dispatch key with no run_id`);
+            await escalate(observed.epic_key, `dispatch-orphan:${ticketKey}`);
+        }
+        return;
+    }
+    const dispatchKey = claim.dispatch.dispatch_key;
+    let runId;
+    try {
+        runId = await dispatchReviewSeam(observed.epic_key, ticketKey, 0);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "dispatch error";
+        result.warnings.push(`review-dispatch-failed for ${ticketKey}: ${safeMsg}`);
+        return;
+    }
+    try {
+        await deps.correlateRunId(dispatchKey, runId);
+        deps.log(`[epic-reconcile] dispatched spec re-review for ${ticketKey} ` +
+            `run_id=${runId} (planned → reviewing; implementation deferred)`);
+    }
+    catch (err) {
+        const safeMsg = err instanceof Error ? err.constructor.name : "correlate error";
+        result.warnings.push(`review-correlate-failed for ${ticketKey}: ${safeMsg}`);
+    }
+}