audit-tools 0.50.11 → 0.50.13

package/dist/remediate/steps/contractPipeline.js

@@ -24,17 +24,17 @@ import { mkdir, readFile, rename, rm } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { writeJsonFile, readOptionalJsonFile, formatValidationIssues, hashContent, isRecord, withFsRetry, projectApprovedFindings, captureStepBoundaryFriction, climbOutOfAuditTools, partitionCommandsByDeclaredShape, normalizeRepoPath, repoRelativePath, toPosixPath, } from "audit-tools/shared";
 import { createStepEmissionScaffold, } from "../../shared/steps/stepEmissionScaffold.js";
-import { counterexampleFingerprint } from "../contractPipeline/counterexampleFingerprint.js";
 import { OBLIGATION_KIND_PRIORITY, } from "../contractPipeline/obligationKinds.js";
 import { CP_ARTIFACT_NAMES, contractArtifactExists, contractArtifactFilePath, contractInputFilePath, contractPipelineDir, detectStaleArtifacts, envelopePayload, envelopeSemanticHash, isEnvelope, pathASeedFilePath, payloadSemanticHash, readContractArtifact, stampToolCreatedAt, writeContractArtifact, writeDerivedContractArtifact, } from "../contractPipeline/artifactStore.js";
 import { readIntakeRiskSignal, writeIntakeRiskSignal, escalateRiskSignal, decompositionRiskEvidence, adversarialDepthForTier, roundTripGranularityForTier, } from "../riskSignal.js";
-import { phaseOrdinalForObligations, moduleSlug, renderPhaseCutSection, } from "../contractPipeline/phaseCut.js";
+import { phaseOrdinalForObligations, moduleSlug, moduleSlugForObligationId, renderPhaseCutSection, detectContractTokenCycles, } from "../contractPipeline/phaseCut.js";
 import { ensurePhaseCutArtifact, readPhaseCutArtifact } from "../contractPipeline/phaseCutArtifact.js";
 import { detectCyclicSeamObligations, validateAuthoredCycleBreak, } from "../contractPipeline/cyclicSeamResolution.js";
 import { deriveObligationLedger, deriveFinalizedModuleContracts, buildTestValidatorPlanScaffold, buildImplementationDagScaffold, acceptedCounterexampleIds, advisoryCritiqueItems, } from "../contractPipeline/derive.js";
 import { ensureNodeId, toBlockId } from "../contractPipeline/idRegistry.js";
 import { captureReviewSnapshot, computeReReviewDelta, isReviewArtifact, readReviewSnapshot, renderReReviewSection, reviewSnapshotExists, } from "../contractPipeline/reviewSnapshot.js";
 import { captureTestPlanCarry, readTestPlanCarry, } from "../contractPipeline/testPlanCarry.js";
+import { readRepairState, writeRepairState, counterexamplesByIdOf, counterexampleKeyOf, counterexampleWaiversPath, foldCounterexampleWaivers, waivedAcceptedIds, waivedJudgeAcceptedIds, } from "../contractPipeline/repairState.js";
 import { renderContractPipelinePrompt, renderContractRepairPrompt, CONTRACT_PIPELINE_PHASE_ORDER, PHASE_TO_ARTIFACT, } from "./contractPipelinePrompts.js";
 // The seven cross-artifact validators this module used to call one by one are
 // gone from this list on purpose: every one of them is now reached through
@@ -123,22 +123,6 @@ export const MAX_DAG_REGENERATION_ATTEMPTS = 2;
  * (and, if that also fails, to `blocked`).
  */
 export const MAX_CYCLIC_SEAM_RESOLUTION_ATTEMPTS = 2;
