audit-tools 0.28.0

package/dist/audit/cli/nextStepHelpers.js

@@ -0,0 +1,861 @@
+/**
+ * Extracted helpers for the next-step command.
+ *
+ * Splitting these out of nextStepCommand.ts reduces that file to just the
+ * top-level cmdNextStep dispatcher, keeping each module focused on a single
+ * concern.
+ */
+import { unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { advance, isFileMissingError, readJsonFile, writeJsonFile, } from "audit-tools/shared";
+import { loadArtifactBundle, promoteFinalAuditReport, writeCoreArtifacts, AUDIT_REPORT_FILENAME, } from "../io/artifacts.js";
+import { advanceAudit } from "../orchestrator/advance.js";
+import { groundDesignFindings } from "../validation/designFindingGrounding.js";
+import { captureDesignReviewSnapshot, isDesignReviewStale, } from "../orchestrator/designReviewSnapshot.js";
+import { computeArtifactStateSignature } from "../orchestrator/artifactMetadata.js";
+import { decideNextStep, PRIORITY } from "../orchestrator/nextStep.js";
+import { isHostDelegationExecutor } from "../orchestrator/executors.js";
+import { deriveAuditState } from "../orchestrator/state.js";
+import { checkFileIntegrity } from "../orchestrator/fileIntegrity.js";
+import { collectLowConfidenceEdges, } from "../orchestrator/edgeReasoning.js";
+import { buildPathLookup } from "../extractors/graph.js";
+import { buildDispositionMap } from "../extractors/disposition.js";
+import { resolveAnalyzerPlan, needsInstallDecision, } from "../extractors/analyzers/registry.js";
+import { persistAnalyzerSettings, } from "../supervisor/sessionConfig.js";
+import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "../providers/constants.js";
+import { clearDispatchFiles } from "../io/runArtifacts.js";
+import { runAuditStep } from "./auditStep.js";
+import { writeHandoffOnly, ensureSemanticReviewRun, materializeReviewRun, } from "./reviewRun.js";
+import { buildPendingAuditTasks } from "./dispatch.js";
+import { driveRollingAuditDispatch, resolveAuditRollingEngineEnabled, resolvesToInProcessDispatchProvider, } from "./rollingAuditDispatch.js";
+// ── Incoming-artifact helper ──────────────────────────────────────────────────
+/**
+ * Read a JSON file from the `incoming/` subdirectory of `artifactsDir`.
+ * Returns `{ value, path }` when the file exists and parses successfully.
+ * Returns `undefined` when the file is absent (ENOENT-family errors).
+ * Re-throws all other IO errors unchanged.
+ */
+export async function tryConsumeIncoming(artifactsDir, filename) {
+    const filePath = join(artifactsDir, "incoming", filename);
+    try {
+        const value = await readJsonFile(filePath);
+        return { value, path: filePath };
+    }
+    catch (error) {
+        if (isFileMissingError(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Finalization thrashing tolerance (ARC-b8fed771 / the finalization-cycle guard).
+ * The deterministic fold may legitimately revisit a prior artifact state a bounded
+ * number of times (e.g. a runtime_validation <-> synthesis ping-pong, or
+ * filesystem-retry revision churn) before the canonical report is rendered; only
+ * outrunning distinct states by THIS many revisits is a non-converging cycle. Kept
+ * a single named constant — never inline the literal (HANDOFF approach-B mandate:
+ * no magic numbers).
+ */
+export const FINALIZATION_CYCLE_TOLERANCE = 16;
+// ── Extracted helpers ─────────────────────────────────────────────────────────
+/**
+ * Build the terminal step for a deterministic fold that has stopped advancing
+ * (no actionable obligation, or a cycle guard fired). A rendered report is the
+ * deliverable: if synthesis already produced one — or the state is formally
+ * complete — present it instead of reporting the stopped fold as a bare
+ * "blocked" failure. A completed audit must never surface as blocked just
+ * because finalization kept churning (e.g. a runtime_validation <-> synthesis
+ * ping-pong, or revision churn from filesystem retries) after the report was
+ * written. With no report yet, the stop is a genuine block.
+ */
+export async function buildTerminalStep(params, bundle, state, blockedReason) {
+    const reportRendered = state.status === "complete" || Boolean(bundle.audit_report);
+    await writeHandoffOnly({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        bundle,
+        audit_state: state,
+        progress_summary: reportRendered && state.status !== "complete"
+            ? `Audit report already rendered; ending run. ${blockedReason}`
+            : blockedReason,
+        providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+    });
+    if (!reportRendered) {
+        return { kind: "blocked", state, bundle, reason: blockedReason };
+    }
+    const promoted = await promoteFinalAuditReport({
+        artifactsDir: params.artifactsDir,
+    });
+    return {
+        kind: "complete",
+        state,
+        bundle,
+        finalReportPath: promoted.promoted
+            ? join(dirname(params.artifactsDir), AUDIT_REPORT_FILENAME)
+            : join(params.artifactsDir, AUDIT_REPORT_FILENAME),
+    };
+}
+/**
+ * Handle the `graph_enrichment_executor` incoming-artifact polling block.
+ * Checks for pending analyzer install decisions and edge-reasoning results.
+ * Returns an action object:
+ *   - `continue`    → caller should keep folding (already consumed an artifact).
+ *   - `return`      → caller should emit the embedded result to cmdNextStep.
+ *   - `fallthrough` → no incoming artifacts; run the deterministic executor.
+ */
+export async function handleGraphEnrichmentBranch(params, bundle, state, analyzersRef) {
+    const includedFiles = bundle.repo_manifest
+        ? [
+            ...new Set(buildPathLookup(bundle.repo_manifest, buildDispositionMap(bundle.file_disposition)).values()),
+        ]
+        : [];
+    const plan = resolveAnalyzerPlan(params.root, analyzersRef.value, includedFiles);
+    const unresolved = plan.filter(needsInstallDecision);
+    if (unresolved.length > 0) {
+        const incoming = await tryConsumeIncoming(params.artifactsDir, "analyzer-decisions.json");
+        if (incoming && incoming.value !== null && typeof incoming.value === "object") {
+            const settings = {};
+            for (const [id, value] of Object.entries(incoming.value)) {
+                if (value === "ephemeral" ||
+                    value === "permanent" ||
+                    value === "skip" ||
+                    value === "repo" ||
+                    value === "auto") {
+                    settings[id] = value;
+                }
+            }
+            if (Object.keys(settings).length > 0) {
+                const merged = await persistAnalyzerSettings(params.artifactsDir, settings);
+                analyzersRef.value = merged.analyzers;
+            }
+            else {
+                // All entries in analyzer-decisions.json failed the recognized-value
+                // check (ephemeral|permanent|skip|repo|auto). Emit a diagnostic so the
+                // operator knows why no settings were applied (COR-03418a9f fix).
+                const invalidEntries = Object.keys(incoming.value).join(", ") || "(none)";
+                process.stderr.write(`[audit-code] analyzer-decisions.json ignored: no recognized values (got: ${invalidEntries}). ` +
+                    `Valid values are: ephemeral, permanent, skip, repo, auto.\n`);
+            }
+            await unlink(incoming.path).catch(() => { });
+            return { action: "continue" };
+        }
+        return { action: "return", result: { kind: "analyzer_install", state, bundle, unresolved } };
+    }
+    // Phase 4B — optional edge-reasoning producing turn. Once analyzer installs
+    // are resolved, if the flag is on and the floor carries low-confidence
+    // (< 0.65) edges, emit one bounded host turn (subagent dispatch or a single
+    // host step) to produce reason rewrites, then re-run. The enrichment
+    // executor applies the host-supplied rewrites in the SAME advanceAudit call
+    // that merges analyzer edges and writes analyzer_capability, so graph_bundle
+    // and its marker stay revision-consistent (no staleness loop). Flag off or
+    // no candidates → fall through and run the executor with no rewrites.
+    if (params.graphLlmEdgeReasoning === true && bundle.graph_bundle) {
+        const candidates = collectLowConfidenceEdges(bundle.graph_bundle);
+        if (candidates.length > 0) {
+            const edgeReasoningIncoming = await tryConsumeIncoming(params.artifactsDir, "edge-reasoning.json");
+            if (edgeReasoningIncoming) {
+                await runAuditStep({
+                    root: params.root,
+                    artifactsDir: params.artifactsDir,
+                    analyzers: analyzersRef.value,
+                    graphLlmEdgeReasoning: true,
+                    edgeReasoningResultsPath: edgeReasoningIncoming.path,
+                    since: params.since,
+                });
+                await unlink(edgeReasoningIncoming.path).catch(() => { });
+                return { action: "continue" };
+            }
+            return { action: "return", result: { kind: "edge_reasoning", state, bundle, candidates } };
+        }
+    }
+    // No undecided installs (and no pending edge reasoning): fall through to run
+    // the executor below (it installs for ephemeral/permanent, uses repo/cache,
+    // skips the rest).
+    return { action: "fallthrough" };
+}
+/**
+ * Handle the `design_review_contract` or `design_review_conceptual` incoming-artifact
+ * polling blocks. Checks for contract and/or conceptual findings files independently.
+ *
+ * Returns:
+ *   - `continue`               → one or both incoming files were consumed; keep folding.
+ *   - `design_review_parallel` → both passes still needed; dispatch two subagents.
+ *   - `design_review_contract` → only contract pass still needed.
+ *   - `design_review_conceptual` → only conceptual pass still needed.
+ *
+ * Also handles legacy `design-review-findings.json` for backward compatibility.
+ */
+/** Whether a completed design-review pass has gone stale vs. its snapshot. */
+function passIsStale(bundle, pass) {
+    const snapshot = bundle.design_review_snapshots?.[pass];
+    return snapshot ? isDesignReviewStale(snapshot, bundle) : false;
+}
+export async function handleDesignReviewBranch(params, bundle, state) {
+    const existing = bundle.design_assessment;
+    // Legacy: consume old combined findings file. Always unlink when present to
+    // prevent accumulation, even when design_assessment is absent (COR-68f07c3e).
+    const legacyIncoming = await tryConsumeIncoming(params.artifactsDir, "design-review-findings.json");
+    if (legacyIncoming) {
+        await unlink(legacyIncoming.path).catch(() => { });
+        if (Array.isArray(legacyIncoming.value) && existing) {
+            existing.review_findings = groundDesignFindings(legacyIncoming.value, bundle.repo_manifest);
+            existing.reviewed = true;
+            await writeJsonFile(join(params.artifactsDir, "design_assessment.json"), existing);
+            return { action: "continue" };
+        }
+        // File consumed (deleted) but no target to merge into — keep folding.
+        return { action: "continue" };
+    }
+    // New: consume contract-findings and/or conceptual-findings independently.
+    const contractIncoming = await tryConsumeIncoming(params.artifactsDir, "design-review-contract-findings.json");
+    const conceptualIncoming = await tryConsumeIncoming(params.artifactsDir, "design-review-conceptual-findings.json");
+    let consumed = false;
+    // Always delete incoming files when present; only merge data when existing
+    // design_assessment is present (COR-68f07c3e).
+    if (contractIncoming) {
+        await unlink(contractIncoming.path).catch(() => { });
+        if (Array.isArray(contractIncoming.value) && existing) {
+            existing.contract_findings = groundDesignFindings(contractIncoming.value, bundle.repo_manifest);
+            existing.contract_reviewed = true;
+            consumed = true;
+        }
+    }
+    if (conceptualIncoming) {
+        await unlink(conceptualIncoming.path).catch(() => { });
+        if (Array.isArray(conceptualIncoming.value) && existing) {
+            existing.conceptual_findings = groundDesignFindings(conceptualIncoming.value, bundle.repo_manifest);
+            existing.conceptual_reviewed = true;
+            consumed = true;
+        }
+    }
+    if (consumed && existing) {
+        await writeJsonFile(join(params.artifactsDir, "design_assessment.json"), existing);
+        // Snapshot each just-completed pass (B2 parity port): record the verdict +
+        // the semantic projection of the structural inputs it reviewed, so a later
+        // upstream change re-stales the pass and the re-emit can be diff-scoped
+        // rather than a blind full re-run. Capture after the design_assessment write
+        // so the projection reflects the persisted findings.
+        const reviewedAt = new Date().toISOString();
+        if (contractIncoming) {
+            await captureDesignReviewSnapshot(params.artifactsDir, "contract", existing.contract_findings ?? [], bundle, reviewedAt);
+        }
+        if (conceptualIncoming) {
+            await captureDesignReviewSnapshot(params.artifactsDir, "conceptual", existing.conceptual_findings ?? [], bundle, reviewedAt);
+        }
+        return { action: "continue" };
+    }
+    // Determine which passes still need to run. A completed pass whose snapshot has
+    // gone stale (a structural input changed in projection) is NOT done — it must
+    // re-run as a diff-based re-review. This mirrors the obligation staleness in
+    // `designReviewPassState`.
+    const contractDone = existing?.contract_reviewed === true && !passIsStale(bundle, "contract");
+    const conceptualDone = existing?.conceptual_reviewed === true && !passIsStale(bundle, "conceptual");
+    if (!contractDone && !conceptualDone) {
+        return { action: "return", result: { kind: "design_review_parallel", state, bundle } };
+    }
+    if (!contractDone) {
+        return { action: "return", result: { kind: "design_review_contract", state, bundle } };
+    }
+    if (!conceptualDone) {
+        return { action: "return", result: { kind: "design_review_conceptual", state, bundle } };
+    }
+    // Both done — should not normally reach here (obligations would be satisfied).
+    return { action: "continue" };
+}
+/**
+ * Handle the `synthesis_narrative_executor` incoming-artifact polling block.
+ * Returns:
+ *   - `continue`  → an incoming narrative file was consumed + applied (progress
+ *     made); re-scan on the reloaded bundle.
+ *   - `return`    → a host turn is still needed (narrative enabled, none supplied
+ *     yet); emit the synthesis_narrative step.
+ *   - `run_omit`  → narrative disabled; run the deterministic omit executor (it
+ *     writes the `status:omitted` marker, satisfying synthesis_narrative_current).
+ *     This MUST make progress, never a no-op reload — otherwise the obligation
+ *     stays actionable and the fold spins (the guards do not cover this branch).
+ */
+export async function handleSynthesisNarrativeBranch(params, bundle, state) {
+    const narrativeIncoming = await tryConsumeIncoming(params.artifactsDir, "synthesis-narrative.json");
+    if (narrativeIncoming) {
+        await runAuditStep({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            preferredExecutor: "synthesis_narrative_executor",
+            narrativeResultsPath: narrativeIncoming.path,
+        });
+        await unlink(narrativeIncoming.path).catch(() => { });
+        return { action: "continue" };
+    }
+    if (params.narrativeEnabled) {
+        return { action: "return", result: { kind: "synthesis_narrative", state, bundle } };
+    }
+    // Narrative disabled: run the deterministic omit executor below.
+    return { action: "run_omit" };
+}
+/**
+ * Execute one deterministic audit step and record its progress. Throws (with
+ * cause) if the executor fails, preserving the existing throw-with-cause pattern.
+ * `index` is the 0-based fold position (the transition counter), surfaced as the
+ * 1-based `iteration` in the `deterministic-progress.json` marker a
+ * filesystem-watching host reads.
+ */
+export async function executeAndRecord(params, analyzers, decision, index, lastSummary) {
+    try {
+        // Write a "started" marker before execution so a host watching the filesystem
+        // can tell which executor is active during a long-running step (OBS-0d4c2311).
+        const startedAt = new Date().toISOString();
+        await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
+            iteration: index + 1,
+            executor: decision.selected_executor,
+            obligation: decision.selected_obligation,
+            status: "running",
+            started_at: startedAt,
+        });
+        const result = await runAuditStep({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            analyzers,
+            graphLlmEdgeReasoning: params.graphLlmEdgeReasoning,
+            since: params.since,
+        });
+        await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
+            iteration: index + 1,
+            last_executor: result.selected_executor,
+            last_obligation: decision.selected_obligation,
+            progress_made: result.progress_made,
+            summary: result.progress_summary,
+            status: "complete",
+            started_at: startedAt,
+            timestamp: new Date().toISOString(),
+        });
+        return result;
+    }
+    catch (error) {
+        const current = await loadArtifactBundle(params.artifactsDir);
+        const currentState = deriveAuditState(current);
+        currentState.last_executor = decision.selected_executor ?? undefined;
+        currentState.last_obligation = decision.selected_obligation ?? undefined;
+        await writeCoreArtifacts(params.artifactsDir, { ...current, audit_state: currentState });
+        await writeJsonFile(join(params.artifactsDir, "steps", "deterministic-progress.json"), {
+            iteration: index + 1,
+            last_executor: decision.selected_executor,
+            last_obligation: decision.selected_obligation,
+            prior_summary: lastSummary || null,
+            error: error instanceof Error ? error.message : String(error),
+            timestamp: new Date().toISOString(),
+        });
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Deterministic executor ${decision.selected_executor} failed on obligation ${decision.selected_obligation} (iteration ${index + 1}, prior progress: ${lastSummary || "none"}): ${detail}`, { cause: error instanceof Error ? error : undefined });
+    }
+}
+// ── Cycle guards (kept in audit's Ctx; NOT routed through advance) ─────────────
+//
+// HANDOFF approach-B: the shared `advance` engine is inherently 0-tolerance (it
+// signs `current` at the top of every loop and stops on the FIRST revisit), so it
+// cannot express the finalization-cycle tolerance window or the no-metadata-skip
+// the hand loop relied on. Approach A collapsed both guards into advance's
+// `stateSignature` and false-tripped on a fresh-Linux floor-only chain. So the two
+// guards stay HERE, invoked from inside the deterministic-executor obligation, and
+// `advance` runs with no `stateSignature` (its `maxTransitions` is the pure
+// runaway backstop only).
+/**
+ * Pre-dispatch no-progress guard (ARC-b8fed771).
+ *
+ * Runs BEFORE a deterministic executor is dispatched. If the fold is about to
+ * re-dispatch the SAME executor for the SAME obligation from an artifact-state
+ * signature it has ALREADY dispatched that exact (executor, obligation) pair
+ * from this run, the prior dispatch left the content-state unchanged (same
+ * signature) — so dispatching it again cannot make progress and would spin.
+ * Stop the fold with a terminal step instead of re-dispatching.
+ *
+ * The dispatch IDENTITY (signature + executor + obligation), not the signature
+ * alone, is the recurrence key. A recurring signature across DIFFERENT executors
+ * is legitimate: no-op-but-satisfying steps (auto-fix with nothing to fix,
+ * syntax-resolution with no errors) leave the artifact content unchanged while
+ * still advancing the obligation chain — those must NOT trip the guard. Only a
+ * literal re-entry of the same executor on the same unchanged state is the
+ * infinite loop this catches.
+ *
+ * This is the immediate-recurrence complement to `checkFinalizationCycle` (the
+ * post-dispatch tolerance-based thrash detector across many executors): this
+ * guard refuses to re-enter the SAME executor on a state it already failed to
+ * advance, rather than waiting for the tolerance window to fill. Returns a
+ * terminal-step result when the guard fires, or undefined to proceed.
+ *
+ * `dispatchedSignatures` is mutated: the current dispatch identity is recorded
+ * so a later iteration that returns to this exact (state, executor, obligation)
+ * trips the guard.
+ */
+export async function checkNoProgressBeforeDispatch(ctx) {
+    const signature = computeArtifactStateSignature(ctx.bundle);
+    const dispatchKey = `${signature}|${ctx.selectedExecutor ?? ""}|${ctx.selectedObligation ?? ""}`;
+    // "no-metadata" is the pre-artifact bootstrap state (no artifact_metadata yet
+    // — e.g. before the first executor stamps any metadata). Many early
+    // deterministic steps legitimately dispatch from it before metadata exists, so
+    // it is not a no-progress signal; only a real, metadata-bearing signature
+    // recurring for the SAME executor means an executor already ran here without
+    // changing content.
+    if (signature !== "no-metadata" && ctx.dispatchedSignatures.has(dispatchKey)) {
+        await writeJsonFile(join(ctx.params.artifactsDir, "steps", "deterministic-progress.json"), {
+            iteration: ctx.index + 1,
+            no_progress_detected: true,
+            repeated_obligation: ctx.selectedObligation ?? "unknown",
+            repeated_executor: ctx.selectedExecutor ?? "unknown",
+            summary: "Pre-dispatch no-progress guard: about to re-dispatch " +
+                `${ctx.selectedExecutor ?? "an executor"} for obligation ` +
+                `${ctx.selectedObligation ?? "unknown"} from an artifact state already ` +
+                "dispatched this run without net progress; stopping instead of looping.",
+            timestamp: new Date().toISOString(),
+        });
+        return buildTerminalStep(ctx.params, ctx.bundle, ctx.state, "No-progress guard: a deterministic executor was about to re-run on an " +
+            "artifact state it already processed this run without changing it " +
+            `(obligation ${ctx.selectedObligation ?? "unknown"}, executor ` +
+            `${ctx.selectedExecutor ?? "unknown"}). Stopping to avoid an infinite ` +
+            "no-progress loop.");
+    }
+    ctx.dispatchedSignatures.add(dispatchKey);
+    return undefined;
+}
+/**
+ * Check for a finalization cycle: when fold transitions outrun distinct artifact
+ * states by FINALIZATION_CYCLE_TOLERANCE, the deterministic executors are
+ * revisiting states rather than progressing. Returns a terminal-step result
+ * when a cycle is detected, or undefined when the run is still progressing.
+ */
+export async function checkFinalizationCycle(ctx) {
+    ctx.obligationTrail.push(ctx.selectedObligation ?? "unknown");
+    ctx.seenStateSignatures.add(computeArtifactStateSignature(ctx.result.updated_bundle));
+    if (ctx.index + 1 - ctx.seenStateSignatures.size < ctx.tolerance) {
+        return undefined;
+    }
+    const cycle = Array.from(new Set(ctx.obligationTrail.slice(-ctx.tolerance)));
+    await writeJsonFile(join(ctx.params.artifactsDir, "steps", "deterministic-progress.json"), {
+        iteration: ctx.index + 1,
+        cycle_detected: true,
+        cycling_obligations: cycle,
+        summary: "Finalization kept revisiting prior artifact states without net " +
+            `progress; stopping. Cycling obligations: ${cycle.join(" -> ")}.`,
+        timestamp: new Date().toISOString(),
+    });
+    return buildTerminalStep(ctx.params, ctx.result.updated_bundle, ctx.result.audit_state, "Finalization is not converging: deterministic executors kept revisiting " +
+        `prior artifact states (${cycle.join(" -> ")}). Review whether these ` +
+        "obligations are erroneously invalidating each other.");
+}
+/**
+ * A deterministic-executor `emit` of a blocked step — the `!progress_made`
+ * dead-end the hand loop returned directly from `executeAndRecord`.
+ */
+function blockedFromResult(result) {
+    return {
+        kind: "emit",
+        step: {
+            kind: "blocked",
+            state: result.audit_state,
+            bundle: result.updated_bundle,
+            reason: result.progress_summary,
+        },
+    };
+}
+/**
+ * Run one deterministic executor for the selected obligation, reproducing the
+ * hand loop's normal-path arm: the pre-dispatch no-progress guard, then
+ * record + dispatch, then the post-dispatch finalization-cycle guard. A guard
+ * that fires `emit`s its terminal step (so `advance` returns it); a
+ * `!progress_made` dead-end emits a blocked step; otherwise clear dispatch
+ * staging and `transition` on the reloaded bundle so the fold continues.
+ *
+ * The two guards stay HERE (not in `advance.opts.stateSignature`) so the
+ * no-metadata-skip and the FINALIZATION_CYCLE_TOLERANCE window are preserved —
+ * see the cycle-guard section comment.
+ */
+async function runDeterministicExecutor(bundle, ctx) {
+    const decision = decideNextStep(bundle);
+    const noProgress = await checkNoProgressBeforeDispatch({
+        index: ctx.iterationRef.value,
+        dispatchedSignatures: ctx.dispatchedSignatures,
+        params: ctx.params,
+        bundle,
+        state: decision.state,
+        selectedObligation: decision.selected_obligation,
+        selectedExecutor: decision.selected_executor,
+    });
+    if (noProgress !== undefined)
+        return { kind: "emit", step: noProgress };
+    const result = await executeAndRecord(ctx.params, ctx.analyzersRef.value, decision, ctx.iterationRef.value, ctx.lastSummaryRef.value);
+    ctx.lastSummaryRef.value = result.progress_summary;
+    if (!isHostDelegationExecutor(result.selected_executor ?? "")) {
+        await clearDispatchFiles(ctx.params.artifactsDir);
+    }
+    if (!result.progress_made) {
+        return blockedFromResult(result);
+    }
+    const cycle = await checkFinalizationCycle({
+        index: ctx.iterationRef.value,
+        obligationTrail: ctx.obligationTrail,
+        seenStateSignatures: ctx.seenStateSignatures,
+        tolerance: FINALIZATION_CYCLE_TOLERANCE,
+        params: ctx.params,
+        bundle,
+        state: decision.state,
+        result,
+        selectedObligation: decision.selected_obligation,
+    });
+    if (cycle !== undefined)
+        return { kind: "emit", step: cycle };
+    return { kind: "transition", state: await loadArtifactBundle(ctx.params.artifactsDir) };
+}
+/**
+ * `derive` for an audit obligation: look up its precomputed satisfaction state
+ * from `deriveAuditState` — the holistic content-hash staleness pass that
+ * computes EVERY obligation's state in one scan (`state.ts`). A pruned/absent
+ * obligation is satisfied. `decideNextStep`'s persisted-`complete` short-circuit
+ * yields an all-satisfied scan (no actionable obligation), which `advance`
+ * surfaces as `step === null` → the post-fold terminal.
+ */
+function deriveObligationState(id) {
+    return (bundle) => {
+        if (bundle.audit_state?.status === "complete")
+            return "satisfied";
+        const state = deriveAuditState(bundle);
+        const found = state.obligations.find((o) => o.id === id);
+        if (!found)
+            return "satisfied";
+        return found.state === "missing" || found.state === "stale"
+            ? found.state
+            : "satisfied";
+    };
+}
+/**
+ * Build the audit obligation definitions in `PRIORITY` order. Each `execute`
+ * relocates the corresponding arm of the hand-rolled `for` loop:
+ * deterministic executors `transition` (fold), host-delegation / dispatch /
+ * terminal points `emit` the host-actionable step. Selection stays single-sourced
+ * (`deriveObligationState` reads `deriveAuditState`, and `decideNextStep` resolves
+ * the executor for the selected id), so the obligation list cannot drift from the
+ * priority scan it mirrors.
+ */
+function buildAuditObligations() {
+    const deterministic = (id) => ({
+        id,
+        derive: deriveObligationState(id),
+        execute: (bundle, ctx) => runDeterministicExecutor(bundle, ctx),
+    });
+    return [
+        // Provider confirmation gate: a session-level deterministic auto-complete
+        // (writes a default provider_confirmation.json) — folds on like any other
+        // deterministic executor.
+        deterministic("provider_confirmation"),
+        deterministic("repo_manifest"),
+        deterministic("file_disposition"),
+        deterministic("auto_fixes_applied"),
+        deterministic("syntax_resolved"),
+        deterministic("structure_artifacts"),
+        {
+            // Graph enrichment: poll the analyzer-decision / edge-reasoning incoming
+            // artifacts first (emit a host step when one is needed), otherwise run the
+            // deterministic enrichment executor.
+            id: "graph_enrichment_current",
+            derive: deriveObligationState("graph_enrichment_current"),
+            execute: async (bundle, ctx) => {
+                const state = deriveAuditState(bundle);
+                const branch = await handleGraphEnrichmentBranch(ctx.params, bundle, state, ctx.analyzersRef);
+                if (branch.action === "return") {
+                    return { kind: "emit", step: branch.result };
+                }
+                if (branch.action === "continue") {
+                    // A decisions/edge file was consumed (and possibly applied): re-scan on
+                    // the reloaded bundle without running the executor this turn.
+                    return { kind: "transition", state: await loadArtifactBundle(ctx.params.artifactsDir) };
+                }
+                // fallthrough: run the deterministic enrichment executor.
+                return runDeterministicExecutor(bundle, ctx);
+            },
+        },
+        deterministic("design_assessment_current"),
+        {
+            // Confirm-intent host step: the host writes intent_checkpoint.json (read by
+            // deriveAuditState on re-invocation), so there is no incoming artifact to
+            // consume — emit the step directly.
+            id: "intent_checkpoint_current",
+            derive: deriveObligationState("intent_checkpoint_current"),
+            execute: async (bundle) => ({
+                kind: "emit",
+                step: { kind: "confirm_intent", state: deriveAuditState(bundle), bundle },
+            }),
+        },
+        {
+            // Contract design-review pass: poll incoming contract/conceptual findings;
+            // emit the dispatch step when a pass still needs to run.
+            id: "design_review_contract_completed",
+            derive: deriveObligationState("design_review_contract_completed"),
+            execute: (bundle, ctx) => runDesignReviewObligation(bundle, ctx),
+        },
+        {
+            // Conceptual design-review pass: same incoming-poll handler (it resolves
+            // which pass remains).
+            id: "design_review_conceptual_completed",
+            derive: deriveObligationState("design_review_conceptual_completed"),
+            execute: (bundle, ctx) => runDesignReviewObligation(bundle, ctx),
+        },
+        deterministic("planning_artifacts"),
+        {
+            // The audit-task dispatch obligation maps to the host-delegation
+            // rolling_dispatch_executor (no deterministic runner) → semantic review.
+            id: "audit_tasks_completed",
+            derive: deriveObligationState("audit_tasks_completed"),
+            execute: (bundle, ctx) => runHostDelegationObligation(bundle, ctx),
+        },
+        deterministic("audit_results_ingested"),
+        deterministic("runtime_validation_current"),
+        deterministic("synthesis_current"),
+        {
+            // Synthesis narrative: poll the incoming narrative; emit the host step when
+            // narrative is enabled and not yet supplied, otherwise the deterministic
+            // omit runs (fold on).
+            id: "synthesis_narrative_current",
+            derive: deriveObligationState("synthesis_narrative_current"),
+            execute: async (bundle, ctx) => {
+                const state = deriveAuditState(bundle);
+                const branch = await handleSynthesisNarrativeBranch(ctx.params, bundle, state);
+                if (branch.action === "return") {
+                    return { kind: "emit", step: branch.result };
+                }
+                if (branch.action === "run_omit") {
+                    // Narrative disabled: run the deterministic omit executor so the
+                    // status:omitted marker is written and the obligation is satisfied.
+                    // (A bare reload here would leave it actionable and spin the fold.)
+                    return runDeterministicExecutor(bundle, ctx);
+                }
+                // continue: an incoming narrative was consumed + applied — re-scan.
+                return { kind: "transition", state: await loadArtifactBundle(ctx.params.artifactsDir) };
+            },
+        },
+    ];
+}
+/** Shared design-review-pass executor (both pass obligations route here). */
+async function runDesignReviewObligation(bundle, ctx) {
+    const state = deriveAuditState(bundle);
+    const branch = await handleDesignReviewBranch(ctx.params, bundle, state);
+    if (branch.action === "return") {
+        return { kind: "emit", step: branch.result };
+    }
+    return { kind: "transition", state: await loadArtifactBundle(ctx.params.artifactsDir) };
+}
+/**
+ * Host-delegation dispatch obligation (`audit_tasks_completed` →
+ * rolling_dispatch_executor, no deterministic runner): materialize the semantic
+ * review run and emit it. Guards on the executor actually being host-delegation,
+ * mirroring the hand loop's `isHostDelegationExecutor` branch; a missing/non-
+ * delegation executor emits the same blocked step the no-executor branch did.
+ */
+async function runHostDelegationObligation(bundle, ctx) {
+    const decision = decideNextStep(bundle);
+    const state = decision.state;
+    if (!decision.selected_executor) {
+        return emitNoExecutorBlocked(bundle, ctx, decision);
+    }
+    if (!isHostDelegationExecutor(decision.selected_executor)) {
+        // Not host-delegation and no deterministic graph_enrichment/design-review
+        // handler claimed it: fall back to the deterministic executor path (which
+        // emits blocked when the runner is absent / makes no progress).
+        return runDeterministicExecutor(bundle, ctx);
+    }
+    // A8(a) in-process provider driver: when the rolling engine is enabled AND the
+    // operator EXPLICITLY configured a programmatic backend provider
+    // (openai-compatible / codex / opencode), the orchestrator drives the WHOLE
+    // semantic-review dispatch ITSELF — the provider is the per-packet worker —
+    // instead of emitting a host-subagent dispatch step. It `transition`s once the
+    // results are ingested so the fold re-derives state (the obligation-engine analog
+    // of the hand loop's `continue`), mirroring remediate's decideNextStep transition
+    // after driveRollingImplementDispatch.
+    const sessionConfig = ctx.params.sessionConfig;
+    if (resolveAuditRollingEngineEnabled({ sessionConfig }) &&
+        resolvesToInProcessDispatchProvider(sessionConfig)) {
+        const { activeReviewRun } = await materializeReviewRun({
+            root: ctx.params.root,
+            artifactsDir: ctx.params.artifactsDir,
+            bundle,
+            obligationId: decision.selected_obligation,
+            selfCliPath: ctx.params.selfCliPath,
+            timeoutMs: ctx.params.timeoutMs,
+        });
+        const driven = await driveRollingAuditDispatch({
+            root: ctx.params.root,
+            artifactsDir: ctx.params.artifactsDir,
+            activeReviewRun,
+            sessionConfig: sessionConfig,
+            timeoutMs: ctx.params.timeoutMs,
+        });
+        await clearDispatchFiles(ctx.params.artifactsDir);
+        // Convergence guard: a pass that ingested NO new results and stranded nothing
+        // (every packet errored at the provider) made no net progress, and
+        // re-dispatching the same unchanged state would loop to the maxTransitions
+        // backstop. Emit the block rather than spin. Progress (ingest ran, or a strand
+        // terminal was recorded) `transition`s so the fold re-derives normally.
+        if (!driven.ingest && driven.stranded_ids.length === 0) {
+            return {
+                kind: "emit",
+                step: {
+                    kind: "blocked",
+                    state,
+                    bundle,
+                    reason: `In-process rolling dispatch produced no results for ${driven.packet_count} ` +
+                        `review packet(s) (provider '${sessionConfig?.provider}' errored on every packet); ` +
+                        "stopping to avoid a no-progress loop.",
+                },
+            };
+        }
+        return {
+            kind: "transition",
+            state: await loadArtifactBundle(ctx.params.artifactsDir),
+        };
+    }
+    const review = await ensureSemanticReviewRun({
+        root: ctx.params.root,
+        artifactsDir: ctx.params.artifactsDir,
+        bundle,
+        state,
+        obligationId: decision.selected_obligation,
+        selfCliPath: ctx.params.selfCliPath,
+        timeoutMs: ctx.params.timeoutMs,
+    });
+    return {
+        kind: "emit",
+        step: {
+            kind: "semantic_review",
+            selectedExecutor: decision.selected_executor,
+            ...review,
+        },
+    };
+}
+/** Emit the no-executor blocked step (the hand loop's `!selected_executor` arm). */
+async function emitNoExecutorBlocked(bundle, ctx, decision) {
+    const state = decision.state;
+    const reason = ctx.lastSummaryRef.value || decision.reason;
+    await writeHandoffOnly({
+        root: ctx.params.root,
+        artifactsDir: ctx.params.artifactsDir,
+        bundle,
+        audit_state: state,
+        progress_summary: reason,
+        providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+    });
+    return { kind: "emit", step: { kind: "blocked", state, bundle, reason } };
+}
+/**
+ * Wrap each obligation so the transition counter advances exactly once per fold
+ * iteration — the analog of the hand loop's `index++`. Incrementing AFTER a
+ * `transition` (and never on an `emit`, which exits the fold) means during any
+ * `execute` the counter holds the current iteration's 0-based index, which the
+ * two cycle guards read as `index`. Single point of truth so a new obligation
+ * cannot forget to count.
+ */
+function countTransitions(obligations) {
+    return obligations.map((obligation) => ({
+        ...obligation,
+        execute: async (bundle, ctx) => {
+            const outcome = await obligation.execute(bundle, ctx);
+            if (outcome.kind === "transition")
+                ctx.iterationRef.value += 1;
+            return outcome;
+        },
+    }));
+}
+// ── Coordinator ───────────────────────────────────────────────────────────────
+/**
+ * Drive the deterministic fold for one `next-step` call.
+ *
+ * Structure mirrors remediate-code's `decideNextStepLoop` (the proven engine
+ * consumer): a PREAMBLE (the `index===0` file-integrity re-intake, the analog of
+ * remediate's `forceReplan`) then the shared `advance` running audit's `PRIORITY`
+ * obligations. Each deterministic executor `transition`s (folding the whole chain
+ * into one host round-trip); host-delegation / dispatch / terminal obligations
+ * `emit` the host-actionable step.
+ *
+ * Cycle detection stays in audit's `Ctx` (the pre-dispatch no-progress guard +
+ * the FINALIZATION_CYCLE_TOLERANCE finalization-cycle guard, both invoked from
+ * inside `runDeterministicExecutor`), NOT in `advance.opts.stateSignature` — the
+ * shared engine is inherently 0-tolerance and cannot express the tolerance window
+ * or the no-metadata-skip (HANDOFF approach B). `advance`'s `maxTransitions` is
+ * left as its pure runaway backstop. A `step === null` result (no actionable
+ * obligation, e.g. synthesis flipped the state to complete) resolves to the
+ * terminal step (present_report when a report is rendered, else blocked).
+ */
+export async function runDeterministicForNextStep(params) {
+    const analyzersRef = {
+        value: params.analyzers,
+    };
+    // PREAMBLE — file-integrity re-intake (runs once, like remediate's
+    // forceReplan). When pending audit-task files have changed/vanished since the
+    // manifest was built, re-run intake so planning re-grounds. advanceAudit does
+    // not persist (only runAuditStep does), so this is the same diagnostic-then-
+    // reload the hand loop performed on its first iteration: the warning fires and
+    // the fold below starts from the freshly-loaded disk bundle.
+    {
+        const bundle = await loadArtifactBundle(params.artifactsDir);
+        if (bundle.audit_state?.status !== "complete" && bundle.repo_manifest) {
+            const pendingTasks = buildPendingAuditTasks(bundle);
+            const taskFiles = new Set();
+            for (const task of pendingTasks) {
+                for (const fp of Object.keys(task.file_line_counts ?? {}))
+                    taskFiles.add(fp);
+            }
+            if (taskFiles.size > 0) {
+                const integrity = await checkFileIntegrity(params.root, bundle.repo_manifest, [...taskFiles]);
+                if (!integrity.is_clean) {
+                    // Route this diagnostic OFF stdout: cmdNextStep emits the step
+                    // contract as the sole stdout payload via console.log(JSON.stringify),
+                    // so a console.log here would corrupt the JSON-on-stdout contract.
+                    process.stderr.write(`[audit-code] nextStep: integrity check — ${integrity.changed_files.length} changed, ` +
+                        `${integrity.missing_files.length} missing, ${integrity.io_errors.length} io-error(s); re-running intake.\n`);
+                    await advanceAudit(bundle, { root: params.root, preferredExecutor: "intake_executor" });
+                }
+            }
+        }
+    }
+    const ctx = {
+        params,
+        analyzersRef,
+        lastSummaryRef: { value: "" },
+        iterationRef: { value: 0 },
+        dispatchedSignatures: new Set(),
+        seenStateSignatures: new Set(),
+        obligationTrail: [],
+    };
+    const startBundle = await loadArtifactBundle(params.artifactsDir);
+    const outcome = await advance({ priority: PRIORITY, obligations: countTransitions(buildAuditObligations()) }, startBundle, ctx);
+    if (outcome.step)
+        return outcome.step;
+    // No actionable obligation: the fold reached completion (e.g. synthesis flipped
+    // the state to complete and every obligation is now satisfied). Build the
+    // terminal: present_report when the state is complete / a report is rendered,
+    // else blocked.
+    const bundle = await loadArtifactBundle(params.artifactsDir);
+    const decision = decideNextStep(bundle);
+    const state = decision.state;
+    if (state.status === "complete") {
+        await writeHandoffOnly({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            bundle,
+            audit_state: state,
+            progress_summary: decision.reason,
+            providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+        });
+        const promoted = await promoteFinalAuditReport({
+            artifactsDir: params.artifactsDir,
+        });
+        return {
+            kind: "complete",
+            state,
+            bundle,
+            // Promotion copies the report to the artifacts dir's PARENT
+            // (.audit-tools/audit-report.md), not the repo root.
+            finalReportPath: promoted.promoted
+                ? join(dirname(params.artifactsDir), AUDIT_REPORT_FILENAME)
+                : join(params.artifactsDir, AUDIT_REPORT_FILENAME),
+        };
+    }
+    return buildTerminalStep(params, bundle, state, ctx.lastSummaryRef.value || decision.reason);
+}
+//# sourceMappingURL=nextStepHelpers.js.map