@getripple/core 1.0.8 → 1.0.9

package/dist/change-intent.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultChangeIntentPath = exports.loadChangeIntent = exports.saveChangeIntent = exports.buildIntentDriftRepairPlan = exports.validateStagedCheckAgainstIntent = exports.buildAgentHandoffVerdict = exports.buildChangeIntentReadinessSnapshot = exports.buildChangeIntent = void 0;
+exports.appendRippleVerificationEvidence = exports.defaultChangeIntentPath = exports.loadChangeIntent = exports.saveChangeIntent = exports.buildIntentDriftRepairPlan = exports.buildRippleReviewPacket = exports.validateStagedCheckAgainstIntent = exports.buildVerificationCommandSuggestions = exports.buildAgentHandoffVerdict = exports.buildChangeIntentReadinessSnapshot = exports.buildChangeIntent = void 0;
 const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -90,6 +90,7 @@ function buildChangeIntent(plan, options = {}) {
         expectedSymbols,
         protectedContracts,
         verificationTargets: plan.verificationTargets,
+        verificationEvidence: [],
         readinessSnapshot: options.readinessSnapshot ?? fallbackReadinessSnapshot(),
         why: plan.why,
     };
@@ -141,17 +142,122 @@ function buildAgentHandoffVerdict(input) {
     };
 }
 exports.buildAgentHandoffVerdict = buildAgentHandoffVerdict;
