@ttfw/envoi 1.0.0

package/dist/lib/guardrails.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Guardrail preflight checks for verifying state before running verify commands.
+ *
+ * These checks validate:
+ * - Branch match: git branch must equal STATE.branch
+ * - Fingerprint match: TASK fingerprint must match STATE.task_fingerprint
+ * - Worktree clean: git worktree must be clean
+ *
+ * If any check fails, returns a STOP code to prevent unsafe execution.
+ */
+import type { ReportCode } from '../types/report.js';
+import type { Task } from '../types/task.js';
+import type { TickState } from '../types/state.js';
+import type { EnvoiConfig } from '../types/config.js';
+/**
+ * Verify result type classification.
+ */
+export type VerifyResultType = 'PASS' | 'FAIL' | 'TIMEOUT';
+/**
+ * Classification result for a verify command execution.
+ */
+export interface VerifyClassification {
+    /** Result type: PASS, FAIL, or TIMEOUT */
+    resultType: VerifyResultType;
+    /** STOP code if verification failed or timed out, null if passed */
+    stopCode: ReportCode | null;
+    /** Whether this result should increment the failure streak */
+    shouldIncrementFailureStreak: boolean;
+}
+/**
+ * State structure required for guardrail preflight checks.
+ */
+export interface GuardrailState {
+    /** Expected branch name */
+    branch: string;
+    /** Current task fingerprint (SHA256) */
+    task_fingerprint?: string;
+    /** Fingerprint of last failed task */
+    last_failed_fingerprint?: string;
+}
+/**
+ * Result of guardrail preflight checks.
+ */
+export interface PreflightResult {
+    /** Whether all checks passed */
+    ok: boolean;
+    /** Stop code if check failed */
+    stopCode?: ReportCode;
+    /** Human-readable reason for failure */
+    reason?: string;
+}
+/**
+ * Checks if the current git branch matches the expected branch from state.
+ *
+ * @param state - State containing expected branch name
+ * @returns PreflightResult with ok=true if match, or STOP_BRANCH_MISMATCH if mismatch
+ *
+ * @example
+ * ```typescript
+ * const result = checkBranchMatch({ branch: 'task/wp-001' });
+ * if (!result.ok) {
+ *   console.error(`Branch mismatch: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function checkBranchMatch(state: GuardrailState): PreflightResult;
+/**
+ * Checks if the task fingerprint matches state expectations.
+ *
+ * Compares the computed task fingerprint with:
+ * - STATE.task_fingerprint (must match if present)
+ * - STATE.last_failed_fingerprint (must not match - prevents re-dispatch of identical failed task)
+ *
+ * @param state - State containing fingerprint information
+ * @param task - Task to compute fingerprint for
+ * @returns PreflightResult with ok=true if checks pass, or STOP_REDISPATCH_IDENTICAL_TASK if fingerprint matches last failed
+ *
+ * @example
+ * ```typescript
+ * const result = checkFingerprintMatch(state, task);
+ * if (!result.ok) {
+ *   console.error(`Fingerprint check failed: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function checkFingerprintMatch(state: GuardrailState, task: Task): PreflightResult;
+/**
+ * Checks if the git worktree is clean (no uncommitted changes).
+ *
+ * @returns PreflightResult with ok=true if clean, or STOP_MERGE_DIRTY_WORKTREE if dirty
+ *
+ * @example
+ * ```typescript
+ * const result = checkWorktreeClean();
+ * if (!result.ok) {
+ *   console.error(`Worktree is dirty: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function checkWorktreeClean(): PreflightResult;
+/**
+ * Runs all guardrail preflight checks before verify commands.
+ *
+ * Checks are run in order, returning immediately on first failure:
+ * 1. Branch match check
+ * 2. Fingerprint match check
+ * 3. Worktree clean check
+ *
+ * @param state - State containing branch and fingerprint information
+ * @param task - Task to validate fingerprint for
+ * @returns PreflightResult indicating if all checks passed or which check failed
+ *
+ * @example
+ * ```typescript
+ * const result = runGuardrailPreflight(state, task);
+ * if (!result.ok) {
+ *   console.error(`Preflight failed: ${result.stopCode}: ${result.reason}`);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function runGuardrailPreflight(state: GuardrailState, task: Task): PreflightResult;
+/**
+ * Escalation decision result.
+ */
+export interface EscalationDecision {
+    /** Escalation mode: 'none' (no escalation), 'reviewer' (escalate to reviewer), or 'human' (escalate to human) */
+    mode: 'none' | 'reviewer' | 'human';
+    /** Human-readable reason explaining why escalation was triggered (or why it wasn't) */
+    reason: string;
+}
+/**
+ * Determines if escalation should be triggered based on failure streak and stop history.
+ *
+ * Escalation triggers:
+ * - failure_streak >= 2: After 2 consecutive failures, escalate instead of allowing a third normal retry
+ * - stop_history window: If STOPs in last stop_window_ticks >= max_stops_in_window, escalate
+ * - Risk level: MED/HIGH tasks with verify failures may have stricter thresholds (not yet implemented - requires risk field in Task)
+ *
+ * Escalation mode selection:
+ * - If reviewer is enabled in config → mode is 'reviewer'
+ * - Otherwise → mode is 'human'
+ *
+ * @param state - Current tick state containing failure_streak and stop_history
+ * @param config - Envoi configuration containing escalation settings
+ * @param currentTick - Current tick number (for stop window calculation)
+ * @returns EscalationDecision with mode and reason
+ *
+ * @example
+ * ```typescript
+ * const decision = shouldEscalate(state, config, 10);
+ * if (decision.mode !== 'none') {
+ *   console.log(`Escalation required: ${decision.mode} - ${decision.reason}`);
+ * }
+ * ```
+ */
+export declare function shouldEscalate(state: TickState, config: EnvoiConfig, currentTick: number): EscalationDecision;
+/**
+ * Classifies a verify command result into PASS, FAIL, or TIMEOUT.
+ *
+ * Classification rules:
+ * - PASS: exitCode === 0 && !timedOut
+ * - FAIL: exitCode !== 0 && !timedOut
+ * - TIMEOUT: timedOut === true
+ *
+ * STOP code mapping:
+ * - PASS: null (no stop)
+ * - FAIL: STOP_VERIFY_FAILED_FAST (if phase === 'fast') or STOP_VERIFY_FAILED_SLOW (if phase === 'slow')
+ * - TIMEOUT: STOP_VERIFY_FLAKY_OR_TIMEOUT
+ *
+ * Failure streak increment:
+ * - TIMEOUT: always increments failure_streak
+ * - FAIL: may increment based on config (default: true)
+ * - PASS: never increments
+ *
+ * @param exitCode - Process exit code
+ * @param timedOut - Whether the command timed out
+ * @param durationMs - Duration in milliseconds (used for logging/debugging)
+ * @param phase - Verification phase ('fast' or 'slow') to determine correct STOP code for FAIL
+ * @returns VerifyClassification with result type, stop code, and failure streak flag
+ *
+ * @example
+ * ```typescript
+ * const classification = classifyVerifyResult(0, false, 1500, 'fast');
+ * // Returns: { resultType: 'PASS', stopCode: null, shouldIncrementFailureStreak: false }
+ *
+ * const classification = classifyVerifyResult(1, false, 2000, 'slow');
+ * // Returns: { resultType: 'FAIL', stopCode: 'STOP_VERIFY_FAILED_SLOW', shouldIncrementFailureStreak: true }
+ *
+ * const classification = classifyVerifyResult(124, true, 30000, 'fast');
+ * // Returns: { resultType: 'TIMEOUT', stopCode: 'STOP_VERIFY_FLAKY_OR_TIMEOUT', shouldIncrementFailureStreak: true }
+ * ```
+ */
+export declare function classifyVerifyResult(exitCode: number, timedOut: boolean, durationMs: number, phase: 'fast' | 'slow'): VerifyClassification;
+/**
+ * Merge eligibility result indicating whether a merge can proceed.
+ */
+export interface MergeEligibility {
+    /** Whether merge is eligible to proceed */
+    eligible: boolean;
+    /** List of reasons explaining eligibility status */
+    reasons: string[];
+}
+/**
+ * Report structure with git_diff_files field for merge eligibility checks.
+ */
+export interface MergeEligibilityReport {
+    /** List of files changed (from git diff --name-only main...HEAD) */
+    git_diff_files?: string[];
+}
+/**
+ * Checks if merge is eligible based on verification history, diff evidence, and worktree state.
+ *
+ * Merge eligibility requirements:
+ * - verify_history must contain at least one PASS result
+ * - git_diff_files must be non-empty (evidence of changes)
+ * - worktree must be clean (no uncommitted changes)
+ *
+ * @param state - Tick state containing verify_history
+ * @param report - Report containing git_diff_files array
+ * @returns MergeEligibility with eligible status and reasons
+ *
+ * @example
+ * ```typescript
+ * const eligibility = checkMergeEligibility(state, report);
+ * if (!eligibility.eligible) {
+ *   console.error(`Merge not eligible: ${eligibility.reasons.join(', ')}`);
+ * }
+ * ```
+ */
+export declare function checkMergeEligibility(state: TickState, report: MergeEligibilityReport): MergeEligibility;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/lib/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/lib/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,4BAA4B,EAAE,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,gCAAgC;IAChC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAkBvE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,IAAI,GACT,eAAe,CAkBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CASpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,IAAI,GACT,eAAe,CAqBjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iHAAiH;IACjH,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;IACpC,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,GAClB,kBAAkB,CAwDpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GAAG,MAAM,GACrB,oBAAoB,CA4BtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,sBAAsB,GAC7B,gBAAgB,CA0BlB"}

