audit-tools 0.28.2 → 0.28.4

package/dist/remediate/steps/nextStep.js

@@ -8,7 +8,7 @@ import { groundExtractedFindings } from "../phases/grounding.js";
 import { runTriagePhase } from "../phases/triage.js";
 import { runClosePhase } from "../phases/close.js";
 import { validateRemediationPlan } from "../validation/remediationState.js";
-import { mergeImplementResults, prepareImplementDispatch, readExtractedPlanIfPresent, buildConfirmedPools, createWorktree, removeWorktree, resetNodeWorktreeAndBranch, acceptNodeWorktree, recordNodeAcceptOutcome, ensureWorktreeNodeModules, worktreePath, worktreeBranchForBlock, } from "./dispatch.js";
+import { mergeImplementResults, prepareImplementDispatch, readExtractedPlanIfPresent, buildConfirmedPools, createWorktree, removeWorktree, resetNodeWorktreeAndBranch, acceptNodeWorktree, recordNodeAcceptOutcome, ensureWorktreeNodeModules, seedUntrackedDeclaredPaths, worktreePath, worktreeBranchForBlock, blockScopesFromPlan, } from "./dispatch.js";
 import { makeProviderNodeDispatcher } from "./providerNodeDispatch.js";
 import { prepareHostRollingDispatch } from "./rollingSession.js";
 import { writeCurrentStep } from "./stepWriter.js";
@@ -24,7 +24,7 @@ import { contractArtifactExists, contractPipelineDir, } from "../contractPipelin
 import { buildReviewRequest, applyReviewResolution, } from "../review/reviewGate.js";
 import { runFindingFilterPass } from "../findingFilter.js";
 import { intakePaths, isIntakeReady, readIntakeArtifacts, resolveManifestSources, } from "../intake.js";
