sequant 1.20.2 → 2.0.0

package/dist/src/lib/workflow/reconcile.js

@@ -0,0 +1,290 @@
+/**
+ * Reconciliation engine for sequant status
+ *
+ * Reconciles local state.json with GitHub API and filesystem
+ * to provide accurate, up-to-date status information.
+ *
+ * @module reconcile
+ */
+import * as fs from "fs";
+import { StateManager } from "./state-manager.js";
+import { GitHubProvider, } from "./platforms/github.js";
+/**
+ * Classify drift for a single issue based on GitHub and filesystem state.
+ */
+export function classifyDrift(issue, githubIssue, githubPR, worktreeExists) {
+    const num = issue.number;
+    // Check PR merge → unambiguous
+    if (githubPR?.state === "MERGED" && issue.status !== "merged") {
+        return {
+            issueNumber: num,
+            type: "unambiguous",
+            action: "update_to_merged",
+            description: `PR #${githubPR.number} merged on GitHub`,
+        };
+    }
+    // Check issue closed + no merged PR → unambiguous abandoned
+    if (githubIssue?.state === "CLOSED" &&
+        issue.status !== "merged" &&
+        issue.status !== "abandoned" &&
+        githubPR?.state !== "MERGED") {
+        return {
+            issueNumber: num,
+            type: "unambiguous",
+            action: "update_to_abandoned",
+            description: `Issue #${num} closed on GitHub without merged PR`,
+        };
+    }
+    // Check worktree missing
+    if (issue.worktree && worktreeExists === false) {
+        if (!issue.pr?.number) {
+            if (githubIssue?.state === "OPEN") {
+                // Confirmed open on GitHub, no PR → ambiguous
+                return {
+                    issueNumber: num,
+                    type: "ambiguous",
+                    action: "flag_missing_worktree",
+                    description: `Worktree deleted but issue #${num} still open on GitHub with no PR`,
+                };
+            }
+            if (!githubIssue) {
+                // GitHub data unavailable → ambiguous (can't determine if safe to clear)
+                return {
+                    issueNumber: num,
+                    type: "ambiguous",
+                    action: "flag_missing_worktree",
+                    description: `Worktree deleted for issue #${num} but GitHub state unknown (API unreachable)`,
+                };
+            }
+        }
+        // Otherwise just clear worktree (unambiguous)
+        return {
+            issueNumber: num,
+            type: "unambiguous",
+            action: "clear_worktree",
+            description: `Worktree path no longer exists for issue #${num}`,
+        };
+    }
+    // Check local abandoned but GitHub open → ambiguous
+    if (issue.status === "abandoned" && githubIssue?.state === "OPEN") {
+        return {
+            issueNumber: num,
+            type: "ambiguous",
+            action: "flag_status_mismatch",
+            description: `Issue #${num} marked abandoned locally but still open on GitHub`,
+        };
+    }
+    return null;
+}
+/**
+ * Get a next-action hint for an issue based on its current state.
+ */
+export function getNextActionHint(issue) {
+    switch (issue.status) {
+        case "not_started":
+            return `sequant run ${issue.number}`;
+        case "in_progress": {
+            // Suggest resuming at current phase or next phase
+            if (issue.currentPhase) {
+                const failedPhase = Object.entries(issue.phases).find(([, ps]) => ps.status === "failed");
+                if (failedPhase) {
+                    return `sequant run ${issue.number} --phase ${failedPhase[0]}`;
+                }
+            }
+            return `sequant run ${issue.number}`;
+        }
+        case "waiting_for_qa_gate":
+            return `sequant run ${issue.number} --phase qa`;
+        case "ready_for_merge":
+            if (issue.pr?.number) {
+                return `gh pr merge ${issue.pr.number}`;
+            }
+            return `gh pr merge`;
+        case "blocked":
+            return `resolve blockers, then sequant run ${issue.number}`;
+        case "merged":
+            return `sequant status --cleanup`;
+        case "abandoned":
+            return `reopen issue or sequant status --cleanup`;
+        default:
+            return "";
+    }
+}
+/**
+ * Format a relative time string from an ISO timestamp.
+ */
+export function formatRelativeTime(isoTimestamp) {
+    if (!isoTimestamp)
+        return "unknown";
+    const date = new Date(isoTimestamp);
+    if (isNaN(date.getTime()))
+        return "unknown";
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    // Handle future timestamps (clock skew)
+    if (diffMs < 0)
+        return "just now";
+    const diffSec = Math.floor(diffMs / 1000);
+    const diffMin = Math.floor(diffSec / 60);
+    const diffHour = Math.floor(diffMin / 60);
+    const diffDay = Math.floor(diffHour / 24);
+    if (diffSec < 60)
+        return "just now";
+    if (diffMin < 60)
+        return `${diffMin} minute${diffMin > 1 ? "s" : ""} ago`;
+    if (diffHour < 24)
+        return `${diffHour} hour${diffHour > 1 ? "s" : ""} ago`;
+    if (diffDay < 7)
+        return `${diffDay} day${diffDay > 1 ? "s" : ""} ago`;
+    return date.toLocaleDateString();
+}
+/**
+ * Reconcile local workflow state with GitHub and filesystem.
+ *
+ * This is the main entry point for reconciliation. Called by:
+ * - `sequant status` (CLI)
+ * - `sequant_status` (MCP tool)
+ */
+export async function reconcileState(options = {}) {
+    const stateManager = options.stateManager ??
+        new StateManager({
+            // Increase lock timeout for reconcile — GitHub API calls may be slow
+            lockTimeout: 30_000,
+        });
+    const now = new Date().toISOString();
+    if (!stateManager.stateExists()) {
+        return {
+            success: true,
+            healed: [],
+            warnings: [],
+            lastSynced: now,
+            githubReachable: !options.offline,
+        };
+    }
+    try {
+        // Wrap the entire read-modify-write cycle (including GitHub API calls)
+        // in a single lock to prevent concurrent updatePhaseStatus from
+        // interleaving and causing state regression. (#458 AC-4)
+        return await stateManager.withLock(async () => {
+            const state = await stateManager.getState();
+            const issues = Object.values(state.issues);
+            if (issues.length === 0) {
+                state.lastSynced = now;
+                await stateManager.saveState(state);
+                return {
+                    success: true,
+                    healed: [],
+                    warnings: [],
+                    lastSynced: now,
+                    githubReachable: !options.offline,
+                };
+            }
+            // Collect issue and PR numbers to query
+            const issueNumbers = issues.map((i) => i.number);
+            const prNumbers = issues
+                .filter((i) => i.pr?.number)
+                .map((i) => i.pr.number);
+            // Batch fetch from GitHub (unless offline)
+            let githubIssues = {};
+            let githubPRs = {};
+            let githubReachable = false;
+            if (!options.offline) {
+                const github = new GitHubProvider();
+                const batchResult = github.batchFetchIssueAndPRStatus(issueNumbers, prNumbers);
+                if (!batchResult.error) {
+                    githubIssues = batchResult.issues;
+                    githubPRs = batchResult.pullRequests;
+                    githubReachable = true;
+                }
+                // On error: graceful degradation — proceed with cached data
+            }
+            // Check filesystem for worktrees
+            const worktreeExists = {};
+            for (const issue of issues) {
+                if (issue.worktree) {
+                    worktreeExists[issue.number] = fs.existsSync(issue.worktree);
+                }
+            }
+            // Classify and apply drift
+            const healed = [];
+            const warnings = [];
+            let stateModified = false;
+            for (const issue of issues) {
+                const issueKey = String(issue.number);
+                const ghIssue = githubIssues[issue.number];
+                const ghPR = issue.pr?.number ? githubPRs[issue.pr.number] : undefined;
+                const wtExists = issue.worktree
+                    ? worktreeExists[issue.number]
+                    : undefined;
+                // Update title from GitHub if available
+                if (ghIssue?.title && ghIssue.title !== issue.title) {
+                    state.issues[issueKey].title = ghIssue.title;
+                    stateModified = true;
+                }
+                const drift = classifyDrift(issue, ghIssue, ghPR, wtExists);
+                // Always clear missing worktrees independently of other drift
+                if (issue.worktree &&
+                    wtExists === false &&
+                    drift?.type !== "ambiguous") {
+                    state.issues[issueKey].worktree = undefined;
+                    stateModified = true;
+                }
+                if (!drift)
+                    continue;
+                if (drift.type === "unambiguous") {
+                    // Auto-heal
+                    switch (drift.action) {
+                        case "update_to_merged":
+                            state.issues[issueKey].status = "merged";
+                            state.issues[issueKey].lastActivity = now;
+                            if (!state.issues[issueKey].resolvedAt) {
+                                state.issues[issueKey].resolvedAt = now;
+                            }
+                            stateModified = true;
+                            break;
+                        case "update_to_abandoned":
+                            state.issues[issueKey].status = "abandoned";
+                            state.issues[issueKey].lastActivity = now;
+                            if (!state.issues[issueKey].resolvedAt) {
+                                state.issues[issueKey].resolvedAt = now;
+                            }
+                            stateModified = true;
+                            break;
+                        case "clear_worktree":
+                            state.issues[issueKey].worktree = undefined;
+                            state.issues[issueKey].lastActivity = now;
+                            stateModified = true;
+                            break;
+                    }
+                    healed.push(drift);
+                }
+                else {
+                    // Flag to user
+                    warnings.push(drift);
+                }
+            }
+            // Persist if changed
+            if (stateModified || githubReachable) {
+                state.lastSynced = now;
+                await stateManager.saveState(state);
+            }
+            return {
+                success: true,
+                healed,
+                warnings,
+                lastSynced: now,
+                githubReachable,
+            };
+        });
+    }
+    catch (error) {
+        return {
+            success: false,
+            healed: [],
+            warnings: [],
+            lastSynced: now,
+            githubReachable: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/src/lib/workflow/ring-buffer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RingBuffer — fixed-capacity circular buffer for retaining the last N lines.
+ *
+ * Used by agent drivers to capture the tail of stderr/stdout without
+ * unbounded memory growth.
+ */
+export declare class RingBuffer {
+    private buffer;
+    private head;
+    private count;
+    private readonly capacity;
+    constructor(capacity: number);
+    /** Push a line into the buffer, evicting the oldest if at capacity. */
+    push(line: string): void;
+    /** Return the stored lines in insertion order (oldest first). */
+    getLines(): string[];
+}

package/dist/src/lib/workflow/ring-buffer.js

@@ -0,0 +1,37 @@
+/**
+ * RingBuffer — fixed-capacity circular buffer for retaining the last N lines.
+ *
+ * Used by agent drivers to capture the tail of stderr/stdout without
+ * unbounded memory growth.
+ */
+export class RingBuffer {
+    buffer;
+    head = 0;
+    count = 0;
+    capacity;
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+    /** Push a line into the buffer, evicting the oldest if at capacity. */
+    push(line) {
+        this.buffer[this.head] = line;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity) {
+            this.count++;
+        }
+    }
+    /** Return the stored lines in insertion order (oldest first). */
+    getLines() {
+        if (this.count === 0)
+            return [];
+        if (this.count < this.capacity) {
+            return this.buffer.slice(0, this.count);
+        }
+        // Buffer is full — head points to the oldest entry
+        return [
+            ...this.buffer.slice(this.head),
+            ...this.buffer.slice(0, this.head),
+        ];
+    }
+}

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -16,19 +16,9 @@
  * ```
  */
 import { z } from "zod";
-/**
- * Available workflow phases
- */
-export declare const PhaseSchema: z.ZodEnum<{
-    loop: "loop";
-    spec: "spec";
-    exec: "exec";
-    qa: "qa";
-    "security-review": "security-review";
-    testgen: "testgen";
-    test: "test";
-}>;
-export type Phase = z.infer<typeof PhaseSchema>;
+import { PhaseSchema, type Phase } from "./types.js";
+export { PhaseSchema };
+export type { Phase } from "./types.js";
 /**
  * Phase execution status
  */
@@ -82,18 +72,54 @@ export declare const CacheMetricsSchema: z.ZodObject<{
     skipped: z.ZodNumber;
 }, z.core.$strip>;
 export type CacheMetrics = z.infer<typeof CacheMetricsSchema>;
+/**
+ * Structured error context captured from phase failures (#447).
+ *
+ * Provides stderr/stdout tails and a categorized error type
+ * for better failure diagnostics and analytics.
+ */
+export declare const ErrorContextSchema: z.ZodObject<{
+    stderrTail: z.ZodArray<z.ZodString>;
+    stdoutTail: z.ZodArray<z.ZodString>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    category: z.ZodEnum<{
+        unknown: "unknown";
+        timeout: "timeout";
+        context_overflow: "context_overflow";
+        api_error: "api_error";
+        hook_failure: "hook_failure";
+        build_error: "build_error";
+    }>;
+}, z.core.$strip>;
+export type ErrorContext = z.infer<typeof ErrorContextSchema>;
+/**
+ * Condensed QA verdict summary for structured log output (#434).
+ *
+ * Provides AC coverage counts, gaps, and suggestions so that
+ * `sequant_logs` consumers can review QA results without
+ * fetching issue comments separately.
+ */
+export declare const QaSummarySchema: z.ZodObject<{
+    acMet: z.ZodNumber;
+    acTotal: z.ZodNumber;
+    gaps: z.ZodArray<z.ZodString>;
+    suggestions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type QaSummary = z.infer<typeof QaSummarySchema>;
 /**
  * Log entry for a single phase execution
  */
 export declare const PhaseLogSchema: z.ZodObject<{
     phase: z.ZodEnum<{
+        qa: "qa";
         loop: "loop";
+        verify: "verify";
         spec: "spec";
-        exec: "exec";
-        qa: "qa";
         "security-review": "security-review";
+        exec: "exec";
         testgen: "testgen";
         test: "test";
+        merger: "merger";
     }>;
     issueNumber: z.ZodNumber;
     startTime: z.ZodString;
@@ -116,6 +142,12 @@ export declare const PhaseLogSchema: z.ZodObject<{
         AC_NOT_MET: "AC_NOT_MET";
         NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
     }>>;
+    summary: z.ZodOptional<z.ZodObject<{
+        acMet: z.ZodNumber;
+        acTotal: z.ZodNumber;
+        gaps: z.ZodArray<z.ZodString>;
+        suggestions: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
     commitHash: z.ZodOptional<z.ZodString>;
     fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -133,6 +165,19 @@ export declare const PhaseLogSchema: z.ZodObject<{
         misses: z.ZodNumber;
         skipped: z.ZodNumber;
     }, z.core.$strip>>;
+    errorContext: z.ZodOptional<z.ZodObject<{
+        stderrTail: z.ZodArray<z.ZodString>;
+        stdoutTail: z.ZodArray<z.ZodString>;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        category: z.ZodEnum<{
+            unknown: "unknown";
+            timeout: "timeout";
+            context_overflow: "context_overflow";
+            api_error: "api_error";
+            hook_failure: "hook_failure";
+            build_error: "build_error";
+        }>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PhaseLog = z.infer<typeof PhaseLogSchema>;
 /**
@@ -149,13 +194,15 @@ export declare const IssueLogSchema: z.ZodObject<{
     }>;
     phases: z.ZodArray<z.ZodObject<{
         phase: z.ZodEnum<{
+            qa: "qa";
             loop: "loop";
+            verify: "verify";
             spec: "spec";
-            exec: "exec";
-            qa: "qa";
             "security-review": "security-review";
+            exec: "exec";
             testgen: "testgen";
             test: "test";
+            merger: "merger";
         }>;
         issueNumber: z.ZodNumber;
         startTime: z.ZodString;
@@ -178,6 +225,12 @@ export declare const IssueLogSchema: z.ZodObject<{
             AC_NOT_MET: "AC_NOT_MET";
             NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
         }>>;
+        summary: z.ZodOptional<z.ZodObject<{
+            acMet: z.ZodNumber;
+            acTotal: z.ZodNumber;
+            gaps: z.ZodArray<z.ZodString>;
+            suggestions: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
         commitHash: z.ZodOptional<z.ZodString>;
         fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
@@ -195,6 +248,19 @@ export declare const IssueLogSchema: z.ZodObject<{
             misses: z.ZodNumber;
             skipped: z.ZodNumber;
         }, z.core.$strip>>;
+        errorContext: z.ZodOptional<z.ZodObject<{
+            stderrTail: z.ZodArray<z.ZodString>;
+            stdoutTail: z.ZodArray<z.ZodString>;
+            exitCode: z.ZodOptional<z.ZodNumber>;
+            category: z.ZodEnum<{
+                unknown: "unknown";
+                timeout: "timeout";
+                context_overflow: "context_overflow";
+                api_error: "api_error";
+                hook_failure: "hook_failure";
+                build_error: "build_error";
+            }>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     totalDurationSeconds: z.ZodNumber;
     prNumber: z.ZodOptional<z.ZodNumber>;
@@ -206,13 +272,15 @@ export type IssueLog = z.infer<typeof IssueLogSchema>;
  */
 export declare const RunConfigSchema: z.ZodObject<{
     phases: z.ZodArray<z.ZodEnum<{
+        qa: "qa";
         loop: "loop";
+        verify: "verify";
         spec: "spec";
-        exec: "exec";
-        qa: "qa";
         "security-review": "security-review";
+        exec: "exec";
         testgen: "testgen";
         test: "test";
+        merger: "merger";
     }>>;
     sequential: z.ZodBoolean;
     qualityLoop: z.ZodBoolean;
@@ -243,13 +311,15 @@ export declare const RunLogSchema: z.ZodObject<{
     endTime: z.ZodString;
     config: z.ZodObject<{
         phases: z.ZodArray<z.ZodEnum<{
+            qa: "qa";
             loop: "loop";
+            verify: "verify";
             spec: "spec";
-            exec: "exec";
-            qa: "qa";
             "security-review": "security-review";
+            exec: "exec";
             testgen: "testgen";
             test: "test";
+            merger: "merger";
         }>>;
         sequential: z.ZodBoolean;
         qualityLoop: z.ZodBoolean;
@@ -268,13 +338,15 @@ export declare const RunLogSchema: z.ZodObject<{
         }>;
         phases: z.ZodArray<z.ZodObject<{
             phase: z.ZodEnum<{
+                qa: "qa";
                 loop: "loop";
+                verify: "verify";
                 spec: "spec";
-                exec: "exec";
-                qa: "qa";
                 "security-review": "security-review";
+                exec: "exec";
                 testgen: "testgen";
                 test: "test";
+                merger: "merger";
             }>;
             issueNumber: z.ZodNumber;
             startTime: z.ZodString;
@@ -297,6 +369,12 @@ export declare const RunLogSchema: z.ZodObject<{
                 AC_NOT_MET: "AC_NOT_MET";
                 NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
             }>>;
+            summary: z.ZodOptional<z.ZodObject<{
+                acMet: z.ZodNumber;
+                acTotal: z.ZodNumber;
+                gaps: z.ZodArray<z.ZodString>;
+                suggestions: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
             commitHash: z.ZodOptional<z.ZodString>;
             fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
@@ -314,6 +392,19 @@ export declare const RunLogSchema: z.ZodObject<{
                 misses: z.ZodNumber;
                 skipped: z.ZodNumber;
             }, z.core.$strip>>;
+            errorContext: z.ZodOptional<z.ZodObject<{
+                stderrTail: z.ZodArray<z.ZodString>;
+                stdoutTail: z.ZodArray<z.ZodString>;
+                exitCode: z.ZodOptional<z.ZodNumber>;
+                category: z.ZodEnum<{
+                    unknown: "unknown";
+                    timeout: "timeout";
+                    context_overflow: "context_overflow";
+                    api_error: "api_error";
+                    hook_failure: "hook_failure";
+                    build_error: "build_error";
+                }>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         totalDurationSeconds: z.ZodNumber;
         prNumber: z.ZodOptional<z.ZodNumber>;
@@ -372,7 +463,7 @@ export declare function createPhaseLog(phase: Phase, issueNumber: number): Omit<
  * @param options - Additional fields (error, filesModified, verdict, etc.)
  * @returns Complete PhaseLog
  */
-export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "durationSeconds" | "status">, status: PhaseStatus, options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "commitHash" | "fileDiffStats" | "cacheMetrics">>): PhaseLog;
+export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "durationSeconds" | "status">, status: PhaseStatus, options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "summary" | "commitHash" | "fileDiffStats" | "cacheMetrics" | "errorContext">>): PhaseLog;
 /**
  * Finalize a run log with summary statistics
  *

package/dist/src/lib/workflow/run-log-schema.js

@@ -17,18 +17,9 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-/**
- * Available workflow phases
- */
-export const PhaseSchema = z.enum([
-    "spec",
-    "security-review",
-    "testgen",
-    "exec",
-    "test",
-    "qa",
-    "loop",
-]);
+// Import canonical Phase types from types.ts (single source of truth)
+import { PhaseSchema } from "./types.js";
+export { PhaseSchema };
 /**
  * Phase execution status
  */
@@ -75,6 +66,46 @@ export const CacheMetricsSchema = z.object({
     /** Number of skipped checks */
     skipped: z.number().int().nonnegative(),
 });
+/**
+ * Structured error context captured from phase failures (#447).
+ *
+ * Provides stderr/stdout tails and a categorized error type
+ * for better failure diagnostics and analytics.
+ */
+export const ErrorContextSchema = z.object({
+    /** Last N lines of stderr before process exit */
+    stderrTail: z.array(z.string()),
+    /** Last N lines of stdout before process exit */
+    stdoutTail: z.array(z.string()),
+    /** Process exit code */
+    exitCode: z.number().int().optional(),
+    /** Classified error category */
+    category: z.enum([
+        "context_overflow",
+        "api_error",
+        "hook_failure",
+        "build_error",
+        "timeout",
+        "unknown",
+    ]),
+});
+/**
+ * Condensed QA verdict summary for structured log output (#434).
+ *
+ * Provides AC coverage counts, gaps, and suggestions so that
+ * `sequant_logs` consumers can review QA results without
+ * fetching issue comments separately.
+ */
+export const QaSummarySchema = z.object({
+    /** Number of acceptance criteria marked MET */
+    acMet: z.number().int().nonnegative(),
+    /** Total number of acceptance criteria evaluated */
+    acTotal: z.number().int().nonnegative(),
+    /** List of gaps identified during QA */
+    gaps: z.array(z.string()),
+    /** List of improvement suggestions from QA */
+    suggestions: z.array(z.string()),
+});
 /**
  * Log entry for a single phase execution
  */
@@ -103,12 +134,16 @@ export const PhaseLogSchema = z.object({
     testsPassed: z.number().int().nonnegative().optional(),
     /** Parsed QA verdict (only for qa phase) */
     verdict: QaVerdictSchema.optional(),
+    /** Condensed QA summary with AC coverage (#434) */
+    summary: QaSummarySchema.optional(),
     /** Git commit SHA after phase completes (AC-2) */
     commitHash: z.string().optional(),
     /** Per-file diff statistics (AC-3) */
     fileDiffStats: z.array(FileDiffStatSchema).optional(),
     /** Cache metrics for QA phase (AC-7) */
     cacheMetrics: CacheMetricsSchema.optional(),
+    /** Structured error context for failed phases (#447) */
+    errorContext: ErrorContextSchema.optional(),
 });
 /**
  * Complete execution record for a single issue