audit-tools 0.45.0 → 0.48.0

package/dist/remediate/steps/nextStep.js

@@ -1,12 +1,12 @@
 import { loadRemediateSessionConfig } from "./sessionConfigLoad.js";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { StateStore } from "../state/store.js";
 // IO / validation / rendering helpers
 import { discardOnSchemaVersionMismatch, readOptionalJsonFile, stagedAndUntracked, writeJsonFile, writeTextFile, buildAuditDeliverablePair, formatValidationIssues, isRecord, withFsRetry, RunLogger, coerceJsonObjectArg, headCommit, projectAuditFindingsReportSubset, 
 // obligation engine + intent
-interpretFreeFormIntent, advance, decideFrictionTriage, buildFrictionTriageBlock, 
+interpretFreeFormIntent, interpretIntent, unresolvedFromClauses, advance, decideFrictionTriage, buildFrictionTriageBlock, linkFrictionRunIds, 
 // domain constants
 LENSES, SEVERITIES, } from "audit-tools/shared";
 import { applyPlanPipeline, buildCoverageLedger } from "../phases/plan.js";
@@ -27,13 +27,13 @@ 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, buildLeanExtractedPlan, } from "./contractPipeline.js";
+import { buildNextContractPipelineStep, shouldEnterContractPipeline, writePathASeedFromFindings, } from "./contractPipeline.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";
 import { runFindingFilterPass } from "../findingFilter.js";
 import { intakePaths, isIntakeReady, manifestIsInputBound, readIntakeArtifacts, resolveManifestSources, } from "../intake.js";
-import { ensureIntakeRiskSignal, readIntakeRiskSignal, writeIntakeRiskSignal, escalateRiskSignal, findingRiskEvidence, distinctAffectedFiles, interpretLeanLightReviewVerdict, LEAN_LIGHT_REVIEW_SCHEMA_VERSION, } from "../riskSignal.js";
+import { ensureIntakeRiskSignal, readIntakeRiskSignal, writeIntakeRiskSignal, escalateRiskSignal, findingRiskEvidence, distinctAffectedFiles, } from "../riskSignal.js";
 import { ambiguityReviewPrompt, clarificationPrompt, collectIntakeClarificationsPrompt, collectStartingPointPrompt, loaderCommand, reviewApprovalPrompt, synthesizeIntakePrompt, triagePrompt, } from "./prompts.js";
 // Single-sourced prose renders of the canonical lens / severity vocabularies
 // (`audit-tools/shared` `LENSES` / `SEVERITIES`) for the intent-checkpoint