package/dist/lib/guardrails.js

@@ -0,0 +1,323 @@
+/**
+ * Guardrail preflight checks for verifying state before running verify commands.
+ *
+ * These checks validate:
+ * - Branch match: git branch must equal STATE.branch
+ * - Fingerprint match: TASK fingerprint must match STATE.task_fingerprint
+ * - Worktree clean: git worktree must be clean
+ *
+ * If any check fails, returns a STOP code to prevent unsafe execution.
+ */
+import { getCurrentBranch, isWorktreeClean } from './git.js';
+import { computeFingerprint } from './fingerprint.js';
+/**
+ * Checks if the current git branch matches the expected branch from state.
+ *
+ * @param state - State containing expected branch name
+ * @returns PreflightResult with ok=true if match, or STOP_BRANCH_MISMATCH if mismatch
+ *
+ * @example
+ * ```typescript
+ * const result = checkBranchMatch({ branch: 'task/wp-001' });
+ * if (!result.ok) {
+ *   console.error(`Branch mismatch: ${result.reason}`);
+ * }
+ * ```
+ */
+export function checkBranchMatch(state) {
+    try {
+        const currentBranch = getCurrentBranch();
+        if (currentBranch !== state.branch) {
+            return {
+                ok: false,
+                stopCode: 'STOP_BRANCH_MISMATCH',
+                reason: `Current branch '${currentBranch}' does not match expected branch '${state.branch}'`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stopCode: 'STOP_BRANCH_MISMATCH',
+            reason: `Failed to get current branch: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Checks if the task fingerprint matches state expectations.
+ *
+ * Compares the computed task fingerprint with:
+ * - STATE.task_fingerprint (must match if present)
+ * - STATE.last_failed_fingerprint (must not match - prevents re-dispatch of identical failed task)
+ *
+ * @param state - State containing fingerprint information
+ * @param task - Task to compute fingerprint for
+ * @returns PreflightResult with ok=true if checks pass, or STOP_REDISPATCH_IDENTICAL_TASK if fingerprint matches last failed
+ *
+ * @example
+ * ```typescript
+ * const result = checkFingerprintMatch(state, task);
+ * if (!result.ok) {
+ *   console.error(`Fingerprint check failed: ${result.reason}`);
+ * }
+ * ```
+ */
+export function checkFingerprintMatch(state, task) {
+    const taskFingerprint = computeFingerprint(task);
+    // Check if fingerprint matches last failed task (prevent re-dispatch)
+    if (state.last_failed_fingerprint && taskFingerprint === state.last_failed_fingerprint) {
+        return {
+            ok: false,
+            stopCode: 'STOP_REDISPATCH_IDENTICAL_TASK',
+            reason: `Task fingerprint matches last failed fingerprint - identical task re-dispatch detected`,
+        };
+    }
+    // If state has a task_fingerprint, it should match (for consistency check)
+    // Note: This is a guardrail, so we're lenient - if state.task_fingerprint exists but doesn't match,
+    // it might indicate state inconsistency, but we don't stop on this (fingerprint is updated during tick)
+    // The main check is preventing re-dispatch of identical failed tasks
+    return { ok: true };
+}
+/**
+ * Checks if the git worktree is clean (no uncommitted changes).
+ *
+ * @returns PreflightResult with ok=true if clean, or STOP_MERGE_DIRTY_WORKTREE if dirty
+ *
+ * @example
+ * ```typescript
+ * const result = checkWorktreeClean();
+ * if (!result.ok) {
+ *   console.error(`Worktree is dirty: ${result.reason}`);
+ * }
+ * ```
+ */
+export function checkWorktreeClean() {
+    if (!isWorktreeClean()) {
+        return {
+            ok: false,
+            stopCode: 'STOP_MERGE_DIRTY_WORKTREE',
+            reason: 'Git worktree has uncommitted changes or untracked files',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Runs all guardrail preflight checks before verify commands.
+ *
+ * Checks are run in order, returning immediately on first failure:
+ * 1. Branch match check
+ * 2. Fingerprint match check
+ * 3. Worktree clean check
+ *
+ * @param state - State containing branch and fingerprint information
+ * @param task - Task to validate fingerprint for
+ * @returns PreflightResult indicating if all checks passed or which check failed
+ *
+ * @example
+ * ```typescript
+ * const result = runGuardrailPreflight(state, task);
+ * if (!result.ok) {
+ *   console.error(`Preflight failed: ${result.stopCode}: ${result.reason}`);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function runGuardrailPreflight(state, task) {
+    // 1. Check branch match
+    const branchResult = checkBranchMatch(state);
+    if (!branchResult.ok) {
+        return branchResult;
+    }
+    // 2. Check fingerprint match
+    const fingerprintResult = checkFingerprintMatch(state, task);
+    if (!fingerprintResult.ok) {
+        return fingerprintResult;
+    }
+    // 3. Check worktree clean
+    const worktreeResult = checkWorktreeClean();
+    if (!worktreeResult.ok) {
+        return worktreeResult;
+    }
+    // All checks passed
+    return { ok: true };
+}
+/**
+ * Determines if escalation should be triggered based on failure streak and stop history.
+ *
+ * Escalation triggers:
+ * - failure_streak >= 2: After 2 consecutive failures, escalate instead of allowing a third normal retry
+ * - stop_history window: If STOPs in last stop_window_ticks >= max_stops_in_window, escalate
+ * - Risk level: MED/HIGH tasks with verify failures may have stricter thresholds (not yet implemented - requires risk field in Task)
+ *
+ * Escalation mode selection:
+ * - If reviewer is enabled in config → mode is 'reviewer'
+ * - Otherwise → mode is 'human'
+ *
+ * @param state - Current tick state containing failure_streak and stop_history
+ * @param config - Envoi configuration containing escalation settings
+ * @param currentTick - Current tick number (for stop window calculation)
+ * @returns EscalationDecision with mode and reason
+ *
+ * @example
+ * ```typescript
+ * const decision = shouldEscalate(state, config, 10);
+ * if (decision.mode !== 'none') {
+ *   console.log(`Escalation required: ${decision.mode} - ${decision.reason}`);
+ * }
+ * ```
+ */
+export function shouldEscalate(state, config, currentTick) {
+    const failureStreak = state.failure_streak ?? 0;
+    const stopHistory = state.guardrail?.stop_history ?? [];
+    // Check failure streak >= 2
+    if (failureStreak >= 2) {
+        const reviewerEnabled = config.reviewer?.enabled ?? false;
+        const mode = reviewerEnabled ? 'reviewer' : 'human';
+        return {
+            mode,
+            reason: `Failure streak is ${failureStreak} (>= 2). Escalating to prevent infinite retry loops.`,
+        };
+    }
+    // Check stop history window
+    const reviewerConfig = config.reviewer;
+    if (reviewerConfig?.trigger?.on_repeated_stop &&
+        reviewerConfig.trigger.stop_window_ticks > 0 &&
+        reviewerConfig.trigger.max_stops_in_window > 0) {
+        const windowTicks = reviewerConfig.trigger.stop_window_ticks;
+        const maxStops = reviewerConfig.trigger.max_stops_in_window;
+        // Count stops in recent history
+        // Since stop_history entries don't have tick numbers, we count the last N entries
+        // where N = windowTicks (approximating ticks with entries)
+        // This is a reasonable approximation: if we have >= maxStops entries in the window,
+        // we've exceeded the threshold
+        const recentStops = stopHistory.slice(-windowTicks);
+        if (recentStops.length >= maxStops) {
+            const reviewerEnabled = reviewerConfig.enabled ?? false;
+            const mode = reviewerEnabled ? 'reviewer' : 'human';
+            return {
+                mode,
+                reason: `Found ${recentStops.length} stops in last ${windowTicks} entries (>= ${maxStops}). Escalating to prevent repeated failures.`,
+            };
+        }
+    }
+    // Risk level check (MED/HIGH with verify failure)
+    // Note: This requires a risk field in Task which is not yet in the schema.
+    // For now, we skip this check. When risk is added to Task, we can check:
+    // if (task.risk === 'MED' || task.risk === 'HIGH') {
+    //   const verifyFailed = state.verify_history?.some(e => e.result === 'FAIL') ?? false;
+    //   if (verifyFailed) {
+    //     return { mode: reviewerEnabled ? 'reviewer' : 'human', reason: 'MED/HIGH risk task with verify failure' };
+    //   }
+    // }
+    // No escalation needed
+    return {
+        mode: 'none',
+        reason: 'No escalation triggers detected. Failure streak and stop history are within acceptable limits.',
+    };
+}
+/**
+ * Classifies a verify command result into PASS, FAIL, or TIMEOUT.
+ *
+ * Classification rules:
+ * - PASS: exitCode === 0 && !timedOut
+ * - FAIL: exitCode !== 0 && !timedOut
+ * - TIMEOUT: timedOut === true
+ *
+ * STOP code mapping:
+ * - PASS: null (no stop)
+ * - FAIL: STOP_VERIFY_FAILED_FAST (if phase === 'fast') or STOP_VERIFY_FAILED_SLOW (if phase === 'slow')
+ * - TIMEOUT: STOP_VERIFY_FLAKY_OR_TIMEOUT
+ *
+ * Failure streak increment:
+ * - TIMEOUT: always increments failure_streak
+ * - FAIL: may increment based on config (default: true)
+ * - PASS: never increments
+ *
+ * @param exitCode - Process exit code
+ * @param timedOut - Whether the command timed out
+ * @param durationMs - Duration in milliseconds (used for logging/debugging)
+ * @param phase - Verification phase ('fast' or 'slow') to determine correct STOP code for FAIL
+ * @returns VerifyClassification with result type, stop code, and failure streak flag
+ *
+ * @example
+ * ```typescript
+ * const classification = classifyVerifyResult(0, false, 1500, 'fast');
+ * // Returns: { resultType: 'PASS', stopCode: null, shouldIncrementFailureStreak: false }
+ *
+ * const classification = classifyVerifyResult(1, false, 2000, 'slow');
+ * // Returns: { resultType: 'FAIL', stopCode: 'STOP_VERIFY_FAILED_SLOW', shouldIncrementFailureStreak: true }
+ *
+ * const classification = classifyVerifyResult(124, true, 30000, 'fast');
+ * // Returns: { resultType: 'TIMEOUT', stopCode: 'STOP_VERIFY_FLAKY_OR_TIMEOUT', shouldIncrementFailureStreak: true }
+ * ```
+ */
+export function classifyVerifyResult(exitCode, timedOut, durationMs, phase) {
+    // TIMEOUT takes precedence - if timed out, it's always TIMEOUT
+    if (timedOut) {
+        return {
+            resultType: 'TIMEOUT',
+            stopCode: 'STOP_VERIFY_FLAKY_OR_TIMEOUT',
+            shouldIncrementFailureStreak: true,
+        };
+    }
+    // PASS: exit code 0 and not timed out
+    if (exitCode === 0) {
+        return {
+            resultType: 'PASS',
+            stopCode: null,
+            shouldIncrementFailureStreak: false,
+        };
+    }
+    // FAIL: non-zero exit code and not timed out
+    const stopCode = phase === 'fast' ? 'STOP_VERIFY_FAILED_FAST' : 'STOP_VERIFY_FAILED_SLOW';
+    return {
+        resultType: 'FAIL',
+        stopCode,
+        shouldIncrementFailureStreak: true, // Default to true, caller can override based on config
+    };
+}
+/**
+ * Checks if merge is eligible based on verification history, diff evidence, and worktree state.
+ *
+ * Merge eligibility requirements:
+ * - verify_history must contain at least one PASS result
+ * - git_diff_files must be non-empty (evidence of changes)
+ * - worktree must be clean (no uncommitted changes)
+ *
+ * @param state - Tick state containing verify_history
+ * @param report - Report containing git_diff_files array
+ * @returns MergeEligibility with eligible status and reasons
+ *
+ * @example
+ * ```typescript
+ * const eligibility = checkMergeEligibility(state, report);
+ * if (!eligibility.eligible) {
+ *   console.error(`Merge not eligible: ${eligibility.reasons.join(', ')}`);
+ * }
+ * ```
+ */
+export function checkMergeEligibility(state, report) {
+    const reasons = [];
+    // Check 1: verify_history must contain at least one PASS
+    const verifyHistory = state.verify_history ?? [];
+    const hasPass = verifyHistory.some((entry) => entry.result === 'PASS');
+    if (!hasPass) {
+        reasons.push('verify_history does not contain any PASS results');
+    }
+    // Check 2: git_diff_files must be non-empty
+    const gitDiffFiles = report.git_diff_files ?? [];
+    if (gitDiffFiles.length === 0) {
+        reasons.push('git_diff_files is empty (no evidence of changes)');
+    }
+    // Check 3: worktree must be clean
+    const worktreeResult = checkWorktreeClean();
+    if (!worktreeResult.ok) {
+        reasons.push(worktreeResult.reason || 'Git worktree has uncommitted changes');
+    }
+    return {
+        eligible: reasons.length === 0,
+        reasons: reasons.length > 0 ? reasons : ['All merge eligibility checks passed'],
+    };
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/lib/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/lib/guardrails.ts"],"names":[],"mappings":"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"}

package/dist/lib/history.d.ts

@@ -0,0 +1,110 @@
+/**
+ * History management utilities for preserving tick run artifacts.
+ *
+ * Each tick's artifacts (report.json, report.md, diff.patch, verify.log) are
+ * preserved in history/<run_id>/ to enable debugging and audit trails.
+ */
+import type { EnvoiConfig } from '../types/config.js';
+import type { ReportData } from '../types/report.js';
+import type { RawAjvError } from './schema.js';
+/**
+ * Creates the history snapshot directory for a run.
+ *
+ * @param runId - Run ID
+ * @param config - Envoi configuration
+ * @returns Promise that resolves when directory is created
+ * @throws {Error} If directory creation fails
+ */
+export declare function createHistorySnapshot(runId: string, config: EnvoiConfig): Promise<void>;
+/**
+ * Writes an artifact file to the history directory for a run.
+ *
+ * @param runId - Run ID
+ * @param filename - Name of the artifact file (e.g., 'report.json', 'diff.patch')
+ * @param content - Content to write (string for text files, object for JSON)
+ * @param config - Envoi configuration
+ * @returns Promise that resolves when write completes
+ * @throws {Error} If the write operation fails
+ */
+export declare function writeHistoryArtifact(runId: string, filename: string, content: string | object, config: EnvoiConfig): Promise<void>;
+/**
+ * Creates a complete history snapshot for a tick run.
+ *
+ * Saves all artifacts (meta.json, report.json, report.md, and optionally
+ * diff.patch and verify.log) to history/<run_id>/.
+ *
+ * @param runId - Run ID
+ * @param report - Report data
+ * @param markdown - Markdown rendering of the report
+ * @param diffPatch - Optional diff patch content
+ * @param verifyLog - Optional verification log content
+ * @param config - Envoi configuration
+ * @returns Promise that resolves when all artifacts are saved
+ * @throws {Error} If any write operation fails
+ */
+export declare function snapshotRun(runId: string, report: ReportData, markdown: string, diffPatch: string | null, verifyLog: string | null, config: EnvoiConfig): Promise<void>;
+/**
+ * Counts the number of existing history entries.
+ *
+ * @param config - Envoi configuration
+ * @returns Promise that resolves to the count of history entries
+ * @throws {Error} If reading the history directory fails
+ */
+/**
+ * Error information for builder failures.
+ */
+export interface BuilderErrorInfo {
+    /** Error kind matching BuilderParseErrorKind or 'cli_error' */
+    kind: 'json_parse' | 'schema' | 'shape' | 'cli_error';
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: unknown;
+}
+/**
+ * Persists builder failure artifacts to history for debugging.
+ *
+ * Writes raw stdout, stderr (if available), and error info to
+ * history/<run_id>/ for post-mortem analysis.
+ *
+ * @param runId - Run ID
+ * @param stdout - Raw stdout from builder invocation
+ * @param stderr - Raw stderr from builder invocation (may be null)
+ * @param errorInfo - Structured error information
+ * @param config - Envoi configuration
+ * @returns Promise that resolves when all artifacts are saved
+ * @throws {Error} If any write operation fails
+ */
+export declare function persistBuilderFailure(runId: string, stdout: string, stderr: string | null, errorInfo: BuilderErrorInfo, config: EnvoiConfig): Promise<void>;
+/**
+ * Metadata for orchestrator failure artifacts.
+ */
+export interface OrchestratorFailureMeta {
+    run_id: string;
+    phase: 'orchestrator';
+    model: string;
+    timeout_ms: number;
+    prompt_chars: number;
+    system_prompt_chars: number;
+    cwd: string;
+    args_summary_redacted: string;
+}
+/**
+ * Persists orchestrator failure artifacts to history for debugging.
+ *
+ * Writes stdout, stderr, extracted JSON, schema errors, and meta to
+ * history/<run_id>/orchestrator/ for post-mortem analysis.
+ *
+ * @param runId - Run ID
+ * @param stdout - Raw stdout from orchestrator invocation
+ * @param stderr - Raw stderr from orchestrator invocation
+ * @param extractedJson - Extracted JSON candidate if extraction succeeded
+ * @param schemaErrors - Ajv errors array when validation fails
+ * @param meta - Invocation metadata
+ * @param config - Envoi configuration
+ * @returns Promise that resolves when all artifacts are saved
+ * @throws {Error} If any write operation fails
+ */
+export declare function persistOrchestratorFailure(runId: string, stdout: string, stderr: string, extractedJson: unknown | null, schemaErrors: RawAjvError[] | null, meta: OrchestratorFailureMeta, config: EnvoiConfig): Promise<void>;
+export declare function getHistoryCount(config: EnvoiConfig): Promise<number>;
+//# sourceMappingURL=history.d.ts.map

package/dist/lib/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/lib/history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,oBAAoB,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuE/C;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7F;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CASf;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;GAMG;AACH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,IAAI,EAAE,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;IACtD,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf;AAeD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,OAAO,GAAG,IAAI,EAC7B,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI,EAClC,IAAI,EAAE,uBAAuB,EAC7B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1E"}