-function repairStatePath(artifactsDir) {
-    return join(contractPipelineDir(artifactsDir), "repair-state.json");
-}
-async function readRepairState(artifactsDir) {
-    const state = await readOptionalJsonFile(repairStatePath(artifactsDir));
-    return (state ?? {
-        schema_version: "remediate-code-contract-pipeline/repair-state/v1alpha1",
-        repairs: [],
-        critique_repairs: [],
-        dag_regenerations: [],
-    });
-}
-async function writeRepairState(artifactsDir, state) {
-    await mkdir(contractPipelineDir(artifactsDir), { recursive: true });
-    await writeJsonFile(repairStatePath(artifactsDir), state);
-}
 function cyclicSeamRepairStatePath(artifactsDir) {
     return join(contractPipelineDir(artifactsDir), "cyclic-seam-repair-state.json");
 }
@@ -561,7 +545,47 @@ async function evaluateJudgeGate(artifactsDir) {
     const judge = envelopePayload(judgeEnvelope);
     if (!judge || judge.verdict === "approved")
         return { kind: "proceed" };
+    // Content-fingerprint keying (not raw id): two independent adversarial
+    // rounds may each label their genuinely-distinct top counterexample with
+    // the SAME reviewer id string (e.g. "CE-001", the prompt schema's own
+    // example value). Keying convergence on the raw id would then read "same CE
+    // re-accepted after a repair" and falsely escalate while a real new defect
+    // is being correctly repaired. Resolve each accepted id against the live
+    // counterexample artifact and key on content instead; an id with no
+    // matching counterexample falls back to raw-id keying — today's behavior —
+    // so nothing regresses when content can't be resolved. The keying is
+    // single-sourced with the waiver ledger (counterexampleKeyOf).
+    const cePayload = envelopePayload(await readContractArtifact(artifactsDir, "counterexample"));
+    const ceById = counterexamplesByIdOf(cePayload);
+    const keyOf = (rawId) => counterexampleKeyOf(ceById, rawId);
+    const acceptedIds = acceptedCeIdsOf(judge);
+    // Owner waivers (open-bugs.md:108, the recorded resolution verb): fold the
+    // host-written waiver file BEFORE any convergence math, so a waiver recorded
+    // against a blocked escalation unblocks this same invocation — including one
+    // recorded after a repair for this judge hash was already dispatched. An
+    // invalid file escalates loudly and applies NOTHING (never half-applied).
+    const fold = await foldCounterexampleWaivers(artifactsDir, {
+        counterexamplesById: ceById,
+        judgeAcceptedIds: new Set(acceptedIds),
+    });
+    if (fold.issues.length > 0) {
+        return {
+            kind: "escalate",
+            reason: "invalid_waivers",
+            outstanding: acceptedIds,
+            waiverIssues: fold.issues,
+            note: "The counterexample waiver file was refused and nothing was applied. " +
+                "Fix or delete it, then re-run next-step.",
+        };
+    }
     const repairState = await readRepairState(artifactsDir);
+    const waived = waivedAcceptedIds(repairState, ceById, acceptedIds);
+    const unwaivedAccepted = acceptedIds.filter((id) => !waived.has(id));
+    // Every accepted counterexample carries a recorded owner waiver → the
+    // needs_repair verdict is resolved by decision: proceed.
+    if (acceptedIds.length > 0 && unwaivedAccepted.length === 0) {
+        return { kind: "proceed" };
+    }
     const judgeHash = judgeEnvelope.content_hash;
     const alreadyHandled = repairState.repairs.some((repair) => repair.judge_hash === judgeHash);
     // Map judge.repair_directive.target if present; if absent, infer from classifications.
@@ -574,25 +598,9 @@ async function evaluateJudgeGate(artifactsDir) {
             instruction: rawDirective.instruction,
         }
         : inferRepairDirective(judge);
-    const acceptedIds = acceptedCeIdsOf(judge);
-    // Content-fingerprint keying (not raw id): two independent adversarial
-    // rounds may each label their genuinely-distinct top counterexample with
-    // the SAME reviewer id string (e.g. "CE-001", the prompt schema's own
-    // example value). Keying convergence on the raw id would then read "same CE
-    // re-accepted after a repair" and falsely escalate while a real new defect
-    // is being correctly repaired. Resolve each accepted id against the live
-    // counterexample artifact and key on content instead; an id with no
-    // matching counterexample falls back to raw-id keying — today's behavior —
-    // so nothing regresses when content can't be resolved.
-    const cePayload = envelopePayload(await readContractArtifact(artifactsDir, "counterexample"));
-    const ceById = new Map((cePayload?.counterexamples ?? []).map((ce) => [ce.id, ce]));
-    const keyOf = (rawId) => {
-        const ce = ceById.get(rawId);
-        return ce ? `fp:${counterexampleFingerprint(ce)}` : `id:${rawId}`;
-    };
     const addressed = new Set(repairState.repairs.flatMap((r) => r.addressed_ce_fingerprints ??
         (r.accepted_ce_ids ?? []).map((id) => `id:${id}`)));
-    const newAccepted = acceptedIds.filter((id) => !addressed.has(keyOf(id)));
+    const newAccepted = unwaivedAccepted.filter((id) => !addressed.has(keyOf(id)));
     const newAcceptedFingerprints = newAccepted.map(keyOf);
     // Idempotent re-entry: this exact judge report already drove a repair (its hash
     // is recorded). Re-emit the same repair directive; do not re-evaluate convergence
@@ -611,7 +619,7 @@ async function evaluateJudgeGate(artifactsDir) {
         return {
             kind: "escalate",
             reason: "runaway",
-            outstanding: acceptedIds,
+            outstanding: unwaivedAccepted,
             note: `The judge↔repair loop reached its runaway backstop (${repairState.repairs.length} repair rounds) without converging. Each round was still surfacing accepted counterexamples. This is pathological non-convergence — review the outstanding counterexamples and the contract design with the user before proceeding.`,
         };
     }
@@ -630,8 +638,8 @@ async function evaluateJudgeGate(artifactsDir) {
     return {
         kind: "escalate",
         reason: "stall",
-        outstanding: acceptedIds,
-        note: `The judge re-accepted counterexample(s) that a prior repair already addressed (${acceptedIds.join(", ") || "none newly accepted"}), with no new accepted counterexample this round. The repair loop is not converging on these items. Resolve them with the user — adjust the contract design or accept the counterexamples as known limitations — before the plan can be promoted.`,
+        outstanding: unwaivedAccepted,
+        note: `The judge re-accepted counterexample(s) that a prior repair already addressed (${unwaivedAccepted.join(", ") || "none newly accepted"}), with no new accepted counterexample this round. The repair loop is not converging on these items. Resolve them with the user — adjust the contract design, or record an owner waiver accepting them as known limitations — before the plan can be promoted.`,
     };
 }
 /** Blocking-severity critique item ids from a conceptual_design_critique payload. */
@@ -1485,7 +1493,16 @@ async function readCrossGateInputs(artifactsDir, root) {
             payloads.set(name, envelopePayload(envelope));
     }
     const findingEnumeration = await readOptionalJsonFile(intakePaths(artifactsDir).findingEnumeration);
-    return { payloads, findingEnumeration, root };
+    // Waived counterexamples (open-bugs.md:108): the coverage gates must not
+    // demand DAG nodes for a counterexample the owner recorded as an accepted
+    // limitation — that would recreate the judge-gate wedge one gate later.
+    const repairState = await readRepairState(artifactsDir);
+    return {
+        payloads,
+        findingEnumeration,
+        root,
+        waivedCounterexampleIds: waivedJudgeAcceptedIds(repairState, payloads.get("judge_report"), payloads.get("counterexample")),
+    };
 }
 /**
  * Read every contract-pipeline payload FRESH for the shared cross-gates.
@@ -1922,21 +1939,56 @@ const degenerateSeamReconciliationGate = async (ctx) => {
     });
     return { via: "rederive" };
 };
+/** Render the cycle section for the LLM finalization step: every declared-graph
+ *  cycle, its members, and the exact artifact tokens forming each edge. */
+function renderTokenCycleSection(cycles) {
+    const parts = cycles.map((cycle, i) => {
+        const edges = cycle.edges
+            .map((e) => `- \`${e.consumer}\` depends on \`${e.producer}\` via \`artifact:${e.artifact}\` ` +
+            `(${e.consumer} consumes it; ${e.producer} produces it)`)
+            .join("\n");
+        return `### Cycle ${i + 1}: [${cycle.members.join(", ")}]\n\n${edges}`;
+    });
+    return `## Cyclic Artifact-Token Dependencies — Resolve These In Your Output
+
+The drafted contracts declare a CYCLIC artifact-token flow. Implementation ordering derives from
+producer/consumer \`artifact:<name>\` tokens ALONE, so the declared flow must be acyclic — a cycle
+cannot be phased, and the finalized contracts are REJECTED at validation while one remains.
+
+${parts.join("\n\n")}
+
+Rewrite the finalized \`inputs\`/\`outputs\` so one direction owns each flow: move an artifact token
+to the module that genuinely produces it, split a shared primitive into an earlier module's output,
+or drop a token that does not describe a real data handoff. Keep the module SET unchanged — do not
+add, drop, rename, or merge modules.`;
+}
 /**
  * Deterministic contract_finalization (all module counts). Finalization is a
- * mechanical merge, not fresh authoring: carry each drafted module contract
- * verbatim (preserving neighbor_needs for the ordering derivation) and attach
+ * mechanical merge, not fresh authoring: carry each drafted module contract's
+ * interface fields verbatim (dropping neighbor_needs — ordering derives from
+ * the artifact-token graph alone, open-bugs.md:106) and attach
  * the agreed_interface of every seam that touches the module as a
  * seam_adjustment. The judgment already happened at seam_reconciliation.
  * Attaching each agreed interface verbatim guarantees the INV-CO-12
  * reconciliation-derivation gate passes. A downstream gate that still finds the
  * merge inadequate re-emits contract_finalization as an LLM step — the only path
- * that still needs judgment.
+ * that still needs judgment. A CYCLIC declared token graph takes that LLM path
+ * up front: the mechanical merge would carry the cycle verbatim into an
+ * artifact validation refuses, so the gate emits the finalization step with the
+ * cycle named instead of deriving.
  */
 const contractFinalizationDerivationGate = async (ctx) => {
     if (ctx.nextPhase !== "contract_finalization")
         return null;
     const drafted = envelopePayload(await readContractArtifact(ctx.artifactsDir, "module_contracts"));
+    const cycles = detectContractTokenCycles(drafted);
+    if (cycles.length > 0) {
+        return {
+            via: "phase",
+            phase: "contract_finalization",
+            extraSection: renderTokenCycleSection(cycles),
+        };
+    }
     const seamReport = envelopePayload(await readContractArtifact(ctx.artifactsDir, "seam_reconciliation_report"));
     await writeDerivedContractArtifact(ctx.artifactsDir, "finalized_module_contracts", deriveFinalizedModuleContracts(drafted, seamReport));
     return { via: "rederive" };
@@ -1988,19 +2040,44 @@ const judgeRepairGate = async (ctx) => {
             note: `Judge↔repair loop escalated (${gate.reason}): ${gate.note}`,
             category: "trap",
         }, "remediate-code");