@@ -449,7 +449,7 @@ function stripPlanTimeBookkeeping(value) {
  * The re-plan carry-forward identity of a finding: canonical JSON with the
  * plan-time bookkeeping keys stripped, so a re-plan whose only delta is a
  * recomputed file hash or a re-evaluated grounding flag carries the prior item
- * (and its `item_spec`) forward, while a real change to the finding does not.
+ * forward, while a real change to the finding does not.
  *
  * EXPORTED so the invariant suite can call THIS function. It was module-internal,
  * and the suite claiming to cover the invariant declared its own copy of the key
@@ -488,14 +488,15 @@ function carryForwardMatchingItems(previous, replanned) {
     for (const finding of replanned.plan.findings) {
         const previousFinding = previousFindings.get(finding.id);
         const previousItem = previous.items[finding.id];
-        // Skip items that were never documented (pending with no item_spec). Under
-        // N-R13 (document phase dissolved), a pending item that already has an
-        // item_spec from a prior planning/document pass should carry forward
-        // together with its spec rather than being discarded.
+        // A still-pending item carries no work to preserve, so it is re-minted from
+        // the fresh plan rather than carried forward. (This test used to also admit
+        // a pending item that held an `item_spec`; the document phase that produced
+        // one was dissolved by N-R13 and the field is gone, so the second condition
+        // could never be true and is not restated here.)
         if (!previousFinding || !previousItem) {
             continue;
         }
-        if (previousItem.status === "pending" && !previousItem.item_spec) {
+        if (previousItem.status === "pending") {
             continue;
         }
         if (findingCarryForwardKey(previousFinding) !== findingCarryForwardKey(finding)) {
@@ -740,6 +741,11 @@ async function buildImplementDispatchStep(ctx) {
             host_handoff: handoff.handoff_record,
         });
     }
+    // Name the runs this dispatch round relates to on the friction record (semantics:
+    // `FrictionRunLinks`). Each reference is sourced from the envelope that owns it — the
+    // persisted handoff record for the dispatch run, the step contract's own run id for
+    // the step — never synthesized from the other.
+    await linkFrictionRunIds(artifactsDir, stateRunId(state), { step_run_id: runId, dispatch_run_id: handoff.handoff_record.run_id }, "remediate-code");
     // Ingest issues reached the PROMPT and nothing else — a channel that survives
     // exactly as long as the host reads that one step. They are also the durable
     // record of which submitted results were rejected and why, so they are logged
@@ -1254,112 +1260,6 @@ async function runReviewApprovalGate(root, artifactsDir, survivors, autonomous =
         declined,
     };
 }
-// ── T1 slice 3b — lean-path light adversarial review gate ───────────────────────
-//
-// Mirrors the review-approval gate's emit→resume→consume idiom, but the step is
-// WORK (status "ready"), not a human decision — so it runs identically in
-// attended and autonomous modes (the host agent executes the light pass like any
-// phase). Fires (and at most once) only when the fast path is eligible.
-function leanLightReviewVerdictPath(artifactsDir) {
-    return join(artifactsDir, "lean_light_review_verdict.json");
-}
-function leanLightReviewDecisionPath(artifactsDir) {
-    return join(artifactsDir, "lean_light_review_decision.json");
-}
-/** Render the bounded light-adversarial-review prompt over the approved findings. */
-function leanLightReviewPrompt(approved, verdictPath) {
-    const findingLines = approved
-        .map((f) => {
-        const files = (f.affected_files ?? [])
-            .map((loc) => loc?.path)
-            .filter((p) => Boolean(p))
-            .join(", ");
-        return `- \`${f.id}\` — ${f.title ?? "(untitled)"}${files ? ` (${files})` : ""}`;
-    })
-        .join("\n");
-    const nextCommand = loaderCommand("next-step");
-    return `# Lean fast path — light adversarial review
-
-These findings cleared the simplicity gate and are headed for the lean fast path (straight to plan→implement, skipping the full contract pipeline). Before they are trusted, do ONE **lightweight adversarial pass** — the floor that replaces the full design loop here. This is proportionate, not an exhaustive counterexample search: remediation legitimately catches upstream audit errors, so nothing skips review entirely.
-
-## Findings to review
-${findingLines || "_(none)_"}
-
-## Your task
-Adopt a brief adversarial stance and ask, across the set:
-- Is any finding actually wrong, already-fixed, or not grounded in the cited code?
-- Would the proposed fix break a caller, an invariant, or an adjacent behavior?
-- Are any two of these coupled / sharing a file in a way that needs seam reconciliation (i.e. NOT really independent)?
-- Is anything subtler or more architectural than the simplicity gate assumed?
-
-Write your verdict to exactly:
-
-\`${verdictPath}\`
-
-\`\`\`json
-{
-  "schema_version": "${LEAN_LIGHT_REVIEW_SCHEMA_VERSION}",
-  "disposition": "clear | escalate",
-  "concerns": ["<required & non-empty when escalate; the concrete concern(s)>"],
-  "created_at": "<ISO-8601>"
-}
-\`\`\`
-
-- **clear** — the light pass surfaced no real concern; the lean path may proceed.
-- **escalate** — a genuine concern surfaced. This is evidence the change is harder than assessed; the run escalates to the full contract pipeline (full independent review). When in doubt, escalate — a wrong call costs extra pipeline work, never a skipped review.
-
-After writing the verdict, run:
-
-\`${nextCommand}\`
-`;
-}
-/**
- * The lean light-review gate. Idempotent across next-step calls: once a decision
- * is recorded it is consumed directly. Returns a halt step while awaiting the
- * host's verdict, then `clear` (proceed to the lean plan) or `escalate` (route to
- * the full pipeline with the concerns).
- */
-async function runLeanLightReviewGate(root, artifactsDir, approved) {
-    const decisionPath = leanLightReviewDecisionPath(artifactsDir);
-    const existing = await readOptionalJsonFile(decisionPath);
-    if (existing) {
-        return existing.disposition === "clear"
-            ? { kind: "clear" }
-            : { kind: "escalate", concerns: existing.concerns ?? [] };
-    }
-    const verdictPath = leanLightReviewVerdictPath(artifactsDir);
-    if (!existsSync(verdictPath)) {
-        const step = await writeCurrentStep({
-            stepKind: "lean_light_review",
-            status: "ready",
-            runId: randomRunId("LEANREVIEW"),
-            repoRoot: root,
-            artifactsDir,
-            prompt: leanLightReviewPrompt(approved, verdictPath),
-            allowedCommands: [loaderCommand("next-step")],
-            stopCondition: "Stop after writing the lean light-review verdict and running next-step.",
-            artifactPaths: { lean_light_review_verdict: verdictPath },
-        });
-        return { kind: "halt", step };
-    }
-    // Verdict present → interpret + record a durable decision, then archive the
-    // consumed verdict so the gate can never re-emit.
-    const raw = await readOptionalJsonFile(verdictPath);
-    const interp = interpretLeanLightReviewVerdict(raw);
-    const record = {
-        schema_version: LEAN_LIGHT_REVIEW_SCHEMA_VERSION,
-        disposition: interp.disposition,
-        concerns: interp.concerns,
-        created_at: new Date().toISOString(),
-    };
-    await writeJsonFile(decisionPath, record);
-    if (existsSync(verdictPath)) {
-        await withFsRetry(() => rename(verdictPath, `${verdictPath}.consumed-${Date.now()}`));
-    }
-    return interp.disposition === "clear"
-        ? { kind: "clear" }
-        : { kind: "escalate", concerns: interp.concerns };
-}
 /**
  * Re-emit the autonomous-run leftovers (findings left LIVE, neither auto-fixed
  * nor durably rejected) as a standard, re-consumable audit deliverable pair:
@@ -1517,22 +1417,13 @@ async function handleReadyIntakeContractPipeline(root, artifactsDir, options, ru
             }
             // Persist the filter dispositions so coverage is built over the originals.
             await persistReviewFilterDispositions(artifactsDir, originals, filter);
-            // Lean path = the `low` risk tier's realization (D-68 — the standalone lean
-            // fast-path folded into the self-scaling dial; its two mechanisms now live in
-            // `riskSignal.ts` (light-review) + `contractPipeline.ts` (lean plan builder)).
-            // A run skips the heavy contract DESIGN loop and
-            // synthesizes the extracted plan directly IFF its effective risk tier is `low`;
-            // the plan→implement→close machinery (per-node verify-before-merge + the final
-            // whole-repo gate) is the retained safety net. Runs only here — on Path A
-            // (structured_audit), the only intake with a pre-existing finding set to judge.
-            //
-            // First fold the APPROVED set's finding-level risk (grounding / confidence /
+            // Fold the APPROVED set's finding-level risk (grounding / confidence /
             // coupling / systemic / architecture / count — the finding-QUALITY dimension the
             // intake path/breadth/intent signal doesn't see) INTO the shared risk signal as
-            // escalate-on-evidence. This makes the tier the SINGLE classifier: there is no
-            // separate fast-path boolean that can DISAGREE with it (a grounded handful
-            // touching a risk subsystem stays `high` and takes the full pipeline, instead of
-            // bypassing it as the old parallel `evaluateFastPath` allowed).
+            // escalate-on-evidence. The tier is the SINGLE classifier and the ONLY thing it
+            // selects is DEPTH: every run enters the contract pipeline, and a `low` tier
+            // traverses it shallowly (collapsed round-trips, light adversarial depth). There
+            // is no second plan producer and no bypass — see COLLAPSE_GROUPS.
             const findingEvidence = findingRiskEvidence(gate.approved);
             let riskSignal = await readIntakeRiskSignal(artifactsDir);
             if (findingEvidence && riskSignal) {
@@ -1544,62 +1435,6 @@ async function handleReadyIntakeContractPipeline(root, artifactsDir, options, ru
                     await writeIntakeRiskSignal(artifactsDir, riskSignal);
                 }
             }
-            // T1 slice 3b — the lean tier is NOT zero-scrutiny: a `low`-tier run first runs
-            // a bounded LIGHT adversarial review over the approved findings (the floor,
-            // never off — `adversarialDepthForTier("low") === "light"`). A clear verdict
-            // proceeds to the lean plan; a verdict that surfaces a real concern escalates
-            // the risk signal and routes to the full pipeline below.
-            if (gate.approved.length > 0 && riskSignal?.tier === "low") {
-                const review = await runLeanLightReviewGate(root, artifactsDir, gate.approved);
-                if (review.kind === "halt") {
-                    return review.step;
-                }
-                if (review.kind === "escalate") {
-                    // Escalate-on-evidence: raise the signal to at least `medium` so the
-                    // full pipeline's adversarial depth is `full` (see slice 3a), then
-                    // fall through to the full pipeline.
-                    await writeIntakeRiskSignal(artifactsDir, escalateRiskSignal(riskSignal, {
-                        tier: "medium",
-                        reason: `lean light review surfaced a concern: ${review.concerns.join("; ")}`,
-                    }));
-                    runLogger.event({
-                        phase: "next-step",
-                        kind: "outcome",
-                        obligation: "lean_fast_path",
-                        note: `lean_fast_path_escalated concerns=${String(review.concerns.length)} ` +
-                            `detail=${review.concerns.join("; ")}`,
-                    });
-                    process.stderr.write(`[remediate-code] Lean light review escalated (${review.concerns.join("; ")}); routing to the full contract pipeline.\n`);
-                }
-                else {
-                    // Clear verdict → proceed with the lean plan.
-                    const leanPlan = buildLeanExtractedPlan(gate.approved, randomRunId("LEAN"));
-                    await writeJsonFile(intakePaths(artifactsDir).extractedPlan, leanPlan);
-                    runLogger.event({
-                        phase: "next-step",
-                        kind: "outcome",
-                        obligation: "lean_fast_path",
-                        note: `lean_fast_path_routed findings=${String(gate.approved.length)} ` +
-                            `rationale=${riskSignal.rationale.join("; ")}`,
-                    });
-                    process.stderr.write(`[remediate-code] Lean fast path (risk tier low): ${riskSignal.rationale.join("; ")}; light review clear. Routing to plan→implement.\n`);
-                    const planned = await handlePendingExtractedPlan(root, artifactsDir, { status: "pending" }, leanPlan, runLogger);
-                    if (planned) {
-                        return planned;
-                    }
-                    // Defensive: a deterministically-built lean plan should always
-                    // normalize. If it somehow didn't, handlePendingExtractedPlan removed
-                    // the file; fall through to the full pipeline (the safety net) rather
-                    // than stalling the run.
-                    runLogger.event({
-                        phase: "next-step",
-                        kind: "outcome",
-                        obligation: "lean_fast_path",
-                        note: "lean_fast_path_fallback plan failed to materialize; routing to the contract pipeline",
-                    });
-                    process.stderr.write("[remediate-code] Lean fast-path plan failed to materialize; falling back to the contract pipeline.\n");
-                }
-            }
             // Seed the pipeline with the approved survivors only. When that set is
             // narrower than the originals (anything filtered or declined), route the
             // seed AND the pipeline's source inputs at a filtered file so a removed
@@ -1855,13 +1690,20 @@ async function applyPlanClarificationResolution(root, artifactsDir, state, store
     // their questions unanswered. Load-bearing now that the round runs at the
     // DRAINED end of the implement phase, where `remainingPending` is normally
     // false — the fall-through it guards is the common case, not a corner.
+    // INV-RS-10 / OBL-seam-prep-remediate-core-inv-1: a resolution that disposes
+    // of every remaining item does NOT write `closing` here. Writing it directly
+    // satisfied the all_terminal derive (`status !== "closing"`) on the very next
+    // scan, so the tool-owned final gate never ran for this arrival at close.
+    // Landing in `implementing` lets the single all-terminal → closing funnel
+    // (handleAllTerminalTransition) run the gate, exactly as every other closing
+    // transition does; `closing_plan` is stamped by that funnel's successor, not
+    // pre-stamped here (the gate-red pause must not leave a half-prepared close).
     state.status = remainingPending
         ? "implementing"
         : hasUnansweredClarification(state)
             ? "waiting_for_clarification"
-            : "closing";
+            : "implementing";
     state.clarifications = [];
-    state.closing_plan ??= { action: "none" };
     await store.saveState(state);
     return { kind: "applied", state };
 }
@@ -2132,9 +1974,8 @@ async function handlePlanning(root, artifactsDir, state, store) {
         if (halt)
             return { kind: "emit", step: halt };
     }
-    // Document phase dissolved: planning transitions directly to implementing.
-    // The host workload reads item_spec from the plan DAG node when present, or
-    // uses finding context directly when absent.
+    // Document phase dissolved (N-R13): planning transitions directly to
+    // implementing, and the host workload reads finding context directly.
     const implementBlocks = implementableBlocks(state);
     if (implementBlocks.length > 0) {
         if (state.plan) {
@@ -2197,11 +2038,29 @@ async function handlePlanning(root, artifactsDir, state, store) {
     await store.saveState(state);
     return { kind: "transition", state };
 }
-async function handleImplementing(root, artifactsDir, state, runLogger, store) {
+async function handleImplementing(root, artifactsDir, state, runLogger, store, options) {
     const triageStart = Date.now();
     runLogger.event({ phase: "next-step", kind: "executor_start", obligation: state.status, note: "triage" });
     const triaged = await runTriagePhase(state, { root, artifactsDir });
     runLogger.event({ phase: "next-step", kind: "executor_end", obligation: state.status, note: "triage", duration_ms: Date.now() - triageStart });
+    // INV-RS-10 / OBL-seam-prep-remediate-core-inv-1..4 (the CP-NODE-3 review
+    // finding): this is the ONE caller of runTriagePhase, shared by the
+    // `implementing` and `triage` obligations, so it is also THE single seam
+    // where a triage closing-intent crosses into close. Persisting
+    // `status: "closing"` directly would satisfy the closing obligation on the
+    // next scan and preempt the all-terminal → closing funnel's tool-owned final
+    // gate — exactly the defect class the finding named. So the intent is
+    // persisted under the NON-closing `triage` status first (keeping every
+    // preparation runTriagePhase made — halted items already converted to
+    // `abandoned`, `closing_context` stamped — so a gate-RED pause, which persists
+    // nothing itself, cannot lose them: re-entering triage with zero blocked items
+    // re-derives this exact intent instead of auto-retrying halted work), and only
+    // then handed to the funnel, which runs the gate and owns the closing stamp.
+    if (triaged.status === "closing") {
+        const prepared = { ...triaged, status: "triage" };
+        await store.saveState(prepared);
+        return handleAllTerminalTransition(root, artifactsDir, prepared, store, options, runLogger);
+    }
     await store.saveState(triaged);
     return { kind: "transition", state: triaged };
 }
@@ -2763,7 +2622,7 @@ To confirm, write the final checkpoint to:
   "intent_summary": "${draft.intent_summary ?? "<the goal>"}",
   "free_form_intent": "<optional: additional guidance>",
   "filters": ${JSON.stringify(draft.filters ?? {}, null, 2)},
-  "excluded_scope": [],
+  "excluded_scope": [{ "path": "<path or prefix>", "reason": "<why>" }],
   "must_not_touch": []
 }
 \`\`\`
@@ -2846,7 +2705,11 @@ Once the file is written, run:
 // on an LLM-authored free-text `intent_interpretation`.
 /** Sidecar artifact recording the deterministic interpretation of free_form_intent. */
 export const INTENT_INTERPRETATION_FILENAME = "intent-interpretation.json";
-export const INTENT_INTERPRETATION_SCHEMA_VERSION = "remediate-code-intent-interpretation/v1alpha1";
+// v1alpha2: unencodable_clauses carries identity-keyed records (clause_id +
+// checkpoint_question), not bare strings — the shape the blocking consumer
+// reads. A v1alpha1 sidecar (string[]) is stale and is repaired by
+// re-derivation; it had no readers, so no migration path is owed.
+export const INTENT_INTERPRETATION_SCHEMA_VERSION = "remediate-code-intent-interpretation/v1alpha2";
 /**
  * Interpret a confirmed checkpoint's `free_form_intent` via the shared
  * deterministic interpreter and persist the structured signals to a sidecar
@@ -2866,33 +2729,99 @@ runLogger) {
     if (typeof raw !== "string" || raw.trim().length === 0)
         return null;
     const interpreted = interpretFreeFormIntent(raw);
+    // The clause pipeline (interpretIntent) owns identity + blocking questions;
+    // the hint interpreter above owns lens/priority/scope signals. Both are
+    // deterministic draws over the same input.
+    const clauseResult = interpretIntent(raw);
+    const unencodable_clauses = [];
+    for (const clause of clauseResult.clauses) {
+        if (clause.encodable || !clause.checkpoint_question)
+            continue;
+        unencodable_clauses.push({
+            clause_id: clause.clause_id,
+            text: clause.text,
+            checkpoint_question: clause.checkpoint_question,
+        });
+    }
     const persisted = {
         schema_version: INTENT_INTERPRETATION_SCHEMA_VERSION,
         interpreted,
-        unencodable_clauses: interpreted.unencodableClauses,
+        unencodable_clauses,
         created_at: new Date().toISOString(),
     };
     try {
         await writeJsonFile(join(artifactsDir, INTENT_INTERPRETATION_FILENAME), persisted);
     }
     catch {
-        // Best-effort sidecar: a write failure must never block the decide loop.
+        // Best-effort WRITE: a write failure must never crash the decide loop.
+        // Enforcement does not depend on it — the consumer re-derives when the
+        // sidecar is missing (readOrRepairIntentInterpretation).
     }
-    if (interpreted.unencodableClauses.length > 0) {
+    if (unencodable_clauses.length > 0) {
+        const clauseTexts = unencodable_clauses.map((c) => c.text);
         runLogger?.event({
             phase: "next-step",
             kind: "outcome",
             obligation: "interpret_intent",
-            note: `intent_unencodable_clauses count=${String(interpreted.unencodableClauses.length)} ` +
-                `clauses=${interpreted.unencodableClauses.join("; ")}`,
+            note: `intent_unencodable_clauses count=${String(unencodable_clauses.length)} ` +
+                `clauses=${clauseTexts.join("; ")}`,
         });
-        process.stderr.write(`[remediate-code] free_form_intent: ${interpreted.unencodableClauses.length} ` +
-            `clause(s) could not be encoded as lens/priority/scope signals and are ` +
-            `surfaced for promotion to constraints: ` +
-            `${interpreted.unencodableClauses.join("; ")}\n`);
+        process.stderr.write(`[remediate-code] free_form_intent: ${unencodable_clauses.length} ` +
+            `clause(s) could not be encoded as lens/priority/scope signals and ` +
+            `block planning until answered via constraint_clauses: ` +
+            `${clauseTexts.join("; ")}\n`);
     }
     return persisted;
 }
+/**
+ * Read the persisted intent interpretation — the LOAD-BEARING input to the
+ * constraint-clause gate — repairing it by re-derivation when it is missing,
+ * unparseable, or carries a stale schema_version. Returns null only when
+ * there is nothing to interpret (no confirmed checkpoint / empty intent).
+ */
+export async function readOrRepairIntentInterpretation(artifactsDir, checkpoint, runLogger) {
+    if (!checkpoint || checkpoint.confirmed_by !== "host")
+        return null;
+    const raw = checkpoint.free_form_intent;
+    if (typeof raw !== "string" || raw.trim().length === 0)
+        return null;
+    const sidecarPath = join(artifactsDir, INTENT_INTERPRETATION_FILENAME);
+    try {
+        const parsed = parsePersistedIntentInterpretation(JSON.parse(await readFile(sidecarPath, "utf8")));
+        if (parsed)
+            return parsed;
+    }
+    catch {
+        // Missing or unreadable — fall through to repair.
+    }
+    return interpretConfirmedCheckpointIntent(artifactsDir, checkpoint, runLogger);
+}
+/** Pure shape gate for the sidecar: current version + record-shaped clauses, else null. */
+function parsePersistedIntentInterpretation(parsed) {
+    if (isRecord(parsed) &&
+        parsed.schema_version === INTENT_INTERPRETATION_SCHEMA_VERSION &&
+        Array.isArray(parsed.unencodable_clauses) &&
+        parsed.unencodable_clauses.every((c) => isRecord(c) &&
+            typeof c.clause_id === "string" &&
+            typeof c.text === "string" &&
+            typeof c.checkpoint_question === "string")) {
+        return parsed;
+    }
+    return null;
+}
+/**
+ * Sync sidecar read for the obligation's derive scan. Returns the persisted
+ * interpretation, or null when the sidecar is missing, unreadable, or stale —
+ * the execute path repairs via {@link readOrRepairIntentInterpretation}.
+ */
+function readPersistedIntentInterpretationSync(sidecarPath) {
+    try {
+        return parsePersistedIntentInterpretation(JSON.parse(readFileSync(sidecarPath, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Narrow a nullable engine state to non-null inside an executor whose `derive`
  * only marks it actionable when the state is present — a violation is an engine
@@ -3020,19 +2949,81 @@ function buildPreIntakeObligations(ctx, snapshot) {
         },
         {
             // Past the intent gate: interpret the confirmed checkpoint's
-            // free_form_intent once (INV-S04) and persist the structured signals. A
-            // transition (state unchanged) — the re-scan skips it once the sidecar
-            // exists.
+            // free_form_intent once (INV-S04), persist the structured signals, and
+            // ENFORCE the unencodable-clause contract: an unanswered clause blocks
+            // the decide loop until the host resolves it via a `constraint_clauses`
+            // entry on the checkpoint (CE-004, identity-keyed — the shared matcher
+            // in audit-tools/shared intent/constraintClauses.ts, the same core the
+            // audit gate uses). The PERSISTED sidecar is the consumed input; a
+            // missing or stale sidecar is repaired by re-derivation, never skipped.
             id: "interpret_intent",
-            derive: () => existingCheckpoint?.confirmed_by === "host" &&
-                typeof existingCheckpoint.free_form_intent === "string" &&
-                existingCheckpoint.free_form_intent.trim().length > 0 &&
-                !existsSync(interpretationPath)
-                ? "missing"
-                : "satisfied",
+            derive: () => {
+                if (existingCheckpoint?.confirmed_by !== "host" ||
+                    typeof existingCheckpoint.free_form_intent !== "string" ||
+                    existingCheckpoint.free_form_intent.trim().length === 0) {
+                    return "satisfied";
+                }
+                const sidecar = readPersistedIntentInterpretationSync(interpretationPath);
+                if (sidecar === null)
+                    return "missing";
+                return unresolvedFromClauses(sidecar.unencodable_clauses, existingCheckpoint)
+                    .length > 0
+                    ? "missing"
+                    : "satisfied";
+            },
             execute: async (state, c) => {
-                await interpretConfirmedCheckpointIntent(artifactsDir, existingCheckpoint, c.runLogger);
-                return { kind: "transition", state };
+                const persisted = await readOrRepairIntentInterpretation(artifactsDir, existingCheckpoint, c.runLogger);
+                const unresolved = persisted
+                    ? unresolvedFromClauses(persisted.unencodable_clauses, existingCheckpoint)
+                    : [];
+                if (unresolved.length === 0)
+                    return { kind: "transition", state };
+                const nextCommand = loaderCommand("next-step");
+                const checkpointPath = join(artifactsDir, "intent_checkpoint.json");
+                const clauseLines = unresolved
+                    .map((clause) => `- **${clause.clause_id}** — "${clause.text}"\n  Question: ${clause.checkpoint_question}`)
+                    .join("\n");
+                const prompt = `
+# Resolve Free-Form Intent Constraints
+
+${unresolved.length} clause(s) of the confirmed checkpoint's \`free_form_intent\` could
+not be encoded as lens/priority/scope signals. Each needs an explicit answer
+before planning proceeds — an unanswered clause would otherwise be silently
+dropped.
+
+${clauseLines}
+
+Answer each clause by adding a \`constraint_clauses\` entry to
+\`intent_checkpoint.json\` (keep the exact \`clause_id\` — answers are keyed on
+clause identity, not on the question text):
+
+\`\`\`json
+"constraint_clauses": [
+  { "clause_id": "<the clause_id above>", "text": "<the clause text>", "checkpoint_question": "<the question above>", "host_answer": "<how to apply this constraint>" }
+]
+\`\`\`
+
+Then run:
+
+\`${nextCommand}\`
+`;
+                return {
+                    kind: "emit",
+                    step: await writeCurrentStep({
+                        stepKind: "confirm_intent",
+                        status: "blocked",
+                        runId: stateRunId(state),
+                        repoRoot: c.root,
+                        artifactsDir,
+                        prompt,
+                        allowedCommands: [nextCommand],
+                        stopCondition: "Stop after adding constraint_clauses answers to intent_checkpoint.json and running next-step.",
+                        artifactPaths: {
+                            intent_checkpoint: checkpointPath,
+                            intent_interpretation: interpretationPath,
+                        },
+                    }),
+                };
             },
         },
         {
@@ -3261,13 +3252,13 @@ function buildMainObligations(ctx) {
                         return { kind: "transition", state: s };
                     }
                 }
-                return handleImplementing(root, artifactsDir, s, runLogger, store);
+                return handleImplementing(root, artifactsDir, s, runLogger, store, options);
             },
         },
         {
             id: "triage",
             derive: (state) => (state?.status === "triage" ? "missing" : "satisfied"),
-            execute: async (state) => handleImplementing(root, artifactsDir, requireState(state), runLogger, store),
+            execute: async (state) => handleImplementing(root, artifactsDir, requireState(state), runLogger, store, options),
         },
         {
             // planning with zero documentable findings is a user question, not a