@bridge_gpt/mcp-server 0.2.10 → 0.2.12

package/build/conductor/epic-state.js

@@ -30,6 +30,12 @@ const NON_TERMINAL_STATUSES = new Set([
     "running",
     "blocked",
     "ready_for_review",
+    // BAPI-445: mid-flight pre-implementation spec re-review. Non-terminal so a
+    // review verdict / completion signal can still advance it on a later tick, but
+    // deliberately NOT a status computeReadySet returns for normal dispatch — a
+    // reviewing ticket is mid-flight, not ready. Stranded reviewing tickets are
+    // re-driven by reconcile's dedicated reviewing re-entry branch.
+    "reviewing",
 ]);
 const TERMINAL_SIGNAL_TYPES = new Set([
     "gate.met",
@@ -37,18 +43,42 @@ const TERMINAL_SIGNAL_TYPES = new Set([
     "ci.failed",
     "run.stopped",
     "review.changes_requested",
+    // BAPI-445: pre-implementation spec re-review verdicts, scoped to review runs.
+    "spec_review.passed",
+    "spec_review.changes_requested",
 ]);
 function isNonTerminal(status) {
     return NON_TERMINAL_STATUSES.has(status);
 }
-export function signalToNextStatus(signalType) {
+/**
+ * Map a terminal ledger signal to the next ticket status.
+ *
+ * `isReviewRun` marks signals correlated to a `:review`-suffixed dispatch
+ * (BAPI-445 Obstacle 2). The spec re-review verdicts fold explicitly:
+ *   - `spec_review.passed`            → `ready`   (verdict: proceed to implementation)
+ *   - `spec_review.changes_requested` → `blocked` (verdict: reject; reconcile escalates)
+ *
+ * FAIL-SAFE (BAPI-445): a review run's INCIDENTAL terminals (`run.stopped`,
+ * `gate.met`, …) are filtered out of folding entirely by `rebuildObservedState`
+ * BEFORE this function is called — a review session merely *ending* must never
+ * advance a `reviewing` ticket, or implementation would proceed regardless of
+ * the review's outcome (fail-open). So for a review run this is only ever called
+ * with a `spec_review.*` verdict; `isReviewRun` is retained for caller clarity.
+ * For implementation runs the BAPI-436 mapping is unchanged.
+ */
+export function signalToNextStatus(signalType, isReviewRun = false) {
+    void isReviewRun; // review-run incidental terminals are filtered before this call
+    if (signalType === "spec_review.passed")
+        return "ready";
+    if (signalType === "spec_review.changes_requested")
+        return "blocked";
     if (signalType === "ci.failed")
         return "blocked";
     if (signalType === "review.changes_requested")
         return "blocked";
     if (signalType === "merge.succeeded")
         return "done";
-    return "ready_for_review"; // gate.met and run.stopped: awaiting merge
+    return "ready_for_review"; // gate.met and (implementation) run.stopped: awaiting merge
 }
 // ---------------------------------------------------------------------------
 // computeReadySet
@@ -74,6 +104,13 @@ export function computeReadySet(plan, ticketStatuses) {
     }
     return ready;
 }
+/**
+ * Default ceiling for spec re-review dispatch attempts on a stranded `reviewing`
+ * ticket (BAPI-445). Counts the initial review dispatch plus liveness-recovery
+ * re-dispatches; once reached, the reviewing recovery branch escalates instead
+ * of re-dispatching. Deliberately independent of the BAPI-441 remediation budget.
+ */
+export const DEFAULT_MAX_SPEC_REVIEW_ATTEMPTS = 3;
 /**
  * Pure, deterministic remediation decision (no I/O, no clock). Given the current
  * budget counters, the ledger-derived worker liveness, and the configured
@@ -124,11 +161,20 @@ export function extractWorkerLiveness(events, runId, nowMs, windowSeconds) {
  */
 export function rebuildObservedState(postgresState, events, _now) {
     const { epic_run, ticket_statuses, dispatches } = postgresState;
-    // Build run_id → ticket_key lookup from dispatch records
+    // Build run_id → {ticket_key, isReview} lookup from dispatch records.
+    // BAPI-445 (Obstacle 2): a review run's dispatch_key carries a ":review"
+    // suffix, so the same run_id map can distinguish a pre-implementation
+    // spec-review run from the implementation run. This is correctness-critical:
+    // it lets the fold below route a review run's run.stopped to "ready" (review
+    // complete → proceed) instead of mis-folding it as implementation completion
+    // ("ready_for_review", awaiting merge), which would skip implementation.
     const runIdToTicketKey = new Map();
     for (const dispatch of dispatches) {
         if (dispatch.run_id) {
-            runIdToTicketKey.set(dispatch.run_id, dispatch.ticket_key);
+            runIdToTicketKey.set(dispatch.run_id, {
+                ticketKey: dispatch.ticket_key,
+                isReview: dispatch.dispatch_key.endsWith(":review"),
+            });
         }
     }
     // Populate base maps from Postgres
@@ -154,16 +200,36 @@ export function rebuildObservedState(postgresState, events, _now) {
     for (const event of events) {
         if (!TERMINAL_SIGNAL_TYPES.has(event.type))
             continue;
-        // Map event → ticket via run_id
+        // Map event → ticket via run_id, resolving the dispatch role (review vs.
+        // implementation) so the fold can treat review-run terminals distinctly.
         const runId = typeof event.run_id === "string" ? event.run_id : null;
-        const ticketKey = runId ? runIdToTicketKey.get(runId) : undefined;
-        if (!ticketKey)
+        const mapped = runId ? runIdToTicketKey.get(runId) : undefined;
+        if (!mapped)
+            continue;
+        const ticketKey = mapped.ticketKey;
+        const isReview = mapped.isReview;
+        // BAPI-445 FAIL-SAFE: a review run's INCIDENTAL terminals (run.stopped,
+        // gate.met, …) must never advance a `reviewing` ticket — ONLY an explicit
+        // spec_review.* verdict does. A review session merely ending must not fold
+        // reviewing → ready and dispatch implementation regardless of whether the
+        // review requested changes (that would be fail-OPEN). When the verdict is
+        // not (yet) emitted, the ticket stays in `reviewing` and the reconcile
+        // liveness-recovery / escalation path surfaces it for operator attention —
+        // implementation never silently proceeds without a pass verdict.
+        const isSpecVerdict = event.type === "spec_review.passed" ||
+            event.type === "spec_review.changes_requested";
+        if (isReview && !isSpecVerdict)
             continue;
         // Record the blocking reason (latest wins; events are seq-ordered) regardless
         // of fold state, so a ticket blocked on a prior tick still resolves a reason.
         if (event.type === "ci.failed" || event.type === "review.changes_requested") {
             ticketBlockedReasons.set(ticketKey, event.type);
         }
+        else if (event.type === "spec_review.changes_requested") {
+            // BAPI-445: spec-review rejection. Tagged distinctly so reconcile escalates
+            // it without spending the BAPI-441 implementation remediation budget.
+            ticketBlockedReasons.set(ticketKey, "spec_review.changes_requested");
+        }
         const postgresStatus = ticketStatusMap.get(ticketKey) ?? "planned";
         if (!isNonTerminal(postgresStatus))
             continue;
@@ -175,16 +241,24 @@ export function rebuildObservedState(postgresState, events, _now) {
             pendingMergeEvents.push(event);
         }
         const signalType = event.type;
-        const nextStatus = signalToNextStatus(signalType);
+        const nextStatus = signalToNextStatus(signalType, isReview);
         if (foldedTicketKeys.has(ticketKey)) {
-            // Allow a same-tick upgrade from ready_for_review → done when
-            // merge.succeeded arrives after gate.met in the same ledger batch.
+            // Allow a bounded same-tick upgrade of an already-folded ticket:
+            //   1. ready_for_review → done when merge.succeeded arrives after gate.met
+            //      in the same ledger batch.
+            //   2. (BAPI-445) <any review fold> → blocked when a review run's
+            //      spec_review.changes_requested arrives after its run.stopped in the
+            //      same batch. A spec-review rejection must dominate plain completion
+            //      so a changes-requested verdict is never lost to event ordering.
             // First-signal-wins for everything else: if ci.failed arrived first,
             // currentLocalStatus is "blocked" (not "ready_for_review"), so the
             // upgrade guard below is false and merge.succeeded is intentionally
             // dropped — a failed-CI ticket must not be silently advanced to done.
             const currentLocalStatus = ticketStatusMap.get(ticketKey);
-            if (currentLocalStatus === "ready_for_review" && nextStatus === "done") {
+            const mergeUpgrade = currentLocalStatus === "ready_for_review" && nextStatus === "done";
+            const specRejectUpgrade = signalType === "spec_review.changes_requested" &&
+                currentLocalStatus !== "blocked";
+            if (mergeUpgrade || specRejectUpgrade) {
                 const existingIdx = unfoldedSignals.findIndex((s) => s.ticket_key === ticketKey);
                 if (existingIdx >= 0) {
                     unfoldedSignals[existingIdx] = {

package/build/conductor/errors.js

@@ -64,6 +64,18 @@ function isSqliteBusyError(error) {
  *     the raw error text, stack, and any secret material are discarded.
  */
 export function toConductorErrorEnvelope(error) {
+    // Optional-native-binding degradation (BAPI-451): the conductor `store.ts`
+    // throws ConductorPersistenceUnavailableError when `better-sqlite3` could not be
+    // loaded. Detected by name (not instanceof) to avoid an import cycle with
+    // store.ts. Surfaced as a retryable-shaped 503 with a fixed, secret-free message
+    // so the caller learns persistence is unavailable instead of getting an opaque 500.
+    if (error instanceof Error && error.name === "ConductorPersistenceUnavailableError") {
+        return {
+            error: "PERSISTENCE_UNAVAILABLE",
+            status: 503,
+            message: "Conductor persistence is unavailable (the optional better-sqlite3 native module is not loaded). Conductor coordination features are disabled; core tools are unaffected.",
+        };
+    }
     if (error instanceof ConductorValidationError) {
         // Validation messages are conductor-authored and name the offending field,
         // never its value — but redact defensively so an adversarial/secret-bearing

package/build/conductor/git-ci-types.js

@@ -33,6 +33,16 @@ export const DEFAULT_GATE_NAME = "done";
 export const REVIEW_PASSED = "review.passed";
 /** Event type emitted when a reviewer requests changes. */
 export const REVIEW_CHANGES_REQUESTED = "review.changes_requested";
+/**
+ * BAPI-445 pre-implementation SPEC re-review verdict event types. Emitted by the
+ * spec re-review run (``/review-ticket --auto``), correlated to that review run,
+ * and kept distinct from the PR-review {@link REVIEW_PASSED} /
+ * {@link REVIEW_CHANGES_REQUESTED} verdicts so a spec-review outcome is never
+ * folded as the implementation PR's review state.
+ */
+export const SPEC_REVIEW_PASSED = "spec_review.passed";
+/** Event type emitted when a spec re-review requests changes. */
+export const SPEC_REVIEW_CHANGES_REQUESTED = "spec_review.changes_requested";
 /** Matches ASCII control characters (C0 range plus DEL). */
 const CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
 /** Matches a 40- or 64-character hex string (git SHA-1 / SHA-256 object ids). */

package/build/conductor/git-producer.js

@@ -79,7 +79,7 @@ export function buildWorktreeChangedEventInput(context, updates, phase) {
  * dedupe by `repo + commit_sha`, and emit best-effort. Returns a
  * success-compatible result for every failure mode so the commit is never blocked.
  */
-export function runPostCommitHookProducer(deps = {}) {
+export async function runPostCommitHookProducer(deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const readMetadata = deps.readMetadata ?? readHeadCommitMetadata;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -90,7 +90,7 @@ export function runPostCommitHookProducer(deps = {}) {
             return { ok: true, emitted: false, reason: "no-head-commit" };
         }
         const input = buildCommitCreatedEventInput(context, metadata);
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "git.commit_created",
             repo: context.repo,
             commit_sha: metadata.sha,
@@ -109,7 +109,7 @@ export function runPostCommitHookProducer(deps = {}) {
  * success-compatible result for every failure mode so the ref update is never
  * blocked.
  */
-export function runReferenceTransactionHookProducer(args, deps = {}) {
+export async function runReferenceTransactionHookProducer(args, deps = {}) {
     const getContext = deps.getContext ?? getGitWorktreeContext;
     const parseUpdates = deps.parseUpdates ?? parseReferenceTransactionUpdates;
     const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
@@ -124,7 +124,7 @@ export function runReferenceTransactionHookProducer(args, deps = {}) {
         const context = getContext({ cwd: deps.cwd, env: deps.env });
         const input = buildWorktreeChangedEventInput(context, updates, args.phase);
         const refUpdatesHash = stableJsonHash({ phase: args.phase, updates });
-        const decision = emitIfNew(input, {
+        const decision = await emitIfNew(input, {
             event_type: "worktree.changed",
             repo: context.repo,
             ref_updates_hash: refUpdatesHash,

package/build/conductor/merge-ledger.js

@@ -103,9 +103,9 @@ export function makeMergeEventId(eventType, actionKey) {
     const h = createHash("sha256").update(`${eventType}:${actionKey}`).digest("hex");
     return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
 }
-function lookupMergeEventByActionKey(eventType, actionKey, deps) {
+async function lookupMergeEventByActionKey(eventType, actionKey, deps) {
     const openDb = deps.openDb ?? (() => openReadonlyConductorDatabaseIfExists());
-    const db = openDb();
+    const db = await openDb();
     if (!db)
         return false;
     try {
@@ -126,7 +126,7 @@ function lookupMergeEventByActionKey(eventType, actionKey, deps) {
  * the action key. Only `merge.succeeded` is terminal — `merge.failed` and
  * `merge.dry_run` are never terminal.
  */
-export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
+export async function hasTerminalMergeSucceeded(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.succeeded", actionKey, deps);
 }
 /**
@@ -134,7 +134,7 @@ export function hasTerminalMergeSucceeded(actionKey, deps = {}) {
  * Dry-run is audit/hygiene only and is NEVER treated as terminal — a later real
  * merge for the same PR/head/gate may still proceed if the repo flag is enabled.
  */
-export function hasMergeDryRun(actionKey, deps = {}) {
+export async function hasMergeDryRun(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.dry_run", actionKey, deps);
 }
 /**
@@ -142,7 +142,7 @@ export function hasMergeDryRun(actionKey, deps = {}) {
  * action key. Pending approval is NEVER terminal — the supervisor must re-dispatch
  * until the backend reports approval (returning `merge.attempted` + `merge.succeeded`).
  */
-export function hasMergePendingApproval(actionKey, deps = {}) {
+export async function hasMergePendingApproval(actionKey, deps = {}) {
     return lookupMergeEventByActionKey("merge.pending_approval", actionKey, deps);
 }
 /** Heuristically detect a SQLite duplicate-id / UNIQUE constraint failure. */
@@ -167,7 +167,7 @@ function isDuplicateConstraintError(error) {
  * outcome fields live under `details`). A duplicate UNIQUE-constraint failure is
  * classified as `{ emitted: false, reason: "duplicate" }` rather than thrown.
  */
-export function emitMergeLedgerEventIfNew(input, deps = {}) {
+export async function emitMergeLedgerEventIfNew(input, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const eventId = makeMergeEventId(input.type, input.action_key);
     const event = {
@@ -186,7 +186,7 @@ export function emitMergeLedgerEventIfNew(input, deps = {}) {
         },
     };
     try {
-        const result = emitEvent(event);
+        const result = await emitEvent(event);
         return { emitted: true, event_id: eventId, event: result.event };
     }
     catch (error) {

package/build/conductor/pr-ci-producer.js

@@ -149,7 +149,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
         reason: "observed",
     };
     // 1. PR opened telemetry (independent of CI / gate).
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -174,7 +174,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     }
     else {
         result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-        const ciDecision = emitIfNew(ciEvent, {
+        const ciDecision = await emitIfNew(ciEvent, {
             event_type: ciEvent.type,
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -210,7 +210,7 @@ async function observeWithResolved(binding, access, gateConfig, deps) {
     result.gate_met = true;
     const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
     if (gateEvent !== null) {
-        const gateDecision = emitIfNew(gateEvent, {
+        const gateDecision = await emitIfNew(gateEvent, {
             event_type: "gate.met",
             repo: binding.repo,
             pr_number: binding.pr_number,
@@ -409,7 +409,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
         gate_emitted: false,
         reason: "observed",
     };
-    const prDecision = emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
+    const prDecision = await emitIfNew(buildPrOpenedEventInput(binding, run_id, worker_id), {
         event_type: "git.pr_opened",
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -423,7 +423,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
         return result;
     }
     result.ci_status = ciEvent.type === "ci.passed" ? "passed" : "failed";
-    const ciDecision = emitIfNew(ciEvent, {
+    const ciDecision = await emitIfNew(ciEvent, {
         event_type: ciEvent.type,
         repo: binding.repo,
         pr_number: binding.pr_number,
@@ -461,7 +461,7 @@ export async function observePrCiFromPollResponse(commitRef, pollResponse, deps
                     result.gate_met = true;
                     const gateEvent = buildGateMetEventInput(binding, evaluation, run_id, worker_id);
                     if (gateEvent !== null) {
-                        const gateDecision = emitIfNew(gateEvent, {
+                        const gateDecision = await emitIfNew(gateEvent, {
                             event_type: "gate.met",
                             repo: binding.repo,
                             pr_number: binding.pr_number,

package/build/conductor/pr-review-producer.js

@@ -99,13 +99,13 @@ export async function observeReviewWithResolved(binding, access, gateConfig, dep
     };
     if (evalResult.changesRequested) {
         const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_CHANGES_REQUESTED, evalResult.reason, run_id, worker_id);
-        const decision = emitIfNew(event, { event_type: REVIEW_CHANGES_REQUESTED, ...baseDimensions });
+        const decision = await emitIfNew(event, { event_type: REVIEW_CHANGES_REQUESTED, ...baseDimensions });
         result.review_changes_requested_emitted = decision.emitted;
         result.reason = "review changes requested";
     }
     else if (evalResult.passed) {
         const event = buildReviewObservationEventInput(binding, snapshot, REVIEW_PASSED, evalResult.reason, run_id, worker_id);
-        const decision = emitIfNew(event, { event_type: REVIEW_PASSED, ...baseDimensions });
+        const decision = await emitIfNew(event, { event_type: REVIEW_PASSED, ...baseDimensions });
         result.review_passed_emitted = decision.emitted;
         result.reason = "review passed";
     }

package/build/conductor/producer-ledger.js

@@ -59,13 +59,13 @@ const LEDGER_SCAN_MAX_PAGES = 200;
  * full details object is visible. Malformed/non-matching events are skipped; the
  * scan never throws.
  */
-export function eventAlreadyExists(dedupeKey, deps = {}) {
+export async function eventAlreadyExists(dedupeKey, deps = {}) {
     const pollEvents = deps.pollEvents ?? ((options) => pollConductorEvents(options));
     let sinceSeq = 1;
     for (let page = 0; page < LEDGER_SCAN_MAX_PAGES; page += 1) {
         let result;
         try {
-            result = pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
+            result = await pollEvents({ since_seq: sinceSeq, data_mode: "full", limit: LEDGER_SCAN_PAGE_LIMIT });
         }
         catch {
             return false;
@@ -95,10 +95,10 @@ export function eventAlreadyExists(dedupeKey, deps = {}) {
  * under `data.details`, then emits. A duplicate-id constraint thrown by a racing
  * producer is classified as a duplicate rather than surfaced as a failure.
  */
-export function emitConductorEventIfNew(input, dimensions, deps = {}) {
+export async function emitConductorEventIfNew(input, dimensions, deps = {}) {
     const emitEvent = deps.emitEvent ?? emitConductorEvent;
     const dedupeKey = makeProducerDedupeKey(dimensions);
-    if (eventAlreadyExists(dedupeKey, deps)) {
+    if (await eventAlreadyExists(dedupeKey, deps)) {
         return { emitted: false, reason: "duplicate" };
     }
     const eventId = makeStableProducerEventId(dedupeKey);
@@ -113,7 +113,7 @@ export function emitConductorEventIfNew(input, dimensions, deps = {}) {
         details: { ...existingDetails, dedupe_key: dedupeKey },
     };
     try {
-        emitEvent({ ...input, id: eventId, data });
+        await emitEvent({ ...input, id: eventId, data });
         return { emitted: true, event_id: eventId };
     }
     catch (error) {

package/build/conductor/spec-review-producer.js

@@ -0,0 +1,88 @@
+/**
+ * Pre-implementation SPEC re-review verdict production (BAPI-445 Phase 2).
+ *
+ * Emits the spec re-review verdict (`spec_review.passed` /
+ * `spec_review.changes_requested`) into the LOCAL conductor ledger, correlated
+ * to the spec-review run via `BAPI_CONDUCTOR_RUN_ID`. The Epic Supervisor's
+ * reconcile pass folds these signals: `passed` → `reviewing → ready` (proceed to
+ * implementation), `changes_requested` → `blocked` (escalate; do NOT implement).
+ *
+ * Why this is a LOCAL producer, not a backend webhook change: the conductor
+ * ledger is a per-worker SQLite file (`~/.config/bridge/events.db`). The
+ * Heroku-hosted Bridge API backend has no access to it. So — exactly like the
+ * PR-review producer ({@link ./pr-review-producer}) — the verdict is emitted by
+ * the LOCAL spec-review run, whose environment carries `BAPI_CONDUCTOR_RUN_ID`
+ * (injected at dispatch time by {@link ../review-tickets}.orchestrateReviewTickets
+ * when an epic identity is present). This corrects the original BAPI-445 plan,
+ * which proposed emitting from the backend review webhook
+ * (`code_writer_jira.py`) — that path cannot reach the worker-local ledger.
+ *
+ * The verdict family is kept DISTINCT from the PR-review `review.passed` /
+ * `review.changes_requested` verdicts (BAPI-440) so a spec-review outcome is
+ * never mis-folded as the implementation PR's review state (Obstacle 2).
+ */
+// TODO(BAPI-445 Phase 2 integration): `emitSpecReviewVerdict` is the verdict
+// EMISSION primitive but currently has no caller. Until the review-ticket
+// completion flow derives a pass/changes-requested decision from the critique
+// and calls this function, no `spec_review.*` event is ever written.
+//
+// This is FAIL-SAFE, not fail-open: epic-state.ts `rebuildObservedState` filters
+// a review run's incidental terminals (run.stopped, …) out of folding, so a
+// completed review with NO verdict leaves the ticket in `reviewing` rather than
+// advancing it to `ready` and dispatching implementation. The reconcile
+// liveness-recovery / escalation path then surfaces the stranded ticket for
+// operator attention. Only an explicit `spec_review.passed` proceeds and only
+// `spec_review.changes_requested` blocks — so wiring this producer in is what
+// makes the gate ACTIVE; without it, opted-in tickets hold safely instead of
+// silently implementing against the review's wishes.
+import { SPEC_REVIEW_CHANGES_REQUESTED, SPEC_REVIEW_PASSED } from "./git-ci-types.js";
+import { emitConductorEventIfNew } from "./producer-ledger.js";
+/** Producer + observed-via identifiers stamped onto emitted spec-review events. */
+export const SPEC_REVIEW_PRODUCER = "spec-review-producer";
+/**
+ * Build a `spec_review.passed` / `spec_review.changes_requested` event input for
+ * a ticket's spec re-review verdict, correlated to the review run via `runId`.
+ */
+export function buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, runId = null, workerId = null) {
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    return {
+        source: "review",
+        type: eventType,
+        subject: ticketKey,
+        run_id: runId,
+        worker_id: workerId,
+        producer: SPEC_REVIEW_PRODUCER,
+        observed_via: SPEC_REVIEW_PRODUCER,
+        data: {
+            summary: verdict === "passed"
+                ? `Spec re-review passed for ${ticketKey}`
+                : `Spec re-review requested changes for ${ticketKey}`,
+            status: verdict,
+            details: { ticket_key: ticketKey, reason },
+        },
+    };
+}
+/**
+ * Emit a spec re-review verdict for `ticketKey` into the local conductor ledger,
+ * correlated to the spec-review run via `BAPI_CONDUCTOR_RUN_ID` (read from the
+ * injected env). Idempotent: deduped by `event_type` + `run_id`, so re-emitting
+ * the same run's verdict is a no-op. A missing run id still emits (uncorrelated)
+ * but is logged in the result so callers can detect the misconfiguration.
+ */
+export async function emitSpecReviewVerdict(ticketKey, verdict, reason, deps = {}) {
+    const emitIfNew = deps.emitIfNew ?? emitConductorEventIfNew;
+    const run_id = deps.env?.BAPI_CONDUCTOR_RUN_ID?.trim() || null;
+    const worker_id = deps.env?.BAPI_CONDUCTOR_WORKER_ID?.trim() || null;
+    const eventType = verdict === "passed" ? SPEC_REVIEW_PASSED : SPEC_REVIEW_CHANGES_REQUESTED;
+    const event = buildSpecReviewVerdictEventInput(ticketKey, verdict, reason, run_id, worker_id);
+    const decision = await emitIfNew(event, {
+        event_type: eventType,
+        run_id: run_id ?? "",
+    });
+    return {
+        emitted: decision.emitted,
+        event_type: eventType,
+        run_id,
+        reason: run_id ? reason : `${reason} (warning: no BAPI_CONDUCTOR_RUN_ID — verdict uncorrelated)`,
+    };
+}