+        const waiversPath = counterexampleWaiversPath(ctx.artifactsDir);
+        const waiverIssuesSection = gate.waiverIssues && gate.waiverIssues.length > 0
+            ? `\n\n## Waiver file refused — fix these first\n\n${gate.waiverIssues
+                .map((issue) => `- ${issue}`)
+                .join("\n")}`
+            : "";
+        const heading = gate.reason === "invalid_waivers"
+            ? "# The Counterexample Waiver File Was Refused"
+            : "# Judge↔Repair Loop Did Not Converge";
         return {
             via: "blocked",
-            prompt: `# Judge↔Repair Loop Did Not Converge
+            prompt: `${heading}
 
-${gate.note}
+${gate.note}${waiverIssuesSection}
 
-## Outstanding accepted counterexamples
+## Outstanding accepted counterexamples (unwaived)
 
 ${gate.outstanding.length > 0
                 ? gate.outstanding.map((id) => `- ${id}`).join("\n")
                 : "_(none newly accepted this round)_"}
 
-Read the judge_report and counterexample artifacts, decide with the user how to resolve each outstanding counterexample (revise the contract design and re-run, or accept it as a known limitation), then re-run next-step.`,
+## Record an owner waiver (the recorded resolution verb)
+
+To accept an outstanding counterexample as a KNOWN LIMITATION of this run, write the operator's decision to:
+
+\`${waiversPath}\`
+
+\`\`\`json
+{
+  "waivers": [
+    { "ce_id": "<id from the list above>", "rationale": "<why this is acceptable>", "waived_by": "<who decided>" }
+  ]
+}
+\`\`\`
+
+The next next-step validates the file, records each waiver in repair-state.json (attributable, content-fingerprint-keyed), consumes the file, and proceeds once every outstanding counterexample is repaired or waived. Record a waiver ONLY for a decision the operator actually made — the record names its decider.
+
+Read the judge_report and counterexample artifacts, decide with the user how to resolve each outstanding counterexample (revise the contract design and re-run, or record a waiver as above), then re-run next-step.`,
             stopCondition: "Stop — the contract pipeline is blocked on a non-converging judge↔repair loop pending a user decision.",
         };
     }