-import { clarificationPrompt, collectIntakeClarificationsPrompt, collectStartingPointPrompt, loaderCommand, reviewApprovalPrompt, synthesizeIntakePrompt, triagePrompt, } from "./prompts.js";
+import { ambiguityReviewPrompt, clarificationPrompt, collectIntakeClarificationsPrompt, collectStartingPointPrompt, loaderCommand, reviewApprovalPrompt, synthesizeIntakePrompt, triagePrompt, } from "./prompts.js";
 export function resolveHostDispatchCapability(options) {
     if (options.hostCanDispatchSubagents !== undefined) {
         return options.hostCanDispatchSubagents;
@@ -141,6 +141,30 @@ function resolveInputPaths(root, input) {
         checked,
     };
 }
+/**
+ * True when a supplied `--input` is the SAME input the existing run was already
+ * built from (its recorded intake source manifest, `created_from: "input"`, with
+ * a path set equal to the supplied paths). The `/remediate-code` loader re-passes
+ * the same `--input` on every `next-step`; treating that unchanged input as a
+ * RESUME — not an `input_conflict` — spares the host a needless resume/restart ack
+ * dance, while a genuinely DIFFERENT input still trips the conflict gate. Enforced
+ * in the tool, never by asking the loader to remember to drop the flag (a needed
+ * manual flag is a bug signal).
+ */
+function suppliedInputMatchesRun(inputResolution, manifest) {
+    if (!inputResolution.supplied)
+        return false;
+    if (!manifest || manifest.created_from !== "input")
+        return false;
+    const supplied = new Set(inputResolution.checked.map((p) => resolve(p)));
+    const recorded = new Set(manifest.sources.map((s) => resolve(s.path)));
+    if (supplied.size === 0 || supplied.size !== recorded.size)
+        return false;
+    for (const p of supplied)
+        if (!recorded.has(p))
+            return false;
+    return true;
+}
 export { NO_CHANGE_RE, dependenciesSatisfied, dependencyVerifiedComplete, specIndicatesNoChange, classifyFindingRisk, } from "./stepUtils.js";
 export { isTerminalStatus, isVerifiedCompleteStatus };
 function documentableFindings(state) {
@@ -377,6 +401,10 @@ export async function driveRollingImplementDispatch(options) {
     const resultPathByBlock = new Map(plan.items
         .filter((i) => typeof i.block_id === "string")
         .map((i) => [i.block_id, i.result_path]));
+    // Every block's declared write scope, for the accept-time write-scope gate's
+    // amendment ownership adjudication (so an amended path owned by a sibling block
+    // is a seam conflict, not a silent grant). Built once from the in-memory plan.
+    const allBlockScopes = blockScopesFromPlan(plan);
     // Map each planned block id to its worktree-rooted prompt path so the
     // provider-backed dispatcher launches the worker with the right prompt.
     const promptPathByBlock = new Map(plan.items
@@ -431,6 +459,11 @@ export async function driveRollingImplementDispatch(options) {
             // A fresh worktree has no node_modules (gitignored); link the main checkout's
             // so this node's verify commands can run.
             ensureWorktreeNodeModules(root, wt);
+            // Bring in declared targets that are untracked/ignored in the main tree so a
+            // committed-files-only worktree can still see this node's own targets.
+            // `touched_files` is the block's authoritative declared write set (the same
+            // source the dispatch plan's write scope is derived from).
+            seedUntrackedDeclaredPaths(root, wt, block.touched_files ?? []);
             const result = await dispatchNode({
                 block,
                 slot,
@@ -445,6 +478,9 @@ export async function driveRollingImplementDispatch(options) {
                 const finding = state.plan?.findings.find((f) => f.id === id);
                 return finding?.targeted_commands ?? [];
             }));
+            // The worker's self-reported amendments, adjudicated (never trusted as the
+            // gate input) by the accept-time write-scope gate before the cherry-pick.
+            const workerResult = await readOptionalJsonFile(resultPath);
             const accept = acceptNodeWorktree({
                 root,
                 runId,
@@ -453,6 +489,7 @@ export async function driveRollingImplementDispatch(options) {
                 branch,
                 workerOutcome: result.outcome,
                 targetedCommands: targeted,
+                scope: { allBlockScopes, amendedFiles: workerResult?.amended_files ?? [] },
             });
             // Persist the tool-owned verify/merge outcome so finalization blocks a node
             // that self-reported resolved but never actually landed (OBL-DS-06). Parity
@@ -949,7 +986,7 @@ async function buildImplementDispatchStep(ctx) {
         }
         const rollMerge = loaderCommand(`merge-implement-results --run-id ${runId}`);
         const rollNext = loaderCommand("next-step");
-        const acceptCmd = loaderCommand("accept-node --id <BLOCK_ID>");
+        const acceptCmd = loaderCommand(`accept-node --id <BLOCK_ID> --run-id ${runId}`);
         const nodeLines = rolling.initial
             .map((n) => `- \`${n.block_id}\` — prompt: \`${n.prompt_path}\` — worktree (subagent cwd): \`${n.worktree_root}\``)
             .join("\n");
@@ -1221,6 +1258,17 @@ function reviewResolutionPath(artifactsDir) {
 function reviewDecisionPath(artifactsDir) {
     return join(artifactsDir, "review_decision.json");
 }
+// Up-front ambiguity gate (note 3, part A) — its own request/resolution/decision
+// files, mirroring the review gate so it fires (and halts) at most once per run.
+function ambiguityRequestPath(artifactsDir) {
+    return join(artifactsDir, "ambiguity_request.json");
+}
+function ambiguityResolutionPath(artifactsDir) {
+    return join(artifactsDir, "ambiguity_resolution.json");
+}
+function ambiguityDecisionPath(artifactsDir) {
+    return join(artifactsDir, "ambiguity_decision.json");
+}
 /** Pull the Finding[] out of a parsed audit-findings.json payload. */
 function extractAuditFindings(parsed) {
     if (isRecord(parsed) && Array.isArray(parsed.findings)) {
@@ -1534,11 +1582,19 @@ Stop after presenting this choice. Do not advance the run until the user decides
         },
     });
 }
+const PLAN_CLARIFICATION_ACTIONS = [
+    "clarified",
+    "deemed_inappropriate",
+    "defer",
+];
+function isPlanClarificationAction(value) {
+    return (typeof value === "string" &&
+        PLAN_CLARIFICATION_ACTIONS.includes(value));
+}
 function normalizePlanClarificationResolutions(value) {
     if (Array.isArray(value)) {
         return value.filter(isRecord).flatMap((entry) => {
-            if (typeof entry.finding_id === "string" &&
-                (entry.action === "clarified" || entry.action === "deemed_inappropriate")) {
+            if (typeof entry.finding_id === "string" && isPlanClarificationAction(entry.action)) {
                 return [
                     {
                         finding_id: entry.finding_id,
@@ -1561,7 +1617,7 @@ function normalizePlanClarificationResolutions(value) {
     return Object.entries(value).flatMap(([findingId, entry]) => {
         if (!isRecord(entry))
             return [];
-        if (entry.action !== "clarified" && entry.action !== "deemed_inappropriate")
+        if (!isPlanClarificationAction(entry.action))
             return [];
         return [{
                 finding_id: typeof entry.finding_id === "string" ? entry.finding_id : findingId,
@@ -1570,6 +1626,33 @@ function normalizePlanClarificationResolutions(value) {
             }];
     });
 }
+/**
+ * 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
+ * item identically: `clarified` re-opens it (pending) with the answer as context,
+ * `deemed_inappropriate` closes it as not-a-real-issue, and `defer` closes it as
+ * an explicit user deferral for this run. Never resurrects a terminal item.
+ */
+function applyClarificationActionToItem(item, res, now) {
+    if (res.action === "deemed_inappropriate") {
+        item.status = "deemed_inappropriate";
+        item.failure_reason = res.rationale;
+        item.started_at ??= now;
+        item.completed_at = now;
+    }
+    else if (res.action === "defer") {
+        item.status = "ignored";
+        item.failure_reason = res.rationale
+            ? `User-deferred for this run: ${res.rationale}`
+            : "User-deferred for this run.";
+        item.started_at ??= now;
+        item.completed_at = now;
+    }
+    else {
+        item.status = "pending";
+        item.clarification_context = res.rationale;
+    }
+}
 /**
  * Consume clarification_resolution.json for plan-phase clarifications.
  * Mirrors the triage resolution consume: deemed_inappropriate → terminal,
@@ -1583,18 +1666,9 @@ async function applyPlanClarificationResolution(artifactsDir, state, store) {
     const now = new Date().toISOString();
     for (const res of resolutions) {
         const item = state.items[res.finding_id];
-        if (!item)
+        if (!item || isTerminalStatus(item.status))
             continue;
-        if (res.action === "deemed_inappropriate") {
-            item.status = "deemed_inappropriate";
-            item.failure_reason = res.rationale;
-            item.started_at ??= now;
-            item.completed_at = now;
-        }
-        else {
-            item.status = "pending";
-            item.clarification_context = res.rationale;
-        }
+        applyClarificationActionToItem(item, res, now);
     }
     if (existsSync(resolutionPath)) {
         await withFsRetry(() => rename(resolutionPath, `${resolutionPath}.consumed-${Date.now()}`));
@@ -1710,6 +1784,110 @@ async function runPlanningReviewGate(root, artifactsDir, state, store) {
         await store.saveState(state);
     return null;
 }
+/**
+ * Deterministic first pass (note 3, part A): scan the plan's non-terminal
+ * findings for scoping/judgment ambiguity, classified into the canonical
+ * clarification categories. These are CANDIDATES — the host reviews them against
+ * the repo, dismisses false positives, and adds any it finds, before batching one
+ * user round. Conservative by design: a candidate the host dismisses costs one
+ * read; a real scoping question that falls silently to mid-run triage is the bug
+ * this gate exists to prevent.
+ */
+function detectPlanAmbiguities(findings, items) {
+    const out = [];
+    for (const f of findings) {
+        const item = items?.[f.id];
+        if (item && isTerminalStatus(item.status))
+            continue;
+        const lens = (f.lens ?? "").toLowerCase();
+        const fileCount = f.affected_files?.length ?? 0;
+        const broadScope = (lens === "architecture" || lens === "maintainability") &&
+            (fileCount === 0 || fileCount >= 5);
+        if (broadScope) {
+            out.push({
+                finding_id: f.id,
+                category: "scope_of_fix",
+                description: `"${f.title}" is a ${lens} finding with ${fileCount === 0 ? "no cited files" : `${fileCount} affected files`}; ` +
+                    "confirm how far the fix should reach (minimal local change vs. broader restructuring).",
+            });
+            continue;
+        }
+        if (f.confidence === "low") {
+            out.push({
+                finding_id: f.id,
+                category: "issue_appropriateness",
+                description: `"${f.title}" is a low-confidence finding; confirm it is a real issue worth fixing in this run.`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Up-front ambiguity gate (note 3, part A). Mirrors {@link runPlanningReviewGate}:
+ * it fires once at planning, BEFORE any implement dispatch, so scoping/judgment
+ * ambiguity is asked as a single batched question up front rather than falling
+ * silently to triage mid-run. Deterministic heuristics seed CANDIDATES; the host
+ * reviews them with repo access, dismisses/adds, and batches one user round. Each
+ * item is resolved as `clarified` (answered → re-opened), `deemed_inappropriate`
+ * (not a real issue), or `defer` (the user's explicit choice to skip this run).
+ *
+ * Idempotent: once `ambiguity_decision.json` exists the gate is done and never
+ * re-halts. An empty resolution proceeds (the host found nothing to ask).
+ */
+async function runPlanAmbiguityGate(root, artifactsDir, state, store) {
+    const findings = state.plan?.findings ?? [];
+    if (findings.length === 0)
+        return null;
+    const requestPath = ambiguityRequestPath(artifactsDir);
+    const resolutionPath = ambiguityResolutionPath(artifactsDir);
+    const decisionPath = ambiguityDecisionPath(artifactsDir);
+    if (!existsSync(resolutionPath)) {
+        // Deterministic detection is the gate trigger: with zero candidates there is
+        // nothing for the host to review, so the plan proceeds without a round. Any
+        // ambiguity the heuristics miss is still caught by the mid-run escape hatch
+        // (part B). When candidates exist, halt for the host's review + the user's
+        // batched answers.
+        const candidates = detectPlanAmbiguities(findings, state.items);
+        if (candidates.length === 0)
+            return null;
+        await writeJsonFile(requestPath, candidates);
+        return writeCurrentStep({
+            stepKind: "collect_clarifications",
+            status: "blocked",
+            runId: stateRunId(state),
+            repoRoot: root,
+            artifactsDir,
+            prompt: ambiguityReviewPrompt(candidates, resolutionPath),
+            allowedCommands: [loaderCommand("next-step")],
+            stopCondition: "Stop after reviewing the candidate ambiguities (and asking the user any genuine ones), unless the resolution is already written and the prompt told you to continue.",
+            artifactPaths: {
+                ambiguity_request: requestPath,
+                ambiguity_resolution: resolutionPath,
+            },
+        });
+    }
+    // Resolution present: apply it to items, mark the gate done, archive inputs so
+    // it cannot re-halt.
+    const resolutions = normalizePlanClarificationResolutions(await readOptionalJsonFile(resolutionPath));
+    const now = new Date().toISOString();
+    let changed = false;
+    for (const res of resolutions) {
+        const item = state.items?.[res.finding_id];
+        if (!item || isTerminalStatus(item.status))
+            continue;
+        applyClarificationActionToItem(item, res, now);
+        changed = true;
+    }
+    await writeJsonFile(decisionPath, { resolved_at: now, resolution_count: resolutions.length });
+    for (const p of [resolutionPath, requestPath]) {
+        if (existsSync(p)) {
+            await withFsRetry(() => rename(p, `${p}.consumed-${Date.now()}`));
+        }
+    }
+    if (changed)
+        await store.saveState(state);
+    return null;
+}
 async function handlePlanning(root, artifactsDir, state, store) {
     // Review-necessity gate (Path B). Path A records its review decision at intake,
     // over the ORIGINAL findings, before the contract pipeline collapses them into
@@ -1723,6 +1901,14 @@ async function handlePlanning(root, artifactsDir, state, store) {
         if (halt)
             return { kind: "emit", step: halt };
     }
+    // Up-front ambiguity gate (note 3, part A): resolve every scoping/judgment
+    // ambiguity in ONE batched round here, before any implement dispatch, so a
+    // question never falls silently to mid-run triage. Fires at most once per run.
+    if (state.plan && !existsSync(ambiguityDecisionPath(artifactsDir))) {
+        const halt = await runPlanAmbiguityGate(root, artifactsDir, state, store);
+        if (halt)
+            return { kind: "emit", step: halt };
+    }
     // Document phase dissolved: planning transitions directly to implementing.
     // The rolling implement dispatch reads item_spec from the plan DAG node when
     // present, or uses finding context directly when absent.
@@ -2264,7 +2450,7 @@ const PRE_INTAKE_PRIORITY = [
  */
 function buildPreIntakeObligations(ctx, snapshot) {
     const { artifactsDir, inputResolution } = ctx;
-    const { existingCheckpoint, resumeAck, entryState } = snapshot;
+    const { existingCheckpoint, resumeAck, entryState, suppliedInputUnchanged } = snapshot;
     const ip = intakePaths(artifactsDir);
     const checkpointPath = join(artifactsDir, "intent_checkpoint.json");
     const ackPath = join(artifactsDir, "confirm_resume_ack.json");
@@ -2276,11 +2462,14 @@ function buildPreIntakeObligations(ctx, snapshot) {
     const warned = { value: false };
     return [
         {
-            // A new --input against a run already past intake must not silently resume
-            // the old plan; require an explicit resume-vs-restart choice. Derives from
-            // the frozen entry state — never an intake-created one.
+            // A new, DIFFERENT --input against a run already past intake must not
+            // silently resume the old plan; require an explicit resume-vs-restart
+            // choice. The SAME --input re-passed (the loader does this every next-step)
+            // is an unchanged input → a resume, not a conflict. Derives from the frozen
+            // entry state — never an intake-created one.
             id: "input_conflict",
             derive: () => inputResolution.supplied &&
+                !suppliedInputUnchanged &&
                 entryState != null &&
                 entryState.status !== "pending"
                 ? "missing"
@@ -2680,6 +2869,10 @@ async function decideNextStepLoop(options, runLogger) {
         ? await readOptionalJsonFile(checkpointPath)
         : undefined;
     const resumeAck = await readOptionalJsonFile(join(artifactsDir, "confirm_resume_ack.json"));
+    // Whether a supplied `--input` matches the input the existing run was built
+    // from — so re-passing the same `--input` (the loader does this each next-step)
+    // resumes rather than tripping the input_conflict gate.
+    const suppliedInputUnchanged = suppliedInputMatchesRun(inputResolution, await readOptionalJsonFile(intakePaths(artifactsDir).sourceManifest));
     // The linear pre-intake gates run as obligations through the shared advance
     // loop. An emit returns to the host; a transition re-scans within this call;
     // exhausting them (step === null) means the run is past intake and falls
@@ -2699,6 +2892,7 @@ async function decideNextStepLoop(options, runLogger) {
             existingCheckpoint,
             resumeAck,
             entryState: state,
+            suppliedInputUnchanged,
         }),
     }, state, ctx);
     if (preIntake.step)