@getripple/core 1.0.4

package/dist/change-intent.js

@@ -0,0 +1,1758 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, 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;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const INTENT_PROTOCOL = "ripple-change-intent";
+const INTENT_VERSION = 1;
+const INTENTS_DIR = path.join(".ripple", "intents");
+const LATEST_INTENT_FILE = "latest.json";
+const SOURCE_FILE_RE = /\.(ts|tsx|js|jsx|py)$/i;
+function buildChangeIntent(plan, options = {}) {
+    const controlMode = options.controlMode ?? options.policy?.defaultMode ?? "file";
+    assertControlMode(controlMode);
+    const editableFiles = editableFilesForControlMode(plan, controlMode, options);
+    const contextFiles = uniqueItems([
+        ...plan.readFirst.map((file) => file.file),
+        ...plan.readIfNeeded.map((file) => file.file),
+        ...plan.verificationTargets.filter(isSourceFilePath),
+    ].filter((file) => !editableFiles.includes(file)));
+    const allowedFiles = uniqueItems([...editableFiles, ...contextFiles]);
+    const allowedSymbols = allowedSymbolsForControlMode(plan, controlMode, options);
+    const expectedSymbols = uniqueItems(allowedSymbols.length > 0
+        ? allowedSymbols
+        : plan.symbolFocus
+            .filter((symbol) => symbol.file === plan.targetFile || symbol.signals.includes("task-match"))
+            .map((symbol) => symbol.symbol));
+    const protectedContracts = uniqueItems(plan.symbolFocus
+        .filter((symbol) => symbol.callers > 0 || symbol.file === plan.targetFile)
+        .map((symbol) => symbol.symbol));
+    const boundaryRisk = strongestBoundaryRisk(controlBoundaryRisk(plan), options.policy?.risk);
+    const humanGate = humanGateForPlan(plan, controlMode, boundaryRisk, options.policy);
+    const humanGateReason = humanGateReasons(plan, controlMode, boundaryRisk, options.policy);
+    const policySource = policySourceLabel(options.policy);
+    const policyMatches = options.policy?.matchedRules ?? [];
+    const policyExplanation = normalizePolicyExplanationSnapshot(options.policyExplanation, {
+        targetFile: plan.targetFile,
+        controlMode,
+        boundaryRisk,
+        humanGate,
+        policySource,
+        policyMatches,
+        policyRisk: options.policy?.risk ?? "none",
+    });
+    const createdAt = new Date().toISOString();
+    return {
+        protocol: INTENT_PROTOCOL,
+        version: INTENT_VERSION,
+        id: makeIntentId(plan, createdAt),
+        createdAt,
+        task: plan.task,
+        targetFile: plan.targetFile,
+        risk: plan.risk,
+        tokenBudget: plan.tokenBudget,
+        controlMode,
+        allowedSymbols,
+        humanGate,
+        humanGateReason,
+        boundaryRisk,
+        policySource,
+        policyMatches,
+        policyExplanation,
+        editableFiles,
+        contextFiles,
+        allowedFiles,
+        expectedFiles: editableFiles,
+        expectedSymbols,
+        protectedContracts,
+        verificationTargets: plan.verificationTargets,
+        readinessSnapshot: options.readinessSnapshot ?? fallbackReadinessSnapshot(),
+        why: plan.why,
+    };
+}
+exports.buildChangeIntent = buildChangeIntent;
+function buildChangeIntentReadinessSnapshot(readiness) {
+    return {
+        status: readiness.status,
+        enforcementLevel: readiness.enforcement.level,
+        canGuideAgents: readiness.enforcement.canGuideAgents,
+        canDetectDrift: readiness.enforcement.canDetectDrift,
+        canBlockInCi: readiness.enforcement.canBlockInCi,
+        policyExplicit: readiness.enforcement.explicitPolicy.ok,
+        graphOk: readiness.checks.graph.ok,
+        gitOk: readiness.checks.git.ok,
+        ciWorkflowOk: readiness.checks.ciWorkflow.ok,
+        latestIntentOk: readiness.checks.latestIntent.ok,
+        gaps: readiness.enforcement.gaps,
+        nextSteps: readiness.nextSteps,
+    };
+}
+exports.buildChangeIntentReadinessSnapshot = buildChangeIntentReadinessSnapshot;
+function buildAgentHandoffVerdict(input) {
+    return {
+        protocol: "ripple-agent-handoff",
+        version: 1,
+        source: input.source,
+        canContinue: input.canContinue,
+        mustStop: input.mustStop ?? !input.canContinue,
+        needsHuman: input.needsHuman,
+        decision: input.decision,
+        nextRequiredPhase: input.nextRequiredPhase,
+        nextRequiredAction: input.nextRequiredAction,
+        summary: input.summary,
+        why: uniqueItems(input.why),
+        fixNow: uniqueItems(input.fixNow),
+        askHuman: uniqueItems(input.askHuman ?? []),
+        commands: {
+            doctor: uniqueItems(input.commands?.doctor ?? []),
+            plan: uniqueItems(input.commands?.plan ?? []),
+            check: uniqueItems(input.commands?.check ?? []),
+            audit: uniqueItems(input.commands?.audit ?? []),
+            repair: uniqueItems(input.commands?.repair ?? []),
+            approve: uniqueItems(input.commands?.approve ?? []),
+            unstage: uniqueItems(input.commands?.unstage ?? []),
+            verify: uniqueItems(input.commands?.verify ?? []),
+        },
+    };
+}
+exports.buildAgentHandoffVerdict = buildAgentHandoffVerdict;
+function validateStagedCheckAgainstIntent(staged, intent, options = {}) {
+    const validation = buildIntentValidation(staged, intent, options);
+    return {
+        ...staged,
+        requiresAttention: staged.requiresAttention || validation.requiresAttention,
+        intentValidation: validation,
+        nextRequiredPhase: validation.nextRequiredPhase,
+        nextRequiredAction: validation.nextRequiredAction,
+    };
+}
+exports.validateStagedCheckAgainstIntent = validateStagedCheckAgainstIntent;
+function buildIntentDriftRepairPlan(staged) {
+    const validation = staged.intentValidation;
+    const verificationTargets = uniqueItems(staged.files.flatMap((file) => file.verificationTargets));
+    if (!validation) {
+        const missingIntentPlan = {
+            protocol: "ripple-intent-drift-repair",
+            version: 1,
+            verdict: "missing-intent",
+            driftVerdict: missingIntentDriftVerdict(),
+            status: "intent-required",
+            summary: "No saved change intent was provided, so Ripple cannot repair plan drift yet.",
+            recommendedAction: "Run staged check with a saved intent before asking Ripple to repair drift.",
+            blockingReasons: ["Missing intent validation"],
+            unstageFiles: [],
+            reviewContracts: [],
+            createNewIntent: false,
+            verificationTargets,
+            fixActions: missingIntentRepairActions(),
+            agentActions: staged.agentActions,
+            commands: {
+                unstage: [],
+                replan: ["Run ripple_plan_context with saveIntent: true, then run ripple_check_staged with intentPath."],
+                verify: verificationTargets,
+            },
+            nextSteps: [
+                "Create or load a saved change intent.",
+                "Run staged check against that intent.",
+            ],
+        };
+        return {
+            ...missingIntentPlan,
+            handoff: buildRepairHandoff(missingIntentPlan),
+        };
+    }
+    const reviewContracts = uniqueItems([
+        ...validation.protectedContractChanges,
+        ...validation.unplannedContractChanges,
+    ]);
+    const unstageFiles = validation.driftVerdict.status === "pass"
+        ? []
+        : uniqueItems([
+            ...validation.unplannedFiles,
+            ...validation.boundaryVerdict.changedOutsideBoundaryFiles,
+        ]);
+    const fixActions = buildRepairActions({
+        validation,
+        unstageFiles,
+        reviewContracts,
+        verificationTargets,
+    });
+    const repairPlan = {
+        protocol: "ripple-intent-drift-repair",
+        version: 1,
+        intentId: validation.intentId,
+        verdict: validation.verdict,
+        driftVerdict: validation.driftVerdict,
+        boundaryVerdict: validation.boundaryVerdict,
+        policyExplanation: validation.policyExplanation,
+        policyDrift: validation.policyDrift,
+        readinessDrift: validation.readinessDrift,
+        status: repairStatus(validation),
+        summary: repairSummary(validation),
+        recommendedAction: validation.recommendedAction,
+        blockingReasons: validation.blockingReasons,
+        unstageFiles,
+        reviewContracts,
+        createNewIntent: validation.driftVerdict.status !== "pass",
+        verificationTargets,
+        fixActions,
+        agentActions: staged.agentActions,
+        commands: {
+            unstage: unstageFiles.map((file) => `git restore --staged -- ${file}`),
+            replan: validation.driftVerdict.status === "pass"
+                ? []
+                : ["Run ripple_plan_context with saveIntent: true for the broader intended scope."],
+            verify: verificationTargets,
+        },
+        nextSteps: validation.nextSteps,
+    };
+    return {
+        ...repairPlan,
+        handoff: buildRepairHandoff(repairPlan),
+    };
+}
+exports.buildIntentDriftRepairPlan = buildIntentDriftRepairPlan;
+function missingIntentDriftVerdict() {
+    return {
+        status: "unknown",
+        decision: "create-intent-first",
+        label: "UNKNOWN",
+        summary: "UNKNOWN: no saved change intent is available, so Ripple cannot judge drift.",
+        why: ["No saved change intent was provided for comparison."],
+        fix: [
+            "Run ripple plan --file <file> --task \"<task>\" --agent --save.",
+            "Stage the intended files, then run ripple check --staged --agent --intent latest.",
+        ],
+    };
+}
+function missingIntentRepairActions() {
+    return [
+        {
+            type: "create-intent",
+            priority: "blocker",
+            command: "ripple plan --file <file> --task \"<task>\" --agent --save",
+            reason: "No saved change intent was available for drift comparison.",
+            instruction: "Create a saved change intent before relying on Ripple to judge whether edits stayed in scope.",
+        },
+    ];
+}
+function buildRepairHandoff(plan) {
+    const canContinue = plan.status === "no-repair-needed";
+    const needsHuman = plan.status === "human-review-required" ||
+        plan.status === "contract-review-required";
+    const nextRequiredPhase = repairHandoffNextRequiredPhase(plan);
+    const nextRequiredAction = repairHandoffNextRequiredAction(plan, nextRequiredPhase);
+    return buildAgentHandoffVerdict({
+        source: "repair",
+        canContinue,
+        needsHuman,
+        decision: repairHandoffDecision(plan, canContinue, needsHuman),
+        nextRequiredPhase,
+        nextRequiredAction,
+        summary: plan.summary,
+        why: plan.blockingReasons.length > 0 ? plan.blockingReasons : plan.driftVerdict.why,
+        fixNow: repairHandoffFixNow(plan),
+        askHuman: repairHandoffAskHuman(plan),
+        commands: {
+            doctor: plan.readinessDrift?.status === "weakened"
+                ? ["ripple doctor --agent --strict"]
+                : [],
+            plan: plan.commands.replan,
+            check: plan.status === "intent-required"
+                ? ["ripple check --staged --agent --intent latest"]
+                : [],
+            audit: canContinue ? ["ripple audit --agent --intent latest"] : [],
+            repair: canContinue ? [] : ["ripple repair --agent --intent latest"],
+            approve: plan.boundaryVerdict?.humanRequired
+                ? [
+                    "ripple approval --intent latest --agent",
+                    `ripple approve --intent latest --gate ${approvalGateForHumanGate(plan.boundaryVerdict.humanGate)}`,
+                ]
+                : [],
+            unstage: plan.commands.unstage,
+            verify: plan.commands.verify,
+        },
+    });
+}
+function repairHandoffDecision(plan, canContinue, needsHuman) {
+    if (plan.status === "intent-required") {
+        return "create-intent";
+    }
+    if (plan.readinessDrift?.status === "weakened") {
+        return "restore-readiness";
+    }
+    if (needsHuman) {
+        return "human-review";
+    }
+    if (!canContinue) {
+        return "repair";
+    }
+    return "audit";
+}
+function repairHandoffNextRequiredPhase(plan) {
+    if (plan.status === "intent-required") {
+        return "plan_before_edit";
+    }
+    if (plan.status === "no-repair-needed") {
+        return "audit_after_change";
+    }
+    return "repair_or_handoff";
+}
+function repairHandoffNextRequiredAction(plan, phase) {
+    if (phase === "plan_before_edit") {
+        return "Create a saved Ripple plan, then run staged check against that intent.";
+    }
+    if (phase === "audit_after_change") {
+        return "Run ripple audit --agent --intent latest before final handoff.";
+    }
+    if (plan.readinessDrift?.status === "weakened") {
+        return "Restore Ripple readiness with the listed commands or ask the human 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.";
+    }
+    return "Apply the repair actions, then rerun ripple check --staged --agent --intent latest.";
+}
+function repairHandoffFixNow(plan) {
+    if (plan.status === "no-repair-needed") {
+        return plan.verificationTargets.length > 0
+            ? plan.verificationTargets.map((target) => `Verify before handoff: ${target}`)
+            : plan.nextSteps;
+    }
+    return uniqueItems([
+        ...plan.fixActions
+            .filter((action) => action.priority === "blocker" || action.priority === "required")
+            .map((action) => action.instruction),
+        ...plan.nextSteps,
+    ]);
+}
+function repairHandoffAskHuman(plan) {
+    const askHuman = [];
+    if (plan.status === "human-review-required") {
+        askHuman.push(plan.summary);
+    }
+    if (plan.status === "contract-review-required") {
+        askHuman.push("Review protected or unplanned contract changes before keeping this change.");
+    }
+    if (plan.readinessDrift?.status === "weakened") {
+        askHuman.push("Approve continuing only if weaker Ripple readiness is intentional.");
+    }
+    if (plan.boundaryVerdict?.humanRequired) {
+        askHuman.push(`Human gate '${plan.boundaryVerdict.humanGate}' applies to this saved intent.`);
+    }
+    return askHuman;
+}
+function buildRepairActions(input) {
+    const actions = [];
+    if (input.validation.driftVerdict.status === "pass") {
+        input.verificationTargets.slice(0, 8).forEach((target) => {
+            actions.push({
+                type: "verify",
+                priority: "required",
+                target,
+                reason: "Staged changes match the saved intent; verification is the remaining handoff step.",
+                instruction: `Run or inspect ${target} before handing off the change.`,
+            });
+        });
+        if (actions.length === 0) {
+            actions.push({
+                type: "proceed",
+                priority: "recommended",
+                reason: "Staged changes match the saved intent and Ripple found no verification targets.",
+                instruction: "Proceed only after doing the narrowest manual check that fits the changed file.",
+            });
+        }
+        return actions;
+    }
+    // Ripple readiness snapshot is saved with the intent.
+    if (input.validation.policyDrift.status === "changed") {
+        actions.push({
+            type: "review-policy",
+            priority: "blocker",
+            target: input.validation.targetFile,
+            command: `ripple policy explain --file ${input.validation.targetFile} --agent`,
+            reason: "Current repo policy differs from the policy snapshot saved with this intent.",
+            instruction: "Ask the human to review the current policy and create a new saved intent if the trust boundary should change.",
+        });
+    }
+    if (input.validation.readinessDrift.status === "weakened") {
+        actions.push({
+            type: "review-readiness",
+            priority: "blocker",
+            target: input.validation.targetFile,
+            command: "ripple doctor --agent --strict",
+            reason: "Current Ripple readiness is weaker than the readiness snapshot saved with this intent.",
+            instruction: "Restore the missing Ripple readiness layer or ask the human to approve continuing with weaker protection.",
+        });
+    }
+    const contextOnlyFiles = new Set(input.validation.contextFilesChanged);
+    input.unstageFiles.forEach((file) => {
+        const isContextOnlyFile = contextOnlyFiles.has(file);
+        actions.push({
+            type: "unstage-file",
+            priority: "blocker",
+            target: file,
+            command: `git restore --staged -- ${file}`,
+            reason: isContextOnlyFile
+                ? "This file was provided as read or verification context, not editable scope."
+                : "This file is outside the saved change intent.",
+            instruction: `Unstage ${file}, or create a new saved intent if editing this file is intentional.`,
+        });
+    });
+    input.validation.unplannedSymbols.forEach((symbol) => {
+        actions.push({
+            type: "review-symbol",
+            priority: "blocker",
+            target: symbol,
+            reason: "This symbol changed outside the expected symbol focus.",
+            instruction: `Undo the accidental change to ${symbol}, or replan with a saved intent that includes it.`,
+        });
+    });
+    input.validation.boundaryVerdict.changedOutsideBoundarySymbols.forEach((symbol) => {
+        actions.push({
+            type: "review-symbol",
+            priority: "blocker",
+            target: symbol,
+            reason: "This symbol changed outside the selected agent control boundary.",
+            instruction: `Undo the accidental change to ${symbol}, or ask the human to approve a wider boundary.`,
+        });
+    });
+    input.reviewContracts.forEach((symbol) => {
+        actions.push({
+            type: "review-contract",
+            priority: "blocker",
+            target: symbol,
+            reason: "A protected or unplanned contract changed.",
+            instruction: `Inspect callers for ${symbol}; preserve its contract or create a broader saved intent before continuing.`,
+        });
+    });
+    actions.push({
+        type: "replan",
+        priority: input.validation.driftVerdict.status === "danger" ? "blocker" : "required",
+        command: `ripple plan --file ${input.validation.targetFile} --task "<updated task>" --mode ${input.validation.controlMode} --agent --save`,
+        reason: "The staged change no longer matches the saved plan or selected control boundary.",
+        instruction: "If the broader scope is intentional, create a new saved intent with the human-approved boundary and run the staged check again.",
+    });
+    input.verificationTargets.slice(0, 8).forEach((target) => {
+        actions.push({
+            type: "verify",
+            priority: "recommended",
+            target,
+            reason: "Use after drift is repaired or explicitly replanned.",
+            instruction: `Run or inspect ${target} after the staged scope matches intent.`,
+        });
+    });
+    return uniqueRepairActions(actions);
+}
+function uniqueRepairActions(actions) {
+    const seen = new Set();
+    return actions.filter((action) => {
+        const key = [
+            action.type,
+            action.priority,
+            action.target ?? "",
+            action.command ?? "",
+            action.instruction,
+        ].join("\0");
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function saveChangeIntent(workspaceRoot, intent, intentPath) {
+    const targetPath = intentPath
+        ? resolveIntentPath(workspaceRoot, intentPath)
+        : defaultChangeIntentPath(workspaceRoot);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, `${JSON.stringify(intent, null, 2)}\n`, "utf8");
+    return targetPath;
+}
+exports.saveChangeIntent = saveChangeIntent;
+function loadChangeIntent(workspaceRoot, intentPath = "latest") {
+    const targetPath = resolveIntentPath(workspaceRoot, intentPath);
+    const parsed = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+    return assertChangeIntent(parsed, targetPath);
+}
+exports.loadChangeIntent = loadChangeIntent;
+function defaultChangeIntentPath(workspaceRoot) {
+    return path.join(workspaceRoot, INTENTS_DIR, LATEST_INTENT_FILE);
+}
+exports.defaultChangeIntentPath = defaultChangeIntentPath;
+function buildIntentValidation(staged, intent, options) {
+    const editableFiles = changeIntentEditableFiles(intent);
+    const contextFiles = changeIntentContextFiles(intent, editableFiles);
+    const editableFileSet = new Set(editableFiles);
+    const contextFileSet = new Set(contextFiles);
+    const expectedSymbols = new Set(intent.expectedSymbols);
+    const protectedContracts = new Set(intent.protectedContracts);
+    const changedFiles = staged.files.map((file) => file.file);
+    const changedSymbols = staged.changedSymbols.map((symbol) => symbol.symbol);
+    const plannedFilesChanged = changedFiles.filter((file) => editableFileSet.has(file));
+    const contextFilesChanged = changedFiles.filter((file) => contextFileSet.has(file) && !editableFileSet.has(file));
+    const unplannedFiles = changedFiles.filter((file) => !editableFileSet.has(file));
+    const expectedSymbolsChanged = changedSymbols.filter((symbol) => expectedSymbols.has(symbol));
+    const unplannedSymbols = staged.changedSymbols
+        .filter((symbol) => !expectedSymbols.has(symbol.symbol) && !editableFileSet.has(symbol.file))
+        .map((symbol) => symbol.symbol);
+    const protectedContractChanges = contractChangedSymbols(staged.changedSymbols)
+        .filter((symbol) => protectedContracts.has(symbol.symbol))
+        .map((symbol) => symbol.symbol);
+    const unplannedContractChanges = contractChangedSymbols(staged.changedSymbols)
+        .filter((symbol) => !protectedContracts.has(symbol.symbol))
+        .map((symbol) => symbol.symbol);
+    const reasons = validationReasons({
+        unplannedFiles,
+        contextFilesChanged,
+        unplannedSymbols,
+        protectedContractChanges,
+        unplannedContractChanges,
+    });
+    const verdict = validationVerdict({
+        unplannedFiles,
+        unplannedSymbols,
+        protectedContractChanges,
+        unplannedContractChanges,
+    });
+    const guidance = validationGuidance({
+        verdict,
+        unplannedFiles,
+        contextFilesChanged,
+        unplannedSymbols,
+        protectedContractChanges,
+        unplannedContractChanges,
+    });
+    const verificationTargets = uniqueItems(staged.files.flatMap((file) => file.verificationTargets));
+    const boundaryVerdict = buildBoundaryVerdict({
+        intent,
+        editableFiles,
+        changedFiles,
+        changedSymbols: staged.changedSymbols,
+    });
+    const policyDrift = buildPolicyDriftSummary(intent.policyExplanation, options.currentPolicyExplanation);
+    const readinessDrift = buildReadinessDriftSummary(intent.readinessSnapshot, options.currentReadinessSnapshot);
+    const boundaryGuidance = mergeBoundaryGuidance(guidance, boundaryVerdict);
+    const policyGuidance = mergePolicyDriftGuidance(boundaryGuidance, policyDrift);
+    const effectiveGuidance = mergeReadinessDriftGuidance(policyGuidance, readinessDrift);
+    const driftVerdict = buildDriftVerdict({
+        verdict,
+        boundaryVerdict,
+        policyDrift,
+        readinessDrift,
+        reasons,
+        blockingReasons: effectiveGuidance.blockingReasons,
+        nextSteps: effectiveGuidance.nextSteps,
+        verificationTargets,
+        contextFilesChanged,
+        unplannedFiles,
+        unplannedSymbols,
+        protectedContractChanges,
+        unplannedContractChanges,
+    });
+    const nextRequiredPhase = validationNextRequiredPhase({
+        driftVerdict,
+        boundaryVerdict,
+        policyDrift,
+        readinessDrift,
+    });
+    const nextRequiredAction = validationNextRequiredAction(nextRequiredPhase);
+    const validation = {
+        intentId: intent.id,
+        targetFile: intent.targetFile,
+        task: intent.task,
+        verdict,
+        driftVerdict,
+        boundaryVerdict,
+        controlMode: intent.controlMode,
+        allowedFiles: editableFiles,
+        allowedSymbols: intent.allowedSymbols,
+        humanGate: intent.humanGate,
+        humanGateReason: intent.humanGateReason,
+        boundaryRisk: intent.boundaryRisk,
+        policyExplanation: intent.policyExplanation,
+        policyDrift,
+        readinessDrift,
+        plannedScope: unplannedFiles.length === 0 ? "matched" : "violated",
+        editableFiles,
+        contextFiles,
+        plannedFilesChanged,
+        contextFilesChanged,
+        expectedSymbolsChanged,
+        unplannedFiles,
+        unplannedSymbols,
+        protectedContractChanges,
+        unplannedContractChanges,
+        reasons,
+        recommendedAction: effectiveGuidance.recommendedAction,
+        nextRequiredPhase,
+        nextRequiredAction,
+        blockingReasons: effectiveGuidance.blockingReasons,
+        nextSteps: effectiveGuidance.nextSteps,
+        requiresAttention: driftVerdict.status !== "pass" ||
+            boundaryVerdict.humanRequired ||
+            policyDrift.status === "changed" ||
+            readinessDrift.status === "weakened",
+    };
+    return {
+        ...validation,
+        handoff: buildValidationHandoff(validation),
+    };
+}
+function validationNextRequiredPhase(input) {
+    if (input.policyDrift.status === "changed" ||
+        input.readinessDrift?.status === "weakened" ||
+        input.boundaryVerdict.status !== "pass" ||
+        input.driftVerdict.status !== "pass") {
+        return "repair_or_handoff";
+    }
+    return "audit_after_change";
+}
+function validationNextRequiredAction(phase) {
+    if (phase === "repair_or_handoff") {
+        return "Run ripple repair --agent --intent latest, then repair or ask the human before continuing.";
+    }
+    if (phase === "audit_after_change") {
+        return "Run ripple audit --agent --intent latest before final handoff; audit checks approval status and final proceed/stop decision.";
+    }
+    return "No staged-check follow-up is required.";
+}
+function buildValidationHandoff(validation) {
+    const needsHuman = validation.boundaryVerdict.humanRequired ||
+        validation.driftVerdict.decision === "stop-and-ask-human" ||
+        validation.policyDrift.status === "changed" ||
+        validation.readinessDrift.status === "weakened" ||
+        validation.verdict === "dangerous";
+    const canContinue = validation.driftVerdict.status === "pass" &&
+        !validation.requiresAttention;
+    const decision = validationHandoffDecision(validation, canContinue, needsHuman);
+    return buildAgentHandoffVerdict({
+        source: "check",
+        canContinue,
+        needsHuman,
+        decision,
+        nextRequiredPhase: validation.nextRequiredPhase,
+        nextRequiredAction: validation.nextRequiredAction,
+        summary: validation.recommendedAction,
+        why: validation.blockingReasons.length > 0
+            ? validation.blockingReasons
+            : validation.driftVerdict.why,
+        fixNow: validationHandoffFixNow(validation),
+        askHuman: validationHandoffAskHuman(validation),
+        commands: validationHandoffCommands(validation),
+    });
+}
+function validationHandoffDecision(validation, canContinue, needsHuman) {
+    if (validation.readinessDrift.status === "weakened") {
+        return "restore-readiness";
+    }
+    if (needsHuman) {
+        return "human-review";
+    }
+    if (!canContinue) {
+        return "repair";
+    }
+    if (validation.nextRequiredPhase === "audit_after_change") {
+        return "audit";
+    }
+    return "continue";
+}
+function validationHandoffFixNow(validation) {
+    if (validation.driftVerdict.status === "pass" && !validation.requiresAttention) {
+        return validation.nextSteps;
+    }
+    return uniqueItems([
+        ...validation.driftVerdict.fix,
+        ...validation.boundaryVerdict.fix,
+        ...(validation.policyDrift.status === "changed" ? validation.policyDrift.fix : []),
+        ...(validation.readinessDrift.status === "weakened" ? validation.readinessDrift.fix : []),
+    ]);
+}
+function validationHandoffAskHuman(validation) {
+    const askHuman = [];
+    if (validation.boundaryVerdict.humanRequired) {
+        askHuman.push(`Human gate '${validation.humanGate}' applies to ${validation.targetFile}.`);
+    }
+    if (validation.policyDrift.status === "changed") {
+        askHuman.push("Review the saved plan against the current repo policy before continuing.");
+    }
+    if (validation.readinessDrift.status === "weakened") {
+        askHuman.push("Approve continuing only if the weaker Ripple readiness is intentional.");
+    }
+    if (validation.verdict === "dangerous") {
+        askHuman.push("Review contract drift before keeping the staged change.");
+    }
+    if (validation.driftVerdict.decision === "stop-and-ask-human") {
+        askHuman.push(validation.driftVerdict.summary);
+    }
+    return askHuman;
+}
+function validationHandoffCommands(validation) {
+    return {
+        doctor: validation.readinessDrift.status === "weakened"
+            ? ["ripple doctor --agent --strict"]
+            : [],
+        plan: validation.verdict === "matched"
+            ? []
+            : [`ripple plan --file ${validation.targetFile} --task "<updated task>" --mode ${validation.controlMode} --agent --save`],
+        audit: validation.nextRequiredPhase === "audit_after_change"
+            ? ["ripple audit --agent --intent latest"]
+            : [],
+        repair: validation.nextRequiredPhase === "repair_or_handoff"
+            ? ["ripple repair --agent --intent latest"]
+            : [],
+        approve: validation.boundaryVerdict.humanRequired
+            ? [
+                "ripple approval --intent latest --agent",
+                `ripple approve --intent latest --gate ${approvalGateForHumanGate(validation.humanGate)}`,
+            ]
+            : [],
+        unstage: uniqueItems([
+            ...validation.unplannedFiles,
+            ...validation.contextFilesChanged,
+            ...validation.boundaryVerdict.changedOutsideBoundaryFiles,
+        ]).map((file) => `git restore --staged -- ${file}`),
+        verify: validation.driftVerdict.status === "pass"
+            ? validation.driftVerdict.fix
+            : validation.nextSteps,
+    };
+}
+function approvalGateForHumanGate(humanGate) {
+    if (humanGate === "required-before-merge") {
+        return "before-merge";
+    }
+    return "before-risky-edit";
+}
+function mergeBoundaryGuidance(guidance, boundaryVerdict) {
+    if (boundaryVerdict.status === "pass") {
+        return guidance;
+    }
+    const hasIntentBlockingReason = guidance.blockingReasons.length > 0;
+    return {
+        recommendedAction: boundaryVerdict.status === "danger"
+            ? "Stop and ask the human to approve the crossed control boundary before keeping these changes."
+            : hasIntentBlockingReason
+                ? guidance.recommendedAction
+                : "Repair boundary drift by undoing changes outside the selected control boundary or save a wider human-approved intent.",
+        blockingReasons: uniqueItems([
+            ...guidance.blockingReasons,
+            ...boundaryVerdict.why,
+        ]),
+        nextSteps: uniqueItems([
+            ...boundaryVerdict.fix,
+            ...guidance.nextSteps,
+        ]),
+    };
+}
+function mergePolicyDriftGuidance(guidance, policyDrift) {
+    if (policyDrift.status !== "changed") {
+        return guidance;
+    }
+    return {
+        recommendedAction: guidance.blockingReasons.length > 0
+            ? guidance.recommendedAction
+            : "Ask the human to review the saved intent against the current repo policy before continuing.",
+        blockingReasons: uniqueItems([
+            ...guidance.blockingReasons,
+            ...policyDrift.why,
+        ]),
+        nextSteps: uniqueItems([
+            ...policyDrift.fix,
+            ...guidance.nextSteps,
+        ]),
+    };
+}
+function mergeReadinessDriftGuidance(guidance, readinessDrift) {
+    if (readinessDrift.status !== "weakened") {
+        return guidance;
+    }
+    return {
+        recommendedAction: guidance.blockingReasons.length > 0
+            ? guidance.recommendedAction
+            : "Restore Ripple readiness or ask the human to approve continuing with weaker protection.",
+        blockingReasons: uniqueItems([
+            ...guidance.blockingReasons,
+            ...readinessDrift.why,
+        ]),
+        nextSteps: uniqueItems([
+            ...readinessDrift.fix,
+            ...guidance.nextSteps,
+        ]),
+    };
+}
+function buildPolicyDriftSummary(saved, current) {
+    if (!current) {
+        return {
+            status: "unchecked",
+            decision: "compare-current-policy",
+            label: "UNKNOWN",
+            summary: "UNKNOWN: current repo policy was not compared with the saved intent policy snapshot.",
+            changedFields: [],
+            why: ["No current policy explanation was provided during intent validation."],
+            fix: ["Compare the saved intent policyExplanation with the current repo policy before final handoff."],
+        };
+    }
+    const changedFields = policyExplanationChangedFields(saved, current);
+    if (changedFields.length === 0) {
+        return {
+            status: "unchanged",
+            decision: "continue",
+            label: "PASS",
+            summary: "PASS: current repo policy matches the saved intent policy snapshot.",
+            changedFields: [],
+            why: ["The effective repo policy for this target still matches the saved intent."],
+            fix: ["Continue with normal staged-change and boundary validation."],
+            currentPolicyExplanation: current,
+        };
+    }
+    return {
+        status: "changed",
+        decision: "review-current-policy",
+        label: "DRIFT",
+        summary: "DRIFT: current repo policy differs from the policy snapshot saved with this intent.",
+        changedFields,
+        why: [
+            "The saved intent was created under a different effective repo policy.",
+            ...changedFields.map((field) => `Policy changed: ${field}`),
+        ],
+        fix: [
+            "Ask the human to review the saved intent against the current repo policy.",
+            "Create a new saved intent if the current policy requires a different trust boundary.",
+        ],
+        currentPolicyExplanation: current,
+    };
+}
+function buildReadinessDriftSummary(saved, current) {
+    if (!current) {
+        return {
+            status: "unchecked",
+            decision: "compare-current-readiness",
+            label: "UNKNOWN",
+            summary: "UNKNOWN: current Ripple readiness was not compared with the saved intent readiness snapshot.",
+            changedFields: [],
+            weakenedFields: [],
+            savedReadiness: saved,
+            why: ["No current readiness snapshot was provided during intent validation."],
+            fix: ["Run ripple doctor --agent before final handoff."],
+        };
+    }
+    const changedFields = readinessChangedFields(saved, current);
+    const weakenedFields = readinessWeakenedFields(saved, current);
+    if (weakenedFields.length === 0) {
+        return {
+            status: "unchanged",
+            decision: "continue",
+            label: "PASS",
+            summary: "PASS: current Ripple readiness is the same as or stronger than the saved intent readiness snapshot.",
+            changedFields,
+            weakenedFields,
+            savedReadiness: saved,
+            currentReadiness: current,
+            why: [
+                `Saved enforcement level: ${saved.enforcementLevel}.`,
+                `Current enforcement level: ${current.enforcementLevel}.`,
+            ],
+            fix: ["Continue with normal staged-change and boundary validation."],
+        };
+    }
+    return {
+        status: "weakened",
+        decision: "restore-readiness",
+        label: "DRIFT",
+        summary: "DRIFT: current Ripple readiness is weaker than the readiness snapshot saved with this intent.",
+        changedFields,
+        weakenedFields,
+        savedReadiness: saved,
+        currentReadiness: current,
+        why: readinessDriftWhy(saved, current, weakenedFields),
+        fix: readinessDriftFix(current, weakenedFields),
+    };
+}
+function readinessChangedFields(saved, current) {
+    const fields = [
+        "status",
+        "enforcementLevel",
+        "canGuideAgents",
+        "canDetectDrift",
+        "canBlockInCi",
+        "policyExplicit",
+        "graphOk",
+        "gitOk",
+        "ciWorkflowOk",
+        "latestIntentOk",
+    ];
+    return fields.filter((field) => saved[field] !== current[field]);
+}
+function readinessWeakenedFields(saved, current) {
+    const weakened = [];
+    if (readinessStatusRank(current.status) < readinessStatusRank(saved.status)) {
+        weakened.push("status");
+    }
+    if (enforcementLevelRank(current.enforcementLevel) < enforcementLevelRank(saved.enforcementLevel)) {
+        weakened.push("enforcementLevel");
+    }
+    const booleanFields = [
+        "canGuideAgents",
+        "canDetectDrift",
+        "canBlockInCi",
+        "policyExplicit",
+        "graphOk",
+        "gitOk",
+        "ciWorkflowOk",
+        "latestIntentOk",
+    ];
+    booleanFields.forEach((field) => {
+        if (saved[field] && !current[field]) {
+            weakened.push(field);
+        }
+    });
+    return uniqueItems(weakened);
+}
+function readinessDriftWhy(saved, current, weakenedFields) {
+    return [
+        `Saved enforcement level: ${saved.enforcementLevel}.`,
+        `Current enforcement level: ${current.enforcementLevel}.`,
+        `Weakened readiness fields: ${weakenedFields.join(", ")}.`,
+        ...current.gaps.map((gap) => `Current readiness gap: ${gap}`),
+    ];
+}
+function readinessDriftFix(current, weakenedFields) {
+    const fixes = ["Run ripple doctor --agent --strict to inspect current readiness gaps."];
+    if (weakenedFields.includes("ciWorkflowOk") || weakenedFields.includes("canBlockInCi")) {
+        fixes.push("Run ripple init to restore setup files and CI gate readiness.");
+    }
+    if (weakenedFields.includes("policyExplicit")) {
+        fixes.push("Restore .ripple/policy.json or run ripple init before continuing.");
+    }
+    if (weakenedFields.includes("latestIntentOk") || weakenedFields.includes("canDetectDrift")) {
+        fixes.push("Create or restore the saved intent with ripple plan --agent --save.");
+    }
+    if (weakenedFields.includes("gitOk")) {
+        fixes.push("Run Ripple inside a git worktree so changed-file drift checks can work.");
+    }
+    if (weakenedFields.includes("graphOk") || weakenedFields.includes("canGuideAgents")) {
+        fixes.push("Run Ripple from a supported source repo so the graph can be scanned.");
+    }
+    current.nextSteps.forEach((step) => fixes.push(step));
+    return uniqueItems(fixes);
+}
+function readinessStatusRank(status) {
+    return status === "ready" ? 1 : 0;
+}
+function enforcementLevelRank(level) {
+    if (level === "ci-gate-ready") {
+        return 3;
+    }
+    if (level === "drift-check-ready") {
+        return 2;
+    }
+    if (level === "advisory") {
+        return 1;
+    }
+    return 0;
+}
+function policyExplanationChangedFields(saved, current) {
+    const changed = [];
+    pushPolicyFieldChange(changed, "policy_source", saved.policySource, current.policySource);
+    pushPolicyFieldChange(changed, "policy_exists", saved.policyExists, current.policyExists);
+    pushPolicyFieldChange(changed, "policy_risk", saved.policyRisk, current.policyRisk);
+    pushPolicyFieldChange(changed, "human_gate", saved.humanGate, current.humanGate);
+    pushPolicyFieldChange(changed, "human_required", saved.humanRequired, current.humanRequired);
+    pushPolicyFieldChange(changed, "allow_pr_mode", saved.allowPrMode, current.allowPrMode);
+    if (!sameStringList(saved.matchedRules, current.matchedRules)) {
+        changed.push(`matched_rules saved=${formatPolicyValue(saved.matchedRules)} current=${formatPolicyValue(current.matchedRules)}`);
+    }
+    return changed;
+}
+function pushPolicyFieldChange(changed, field, saved, current) {
+    if (saved !== current) {
+        changed.push(`${field} saved=${formatPolicyValue(saved)} current=${formatPolicyValue(current)}`);
+    }
+}
+function sameStringList(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((item, index) => item === right[index]);
+}
+function formatPolicyValue(value) {
+    if (Array.isArray(value)) {
+        return value.length > 0 ? `[${value.join("; ")}]` : "[]";
+    }
+    return String(value);
+}
+function buildBoundaryVerdict(input) {
+    const allowedFileSet = new Set(input.editableFiles);
+    const allowedSymbolSet = new Set(input.intent.allowedSymbols);
+    const humanRequired = input.intent.humanGate !== "none";
+    const changedOutsideBoundaryFiles = uniqueItems(input.changedFiles.filter((file) => !allowedFileSet.has(file)));
+    const changedOutsideBoundarySymbols = uniqueItems(input.changedSymbols
+        .filter((symbol) => {
+        if (input.intent.controlMode === "brainstorm") {
+            return true;
+        }
+        if (input.intent.controlMode !== "function") {
+            return false;
+        }
+        return allowedFileSet.has(symbol.file) && !allowedSymbolSet.has(symbol.symbol);
+    })
+        .map((symbol) => symbol.symbol));
+    const crossedBoundary = changedOutsideBoundaryFiles.length > 0 ||
+        changedOutsideBoundarySymbols.length > 0;
+    if (!crossedBoundary) {
+        return {
+            status: "pass",
+            decision: "continue",
+            label: "PASS",
+            controlMode: input.intent.controlMode,
+            humanRequired,
+            humanGate: input.intent.humanGate,
+            summary: humanRequired
+                ? "PASS: staged changes stayed inside the selected boundary; the saved human gate still applies."
+                : "PASS: staged changes stayed inside the selected boundary.",
+            why: boundaryPassReasons(input.intent, input.editableFiles),
+            fix: humanRequired
+                ? [`Respect human gate: ${input.intent.humanGate}.`]
+                : ["Continue only if the staged change still matches the task intent."],
+            changedOutsideBoundaryFiles: [],
+            changedOutsideBoundarySymbols: [],
+        };
+    }
+    const status = humanRequired ? "danger" : "drift";
+    const decision = status === "danger" ? "stop-and-ask-human" : "fix-before-commit";
+    const why = uniqueItems([
+        ...boundaryPassReasons(input.intent, input.editableFiles),
+        ...changedOutsideBoundaryFiles.map((file) => {
+            return `Changed file outside ${input.intent.controlMode} boundary: ${file}`;
+        }),
+        ...changedOutsideBoundarySymbols.map((symbol) => {
+            return `Changed symbol outside ${input.intent.controlMode} boundary: ${symbol}`;
+        }),
+        ...input.intent.humanGateReason,
+    ]);
+    const fix = uniqueItems([
+        ...changedOutsideBoundaryFiles.map((file) => {
+            return `Unstage file outside boundary: ${file}`;
+        }),
+        ...changedOutsideBoundarySymbols.map((symbol) => {
+            return `Undo or replan unapproved symbol: ${symbol}`;
+        }),
+        "Ask the human to approve a wider boundary before keeping these changes.",
+    ]);
+    return {
+        status,
+        decision,
+        label: status === "danger" ? "DANGER" : "DRIFT",
+        controlMode: input.intent.controlMode,
+        humanRequired,
+        humanGate: input.intent.humanGate,
+        summary: status === "danger"
+            ? "DANGER: staged changes crossed a human-gated control boundary."
+            : "DRIFT: staged changes crossed the selected control boundary.",
+        why,
+        fix,
+        changedOutsideBoundaryFiles,
+        changedOutsideBoundarySymbols,
+    };
+}
+function boundaryPassReasons(intent, editableFiles) {
+    const allowedFiles = editableFiles.length > 0
+        ? editableFiles.join(", ")
+        : "no files";
+    const reasons = [
+        `Control mode '${intent.controlMode}' allows edits to ${allowedFiles}.`,
+    ];
+    if (intent.controlMode === "function") {
+        reasons.push(intent.allowedSymbols.length > 0
+            ? `Allowed symbols: ${intent.allowedSymbols.join(", ")}.`
+            : "No allowed symbols were saved for function mode.");
+    }
+    return reasons;
+}
+function buildDriftVerdict(input) {
+    const boundaryVerdict = input.boundaryVerdict;
+    const policyDrift = input.policyDrift;
+    const readinessDrift = input.readinessDrift;
+    if (input.verdict === "matched" &&
+        boundaryVerdict.status === "pass" &&
+        policyDrift.status !== "changed" &&
+        readinessDrift.status !== "weakened") {
+        const fix = input.verificationTargets.length > 0
+            ? input.verificationTargets
+                .slice(0, 8)
+                .map((target) => `Verify before commit: ${target}`)
+            : ["Proceed after the narrowest manual check for the staged change."];
+        return {
+            status: "pass",
+            decision: "continue",
+            label: "PASS",
+            summary: "PASS: staged changes stayed inside the saved Ripple plan.",
+            why: input.reasons,
+            fix,
+        };
+    }
+    if (input.verdict === "matched" &&
+        boundaryVerdict.status === "pass" &&
+        policyDrift.status === "changed") {
+        return {
+            status: "drift",
+            decision: "stop-and-ask-human",
+            label: "DRIFT",
+            summary: policyDrift.summary,
+            why: policyDrift.why,
+            fix: policyDrift.fix,
+        };
+    }
+    if (input.verdict === "matched" &&
+        boundaryVerdict.status === "pass" &&
+        readinessDrift.status === "weakened") {
+        return {
+            status: "drift",
+            decision: "stop-and-ask-human",
+            label: "DRIFT",
+            summary: readinessDrift.summary,
+            why: readinessDrift.why,
+            fix: readinessDrift.fix,
+        };
+    }
+    if (input.verdict === "matched") {
+        return {
+            status: boundaryVerdict.status,
+            decision: boundaryVerdict.decision,
+            label: boundaryVerdict.label,
+            summary: boundaryVerdict.summary,
+            why: boundaryVerdict.why,
+            fix: boundaryVerdict.fix,
+        };
+    }
+    const contextFilesChanged = new Set(input.contextFilesChanged);
+    const outsideIntentFiles = input.unplannedFiles.filter((file) => {
+        return !contextFilesChanged.has(file);
+    });
+    const intentWhy = input.blockingReasons.length > 0
+        ? input.blockingReasons
+        : input.reasons;
+    const policyWhy = policyDrift.status === "changed" ? policyDrift.why : [];
+    const readinessWhy = readinessDrift.status === "weakened" ? readinessDrift.why : [];
+    const why = uniqueItems([...intentWhy, ...boundaryVerdict.why, ...policyWhy, ...readinessWhy]);
+    const fileFixes = [
+        ...input.contextFilesChanged.map((file) => {
+            return `Unstage context-only file: ${file}`;
+        }),
+        ...outsideIntentFiles.map((file) => {
+            return `Unstage unplanned file: ${file}`;
+        }),
+    ];
+    const symbolFixes = input.unplannedSymbols.map((symbol) => {
+        return `Review or undo unplanned symbol change: ${symbol}`;
+    });
+    const boundaryFixes = boundaryVerdict.status === "pass" ? [] : boundaryVerdict.fix;
+    const policyFixes = policyDrift.status === "changed" ? policyDrift.fix : [];
+    const readinessFixes = readinessDrift.status === "weakened" ? readinessDrift.fix : [];
+    if (input.verdict === "dangerous" || boundaryVerdict.status === "danger") {
+        const contractFixes = [
+            ...input.protectedContractChanges.map((symbol) => {
+                return `Stop and review protected contract change: ${symbol}`;
+            }),
+            ...input.unplannedContractChanges.map((symbol) => {
+                return `Stop and review unplanned contract change: ${symbol}`;
+            }),
+        ];
+        return {
+            status: "danger",
+            decision: "stop-and-ask-human",
+            label: "DANGER",
+            summary: boundaryVerdict.status === "danger" && input.verdict !== "dangerous"
+                ? "DANGER: staged changes crossed the human-selected control boundary."
+                : "DANGER: staged changes include contract drift or unsafe scope expansion.",
+            why,
+            fix: uniqueItems([
+                ...fileFixes,
+                ...symbolFixes,
+                ...boundaryFixes,
+                ...policyFixes,
+                ...readinessFixes,
+                ...contractFixes,
+                "Ask the human before keeping any public contract change.",
+                "Create a new saved intent only after the broader contract change is approved.",
+            ]),
+        };
+    }
+    return {
+        status: "drift",
+        decision: "fix-before-commit",
+        label: "DRIFT",
+        summary: "DRIFT: staged changes left the saved Ripple plan.",
+        why,
+        fix: uniqueItems([
+            ...fileFixes,
+            ...symbolFixes,
+            ...boundaryFixes,
+            ...policyFixes,
+            ...readinessFixes,
+            "Create a new saved intent if the broader scope is intentional.",
+            ...input.nextSteps,
+        ]),
+    };
+}
+function validationVerdict(input) {
+    if (input.protectedContractChanges.length > 0 ||
+        input.unplannedContractChanges.length > 0) {
+        return "dangerous";
+    }
+    if (input.unplannedFiles.length > 0 || input.unplannedSymbols.length > 0) {
+        return "drifted";
+    }
+    return "matched";
+}
+function repairStatus(validation) {
+    if (validation.driftVerdict.status === "pass") {
+        return "no-repair-needed";
+    }
+    if (validation.policyDrift.status === "changed") {
+        return "human-review-required";
+    }
+    if (validation.readinessDrift.status === "weakened") {
+        return "human-review-required";
+    }
+    if (validation.boundaryVerdict.status === "danger" &&
+        validation.verdict !== "dangerous") {
+        return "human-review-required";
+    }
+    if (validation.verdict === "dangerous") {
+        return "contract-review-required";
+    }
+    return "repair-required";
+}
+function repairSummary(validation) {
+    if (validation.driftVerdict.status === "pass") {
+        return "Staged changes match the saved intent; no drift repair is needed.";
+    }
+    if (validation.policyDrift.status === "changed") {
+        return "Current repo policy differs from the saved intent policy snapshot; ask the human before continuing.";
+    }
+    if (validation.readinessDrift.status === "weakened") {
+        return "Current Ripple readiness is weaker than the saved intent readiness snapshot; restore readiness or ask the human before continuing.";
+    }
+    if (validation.boundaryVerdict.status === "danger" &&
+        validation.verdict !== "dangerous") {
+        return "Staged changes crossed a human-gated control boundary; ask the human before continuing.";
+    }
+    if (validation.verdict === "dangerous") {
+        return "Staged changes include contract drift; review contracts before continuing.";
+    }
+    return "Staged changes drifted outside the saved intent; unstage extra files or create a new intent.";
+}
+function validationGuidance(input) {
+    if (input.verdict === "matched") {
+        return {
+            recommendedAction: "Proceed with the saved plan and run the planned verification targets before handoff.",
+            blockingReasons: [],
+            nextSteps: [
+                "Run the narrowest verification target(s) from the staged check.",
+                "Keep the staged set scoped to the saved change intent.",
+            ],
+        };
+    }
+    const contextFilesChanged = new Set(input.contextFilesChanged);
+    const outsideIntentFiles = input.unplannedFiles.filter((file) => !contextFilesChanged.has(file));
+    if (input.verdict === "dangerous") {
+        return {
+            recommendedAction: "Stop and review contract drift; preserve the contract or create a new intent that explicitly allows the contract change.",
+            blockingReasons: [
+                ...input.contextFilesChanged.map((file) => {
+                    return `Context-only file changed: ${file}`;
+                }),
+                ...outsideIntentFiles.map((file) => {
+                    return `Unplanned file changed: ${file}`;
+                }),
+                ...input.protectedContractChanges.map((symbol) => {
+                    return `Protected contract changed: ${symbol}`;
+                }),
+                ...input.unplannedContractChanges.map((symbol) => {
+                    return `Unplanned contract changed: ${symbol}`;
+                }),
+            ],
+            nextSteps: [
+                "Review callers for every contract-drift symbol.",
+                "Either adjust the edit to preserve the contract or create a new intent for the broader contract change.",
+            ],
+        };
+    }
+    return {
+        recommendedAction: "Unstage unplanned files or create a new intent that includes the broader scope before continuing.",
+        blockingReasons: [
+            ...input.contextFilesChanged.map((file) => {
+                return `Context-only file changed: ${file}`;
+            }),
+            ...outsideIntentFiles.map((file) => {
+                return `Unplanned file changed: ${file}`;
+            }),
+            ...input.unplannedSymbols.map((symbol) => {
+                return `Unplanned symbol changed: ${symbol}`;
+            }),
+        ],
+        nextSteps: [
+            "Unstage files that are outside the saved edit scope.",
+            "If the broader edit is intentional, create a new plan and save a new intent for that scope.",
+        ],
+    };
+}
+function validationReasons(input) {
+    const reasons = [];
+    const contextFilesChanged = new Set(input.contextFilesChanged);
+    const outsideIntentFiles = input.unplannedFiles.filter((file) => !contextFilesChanged.has(file));
+    if (input.contextFilesChanged.length > 0) {
+        reasons.push(`${input.contextFilesChanged.length} context-only file(s) were edited`);
+    }
+    if (outsideIntentFiles.length > 0) {
+        reasons.push(`${outsideIntentFiles.length} staged file(s) were outside the saved plan`);
+    }
+    if (input.unplannedSymbols.length > 0) {
+        reasons.push(`${input.unplannedSymbols.length} changed symbol(s) were outside expected symbol focus`);
+    }
+    if (input.protectedContractChanges.length > 0) {
+        reasons.push(`${input.protectedContractChanges.length} protected contract(s) changed`);
+    }
+    if (input.unplannedContractChanges.length > 0) {
+        reasons.push(`${input.unplannedContractChanges.length} unplanned contract change(s) found`);
+    }
+    if (reasons.length === 0) {
+        reasons.push("staged changes stayed inside the saved change intent");
+    }
+    return reasons;
+}
+function contractChangedSymbols(symbols) {
+    return symbols.filter((symbol) => {
+        return symbol.symbolStatus !== "created" && symbol.contractChanged;
+    });
+}
+function changeIntentEditableFiles(intent) {
+    return uniqueItems(intent.editableFiles && intent.editableFiles.length > 0
+        ? intent.editableFiles
+        : intent.expectedFiles.length > 0
+            ? intent.expectedFiles
+            : [intent.targetFile]);
+}
+function changeIntentContextFiles(intent, editableFiles) {
+    const editableFileSet = new Set(editableFiles);
+    const contextFiles = intent.contextFiles && intent.contextFiles.length > 0
+        ? intent.contextFiles
+        : intent.allowedFiles.filter((file) => !editableFileSet.has(file));
+    return uniqueItems(contextFiles.filter((file) => !editableFileSet.has(file)));
+}
+function resolveIntentPath(workspaceRoot, intentPath) {
+    const normalized = intentPath.trim();
+    if (normalized.length === 0 || normalized === "latest") {
+        return defaultChangeIntentPath(workspaceRoot);
+    }
+    if (path.isAbsolute(normalized)) {
+        return normalized;
+    }
+    if (normalized.endsWith(".json") || normalized.includes("/") || normalized.includes("\\")) {
+        return path.resolve(workspaceRoot, normalized);
+    }
+    return path.join(workspaceRoot, INTENTS_DIR, `${normalized}.json`);
+}
+function assertChangeIntent(value, sourcePath) {
+    if (!isRecord(value)) {
+        throw new Error(`Invalid Ripple change intent: ${sourcePath}`);
+    }
+    if (value.protocol !== INTENT_PROTOCOL || value.version !== INTENT_VERSION) {
+        throw new Error(`Unsupported Ripple change intent: ${sourcePath}`);
+    }
+    if (typeof value.id !== "string" ||
+        typeof value.createdAt !== "string" ||
+        typeof value.task !== "string" ||
+        typeof value.targetFile !== "string" ||
+        typeof value.tokenBudget !== "number" ||
+        !Array.isArray(value.allowedFiles) ||
+        !Array.isArray(value.expectedFiles) ||
+        (value.editableFiles !== undefined && !Array.isArray(value.editableFiles)) ||
+        (value.contextFiles !== undefined && !Array.isArray(value.contextFiles)) ||
+        !Array.isArray(value.expectedSymbols) ||
+        !Array.isArray(value.protectedContracts) ||
+        !Array.isArray(value.verificationTargets) ||
+        typeof value.why !== "string") {
+        throw new Error(`Malformed Ripple change intent: ${sourcePath}`);
+    }
+    return normalizeChangeIntent(value);
+}
+function normalizeChangeIntent(intent) {
+    const editableFiles = uniqueItems(intent.editableFiles && intent.editableFiles.length > 0
+        ? intent.editableFiles
+        : intent.expectedFiles.length > 0
+            ? intent.expectedFiles
+            : [intent.targetFile]);
+    const editableFileSet = new Set(editableFiles);
+    const contextFiles = uniqueItems((intent.contextFiles && intent.contextFiles.length > 0
+        ? intent.contextFiles
+        : intent.allowedFiles.filter((file) => !editableFileSet.has(file))).filter((file) => !editableFileSet.has(file)));
+    const controlMode = isControlMode(intent.controlMode) ? intent.controlMode : "file";
+    const allowedSymbols = uniqueItems((intent.allowedSymbols ?? []).filter((symbol) => typeof symbol === "string" && symbol.trim().length > 0));
+    const boundaryRisk = isControlBoundaryRisk(intent.boundaryRisk)
+        ? intent.boundaryRisk
+        : riskFromPath(intent.targetFile);
+    const humanGate = isHumanGate(intent.humanGate) ? intent.humanGate : "none";
+    const humanGateReason = (intent.humanGateReason ?? []).filter((reason) => typeof reason === "string" && reason.trim().length > 0);
+    const policySource = typeof intent.policySource === "string"
+        ? intent.policySource
+        : "legacy-intent";
+    const policyMatches = (intent.policyMatches ?? []).filter((match) => typeof match === "string" && match.trim().length > 0);
+    const policyExplanation = normalizePolicyExplanationSnapshot(intent.policyExplanation, {
+        targetFile: intent.targetFile,
+        controlMode,
+        boundaryRisk,
+        humanGate,
+        policySource,
+        policyMatches,
+        policyRisk: policySource !== "built-in default" && policySource !== "legacy-intent"
+            ? boundaryRisk
+            : "none",
+    });
+    const readinessSnapshot = normalizeReadinessSnapshot(intent.readinessSnapshot);
+    return {
+        ...intent,
+        controlMode,
+        allowedSymbols,
+        humanGate,
+        humanGateReason,
+        boundaryRisk,
+        policySource,
+        policyMatches,
+        policyExplanation,
+        editableFiles,
+        contextFiles,
+        allowedFiles: uniqueItems([...editableFiles, ...contextFiles]),
+        expectedFiles: uniqueItems(intent.expectedFiles.length > 0 ? intent.expectedFiles : editableFiles),
+        readinessSnapshot,
+    };
+}
+function normalizeReadinessSnapshot(value) {
+    if (!isRecord(value)) {
+        return fallbackReadinessSnapshot();
+    }
+    return {
+        status: isReadinessStatus(value.status) ? value.status : "needs_setup",
+        enforcementLevel: isRippleEnforcementLevel(value.enforcementLevel)
+            ? value.enforcementLevel
+            : "none",
+        canGuideAgents: typeof value.canGuideAgents === "boolean" ? value.canGuideAgents : false,
+        canDetectDrift: typeof value.canDetectDrift === "boolean" ? value.canDetectDrift : false,
+        canBlockInCi: typeof value.canBlockInCi === "boolean" ? value.canBlockInCi : false,
+        policyExplicit: typeof value.policyExplicit === "boolean" ? value.policyExplicit : false,
+        graphOk: typeof value.graphOk === "boolean" ? value.graphOk : false,
+        gitOk: typeof value.gitOk === "boolean" ? value.gitOk : false,
+        ciWorkflowOk: typeof value.ciWorkflowOk === "boolean" ? value.ciWorkflowOk : false,
+        latestIntentOk: typeof value.latestIntentOk === "boolean" ? value.latestIntentOk : false,
+        gaps: stringList(value.gaps),
+        nextSteps: stringList(value.nextSteps),
+    };
+}
+function fallbackReadinessSnapshot() {
+    return {
+        status: "needs_setup",
+        enforcementLevel: "none",
+        canGuideAgents: false,
+        canDetectDrift: false,
+        canBlockInCi: false,
+        policyExplicit: false,
+        graphOk: false,
+        gitOk: false,
+        ciWorkflowOk: false,
+        latestIntentOk: false,
+        gaps: ["Readiness snapshot was not captured when this intent was saved."],
+        nextSteps: ["Run ripple doctor --agent."],
+    };
+}
+function isReadinessStatus(value) {
+    return value === "ready" || value === "needs_setup";
+}
+function isRippleEnforcementLevel(value) {
+    return (value === "none" ||
+        value === "advisory" ||
+        value === "drift-check-ready" ||
+        value === "ci-gate-ready");
+}
+function normalizePolicyExplanationSnapshot(value, defaults) {
+    const raw = isRecord(value) ? value : undefined;
+    const rawMatchedRules = raw ? stringList(raw.matchedRules) : [];
+    const matchedRules = raw && Array.isArray(raw.matchedRules)
+        ? rawMatchedRules
+        : defaults.policyMatches;
+    const rawWhy = raw ? stringList(raw.why) : [];
+    const rawNextSteps = raw ? stringList(raw.nextSteps) : [];
+    const rawPolicySource = raw?.policySource;
+    const policySource = typeof rawPolicySource === "string" && rawPolicySource.trim().length > 0
+        ? rawPolicySource
+        : defaults.policySource;
+    const rawPolicyRisk = raw?.policyRisk;
+    return {
+        protocol: "ripple-policy-explanation",
+        version: 1,
+        targetFile: defaults.targetFile,
+        policySource,
+        policyExists: typeof raw?.policyExists === "boolean"
+            ? raw.policyExists
+            : policySource !== "built-in default" && policySource !== "legacy-intent",
+        effectiveMode: defaults.controlMode,
+        policyRisk: isPolicyExplanationRisk(rawPolicyRisk)
+            ? rawPolicyRisk
+            : defaults.policyRisk,
+        humanGate: defaults.humanGate,
+        humanRequired: defaults.humanGate !== "none",
+        allowPrMode: typeof raw?.allowPrMode === "boolean" ? raw.allowPrMode : false,
+        matchedRules,
+        why: rawWhy.length > 0 ? rawWhy : fallbackPolicyExplanationWhy(defaults),
+        nextSteps: rawNextSteps.length > 0
+            ? rawNextSteps
+            : fallbackPolicyExplanationNextSteps(defaults.humanGate),
+    };
+}
+function fallbackPolicyExplanationWhy(defaults) {
+    const why = [
+        `Saved control mode: ${defaults.controlMode}.`,
+        `Policy source at plan time: ${defaults.policySource}.`,
+    ];
+    if (defaults.policyRisk !== "none") {
+        why.push(`Policy risk at plan time: ${defaults.policyRisk}.`);
+    }
+    if (defaults.policyMatches.length > 0) {
+        why.push(`Matched policy rules at plan time: ${defaults.policyMatches.join("; ")}.`);
+    }
+    return why;
+}
+function fallbackPolicyExplanationNextSteps(humanGate) {
+    if (humanGate === "required-before-edit") {
+        return ["Ask the human to approve before the agent edits this file."];
+    }
+    if (humanGate === "required-before-merge") {
+        return ["Require human review before merging this change."];
+    }
+    return ["Check staged changes against this saved intent before handoff."];
+}
+function stringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return uniqueItems(value.filter((item) => typeof item === "string" && item.trim().length > 0));
+}
+function editableFilesForControlMode(plan, controlMode, options) {
+    const explicitFiles = uniqueItems(options.allowedFiles ?? []);
+    if (controlMode === "brainstorm") {
+        return [];
+    }
+    if (controlMode === "task" || controlMode === "pr") {
+        return explicitFiles.length > 0
+            ? explicitFiles
+            : [plan.targetFile];
+    }
+    return [plan.targetFile];
+}
+function allowedSymbolsForControlMode(plan, controlMode, options) {
+    const allowedSymbols = uniqueItems((options.allowedSymbols ?? [])
+        .map((symbol) => normalizeAllowedSymbol(plan.targetFile, symbol))
+        .filter(Boolean));
+    if (controlMode === "function" && allowedSymbols.length === 0) {
+        throw new Error("Function control mode requires --symbol or allowedSymbols.");
+    }
+    return allowedSymbols;
+}
+function normalizeAllowedSymbol(targetFile, symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed) {
+        return "";
+    }
+    return trimmed.includes("::") ? trimmed : `${targetFile}::${trimmed}`;
+}
+function controlBoundaryRisk(plan) {
+    const pathRisk = riskFromPath(plan.targetFile);
+    if (pathRisk === "critical" || pathRisk === "high") {
+        return pathRisk;
+    }
+    if (plan.risk === "dangerous") {
+        return "high";
+    }
+    if (plan.risk === "caution") {
+        return "medium";
+    }
+    return pathRisk;
+}
+function strongestBoundaryRisk(baseRisk, policyRisk) {
+    if (!policyRisk) {
+        return baseRisk;
+    }
+    return boundaryRiskRank(policyRisk) > boundaryRiskRank(baseRisk) ? policyRisk : baseRisk;
+}
+function boundaryRiskRank(risk) {
+    if (risk === "critical") {
+        return 3;
+    }
+    if (risk === "high") {
+        return 2;
+    }
+    if (risk === "medium") {
+        return 1;
+    }
+    return 0;
+}
+function humanGateForPlan(plan, controlMode, boundaryRisk, policy) {
+    if (policy?.requireHumanBeforeEdit) {
+        return "required-before-edit";
+    }
+    if (controlMode === "brainstorm") {
+        return "required-before-edit";
+    }
+    if (boundaryRisk === "critical" || boundaryRisk === "high" || plan.risk === "dangerous") {
+        return "required-before-edit";
+    }
+    if (policy?.requireHumanBeforeMerge) {
+        return "required-before-merge";
+    }
+    if (controlMode === "pr") {
+        return "required-before-merge";
+    }
+    return "none";
+}
+function humanGateReasons(plan, controlMode, boundaryRisk, policy) {
+    const reasons = [];
+    if (policy?.source === "file") {
+        reasons.push(`Trust policy loaded from ${policy.sourcePath ?? ".ripple/policy.json"}.`);
+    }
+    if (policy?.matchedRules.length) {
+        reasons.push(`Trust policy matched: ${policy.matchedRules.join("; ")}.`);
+    }
+    if (policy?.requireHumanBeforeEdit) {
+        reasons.push("Trust policy requires human approval before editing this path.");
+    }
+    if (policy?.requireHumanBeforeMerge) {
+        reasons.push("Trust policy requires human approval before merge.");
+    }
+    if (controlMode === "brainstorm") {
+        reasons.push("Brainstorm mode does not allow file edits.");
+    }
+    if (boundaryRisk === "critical" || boundaryRisk === "high") {
+        reasons.push(`Target path is ${boundaryRisk} risk for agent autonomy.`);
+    }
+    if (plan.risk === "dangerous") {
+        reasons.push("Ripple graph marks the target as dangerous because of blast radius or churn.");
+    }
+    if (controlMode === "pr") {
+        reasons.push("PR mode still requires human review before merge.");
+    }
+    return uniqueItems(reasons);
+}
+function policySourceLabel(policy) {
+    if (!policy) {
+        return "built-in default";
+    }
+    if (policy.source === "file") {
+        return policy.sourcePath ?? ".ripple/policy.json";
+    }
+    return "built-in default";
+}
+function riskFromPath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+    const segments = normalized.split("/");
+    const hasSegment = (names) => {
+        return segments.some((segment) => names.includes(segment));
+    };
+    if (hasSegment([
+        "payment",
+        "payments",
+        "billing",
+        "migrations",
+        "migration",
+        "database",
+        "db",
+        "schema",
+        "secrets",
+        "secret",
+        "deploy",
+        "deployment",
+        "infra",
+        "terraform",
+        ".github",
+        "ci",
+    ]) ||
+        /(^|[/.])(schema|migration|billing|payment|secret|deploy)([/.]|$)/i.test(normalized)) {
+        return "critical";
+    }
+    if (/(^|[/.])(auth|security|session|token|permission|permissions|role|roles|acl|oauth|jwt)([/.]|$)/i
+        .test(normalized)) {
+        return "high";
+    }
+    return "low";
+}
+function assertControlMode(value) {
+    if (!isControlMode(value)) {
+        throw new Error(`Unsupported control mode: ${String(value)}`);
+    }
+}
+function isControlMode(value) {
+    return (value === "brainstorm" ||
+        value === "function" ||
+        value === "file" ||
+        value === "task" ||
+        value === "pr");
+}
+function isHumanGate(value) {
+    return (value === "none" ||
+        value === "required-before-edit" ||
+        value === "required-before-merge");
+}
+function isControlBoundaryRisk(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "critical";
+}
+function isPolicyExplanationRisk(value) {
+    return value === "none" || isControlBoundaryRisk(value);
+}
+function makeIntentId(plan, createdAt) {
+    const hash = crypto
+        .createHash("sha1")
+        .update(`${createdAt}:${plan.targetFile}:${plan.task}`)
+        .digest("hex")
+        .slice(0, 10);
+    return `intent-${Date.now().toString(36)}-${hash}`;
+}
+function isSourceFilePath(value) {
+    return SOURCE_FILE_RE.test(value) && !value.endsWith(".d.ts");
+}
+function uniqueItems(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        if (seen.has(item)) {
+            return false;
+        }
+        seen.add(item);
+        return true;
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=change-intent.js.map