audit-tools 0.50.10 → 0.50.12

package/dist/remediate/steps/nextStep.js

@@ -15,19 +15,19 @@ import { runTriagePhase } from "../phases/triage.js";
 import { runClosePhase } from "../phases/close.js";
 import { validateRemediationPlan } from "../validation/remediationState.js";
 import { readExtractedPlanIfPresent, } from "./dispatch.js";
-import { ingestRemediationHostResults, hostDependencyLevels, precomputeRecoveryTestVerdicts, prepareRemediationHostHandoff, } from "./dispatch/hostHandoff.js";
+import { ingestRemediationHostResults, hostDependencyLevels, permanentlyDeadPendingBlocks, precomputeRecoveryTestVerdicts, prepareRemediationHostHandoff, } from "./dispatch/hostHandoff.js";
 import { FileLockTimeoutError, withFileLock, } from "../../shared/io/fileLock.js";
 import { AUDIT_FINDINGS_FILENAME, AUDIT_REPORT_FILENAME, auditArtifactsDir, auditFindingsPath, auditReportPath, promotedAuditFindingsPath, promotedAuditReportPath, remediationArtifactsDir, } from "../../shared/io/auditToolsPaths.js";
 import { callerWorkingDirectory, discoverRepoRoot, resolveRepoRoot, } from "../../shared/io/repoRoot.js";
 import { writeCurrentStep } from "./stepWriter.js";
-import { dependencyAwaitingClarification, dependencyVerifiedComplete, } from "./stepUtils.js";
 import { isTerminalStatus, isVerifiedCompleteStatus, } from "../state/itemStatus.js";
 import { deduplicateCrossLensFindings, fixupBlocksAfterDedup, } from "../dedup/crossLensDedup.js";
 import { checkAffectedFileIntegrity } from "../utils/fileIntegrity.js";
 import { applyIntentOrdering } from "../intent/intentOrdering.js";
 import { resolveIntakeStep } from "./intakeResolver.js";
 import { runToolOwnedFinalGate, writeFinalGateRedRecord, writeFinalGateOutcomeRecord, } from "./finalGate.js";
-import { buildNextContractPipelineStep, shouldEnterContractPipeline, writePathASeedFromFindings, } from "./contractPipeline.js";
+import { buildNextContractPipelineStep, shouldEnterContractPipeline, writePathASeedFromFindings, normalizeBlockTouchedFiles, checkWriteScopePathsAgainstTrackedTree, } from "./contractPipeline.js";
+import { compareCodeUnits } from "../../shared/compareCodeUnits.js";
 import { contractArtifactExists, contractPipelineDir, } from "../contractPipeline/artifactStore.js";
 import { buildReviewRequest, applyReviewResolution, isResolutionForRequest, screenResolutionIds, REVIEW_REQUEST_SCHEMA_VERSION, } from "../review/reviewGate.js";
 import { buildAutonomousReviewDecision } from "../review/autonomousGate.js";
@@ -219,7 +219,7 @@ function suppliedInputMatchesRun(inputResolution, manifest) {
             return false;
     return true;
 }