+function buildVerificationCommandSuggestions(verificationVerdict) {
+    if (verificationVerdict.status !== "failed" &&
+        verificationVerdict.status !== "review") {
+        return [];
+    }
+    const latestEvidence = latestVerificationEvidenceByCommand(verificationVerdict.evidence);
+    const blockingEvidence = latestEvidence.filter((evidence) => evidence.status !== "passed");
+    const evidenceToRerun = blockingEvidence.length > 0 ? blockingEvidence : latestEvidence;
+    return evidenceToRerun
+        .map((evidence) => `ripple verify --run ${quoteCliArgument(evidence.command)} --intent latest`);
+}
+exports.buildVerificationCommandSuggestions = buildVerificationCommandSuggestions;
+function quoteCliArgument(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
 function validateStagedCheckAgainstIntent(staged, intent, options = {}) {
     const validation = buildIntentValidation(staged, intent, options);
     return {
         ...staged,
         requiresAttention: staged.requiresAttention || validation.requiresAttention,
         intentValidation: validation,
+        reviewPacket: buildRippleReviewPacket(staged, intent, validation),
         nextRequiredPhase: validation.nextRequiredPhase,
         nextRequiredAction: validation.nextRequiredAction,
     };
 }
 exports.validateStagedCheckAgainstIntent = validateStagedCheckAgainstIntent;
+function buildRippleReviewPacket(staged, intent, validation) {
+    const changedFiles = uniqueItems([
+        ...staged.files.map((file) => file.file),
+        ...staged.skippedFiles,
+        ...staged.missingFiles,
+    ]);
+    const changedSymbols = uniqueItems(staged.changedSymbols.map((symbol) => symbol.symbol));
+    const contractRiskSymbols = uniqueItems(staged.contractRisks.map((risk) => risk.symbol));
+    const outsideBoundaryFiles = uniqueItems([
+        ...validation.unplannedFiles,
+        ...validation.boundaryVerdict.changedOutsideBoundaryFiles,
+    ]);
+    const outsideBoundarySymbols = uniqueItems([
+        ...validation.unplannedSymbols,
+        ...validation.boundaryVerdict.changedOutsideBoundarySymbols,
+    ]);
+    const verificationTargets = uniqueItems([
+        ...intent.verificationTargets,
+        ...staged.files.flatMap((file) => file.verificationTargets),
+    ]);
+    const mustStop = validation.handoff.mustStop;
+    const verificationEvidence = normalizeVerificationEvidence(intent.verificationEvidence);
+    const reportedVerificationCommands = verificationEvidence
+        .filter((evidence) => evidence.source === "reported")
+        .map((evidence) => evidence.command);
+    const executedVerificationCommands = verificationEvidence
+        .filter((evidence) => evidence.source === "executed")
+        .map((evidence) => evidence.command);
+    return {
+        protocol: "ripple-review-packet",
+        version: 1,
+        intentId: intent.id,
+        originalTask: intent.task,
+        mode: staged.mode,
+        declaredScope: {
+            controlMode: intent.controlMode,
+            targetFile: intent.targetFile,
+            allowedFiles: validation.editableFiles,
+            allowedSymbols: validation.allowedSymbols,
+            humanGate: validation.humanGate,
+            boundaryRisk: validation.boundaryRisk,
+        },
+        actualChanges: {
+            changedFiles,
+            changedSymbols,
+            contractRiskSymbols,
+            skippedFiles: staged.skippedFiles,
+            missingFiles: staged.missingFiles,
+        },
+        scopeFindings: {
+            plannedFilesChanged: validation.plannedFilesChanged,
+            contextFilesChanged: validation.contextFilesChanged,
+            outsideBoundaryFiles,
+            outsideBoundarySymbols,
+            protectedContractChanges: validation.protectedContractChanges,
+            unplannedContractChanges: validation.unplannedContractChanges,
+        },
+        verification: {
+            expectedCommands: verificationTargets,
+            testsRun: verificationEvidence.length > 0
+                ? executedVerificationCommands.length > 0
+                    ? "executed"
+                    : "reported"
+                : "unknown",
+            status: validation.verificationVerdict.status,
+            decision: validation.verificationVerdict.decision,
+            reportedCommands: reportedVerificationCommands,
+            executedCommands: executedVerificationCommands,
+            evidence: verificationEvidence,
+            note: verificationEvidence.length > 0
+                ? executedVerificationCommands.length > 0
+                    ? "Ripple executed at least one verification command and recorded its exit code."
+                    : "Ripple recorded reported verification evidence; it did not independently execute these commands."
+                : verificationTargets.length > 0
+                    ? "Ripple found verification targets, but it cannot prove they were run from this packet alone."
+                    : "Ripple found no verification target; use the narrowest manual check before handoff.",
+        },
+        decision: {
+            canContinue: validation.handoff.canContinue,
+            mustStop,
+            needsHuman: validation.handoff.needsHuman,
+            verdict: validation.verdict,
+            nextRequiredAction: validation.nextRequiredAction,
+            recommendedAction: validation.recommendedAction,
+        },
+        reviewerNotes: buildReviewPacketNotes(validation, verificationTargets),
+    };
+}
+exports.buildRippleReviewPacket = buildRippleReviewPacket;
 function buildIntentDriftRepairPlan(staged) {
     const validation = staged.intentValidation;
     const verificationTargets = uniqueItems(staged.files.flatMap((file) => file.verificationTargets));
@@ -212,6 +318,7 @@ function buildIntentDriftRepairPlan(staged) {
         policyExplanation: validation.policyExplanation,
         policyDrift: validation.policyDrift,
         readinessDrift: validation.readinessDrift,
+        verificationVerdict: validation.verificationVerdict,
         status: repairStatus(validation),
         summary: repairSummary(validation),
         recommendedAction: validation.recommendedAction,
@@ -291,7 +398,7 @@ function buildRepairHandoff(plan) {
             approve: plan.boundaryVerdict?.humanRequired
                 ? [
                     "ripple approval --intent latest --agent",
-                    `ripple approve --intent latest --gate ${approvalGateForHumanGate(plan.boundaryVerdict.humanGate)}`,
+                    `ripple approve --intent latest --gate ${approvalGateForHumanGate(plan.boundaryVerdict.humanGate)} --reason "<why this boundary is safe>"`,
                 ]
                 : [],
             unstage: plan.commands.unstage,
@@ -306,6 +413,12 @@ function repairHandoffDecision(plan, canContinue, needsHuman) {
     if (plan.readinessDrift?.status === "weakened") {
         return "restore-readiness";
     }
+    if (plan.verificationVerdict?.status === "review") {
+        return "human-review";
+    }
+    if (plan.verificationVerdict?.status === "failed") {
+        return "repair";
+    }
     if (needsHuman) {
         return "human-review";
     }
@@ -333,6 +446,12 @@ function repairHandoffNextRequiredAction(plan, phase) {
     if (plan.readinessDrift?.status === "weakened") {
         return "Restore Ripple readiness with the listed commands or ask the human before continuing.";
     }
+    if (plan.verificationVerdict?.status === "failed") {
+        return "Repair failed verification evidence, record a passing rerun, then run Ripple again.";
+    }
+    if (plan.verificationVerdict?.status === "review") {
+        return "Ask the human to review incomplete verification evidence before continuing.";
+    }
     if (plan.status === "human-review-required" || plan.status === "contract-review-required") {
         return "Ask the human to review the blockers before keeping this change.";
     }
@@ -362,6 +481,9 @@ function repairHandoffAskHuman(plan) {
     if (plan.readinessDrift?.status === "weakened") {
         askHuman.push("Approve continuing only if weaker Ripple readiness is intentional.");
     }
+    if (plan.verificationVerdict?.status === "review") {
+        askHuman.push(plan.verificationVerdict.summary);
+    }
     if (plan.boundaryVerdict?.humanRequired) {
         askHuman.push(`Human gate '${plan.boundaryVerdict.humanGate}' applies to this saved intent.`);
     }
@@ -369,6 +491,32 @@ function repairHandoffAskHuman(plan) {
 }
 function buildRepairActions(input) {
     const actions = [];
+    if (input.validation.verificationVerdict.status === "failed" ||
+        input.validation.verificationVerdict.status === "review") {
+        input.validation.verificationVerdict.evidence
+            .filter((evidence) => evidence.status !== "passed")
+            .forEach((evidence) => {
+            actions.push({
+                type: "verify",
+                priority: "blocker",
+                target: evidence.command,
+                command: evidence.command,
+                reason: `Reported verification status was ${evidence.status}.`,
+                instruction: verificationEvidenceFix(evidence),
+            });
+        });
+        if (actions.length === 0) {
+            input.validation.verificationVerdict.fix.forEach((instruction) => {
+                actions.push({
+                    type: "verify",
+                    priority: "blocker",
+                    reason: input.validation.verificationVerdict.summary,
+                    instruction,
+                });
+            });
+        }
+        return uniqueRepairActions(actions);
+    }
     if (input.validation.driftVerdict.status === "pass") {
         input.verificationTargets.slice(0, 8).forEach((target) => {
             actions.push({
@@ -497,7 +645,23 @@ function saveChangeIntent(workspaceRoot, intent, intentPath) {
 exports.saveChangeIntent = saveChangeIntent;
 function loadChangeIntent(workspaceRoot, intentPath = "latest") {
     const targetPath = resolveIntentPath(workspaceRoot, intentPath);
-    const parsed = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+    let raw;
+    try {
+        raw = fs.readFileSync(targetPath, "utf8");
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            throw new Error(`No active Ripple change intent found at ${targetPath}. Run ripple plan --file <file> --task "<task>" --agent --save before an agent edits.`);
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid Ripple change intent JSON at ${targetPath}. Ask the human to inspect or recreate the saved boundary before continuing. ${errorMessage(err)}`);
+    }
     return assertChangeIntent(parsed, targetPath);
 }
 exports.loadChangeIntent = loadChangeIntent;
@@ -557,9 +721,11 @@ function buildIntentValidation(staged, intent, options) {
     });
     const policyDrift = buildPolicyDriftSummary(intent.policyExplanation, options.currentPolicyExplanation);
     const readinessDrift = buildReadinessDriftSummary(intent.readinessSnapshot, options.currentReadinessSnapshot);
+    const verificationVerdict = buildVerificationVerdict(intent.verificationEvidence, changedFiles, staged.changeFingerprint, staged.mode);
     const boundaryGuidance = mergeBoundaryGuidance(guidance, boundaryVerdict);
     const policyGuidance = mergePolicyDriftGuidance(boundaryGuidance, policyDrift);
-    const effectiveGuidance = mergeReadinessDriftGuidance(policyGuidance, readinessDrift);
+    const readinessGuidance = mergeReadinessDriftGuidance(policyGuidance, readinessDrift);
+    const effectiveGuidance = mergeVerificationGuidance(readinessGuidance, verificationVerdict);
     const driftVerdict = buildDriftVerdict({
         verdict,
         boundaryVerdict,
@@ -580,6 +746,7 @@ function buildIntentValidation(staged, intent, options) {
         boundaryVerdict,
         policyDrift,
         readinessDrift,
+        verificationVerdict,
     });
     const nextRequiredAction = validationNextRequiredAction(nextRequiredPhase);
     const validation = {
@@ -598,6 +765,7 @@ function buildIntentValidation(staged, intent, options) {
         policyExplanation: intent.policyExplanation,
         policyDrift,
         readinessDrift,
+        verificationVerdict,
         plannedScope: unplannedFiles.length === 0 ? "matched" : "violated",
         editableFiles,
         contextFiles,
@@ -617,16 +785,55 @@ function buildIntentValidation(staged, intent, options) {
         requiresAttention: driftVerdict.status !== "pass" ||
             boundaryVerdict.humanRequired ||
             policyDrift.status === "changed" ||
-            readinessDrift.status === "weakened",
+            readinessDrift.status === "weakened" ||
+            verificationVerdict.status === "failed" ||
+            verificationVerdict.status === "review",
     };
     return {
         ...validation,
         handoff: buildValidationHandoff(validation),
     };
 }
+function buildReviewPacketNotes(validation, verificationTargets) {
+    const notes = [];
+    if (validation.boundaryVerdict.changedOutsideBoundaryFiles.length > 0) {
+        notes.push("Patch scope crossed: review files outside the declared boundary before keeping this change.");
+    }
+    if (validation.boundaryVerdict.changedOutsideBoundarySymbols.length > 0) {
+        notes.push("Function scope crossed: review changed symbols outside the declared function boundary.");
+    }
+    if (validation.contextFilesChanged.length > 0) {
+        notes.push("Context-only files changed: approve a wider intent if those edits are valid.");
+    }
+    if (validation.protectedContractChanges.length > 0 ||
+        validation.unplannedContractChanges.length > 0) {
+        notes.push("Behavior scope requires review: protected or unplanned contracts changed.");
+    }
+    if (validation.verificationVerdict.status === "failed") {
+        notes.push("Verification failed: repair the failed reported check before handoff.");
+    }
+    else if (validation.verificationVerdict.status === "review") {
+        notes.push("Verification incomplete: ask the human to review skipped or unknown reported evidence.");
+    }
+    else if (validation.verificationVerdict.status === "pass") {
+        notes.push("Verification reported: all recorded verification evidence was reported as passed.");
+    }
+    else if (verificationTargets.length > 0) {
+        notes.push("Verification evidence is required before handoff; this packet records expected checks, not proof that they ran.");
+    }
+    else {
+        notes.push("No automated verification target was found; require a focused manual reviewer pass.");
+    }
+    if (validation.humanGate !== "none") {
+        notes.push(`Human gate applies: ${validation.humanGate}.`);
+    }
+    return uniqueItems(notes);
+}
 function validationNextRequiredPhase(input) {
     if (input.policyDrift.status === "changed" ||
         input.readinessDrift?.status === "weakened" ||
+        input.verificationVerdict?.status === "failed" ||
+        input.verificationVerdict?.status === "review" ||
         input.boundaryVerdict.status !== "pass" ||
         input.driftVerdict.status !== "pass") {
         return "repair_or_handoff";
@@ -647,6 +854,7 @@ function buildValidationHandoff(validation) {
         validation.driftVerdict.decision === "stop-and-ask-human" ||
         validation.policyDrift.status === "changed" ||
         validation.readinessDrift.status === "weakened" ||
+        validation.verificationVerdict.status === "review" ||
         validation.verdict === "dangerous";
     const canContinue = validation.driftVerdict.status === "pass" &&
         !validation.requiresAttention;
@@ -671,6 +879,12 @@ function validationHandoffDecision(validation, canContinue, needsHuman) {
     if (validation.readinessDrift.status === "weakened") {
         return "restore-readiness";
     }
+    if (validation.verificationVerdict.status === "review") {
+        return "human-review";
+    }
+    if (validation.verificationVerdict.status === "failed") {
+        return "repair";
+    }
     if (needsHuman) {
         return "human-review";
     }
@@ -691,6 +905,10 @@ function validationHandoffFixNow(validation) {
         ...validation.boundaryVerdict.fix,
         ...(validation.policyDrift.status === "changed" ? validation.policyDrift.fix : []),
         ...(validation.readinessDrift.status === "weakened" ? validation.readinessDrift.fix : []),
+        ...(validation.verificationVerdict.status === "failed" ||
+            validation.verificationVerdict.status === "review"
+            ? validation.verificationVerdict.fix
+            : []),
     ]);
 }
 function validationHandoffAskHuman(validation) {
@@ -704,6 +922,9 @@ function validationHandoffAskHuman(validation) {
     if (validation.readinessDrift.status === "weakened") {
         askHuman.push("Approve continuing only if the weaker Ripple readiness is intentional.");
     }
+    if (validation.verificationVerdict.status === "review") {
+        askHuman.push(validation.verificationVerdict.summary);
+    }
     if (validation.verdict === "dangerous") {
         askHuman.push("Review contract drift before keeping the staged change.");
     }
@@ -729,7 +950,7 @@ function validationHandoffCommands(validation) {
         approve: validation.boundaryVerdict.humanRequired
             ? [
                 "ripple approval --intent latest --agent",
-                `ripple approve --intent latest --gate ${approvalGateForHumanGate(validation.humanGate)}`,
+                `ripple approve --intent latest --gate ${approvalGateForHumanGate(validation.humanGate)} --reason "<why this boundary is safe>"`,
             ]
             : [],
         unstage: uniqueItems([
@@ -737,9 +958,12 @@ function validationHandoffCommands(validation) {
             ...validation.contextFilesChanged,
             ...validation.boundaryVerdict.changedOutsideBoundaryFiles,
         ]).map((file) => `git restore --staged -- ${file}`),
-        verify: validation.driftVerdict.status === "pass"
-            ? validation.driftVerdict.fix
-            : validation.nextSteps,
+        verify: validation.verificationVerdict.status === "failed" ||
+            validation.verificationVerdict.status === "review"
+            ? buildVerificationCommandSuggestions(validation.verificationVerdict)
+            : validation.driftVerdict.status === "pass"
+                ? validation.driftVerdict.fix
+                : validation.nextSteps,
     };
 }
 function approvalGateForHumanGate(humanGate) {
@@ -805,6 +1029,152 @@ function mergeReadinessDriftGuidance(guidance, readinessDrift) {
         ]),
     };
 }
+function mergeVerificationGuidance(guidance, verificationVerdict) {
+    if (verificationVerdict.status !== "failed" &&
+        verificationVerdict.status !== "review") {
+        return guidance;
+    }
+    return {
+        recommendedAction: guidance.blockingReasons.length > 0
+            ? guidance.recommendedAction
+            : verificationVerdict.status === "failed"
+                ? "Repair failed verification before continuing."
+                : "Ask the human to review incomplete verification evidence before continuing.",
+        blockingReasons: uniqueItems([
+            ...guidance.blockingReasons,
+            ...verificationVerdict.why,
+        ]),
+        nextSteps: uniqueItems([
+            ...verificationVerdict.fix,
+            ...guidance.nextSteps,
+        ]),
+    };
+}
+function buildVerificationVerdict(value, changedFiles = [], changeFingerprint, changeMode = "staged") {
+    const evidence = normalizeVerificationEvidence(value);
+    const latestEvidence = latestVerificationEvidenceByCommand(evidence);
+    if (evidence.length === 0) {
+        return {
+            status: "not-reported",
+            decision: "continue",
+            label: "UNKNOWN",
+            summary: "UNKNOWN: no verification evidence has been reported.",
+            why: [],
+            fix: [],
+            evidence,
+        };
+    }
+    const failed = latestEvidence.filter((item) => item.status === "failed");
+    if (failed.length > 0) {
+        return {
+            status: "failed",
+            decision: "repair",
+            label: "FAILED",
+            summary: "FAILED: latest verification evidence includes failing checks.",
+            why: failed.map((item) => verificationEvidenceWhy(item)),
+            fix: failed.map((item) => verificationEvidenceFix(item)),
+            evidence,
+        };
+    }
+    const incomplete = latestEvidence.filter((item) => item.status === "skipped" || item.status === "unknown");
+    if (incomplete.length > 0) {
+        return {
+            status: "review",
+            decision: "human-review",
+            label: "REVIEW",
+            summary: "REVIEW: latest verification evidence is skipped or unknown, so a human must review before handoff.",
+            why: incomplete.map((item) => verificationEvidenceWhy(item)),
+            fix: incomplete.map((item) => verificationEvidenceFix(item)),
+            evidence,
+        };
+    }
+    const staleEvidence = staleVerificationEvidence(latestEvidence, {
+        changedFiles,
+        changeFingerprint,
+        changeMode,
+    });
+    if (staleEvidence.length > 0) {
+        return {
+            status: "review",
+            decision: "human-review",
+            label: "REVIEW",
+            summary: "REVIEW: latest verification evidence was recorded for a different change snapshot, so the agent must rerun verification before handoff.",
+            why: staleEvidence.map((item) => staleVerificationWhy(item, changedFiles, changeFingerprint)),
+            fix: staleEvidence.map((item) => `Rerun verification against the current changed files: ${item.command}`),
+            evidence,
+        };
+    }
+    return {
+        status: "pass",
+        decision: "continue",
+        label: "PASS",
+        summary: "PASS: latest verification evidence for every command was marked passed.",
+        why: latestEvidence.map((item) => verificationEvidenceWhy(item)),
+        fix: ["Keep the passing verification evidence with the final handoff."],
+        evidence,
+    };
+}
+function latestVerificationEvidenceByCommand(evidence) {
+    const latest = new Map();
+    evidence.forEach((item) => {
+        latest.set(item.command, item);
+    });
+    return Array.from(latest.values());
+}
+function staleVerificationEvidence(evidence, current) {
+    const currentChangedFiles = normalizeVerificationChangedFiles(current.changedFiles);
+    if (currentChangedFiles.length === 0) {
+        return [];
+    }
+    return evidence.filter((item) => {
+        if (item.changeFingerprint &&
+            current.changeFingerprint) {
+            return item.changeFingerprint !== current.changeFingerprint;
+        }
+        if (!item.changedFiles) {
+            return false;
+        }
+        return !sameStringSet(item.changedFiles, currentChangedFiles);
+    });
+}
+function staleVerificationWhy(evidence, changedFiles, changeFingerprint) {
+    if (evidence.changeFingerprint && changeFingerprint) {
+        return `Stale verification proof: ${evidence.command} covered change fingerprint ${evidence.changeFingerprint.slice(0, 12)}, current fingerprint is ${changeFingerprint.slice(0, 12)}.`;
+    }
+    return `Stale verification proof: ${evidence.command} covered ${formatVerificationFileSet(evidence.changedFiles ?? [])}, current changed files are ${formatVerificationFileSet(changedFiles)}.`;
+}
+function normalizeVerificationChangedFiles(files) {
+    return uniqueItems(files.map((file) => normalizeVerificationFilePath(file)));
+}
+function sameStringSet(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    const rightSet = new Set(right);
+    return left.every((item) => rightSet.has(item));
+}
+function formatVerificationFileSet(files) {
+    return files.length > 0 ? files.join(", ") : "no changed files";
+}
+function verificationEvidenceWhy(evidence) {
+    const note = evidence.note ? ` Note: ${evidence.note}` : "";
+    const sourceLabel = evidence.source === "executed" ? "Executed" : "Reported";
+    const exitCode = typeof evidence.exitCode === "number" ? ` exitCode=${evidence.exitCode}.` : "";
+    const duration = typeof evidence.durationMs === "number" ? ` durationMs=${evidence.durationMs}.` : "";
+    return `${sourceLabel} verification ${evidence.status}: ${evidence.command}.${exitCode}${duration}${note}`;
+}
+function verificationEvidenceFix(evidence) {
+    if (evidence.status === "failed") {
+        return `Fix the failing verification, rerun it, then record a passing result: ${evidence.command}`;
+    }
+    if (evidence.status === "skipped") {
+        return `Run the skipped verification or ask the human to approve the skip: ${evidence.command}`;
+    }
+    if (evidence.status === "unknown") {
+        return `Resolve the unknown verification result or ask the human to review it: ${evidence.command}`;
+    }
+    return `Keep passing verification evidence in the handoff: ${evidence.command}`;
+}
 function buildPolicyDriftSummary(saved, current) {
     if (!current) {
         return {
@@ -1239,6 +1609,12 @@ function validationVerdict(input) {
     return "matched";
 }
 function repairStatus(validation) {
+    if (validation.verificationVerdict.status === "failed") {
+        return "repair-required";
+    }
+    if (validation.verificationVerdict.status === "review") {
+        return "human-review-required";
+    }
     if (validation.driftVerdict.status === "pass") {
         return "no-repair-needed";
     }
@@ -1258,6 +1634,12 @@ function repairStatus(validation) {
     return "repair-required";
 }
 function repairSummary(validation) {
+    if (validation.verificationVerdict.status === "failed") {
+        return "Reported verification failed; repair the failing check and record a passing rerun before continuing.";
+    }
+    if (validation.verificationVerdict.status === "review") {
+        return "Reported verification is skipped or unknown; ask the human to review before continuing.";
+    }
     if (validation.driftVerdict.status === "pass") {
         return "Staged changes match the saved intent; no drift repair is needed.";
     }
@@ -1392,10 +1774,13 @@ function resolveIntentPath(workspaceRoot, intentPath) {
 }
 function assertChangeIntent(value, sourcePath) {
     if (!isRecord(value)) {
-        throw new Error(`Invalid Ripple change intent: ${sourcePath}`);
+        throw new Error(`Invalid Ripple change intent at ${sourcePath}. Ask the human to inspect or recreate the saved boundary before continuing.`);
+    }
+    if (value.protocol === "ripple-closed-intent") {
+        throw new Error(closedIntentErrorMessage(value, sourcePath));
     }
     if (value.protocol !== INTENT_PROTOCOL || value.version !== INTENT_VERSION) {
-        throw new Error(`Unsupported Ripple change intent: ${sourcePath}`);
+        throw new Error(`No active Ripple change intent found at ${sourcePath}. Found protocol ${String(value.protocol)} instead of ${INTENT_PROTOCOL}. Run ripple intent status, then create a new saved plan before the agent continues.`);
     }
     if (typeof value.id !== "string" ||
         typeof value.createdAt !== "string" ||
@@ -1410,10 +1795,30 @@ function assertChangeIntent(value, sourcePath) {
         !Array.isArray(value.protectedContracts) ||
         !Array.isArray(value.verificationTargets) ||
         typeof value.why !== "string") {
-        throw new Error(`Malformed Ripple change intent: ${sourcePath}`);
+        throw new Error(`Malformed Ripple change intent at ${sourcePath}. Ask the human to inspect or recreate the saved boundary before continuing.`);
     }
     return normalizeChangeIntent(value);
 }
+function closedIntentErrorMessage(value, sourcePath) {
+    const reason = typeof value.reason === "string" && value.reason.trim().length > 0
+        ? ` Reason: ${value.reason.trim()}`
+        : "";
+    const closedBy = typeof value.closedBy === "string" && value.closedBy.trim().length > 0
+        ? ` Closed by: ${value.closedBy.trim()}.`
+        : "";
+    return [
+        `No active Ripple change intent found at ${sourcePath}; the saved boundary is closed.`,
+        `${closedBy}${reason}`,
+        "Agents must not continue from a closed boundary.",
+        "Run ripple intent status, then create a new saved plan with ripple plan --file <file> --task \"<task>\" --agent --save before editing.",
+    ].filter(Boolean).join(" ");
+}
+function isNodeError(err) {
+    return err instanceof Error && "code" in err;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function normalizeChangeIntent(intent) {
     const controlMode = isControlMode(intent.controlMode) ? intent.controlMode : "file";
     const editableFiles = uniqueItems(controlMode === "brainstorm"
@@ -1463,9 +1868,143 @@ function normalizeChangeIntent(intent) {
         contextFiles,
         allowedFiles: uniqueItems([...editableFiles, ...contextFiles]),
         expectedFiles: uniqueItems(intent.expectedFiles.length > 0 ? intent.expectedFiles : editableFiles),
+        verificationEvidence: normalizeVerificationEvidence(intent.verificationEvidence),
         readinessSnapshot,
     };
 }
+function appendRippleVerificationEvidence(intent, evidence) {
+    const normalizedCommand = evidence.command.trim();
+    if (normalizedCommand.length === 0) {
+        throw new Error("Verification command cannot be empty.");
+    }
+    const normalizedEvidence = {
+        command: normalizedCommand,
+        status: isVerificationStatus(evidence.status) ? evidence.status : "unknown",
+        recordedAt: evidence.recordedAt ?? new Date().toISOString(),
+        source: evidence.source ?? "reported",
+        changedFiles: Array.isArray(evidence.changedFiles)
+            ? uniqueItems(evidence.changedFiles.filter((file) => typeof file === "string" && file.trim().length > 0).map((file) => normalizeVerificationFilePath(file.trim())))
+            : undefined,
+        changeMode: isVerificationChangeMode(evidence.changeMode)
+            ? evidence.changeMode
+            : undefined,
+        changeFingerprint: typeof evidence.changeFingerprint === "string" &&
+            evidence.changeFingerprint.trim().length > 0
+            ? evidence.changeFingerprint.trim()
+            : undefined,
+        exitCode: typeof evidence.exitCode === "number" && Number.isFinite(evidence.exitCode)
+            ? Math.trunc(evidence.exitCode)
+            : undefined,
+        durationMs: typeof evidence.durationMs === "number" && Number.isFinite(evidence.durationMs)
+            ? Math.max(0, Math.trunc(evidence.durationMs))
+            : undefined,
+        stdoutTail: typeof evidence.stdoutTail === "string" && evidence.stdoutTail.trim().length > 0
+            ? evidence.stdoutTail
+            : undefined,
+        stderrTail: typeof evidence.stderrTail === "string" && evidence.stderrTail.trim().length > 0
+            ? evidence.stderrTail
+            : undefined,
+        note: typeof evidence.note === "string" && evidence.note.trim().length > 0
+            ? evidence.note.trim()
+            : undefined,
+    };
+    return {
+        ...intent,
+        verificationEvidence: uniqueVerificationEvidence([
+            ...normalizeVerificationEvidence(intent.verificationEvidence),
+            normalizedEvidence,
+        ]),
+    };
+}
+exports.appendRippleVerificationEvidence = appendRippleVerificationEvidence;
+function normalizeVerificationEvidence(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return uniqueVerificationEvidence(value.flatMap((item) => {
+        if (!isRecord(item) || typeof item.command !== "string") {
+            return [];
+        }
+        const command = item.command.trim();
+        if (command.length === 0) {
+            return [];
+        }
+        const status = isVerificationStatus(item.status) ? item.status : "unknown";
+        const recordedAt = typeof item.recordedAt === "string" && item.recordedAt.trim().length > 0
+            ? item.recordedAt
+            : new Date(0).toISOString();
+        const source = item.source === "executed" ? "executed" : "reported";
+        const changedFiles = Array.isArray(item.changedFiles)
+            ? uniqueItems(item.changedFiles.filter((file) => typeof file === "string" && file.trim().length > 0).map((file) => normalizeVerificationFilePath(file.trim())))
+            : undefined;
+        const changeMode = isVerificationChangeMode(item.changeMode)
+            ? item.changeMode
+            : undefined;
+        const changeFingerprint = typeof item.changeFingerprint === "string" &&
+            item.changeFingerprint.trim().length > 0
+            ? item.changeFingerprint.trim()
+            : undefined;
+        const exitCode = typeof item.exitCode === "number" && Number.isFinite(item.exitCode)
+            ? Math.trunc(item.exitCode)
+            : undefined;
+        const durationMs = typeof item.durationMs === "number" && Number.isFinite(item.durationMs)
+            ? Math.max(0, Math.trunc(item.durationMs))
+            : undefined;
+        const stdoutTail = typeof item.stdoutTail === "string" && item.stdoutTail.trim().length > 0
+            ? item.stdoutTail
+            : undefined;
+        const stderrTail = typeof item.stderrTail === "string" && item.stderrTail.trim().length > 0
+            ? item.stderrTail
+            : undefined;
+        const note = typeof item.note === "string" && item.note.trim().length > 0
+            ? item.note.trim()
+            : undefined;
+        return [{
+                command,
+                status,
+                recordedAt,
+                source,
+                changedFiles,
+                changeMode,
+                changeFingerprint,
+                exitCode,
+                durationMs,
+                stdoutTail,
+                stderrTail,
+                note,
+            }];
+    }));
+}
+function uniqueVerificationEvidence(evidence) {
+    const seen = new Set();
+    return evidence.filter((item) => {
+        const key = [
+            item.command,
+            item.status,
+            item.source,
+            String(item.exitCode ?? ""),
+            (item.changedFiles ?? []).join(","),
+            item.changeMode ?? "",
+            item.changeFingerprint ?? "",
+            item.recordedAt,
+            item.note ?? "",
+        ].join("\0");
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function normalizeVerificationFilePath(filePath) {
+    return filePath.replace(/\\/g, "/");
+}
+function isVerificationStatus(value) {
+    return value === "passed" || value === "failed" || value === "skipped" || value === "unknown";
+}
+function isVerificationChangeMode(value) {
+    return value === "staged" || value === "changed" || value === "worktree";
+}
 function normalizeReadinessSnapshot(value) {
     if (!isRecord(value)) {
         return fallbackReadinessSnapshot();
@@ -1527,6 +2066,9 @@ function normalizePolicyExplanationSnapshot(value, defaults) {
         ? rawPolicySource
         : defaults.policySource;
     const rawPolicyRisk = raw?.policyRisk;
+    const requiredGateNextSteps = defaults.humanGate !== "none"
+        ? fallbackPolicyExplanationNextSteps(defaults.humanGate)
+        : [];
     return {
         protocol: "ripple-policy-explanation",
         version: 1,
@@ -1545,7 +2087,7 @@ function normalizePolicyExplanationSnapshot(value, defaults) {
         matchedRules,
         why: rawWhy.length > 0 ? rawWhy : fallbackPolicyExplanationWhy(defaults),
         nextSteps: rawNextSteps.length > 0
-            ? rawNextSteps
+            ? uniqueItems([...requiredGateNextSteps, ...rawNextSteps])
             : fallbackPolicyExplanationNextSteps(defaults.humanGate),
     };
 }
@@ -1564,10 +2106,10 @@ function fallbackPolicyExplanationWhy(defaults) {
 }
 function fallbackPolicyExplanationNextSteps(humanGate) {
     if (humanGate === "required-before-edit") {
-        return ["Ask the human to approve before the agent edits this file."];
+        return ["Agent must get human approval before editing this file."];
     }
     if (humanGate === "required-before-merge") {
-        return ["Require human review before merging this change."];
+        return ["Agent must get human approval before merging this change."];
     }
     return ["Check staged changes against this saved intent before handoff."];
 }