@@ -2585,7 +2662,7 @@ const parallelModuleWaveGate = async (ctx) => {
  * dependency-ordered foundations→consumers phasing, instead of rejecting an
  * arbitrary N-goal change as "over-scoped" and forcing the host to re-scope by
  * hand at intake. The cut is derived from the finalized module contracts'
- * directional neighbor_needs edges and PERSISTED as `phase_cut.json`, so the cut
+ * producer/consumer artifact-token edges and PERSISTED as `phase_cut.json`, so the cut
  * the critic sees and the cut the implementation-DAG promotion enforces are one
  * source. Only injected when there is a genuine multi-phase cut to communicate.
  */
@@ -2927,20 +3004,43 @@ export async function evaluatePromotedPlanWriteScope(artifactsDir, root) {
     for (const block of Array.isArray(plan?.blocks) ? plan.blocks : []) {
         const blockId = typeof block.block_id === "string" ? block.block_id : "(unnamed block)";
         const touched = Array.isArray(block.touched_files) ? block.touched_files : [];
-        for (const path of touched) {
-            if (typeof path !== "string")
-                continue;
-            const key = normalizeRepoPath(path);
-            const parent = key.includes("/") ? key.slice(0, key.lastIndexOf("/")) : "";
-            if (corpus.files.has(key) || parent === "" || corpus.directories.has(parent)) {
-                continue;
-            }
-            violations.push(`Block "${blockId}" declares the write-scope path "${path}", whose directory does ` +
-                `not exist in the tracked tree.`);
-        }
+        violations.push(...writeScopeCorpusViolations(corpus, touched.filter((path) => typeof path === "string"), `Block "${blockId}"`));
     }
     return violations.length > 0 ? { violations } : null;
 }
+/**
+ * The ONE tracked-tree membership rule for a declared write-scope path: legal
+ * when the file is tracked, sits at the repo root, or its parent directory
+ * exists in the tracked tree (a block legitimately creates NEW files in
+ * existing directories). Shared by the promotion gate above and the
+ * clarification scope-delta validation, so the two cannot drift.
+ */
+function writeScopeCorpusViolations(corpus, paths, label) {
+    const violations = [];
+    for (const path of paths) {
+        const key = normalizeRepoPath(path);
+        const parent = key.includes("/") ? key.slice(0, key.lastIndexOf("/")) : "";
+        if (corpus.files.has(key) || parent === "" || corpus.directories.has(parent)) {
+            continue;
+        }
+        violations.push(`${label} declares the write-scope path "${path}", whose directory does ` +
+            `not exist in the tracked tree.`);
+    }
+    return violations;
+}
+/**
+ * Tracked-tree parity for a POST-promotion write-scope widening
+ * (open-bugs.md:110): a clarification scope delta must clear the same rule the
+ * promotion gate enforced, or the delta lane becomes a bypass of it. Returns
+ * violation lines; [] on an unreadable tree (fail-open, exactly as the
+ * promotion gate degrades).
+ */
+export async function checkWriteScopePathsAgainstTrackedTree(root, paths, label) {
+    const corpus = await readTrackedWriteScopeCorpus(root);
+    if (!corpus)
+        return [];
+    return writeScopeCorpusViolations(corpus, paths, label);
+}
 export function normalizeBlockTargetedCommands(commands, blockId) {
     const partitioned = partitionCommandsByDeclaredShape(commands, (kind, raw) => kind === "empty"
         ? `Block "${blockId}" declares an empty targeted_commands entry.`
@@ -3078,6 +3178,36 @@ export async function promoteImplementationDagToExtractedPlan(artifactsDir, root
     }
     const lastOrdinal = Math.max(0, ...slugToOrdinal.values());
     const hasMultiPhase = phaseCut ? phaseCut.phases.length > 1 : false;
+    // Approved-contract attachment (open-bugs.md:474): resolve each node's
+    // obligation-id slugs against the finalized module contracts, so every
+    // promoted block carries VERBATIM the contract(s) it implements and the
+    // dispatch prompt can bind the worker to the approved interface — the
+    // workflow must never depend on the DAG author restating declared values.
+    const finalizedForBlocks = envelopePayload(await readContractArtifact(artifactsDir, "finalized_module_contracts"));
+    const contractByModuleName = new Map();
+    const contractSlugToName = new Map();
+    for (const mod of finalizedForBlocks?.module_contracts ?? []) {
+        if (isRecord(mod) && typeof mod.name === "string" && mod.name.length > 0) {
+            contractByModuleName.set(mod.name, mod);
+            contractSlugToName.set(moduleSlug(mod.name), mod.name);
+        }
+    }
+    const contractSlugsByLength = [...contractSlugToName.keys()].sort((a, b) => b.length - a.length);
+    const moduleContractsForNode = (node) => {
+        const names = new Set();
+        for (const obligationId of [
+            ...(node.satisfies_obligations ?? []),
+            ...(node.verification_obligation_ids ?? []),
+        ]) {
+            const slug = moduleSlugForObligationId(obligationId, contractSlugsByLength);
+            const name = slug === null ? undefined : contractSlugToName.get(slug);
+            if (name !== undefined)
+                names.add(name);
+        }
+        return [...names]
+            .sort((left, right) => compareCodeUnits(left, right))
+            .map((name) => ({ module: name, contract: contractByModuleName.get(name) }));
+    };
     // Root-cause fix for scope-less nodes: the DAG's write scope
     // (`output_files`/`files_likely_touched`) is host-authored and a coarse
     // "Remediate <module>" decomposition can leave it EMPTY, which promotes a
@@ -3271,6 +3401,7 @@ export async function promoteImplementationDagToExtractedPlan(artifactsDir, root
                 ...(node.verification_obligation_ids ?? []),
             ], slugToOrdinal, lastOrdinal)
             : undefined;
+        const blockModuleContracts = moduleContractsForNode(node);
         return {
             block_id: toBlockId(nodeId),
             items: canonicalItemsByNodeId.get(nodeId) ?? [nodeId],
@@ -3283,6 +3414,9 @@ export async function promoteImplementationDagToExtractedPlan(artifactsDir, root
             touched_files: touchedFiles,
             ...(phaseOrdinal !== undefined ? { phase_ordinal: phaseOrdinal } : {}),
             ...(targetedCommands.length > 0 ? { targeted_commands: targetedCommands } : {}),
+            ...(blockModuleContracts.length > 0
+                ? { module_contracts: blockModuleContracts }
+                : {}),
         };
     });
     const extractedPlan = {