-export { dependencyVerifiedComplete, classifyFindingRisk, } from "./stepUtils.js";
+export { classifyFindingRisk } from "./stepUtils.js";
 export { isTerminalStatus, isVerifiedCompleteStatus };
 export { hostDependencyLevels };
 function documentableFindings(state) {
@@ -228,41 +228,50 @@ function documentableFindings(state) {
     return state.plan.findings.filter((finding) => state.items?.[finding.id]?.status === "pending");
 }
 /**
- * Blocks eligible for the next host handoff: those with pending
- * work AND every dependency VERIFIED-COMPLETE (INV-RS-01 — a SKIP or blocked
- * dependency never makes a dependent eligible). This dependency-frontier gate
- * replaced the old `dependenciesSatisfied` (any-terminal) check so a block whose
- * prerequisite was skipped/blocked is held back until its required surface lands.
+ * The dispatch frontier: the level-0 draw of the SAME dependency/phase
+ * partition the host workload builder emits from ({@link hostDependencyLevels}).
+ * The guard and the builder reading ONE computation is what keeps the
+ * "Cannot prepare an empty remediation host workload" throw unreachable from
+ * the scheduler: whenever this is non-empty, the builder derives the identical
+ * non-empty set (the 2026-08-23 empty-frontier incident — the retired
+ * edge-only predicate ignored the phase barrier and dependency existence, so
+ * the guard dispatched frontiers the builder refused, and next-step died
+ * instead of pausing).
  */
-function implementableBlocks(state) {
-    if (!state.plan || !state.items)
-        return [];
-    return state.plan.blocks.filter((block) => dependencyVerifiedComplete(block, state) &&
-        block.items.some((findingId) => {
-            const item = state.items?.[findingId];
-            return item?.status === "pending";
-        }));
+function dispatchFrontier(state) {
+    return hostDependencyLevels(state)[0] ?? [];
 }
 /**
- * Pending nodes that are genuinely DEAD-ENDED: at least one dependency did not
- * reach a verified-complete disposition and never will (a prerequisite was
- * skipped or blocked, or the edges are cyclic). Once no eligible block remains,
- * these are marked `blocked` — their upstream surface never landed — rather than
- * looping forever.
- *
- * A node held only by an UNANSWERED WORKER QUESTION is deliberately excluded
- * (`dependencyAwaitingClarification`): since the clarification round is deferred
- * to the end of the implement phase, such a node reaches this sweep while its
- * answer is still outstanding, and blocking it would report "upstream failed"
- * for what is really "awaiting an answer". It stays `pending` and is re-decided
- * once the answer lands.
+ * The ONE dead-end sweep, shared by the planning→implementing transition and
+ * the implementing obligation: marks the pending items of every permanently
+ * dead block `blocked` with the INV-RS-01 reason, and reports whether anything
+ * changed. Deadness is the workload boundary's own liveness analysis
+ * ({@link permanentlyDeadPendingBlocks}), so a node held by an unanswered
+ * clarification — or by a lower phase that is merely still working — is NEVER
+ * mis-reported as an upstream failure (the 175cfb89 pin).
  */
-function blockedByUnsatisfiedDependency(state) {
-    if (!state.plan || !state.items)
-        return [];
-    return state.plan.blocks.filter((block) => !dependencyVerifiedComplete(block, state) &&
-        !dependencyAwaitingClarification(block, state) &&
-        block.items.some((findingId) => state.items?.[findingId]?.status === "pending"));
+function sweepPermanentlyDeadBlocks(state) {
+    let changed = false;
+    const now = new Date().toISOString();
+    for (const block of permanentlyDeadPendingBlocks(state)) {
+        for (const findingId of block.items) {
+            const it = state.items?.[findingId];
+            if (!it || it.status !== "pending")
+                continue;
+            it.status = "blocked";
+            it.started_at ??= now;
+            it.completed_at = now;
+            it.failure_reason =
+                it.failure_reason ??
+                    "A prerequisite can never reach a verified-complete disposition " +
+                        "(a dependency or lower-phase block was skipped, blocked, or abandoned; " +
+                        "a declared dependency resolves to no block; or the dependencies are " +
+                        "cyclic); the host handoff will not expose this node against an " +
+                        "upstream surface that never landed (INV-RS-01).";
+            changed = true;
+        }
+    }
+    return changed;
 }
 /**
  * Whether any item is paused on a worker question that has not been answered yet.
@@ -1590,6 +1599,14 @@ function isPlanClarificationAction(value) {
     return (typeof value === "string" &&
         PLAN_CLARIFICATION_ACTIONS.includes(value));
 }
+/** Carry `scope_additions` through when it is an array; keep string entries. */
+function normalizedScopeAdditions(entry) {
+    if (!Array.isArray(entry.scope_additions))
+        return {};
+    return {
+        scope_additions: entry.scope_additions.filter((p) => typeof p === "string"),
+    };
+}
 function normalizePlanClarificationResolutions(value) {
     if (Array.isArray(value)) {
         return value.filter(isRecord).flatMap((entry) => {
@@ -1599,6 +1616,7 @@ function normalizePlanClarificationResolutions(value) {
                         finding_id: entry.finding_id,
                         action: entry.action,
                         rationale: typeof entry.rationale === "string" ? entry.rationale : undefined,
+                        ...normalizedScopeAdditions(entry),
                     },
                 ];
             }
@@ -1622,9 +1640,56 @@ function normalizePlanClarificationResolutions(value) {
                 finding_id: typeof entry.finding_id === "string" ? entry.finding_id : findingId,
                 action: entry.action,
                 rationale: typeof entry.rationale === "string" ? entry.rationale : undefined,
+                ...normalizedScopeAdditions(entry),
             }];
     });
 }
+/**
+ * Validate every `clarified` resolution's `scope_additions` BEFORE anything is
+ * applied: each entry must normalize beneath the repository root against the
+ * finding's owning block (the one write-scope normalizer), must clear the SAME
+ * tracked-tree rule the promotion gate enforced (the delta lane must not
+ * bypass it), and a finding with no owning block has no scope to widen. ANY
+ * refusal refuses the WHOLE resolution file — the uniform id-join contract's
+ * shape: a half-applied decision record is worse than a re-ask.
+ */
+async function validateClarificationScopeAdditions(root, state, resolutions) {
+    const refusals = [];
+    for (const res of resolutions) {
+        if (res.action !== "clarified" || !res.scope_additions?.length)
+            continue;
+        const block = state.plan?.blocks?.find((b) => b.items.includes(res.finding_id));
+        if (!block) {
+            refusals.push(`scope_additions for \`${res.finding_id}\`: no plan block owns this finding, so ` +
+                `there is no write scope to widen.`);
+            continue;
+        }
+        const normalized = normalizeBlockTouchedFiles(root, res.scope_additions, block.block_id);
+        refusals.push(...normalized.refusals);
+        refusals.push(...(await checkWriteScopePathsAgainstTrackedTree(root, normalized.touched_files, `scope_additions for \`${res.finding_id}\` (block "${block.block_id}")`)));
+    }
+    return refusals;
+}
+/**
+ * Apply one validated scope delta: union the normalized additions into the
+ * owning block's `touched_files` (content-sorted — an incidentally-ordered
+ * scope would churn the plan hash). The workload-binding invalidation is the
+ * caller's existing `delete state.host_handoff` on any applied resolution, so
+ * the next prepare re-mints the work item with the widened `allowed_files`
+ * (the open-bugs :661 wedge class); the up-front ambiguity gate has no binding
+ * by construction.
+ */
+function applyClarificationScopeAdditions(root, state, res) {
+    if (res.action !== "clarified" || !res.scope_additions?.length)
+        return;
+    const block = state.plan?.blocks?.find((b) => b.items.includes(res.finding_id));
+    if (!block)
+        return; // refused upstream by validateClarificationScopeAdditions
+    const normalized = normalizeBlockTouchedFiles(root, res.scope_additions, block.block_id);
+    block.touched_files = [
+        ...new Set([...block.touched_files, ...normalized.touched_files]),
+    ].sort((left, right) => compareCodeUnits(left, right));
+}
 /**
  * Apply one clarification resolution to its item. Single-sourced so the up-front
  * ambiguity gate (part A) and the mid-run clarification round (part B) settle an
@@ -1677,6 +1742,17 @@ async function applyPlanClarificationResolution(root, artifactsDir, state, store
             step: await handleWaitingForClarification(root, artifactsDir, state, `finding id(s) not in the plan: ${unknownIds.map((i) => `\`${i}\``).join(", ")}`),
         };
     }
+    // Scope deltas ride the same whole-file fail-closed contract as unknown ids:
+    // an invalid addition refuses everything, so a decision record never
+    // half-applies (open-bugs.md:110).
+    const scopeRefusals = await validateClarificationScopeAdditions(root, state, resolutions);
+    if (scopeRefusals.length > 0) {
+        await withFsRetry(() => rename(resolutionPath, `${resolutionPath}.refused-${Date.now()}`));
+        return {
+            kind: "refused",
+            step: await handleWaitingForClarification(root, artifactsDir, state, `invalid scope_additions — fix and re-submit: ${scopeRefusals.join(" | ")}`),
+        };
+    }
     const now = new Date().toISOString();
     let appliedCount = 0;
     for (const res of resolutions) {
@@ -1684,6 +1760,7 @@ async function applyPlanClarificationResolution(root, artifactsDir, state, store
         if (!item || isTerminalStatus(item.status))
             continue;
         applyClarificationActionToItem(item, res, now);
+        applyClarificationScopeAdditions(root, state, res);
         appliedCount += 1;
     }
     // An applied answer mutates item state that is baked into the dispatch
@@ -1947,6 +2024,29 @@ async function runPlanAmbiguityGate(root, artifactsDir, state, store) {
             },
         });
     }
+    // Scope deltas: the same whole-file fail-closed contract as unknown ids
+    // (open-bugs.md:110). At this up-front gate no workload binding exists yet,
+    // so an applied widening simply flows into the first dispatch.
+    const scopeRefusals = await validateClarificationScopeAdditions(root, state, resolutions);
+    if (scopeRefusals.length > 0) {
+        await withFsRetry(() => rename(resolutionPath, `${resolutionPath}.refused-${Date.now()}`));
+        const candidates = (await readOptionalJsonFile(requestPath)) ??
+            detectPlanAmbiguities(findings, state.items);
+        return writeCurrentStep({
+            stepKind: "collect_clarifications",
+            status: "blocked",
+            runId: stateRunId(state),
+            repoRoot: root,
+            artifactsDir,
+            prompt: ambiguityReviewPrompt(candidates, resolutionPath, findings.map((f) => f.id), `invalid scope_additions — fix and re-submit: ${scopeRefusals.join(" | ")}`),
+            allowedCommands: [loaderCommand("next-step")],
+            stopCondition: "Stop after re-submitting a corrected ambiguity resolution, unless it is already written and the prompt told you to continue.",
+            artifactPaths: {
+                ambiguity_request: requestPath,
+                ambiguity_resolution: resolutionPath,
+            },
+        });
+    }
     const now = new Date().toISOString();
     let changed = false;
     for (const res of resolutions) {
@@ -1954,6 +2054,7 @@ async function runPlanAmbiguityGate(root, artifactsDir, state, store) {
         if (!item || isTerminalStatus(item.status))
             continue;
         applyClarificationActionToItem(item, res, now);
+        applyClarificationScopeAdditions(root, state, res);
         changed = true;
     }
     await writeJsonFile(decisionPath, { resolved_at: now, resolution_count: resolutions.length });
@@ -1989,7 +2090,7 @@ async function handlePlanning(root, artifactsDir, state, store) {
     }
     // Document phase dissolved (N-R13): planning transitions directly to
     // implementing, and the host workload reads finding context directly.
-    const implementBlocks = implementableBlocks(state);
+    const implementBlocks = dispatchFrontier(state);
     if (implementBlocks.length > 0) {
         if (state.plan) {
             const integrity = await checkAffectedFileIntegrity(root, state.plan.findings);
@@ -2024,28 +2125,15 @@ async function handlePlanning(root, artifactsDir, state, store) {
         }
     }
     // Transition directly to implementing — no separate document round.
-    // Any pending item outside every attainable host dependency frontier is
+    // Any pending item that can never enter the host dependency frontier is
     // dead-ended (INV-RS-01): a prerequisite was skipped/blocked, so its
     // verified-complete edge can never be satisfied — never dispatch a dependent
     // against an upstream surface that did not land. Mark it blocked so the run
     // advances to close rather than looping forever. A node that is merely
-    // waiting on a still-running prerequisite is NOT here (it would appear in a
-    // later eligible pass); only nodes with a permanently-unsatisfiable edge are.
+    // waiting on a still-running prerequisite — or on a clarification answer —
+    // is NOT dead; the liveness analysis behind the sweep holds it pending.
     if (implementBlocks.length === 0) {
-        for (const block of blockedByUnsatisfiedDependency(state)) {
-            for (const findingId of block.items) {
-                const it = state.items?.[findingId];
-                if (!it || it.status !== "pending")
-                    continue;
-                it.status = "blocked";
-                it.failure_reason =
-                    it.failure_reason ??
-                        "A dependency node did not reach a verified-complete disposition " +
-                            "(a prerequisite was skipped, blocked, or the dependencies are cyclic); " +
-                            "the host handoff will not expose this node against an upstream " +
-                            "surface that never landed (INV-RS-01).";
-            }
-        }
+        sweepPermanentlyDeadBlocks(state);
     }
     state.status = "implementing";
     await store.saveState(state);
@@ -3236,7 +3324,7 @@ export function buildMainObligations(ctx) {
             derive: (state) => state != null &&
                 (state.status === "implementing" || state.status === "triage") &&
                 hasUnansweredClarification(state) &&
-                implementableBlocks(state).length === 0
+                dispatchFrontier(state).length === 0
                 ? "missing"
                 : "satisfied",
             execute: async (state) => {
@@ -3251,9 +3339,9 @@ export function buildMainObligations(ctx) {
             derive: (state) => state?.status === "implementing" ? "missing" : "satisfied",
             execute: async (state) => {
                 const s = requireState(state);
-                // Pending implementable blocks dispatch; triage only runs once every item
-                // has left "pending".
-                const pendingBlocks = implementableBlocks(s);
+                // A non-empty dispatch frontier dispatches; triage only runs once every
+                // item has left "pending".
+                const pendingBlocks = dispatchFrontier(s);
                 if (pendingBlocks.length > 0) {
                     // Per-phase boundary gate (T3): before opening a phase P > 0, run the
                     // whole-repo suite once over the just-landed foundations. A red PAUSES
@@ -3277,33 +3365,12 @@ export function buildMainObligations(ctx) {
                         runLogger,
                     });
                 }
-                // Dead-end pending nodes whose dependency never reached verified-complete
-                // (INV-RS-01) so the implementing→triage loop can't livelock; transition
-                // so the engine re-scans on the updated state.
-                const deadEnded = blockedByUnsatisfiedDependency(s);
-                if (deadEnded.length > 0) {
-                    const now = new Date().toISOString();
-                    let changed = false;
-                    for (const block of deadEnded) {
-                        for (const findingId of block.items) {
-                            const it = s.items?.[findingId];
-                            if (!it || it.status !== "pending")
-                                continue;
-                            it.status = "blocked";
-                            it.started_at ??= now;
-                            it.completed_at = now;
-                            it.failure_reason =
-                                it.failure_reason ??
-                                    "A dependency node did not reach a verified-complete disposition " +
-                                        "(a prerequisite was skipped, blocked, or the dependencies are cyclic); " +
-                                        "the host handoff will not expose this node (INV-RS-01).";
-                            changed = true;
-                        }
-                    }
-                    if (changed) {
-                        await store.saveState(s);
-                        return { kind: "transition", state: s };
-                    }
+                // Dead-end pending nodes that can never enter the frontier (INV-RS-01)
+                // so the implementing→triage loop can't livelock; transition so the
+                // engine re-scans on the updated state.
+                if (sweepPermanentlyDeadBlocks(s)) {
+                    await store.saveState(s);
+                    return { kind: "transition", state: s };
                 }
                 return handleImplementing(root, artifactsDir, s, runLogger, store, options);
             },