@getripple/core 1.0.4

package/dist/change-intent.d.ts

@@ -0,0 +1,242 @@
+import { ContextPlanSummary } from "./graph";
+import { StagedCheckAgentActions, StagedCheckSummary } from "./staged-check";
+import type { AgentRuntimeNextPhaseId } from "./agent-workflow";
+import type { RipplePolicyExplanation, RipplePolicyResolution } from "./policy";
+import type { RippleEnforcementLevel, RippleReadinessSummary } from "./readiness";
+export type ChangeIntent = {
+    protocol: "ripple-change-intent";
+    version: 1;
+    id: string;
+    createdAt: string;
+    task: string;
+    targetFile: string;
+    risk: ContextPlanSummary["risk"];
+    tokenBudget: number;
+    controlMode: ControlMode;
+    allowedSymbols: string[];
+    humanGate: HumanGate;
+    humanGateReason: string[];
+    boundaryRisk: ControlBoundaryRisk;
+    policySource: string;
+    policyMatches: string[];
+    policyExplanation: RipplePolicyExplanation;
+    editableFiles: string[];
+    contextFiles: string[];
+    allowedFiles: string[];
+    expectedFiles: string[];
+    expectedSymbols: string[];
+    protectedContracts: string[];
+    verificationTargets: string[];
+    readinessSnapshot: ChangeIntentReadinessSnapshot;
+    why: string;
+};
+export type ChangeIntentReadinessSnapshot = {
+    status: RippleReadinessSummary["status"];
+    enforcementLevel: RippleEnforcementLevel;
+    canGuideAgents: boolean;
+    canDetectDrift: boolean;
+    canBlockInCi: boolean;
+    policyExplicit: boolean;
+    graphOk: boolean;
+    gitOk: boolean;
+    ciWorkflowOk: boolean;
+    latestIntentOk: boolean;
+    gaps: string[];
+    nextSteps: string[];
+};
+export type ChangeIntentVerdict = "matched" | "drifted" | "dangerous";
+export type ChangeIntentScope = "matched" | "violated";
+export type ControlMode = "brainstorm" | "function" | "file" | "task" | "pr";
+export type HumanGate = "none" | "required-before-edit" | "required-before-merge";
+export type ControlBoundaryRisk = "low" | "medium" | "high" | "critical";
+export type DriftVerdictStatus = "pass" | "drift" | "danger" | "unknown";
+export type DriftDecision = "continue" | "fix-before-commit" | "stop-and-ask-human" | "create-intent-first";
+export type DriftVerdictSummary = {
+    status: DriftVerdictStatus;
+    decision: DriftDecision;
+    label: "PASS" | "DRIFT" | "DANGER" | "UNKNOWN";
+    summary: string;
+    why: string[];
+    fix: string[];
+};
+export type PolicyDriftStatus = "unchecked" | "unchanged" | "changed";
+export type PolicyDriftDecision = "continue" | "compare-current-policy" | "review-current-policy";
+export type PolicyDriftSummary = {
+    status: PolicyDriftStatus;
+    decision: PolicyDriftDecision;
+    label: "UNKNOWN" | "PASS" | "DRIFT";
+    summary: string;
+    changedFields: string[];
+    why: string[];
+    fix: string[];
+    currentPolicyExplanation?: RipplePolicyExplanation;
+};
+export type ReadinessDriftStatus = "unchecked" | "unchanged" | "weakened";
+export type ReadinessDriftDecision = "continue" | "compare-current-readiness" | "restore-readiness";
+export type ReadinessDriftSummary = {
+    status: ReadinessDriftStatus;
+    decision: ReadinessDriftDecision;
+    label: "UNKNOWN" | "PASS" | "DRIFT";
+    summary: string;
+    changedFields: string[];
+    weakenedFields: string[];
+    savedReadiness: ChangeIntentReadinessSnapshot;
+    currentReadiness?: ChangeIntentReadinessSnapshot;
+    why: string[];
+    fix: string[];
+};
+export type RippleAgentHandoffSource = "check" | "repair" | "audit";
+export type RippleAgentHandoffDecision = "continue" | "audit" | "repair" | "human-review" | "restore-readiness" | "create-intent";
+export type RippleAgentHandoffCommands = {
+    doctor: string[];
+    plan: string[];
+    check: string[];
+    audit: string[];
+    repair: string[];
+    approve: string[];
+    unstage: string[];
+    verify: string[];
+};
+export type RippleAgentHandoffVerdict = {
+    protocol: "ripple-agent-handoff";
+    version: 1;
+    source: RippleAgentHandoffSource;
+    canContinue: boolean;
+    mustStop: boolean;
+    needsHuman: boolean;
+    decision: RippleAgentHandoffDecision;
+    nextRequiredPhase: AgentRuntimeNextPhaseId;
+    nextRequiredAction: string;
+    summary: string;
+    why: string[];
+    fixNow: string[];
+    askHuman: string[];
+    commands: RippleAgentHandoffCommands;
+};
+export type BoundaryVerdictStatus = "pass" | "drift" | "danger";
+export type BoundaryDecision = "continue" | "fix-before-commit" | "stop-and-ask-human";
+export type BoundaryVerdictSummary = {
+    status: BoundaryVerdictStatus;
+    decision: BoundaryDecision;
+    label: "PASS" | "DRIFT" | "DANGER";
+    controlMode: ControlMode;
+    humanRequired: boolean;
+    humanGate: HumanGate;
+    summary: string;
+    why: string[];
+    fix: string[];
+    changedOutsideBoundaryFiles: string[];
+    changedOutsideBoundarySymbols: string[];
+};
+export type ChangeIntentValidationSummary = {
+    intentId: string;
+    targetFile: string;
+    task: string;
+    verdict: ChangeIntentVerdict;
+    driftVerdict: DriftVerdictSummary;
+    boundaryVerdict: BoundaryVerdictSummary;
+    controlMode: ControlMode;
+    allowedFiles: string[];
+    allowedSymbols: string[];
+    humanGate: HumanGate;
+    humanGateReason: string[];
+    boundaryRisk: ControlBoundaryRisk;
+    policyExplanation: RipplePolicyExplanation;
+    policyDrift: PolicyDriftSummary;
+    readinessDrift: ReadinessDriftSummary;
+    plannedScope: ChangeIntentScope;
+    editableFiles: string[];
+    contextFiles: string[];
+    plannedFilesChanged: string[];
+    contextFilesChanged: string[];
+    expectedSymbolsChanged: string[];
+    unplannedFiles: string[];
+    unplannedSymbols: string[];
+    protectedContractChanges: string[];
+    unplannedContractChanges: string[];
+    reasons: string[];
+    recommendedAction: string;
+    nextRequiredPhase: AgentRuntimeNextPhaseId;
+    nextRequiredAction: string;
+    blockingReasons: string[];
+    nextSteps: string[];
+    requiresAttention: boolean;
+    handoff: RippleAgentHandoffVerdict;
+};
+export type StagedCheckWithIntentSummary = StagedCheckSummary & {
+    intentValidation?: ChangeIntentValidationSummary;
+    nextRequiredPhase?: AgentRuntimeNextPhaseId;
+    nextRequiredAction?: string;
+};
+export type IntentDriftRepairStatus = "no-repair-needed" | "repair-required" | "human-review-required" | "contract-review-required" | "intent-required";
+export type IntentDriftRepairActionType = "proceed" | "unstage-file" | "review-symbol" | "review-contract" | "review-policy" | "review-readiness" | "replan" | "verify" | "create-intent";
+export type IntentDriftRepairActionPriority = "blocker" | "required" | "recommended";
+export type IntentDriftRepairAction = {
+    type: IntentDriftRepairActionType;
+    priority: IntentDriftRepairActionPriority;
+    target?: string;
+    command?: string;
+    reason: string;
+    instruction: string;
+};
+export type IntentDriftRepairPlan = {
+    protocol: "ripple-intent-drift-repair";
+    version: 1;
+    intentId?: string;
+    verdict: ChangeIntentVerdict | "missing-intent";
+    driftVerdict: DriftVerdictSummary;
+    boundaryVerdict?: BoundaryVerdictSummary;
+    policyExplanation?: RipplePolicyExplanation;
+    policyDrift?: PolicyDriftSummary;
+    readinessDrift?: ReadinessDriftSummary;
+    status: IntentDriftRepairStatus;
+    summary: string;
+    recommendedAction: string;
+    blockingReasons: string[];
+    unstageFiles: string[];
+    reviewContracts: string[];
+    createNewIntent: boolean;
+    verificationTargets: string[];
+    fixActions: IntentDriftRepairAction[];
+    agentActions: StagedCheckAgentActions;
+    commands: {
+        unstage: string[];
+        replan: string[];
+        verify: string[];
+    };
+    nextSteps: string[];
+    handoff: RippleAgentHandoffVerdict;
+};
+export type BuildChangeIntentOptions = {
+    controlMode?: ControlMode;
+    allowedFiles?: string[];
+    allowedSymbols?: string[];
+    policy?: RipplePolicyResolution;
+    policyExplanation?: RipplePolicyExplanation;
+    readinessSnapshot?: ChangeIntentReadinessSnapshot;
+};
+export type ValidateChangeIntentOptions = {
+    currentPolicyExplanation?: RipplePolicyExplanation;
+    currentReadinessSnapshot?: ChangeIntentReadinessSnapshot;
+};
+export declare function buildChangeIntent(plan: ContextPlanSummary, options?: BuildChangeIntentOptions): ChangeIntent;
+export declare function buildChangeIntentReadinessSnapshot(readiness: RippleReadinessSummary): ChangeIntentReadinessSnapshot;
+export declare function buildAgentHandoffVerdict(input: {
+    source: RippleAgentHandoffSource;
+    canContinue: boolean;
+    needsHuman: boolean;
+    decision: RippleAgentHandoffDecision;
+    nextRequiredPhase: AgentRuntimeNextPhaseId;
+    nextRequiredAction: string;
+    summary: string;
+    why: string[];
+    fixNow: string[];
+    askHuman?: string[];
+    commands?: Partial<RippleAgentHandoffCommands>;
+    mustStop?: boolean;
+}): RippleAgentHandoffVerdict;
+export declare function validateStagedCheckAgainstIntent(staged: StagedCheckSummary, intent: ChangeIntent, options?: ValidateChangeIntentOptions): StagedCheckWithIntentSummary;
+export declare function buildIntentDriftRepairPlan(staged: StagedCheckWithIntentSummary): IntentDriftRepairPlan;
+export declare function saveChangeIntent(workspaceRoot: string, intent: ChangeIntent, intentPath?: string): string;
+export declare function loadChangeIntent(workspaceRoot: string, intentPath?: string): ChangeIntent;
+export declare function defaultChangeIntentPath(workspaceRoot: string): string;