@soleri/core 2.4.0 → 2.6.0

package/src/planning/planner.ts

@@ -1,13 +1,113 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
 import type { PlanGap } from './gap-types.js';
 import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS } from './gap-types.js';
 import { runGapAnalysis } from './gap-analysis.js';
 import type { GapAnalysisOptions } from './gap-analysis.js';
 
-export type PlanStatus = 'draft' | 'approved' | 'executing' | 'completed';
+/**
+ * Plan lifecycle status.
+ * Ported from Salvador's PlanLifecycleStatus with full 8-state lifecycle.
+ *
+ * Lifecycle: brainstorming → draft → approved → executing → [validating] → reconciling → completed → archived
+ */
+export type PlanStatus =
+  | 'brainstorming'
+  | 'draft'
+  | 'approved'
+  | 'executing'
+  | 'validating'
+  | 'reconciling'
+  | 'completed'
+  | 'archived';
+
+/**
+ * Valid status transitions.
+ * Each key maps to the set of statuses it can transition to.
+ * Ported from Salvador's LIFECYCLE_TRANSITIONS.
+ */
+export const LIFECYCLE_TRANSITIONS: Record<PlanStatus, PlanStatus[]> = {
+  brainstorming: ['draft'],
+  draft: ['approved'],
+  approved: ['executing'],
+  executing: ['validating', 'reconciling'],
+  validating: ['reconciling', 'executing'],
+  reconciling: ['completed'],
+  completed: ['archived'],
+  archived: [],
+};
+
+/**
+ * Statuses where the 30-minute TTL should NOT apply.
+ * Plans in these states may span multiple sessions.
+ */
+export const NON_EXPIRING_STATUSES: PlanStatus[] = [
+  'brainstorming',
+  'executing',
+  'validating',
+  'reconciling',
+];
+
+/**
+ * Validate a lifecycle status transition.
+ * Returns true if the transition is valid, false otherwise.
+ */
+export function isValidTransition(from: PlanStatus, to: PlanStatus): boolean {
+  return LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Get the valid next statuses for a given status.
+ */
+export function getValidNextStatuses(status: PlanStatus): PlanStatus[] {
+  return LIFECYCLE_TRANSITIONS[status];
+}
+
+/**
+ * Check if a status should have TTL expiration.
+ * Plans in executing/reconciling states persist indefinitely.
+ */
+export function shouldExpire(status: PlanStatus): boolean {
+  return !NON_EXPIRING_STATUSES.includes(status);
+}
+
 export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
 
+export interface TaskEvidence {
+  /** What the evidence proves (maps to an acceptance criterion). */
+  criterion: string;
+  /** Evidence content — command output, URL, file path, description. */
+  content: string;
+  /** Evidence type. */
+  type: 'command_output' | 'url' | 'file' | 'description';
+  submittedAt: number;
+}
+
+export interface TaskMetrics {
+  durationMs?: number;
+  iterations?: number;
+  toolCalls?: number;
+  modelTier?: string;
+  estimatedCostUsd?: number;
+}
+
+export interface TaskDeliverable {
+  type: 'file' | 'vault_entry' | 'url';
+  path: string;
+  hash?: string;
+  verifiedAt?: number;
+  stale?: boolean;
+}
+
+export interface ExecutionSummary {
+  totalDurationMs: number;
+  tasksCompleted: number;
+  tasksSkipped: number;
+  tasksFailed: number;
+  avgTaskDurationMs: number;
+}
+
 export interface PlanTask {
   id: string;
   title: string;
@@ -15,20 +115,64 @@ export interface PlanTask {
   status: TaskStatus;
   /** Optional dependency IDs — tasks that must complete before this one. */
   dependsOn?: string[];
+  /** Evidence submitted for task acceptance criteria. */
+  evidence?: TaskEvidence[];
+  /** Whether this task has been verified (all evidence checked + reviews passed). */
+  verified?: boolean;
+  /** Task-level acceptance criteria (for verification checking). */
+  acceptanceCriteria?: string[];
+  /** Timestamp when task was first moved to in_progress. */
+  startedAt?: number;
+  /** Timestamp when task reached a terminal state (completed/skipped/failed). */
+  completedAt?: number;
+  /** Per-task execution metrics. */
+  metrics?: TaskMetrics;
+  /** Deliverables produced by this task. */
+  deliverables?: TaskDeliverable[];
   updatedAt: number;
 }
 
 export interface DriftItem {
+  /** Type of drift */
   type: 'skipped' | 'added' | 'modified' | 'reordered';
+  /** What drifted */
   description: string;
+  /** How much this affected the plan */
   impact: 'low' | 'medium' | 'high';
+  /** Why the drift occurred */
   rationale: string;
 }
 
+/**
+ * Severity weights for drift accuracy score calculation.
+ * Score = 100 - sum(drift_items * weight_per_impact)
+ * Ported from Salvador's plan-lifecycle-types.ts.
+ */
+export const DRIFT_WEIGHTS: Record<DriftItem['impact'], number> = {
+  high: 20,
+  medium: 10,
+  low: 5,
+};
+
+/**
+ * Calculate drift accuracy score from drift items.
+ * Score = max(0, 100 - sum(weight_per_impact))
+ * Ported from Salvador's calculateDriftScore.
+ */
+export function calculateDriftScore(items: DriftItem[]): number {
+  let deductions = 0;
+  for (const item of items) {
+    deductions += DRIFT_WEIGHTS[item.impact];
+  }
+  return Math.max(0, 100 - deductions);
+}
+
 export interface ReconciliationReport {
   planId: string;
+  /** Accuracy score: 100 = perfect execution, 0 = total drift. Impact-weighted. */
   accuracy: number;
   driftItems: DriftItem[];
+  /** Human-readable summary of the drift */
   summary: string;
   reconciledAt: number;
 }
@@ -88,13 +232,38 @@ export function calculateScore(gaps: PlanGap[], iteration: number = 1): number {
   return Math.max(0, 100 - deductions);
 }
 
+/**
+ * A structured decision with rationale.
+ * Ported from Salvador's PlanContent.decisions.
+ */
+export interface PlanDecision {
+  decision: string;
+  rationale: string;
+}
+
 export interface Plan {
   id: string;
   objective: string;
   scope: string;
   status: PlanStatus;
-  decisions: string[];
+  /**
+   * Decisions can be flat strings (backward compat) or structured {decision, rationale}.
+   * New plans should prefer PlanDecision[].
+   */
+  decisions: (string | PlanDecision)[];
   tasks: PlanTask[];
+  /** High-level approach description. Ported from Salvador's PlanContent. */
+  approach?: string;
+  /** Additional context for the plan. */
+  context?: string;
+  /** Measurable success criteria. */
+  success_criteria?: string[];
+  /** Tools to use in execution order. */
+  tool_chain?: string[];
+  /** Flow definition to follow (e.g., 'developer', 'reviewer', 'designer'). */
+  flow?: string;
+  /** Target operational mode (e.g., 'build', 'review', 'fix'). */
+  target_mode?: string;
   /** Reconciliation report — populated by reconcile(). */
   reconciliation?: ReconciliationReport;
   /** Review evidence — populated by addReview(). */
@@ -103,6 +272,14 @@ export interface Plan {
   latestCheck?: PlanCheck;
   /** All check history. */
   checks: PlanCheck[];
+  /** Matched playbook info (set by orchestration layer via playbook_match). */
+  playbookMatch?: {
+    label: string;
+    genericId?: string;
+    domainId?: string;
+  };
+  /** Aggregate execution metrics — populated by reconcile() and complete(). */
+  executionSummary?: ExecutionSummary;
   createdAt: number;
   updatedAt: number;
 }
@@ -148,15 +325,23 @@ export class Planner {
   create(params: {
     objective: string;
     scope: string;
-    decisions?: string[];
+    decisions?: (string | PlanDecision)[];
     tasks?: Array<{ title: string; description: string }>;
+    approach?: string;
+    context?: string;
+    success_criteria?: string[];
+    tool_chain?: string[];
+    flow?: string;
+    target_mode?: string;
+    /** Start in 'brainstorming' instead of 'draft'. Default: 'draft'. */
+    initialStatus?: 'brainstorming' | 'draft';
   }): Plan {
     const now = Date.now();
     const plan: Plan = {
       id: `plan-${now}-${Math.random().toString(36).slice(2, 8)}`,
       objective: params.objective,
       scope: params.scope,
-      status: 'draft',
+      status: params.initialStatus ?? 'draft',
       decisions: params.decisions ?? [],
       tasks: (params.tasks ?? []).map((t, i) => ({
         id: `task-${i + 1}`,
@@ -165,6 +350,12 @@ export class Planner {
         status: 'pending' as TaskStatus,
         updatedAt: now,
       })),
+      ...(params.approach !== undefined && { approach: params.approach }),
+      ...(params.context !== undefined && { context: params.context }),
+      ...(params.success_criteria !== undefined && { success_criteria: params.success_criteria }),
+      ...(params.tool_chain !== undefined && { tool_chain: params.tool_chain }),
+      ...(params.flow !== undefined && { flow: params.flow }),
+      ...(params.target_mode !== undefined && { target_mode: params.target_mode }),
       checks: [],
       createdAt: now,
       updatedAt: now,
@@ -182,13 +373,38 @@ export class Planner {
     return [...this.store.plans];
   }
 
+  /**
+   * Transition a plan to a new status using the typed FSM.
+   * Validates that the transition is allowed before applying it.
+   */
+  private transition(plan: Plan, to: PlanStatus): void {
+    if (!isValidTransition(plan.status, to)) {
+      const valid = getValidNextStatuses(plan.status);
+      throw new Error(
+        `Invalid transition: '${plan.status}' → '${to}'. ` +
+          `Valid transitions from '${plan.status}': ${valid.length > 0 ? valid.join(', ') : 'none'}`,
+      );
+    }
+    plan.status = to;
+    plan.updatedAt = Date.now();
+  }
+
+  /**
+   * Promote a brainstorming plan to draft status.
+   * Only allowed from 'brainstorming'.
+   */
+  promoteToDraft(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    this.transition(plan, 'draft');
+    this.save();
+    return plan;
+  }
+
   approve(planId: string): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'draft')
-      throw new Error(`Cannot approve plan in '${plan.status}' status — must be 'draft'`);
-    plan.status = 'approved';
-    plan.updatedAt = Date.now();
+    this.transition(plan, 'approved');
     this.save();
     return plan;
   }
@@ -196,10 +412,7 @@ export class Planner {
   startExecution(planId: string): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'approved')
-      throw new Error(`Cannot execute plan in '${plan.status}' status — must be 'approved'`);
-    plan.status = 'executing';
-    plan.updatedAt = Date.now();
+    this.transition(plan, 'executing');
     this.save();
     return plan;
   }
@@ -207,37 +420,87 @@ export class Planner {
   updateTask(planId: string, taskId: string, status: TaskStatus): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'executing')
+    if (plan.status !== 'executing' && plan.status !== 'validating')
       throw new Error(
-        `Cannot update tasks on plan in '${plan.status}' status — must be 'executing'`,
+        `Cannot update tasks on plan in '${plan.status}' status — must be 'executing' or 'validating'`,
       );
     const task = plan.tasks.find((t) => t.id === taskId);
     if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    const now = Date.now();
+
+    // Auto-set startedAt on first in_progress transition
+    if (status === 'in_progress' && !task.startedAt) {
+      task.startedAt = now;
+    }
+
+    // Auto-set completedAt and compute durationMs on terminal transitions
+    if (status === 'completed' || status === 'skipped' || status === 'failed') {
+      task.completedAt = now;
+      if (task.startedAt) {
+        if (!task.metrics) task.metrics = {};
+        task.metrics.durationMs = now - task.startedAt;
+      }
+    }
+
     task.status = status;
-    task.updatedAt = Date.now();
-    plan.updatedAt = Date.now();
+    task.updatedAt = now;
+    plan.updatedAt = now;
+    this.save();
+    return plan;
+  }
+
+  /**
+   * Transition plan to 'validating' state (post-execution verification).
+   * Only allowed from 'executing'.
+   */
+  startValidation(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    this.transition(plan, 'validating');
+    this.save();
+    return plan;
+  }
+
+  /**
+   * Transition plan to 'reconciling' state.
+   * Allowed from 'executing' or 'validating'.
+   */
+  startReconciliation(planId: string): Plan {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    this.transition(plan, 'reconciling');
     this.save();
     return plan;
   }
 
+  /**
+   * Complete a plan. Only allowed from 'reconciling'.
+   * Use startReconciliation() + reconcile() + complete() for the full lifecycle,
+   * or reconcile() which auto-transitions through reconciling → completed.
+   */
   complete(planId: string): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'executing')
-      throw new Error(`Cannot complete plan in '${plan.status}' status — must be 'executing'`);
-    plan.status = 'completed';
-    plan.updatedAt = Date.now();
+    plan.executionSummary = this.computeExecutionSummary(plan);
+    this.transition(plan, 'completed');
     this.save();
     return plan;
   }
 
   getExecuting(): Plan[] {
-    return this.store.plans.filter((p) => p.status === 'executing');
+    return this.store.plans.filter((p) => p.status === 'executing' || p.status === 'validating');
   }
 
   getActive(): Plan[] {
     return this.store.plans.filter(
-      (p) => p.status === 'draft' || p.status === 'approved' || p.status === 'executing',
+      (p) =>
+        p.status === 'brainstorming' ||
+        p.status === 'draft' ||
+        p.status === 'approved' ||
+        p.status === 'executing' ||
+        p.status === 'validating' ||
+        p.status === 'reconciling',
     );
   }
 
@@ -250,20 +513,34 @@ export class Planner {
     changes: {
       objective?: string;
       scope?: string;
-      decisions?: string[];
+      decisions?: (string | PlanDecision)[];
       addTasks?: Array<{ title: string; description: string }>;
       removeTasks?: string[];
+      approach?: string;
+      context?: string;
+      success_criteria?: string[];
+      tool_chain?: string[];
+      flow?: string;
+      target_mode?: string;
     },
   ): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'draft')
-      throw new Error(`Cannot iterate plan in '${plan.status}' status — must be 'draft'`);
+    if (plan.status !== 'draft' && plan.status !== 'brainstorming')
+      throw new Error(
+        `Cannot iterate plan in '${plan.status}' status — must be 'draft' or 'brainstorming'`,
+      );
 
     const now = Date.now();
     if (changes.objective !== undefined) plan.objective = changes.objective;
     if (changes.scope !== undefined) plan.scope = changes.scope;
     if (changes.decisions !== undefined) plan.decisions = changes.decisions;
+    if (changes.approach !== undefined) plan.approach = changes.approach;
+    if (changes.context !== undefined) plan.context = changes.context;
+    if (changes.success_criteria !== undefined) plan.success_criteria = changes.success_criteria;
+    if (changes.tool_chain !== undefined) plan.tool_chain = changes.tool_chain;
+    if (changes.flow !== undefined) plan.flow = changes.flow;
+    if (changes.target_mode !== undefined) plan.target_mode = changes.target_mode;
 
     // Remove tasks by ID
     if (changes.removeTasks && changes.removeTasks.length > 0) {
@@ -300,13 +577,18 @@ export class Planner {
    */
   splitTasks(
     planId: string,
-    tasks: Array<{ title: string; description: string; dependsOn?: string[] }>,
+    tasks: Array<{
+      title: string;
+      description: string;
+      dependsOn?: string[];
+      acceptanceCriteria?: string[];
+    }>,
   ): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'draft' && plan.status !== 'approved')
+    if (plan.status !== 'brainstorming' && plan.status !== 'draft' && plan.status !== 'approved')
       throw new Error(
-        `Cannot split tasks on plan in '${plan.status}' status — must be 'draft' or 'approved'`,
+        `Cannot split tasks on plan in '${plan.status}' status — must be 'brainstorming', 'draft', or 'approved'`,
       );
 
     const now = Date.now();
@@ -316,6 +598,7 @@ export class Planner {
       description: t.description,
       status: 'pending' as TaskStatus,
       dependsOn: t.dependsOn,
+      ...(t.acceptanceCriteria && { acceptanceCriteria: t.acceptanceCriteria }),
       updatedAt: now,
     }));
 
@@ -338,39 +621,53 @@ export class Planner {
 
   /**
    * Reconcile a plan — compare what was planned vs what actually happened.
-   * Only allowed on 'executing' or 'completed' plans.
+   * Uses impact-weighted drift scoring (ported from Salvador's calculateDriftScore).
+   *
+   * Transitions: executing → reconciling → completed (automatic).
+   * Also allowed from 'validating' and 'reconciling' states.
    */
   reconcile(
     planId: string,
     report: {
       actualOutcome: string;
       driftItems?: DriftItem[];
+      /** Who initiated the reconciliation. */
+      reconciledBy?: 'human' | 'auto';
     },
   ): Plan {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
-    if (plan.status !== 'executing' && plan.status !== 'completed')
+    if (
+      plan.status !== 'executing' &&
+      plan.status !== 'validating' &&
+      plan.status !== 'reconciling'
+    )
       throw new Error(
-        `Cannot reconcile plan in '${plan.status}' status — must be 'executing' or 'completed'`,
+        `Cannot reconcile plan in '${plan.status}' status — must be 'executing', 'validating', or 'reconciling'`,
       );
 
     const driftItems = report.driftItems ?? [];
-    const totalTasks = plan.tasks.length;
-    const driftCount = driftItems.length;
-    const accuracy = totalTasks > 0 ? Math.round(((totalTasks - driftCount) / totalTasks) * 100) : 100;
+
+    // Impact-weighted drift scoring (ported from Salvador)
+    const accuracy = calculateDriftScore(driftItems);
 
     plan.reconciliation = {
       planId,
-      accuracy: Math.max(0, Math.min(100, accuracy)),
+      accuracy,
       driftItems,
       summary: report.actualOutcome,
       reconciledAt: Date.now(),
     };
 
-    // If still executing, mark completed
-    if (plan.status === 'executing') {
-      plan.status = 'completed';
+    // Compute execution summary from per-task metrics
+    plan.executionSummary = this.computeExecutionSummary(plan);
+
+    // Transition through reconciling → completed via FSM
+    if (plan.status === 'executing' || plan.status === 'validating') {
+      plan.status = 'reconciling';
     }
+    // Auto-complete after reconciliation
+    plan.status = 'completed';
     plan.updatedAt = Date.now();
     this.save();
     return plan;
@@ -418,7 +715,12 @@ export class Planner {
   getDispatch(
     planId: string,
     taskId: string,
-  ): { task: PlanTask; unmetDependencies: PlanTask[]; ready: boolean } {
+  ): {
+    task: PlanTask;
+    unmetDependencies: PlanTask[];
+    ready: boolean;
+    deliverableStatus?: { count: number; staleCount: number };
+  } {
     const plan = this.get(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
     const task = plan.tasks.find((t) => t.id === taskId);
@@ -434,22 +736,476 @@ export class Planner {
       }
     }
 
-    return { task, unmetDependencies, ready: unmetDependencies.length === 0 };
+    const result: {
+      task: PlanTask;
+      unmetDependencies: PlanTask[];
+      ready: boolean;
+      deliverableStatus?: { count: number; staleCount: number };
+    } = {
+      task,
+      unmetDependencies,
+      ready: unmetDependencies.length === 0,
+    };
+
+    // Include deliverable status if deliverables exist
+    if (task.deliverables && task.deliverables.length > 0) {
+      result.deliverableStatus = {
+        count: task.deliverables.length,
+        staleCount: task.deliverables.filter((d) => d.stale).length,
+      };
+    }
+
+    return result;
   }
 
+  // ─── Execution Metrics & Deliverables ──────────────────────────
+
   /**
-   * Archive completed plans older than the given number of days.
-   * Removes them from the active store and returns the archived plans.
+   * Compute aggregate execution summary from per-task metrics.
+   * Called from reconcile() and complete() to populate plan.executionSummary.
    */
-  archive(olderThanDays: number): Plan[] {
-    const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+  private computeExecutionSummary(plan: Plan): ExecutionSummary {
+    let totalDurationMs = 0;
+    let tasksCompleted = 0;
+    let tasksSkipped = 0;
+    let tasksFailed = 0;
+    let tasksWithDuration = 0;
+
+    for (const task of plan.tasks) {
+      if (task.status === 'completed') tasksCompleted++;
+      else if (task.status === 'skipped') tasksSkipped++;
+      else if (task.status === 'failed') tasksFailed++;
+
+      if (task.metrics?.durationMs) {
+        totalDurationMs += task.metrics.durationMs;
+        tasksWithDuration++;
+      }
+    }
+
+    return {
+      totalDurationMs,
+      tasksCompleted,
+      tasksSkipped,
+      tasksFailed,
+      avgTaskDurationMs:
+        tasksWithDuration > 0 ? Math.round(totalDurationMs / tasksWithDuration) : 0,
+    };
+  }
+
+  /**
+   * Submit a deliverable for a task. Auto-computes SHA-256 hash for file deliverables.
+   */
+  submitDeliverable(
+    planId: string,
+    taskId: string,
+    deliverable: { type: TaskDeliverable['type']; path: string; hash?: string },
+  ): PlanTask {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    const entry: TaskDeliverable = {
+      type: deliverable.type,
+      path: deliverable.path,
+    };
+
+    // Auto-compute hash for file deliverables
+    if (deliverable.type === 'file' && !deliverable.hash) {
+      try {
+        if (existsSync(deliverable.path)) {
+          const content = readFileSync(deliverable.path);
+          entry.hash = createHash('sha256').update(content).digest('hex');
+        }
+      } catch {
+        // Graceful degradation — skip hash if file can't be read
+      }
+    } else if (deliverable.hash) {
+      entry.hash = deliverable.hash;
+    }
+
+    if (!task.deliverables) task.deliverables = [];
+    task.deliverables.push(entry);
+    task.updatedAt = Date.now();
+    plan.updatedAt = Date.now();
+    this.save();
+    return task;
+  }
+
+  /**
+   * Verify all deliverables for a task.
+   * - file: checks existsSync + SHA-256 hash match
+   * - vault_entry: checks vault.get(path) non-null (requires vault instance)
+   * - url: skips (just records, no fetch)
+   */
+  verifyDeliverables(
+    planId: string,
+    taskId: string,
+    vault?: { get(id: string): unknown | null },
+  ): { verified: boolean; deliverables: TaskDeliverable[]; staleCount: number } {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    const deliverables = task.deliverables ?? [];
+    let staleCount = 0;
+    const now = Date.now();
+
+    for (const d of deliverables) {
+      d.stale = false;
+
+      if (d.type === 'file') {
+        if (!existsSync(d.path)) {
+          d.stale = true;
+          staleCount++;
+        } else if (d.hash) {
+          try {
+            const content = readFileSync(d.path);
+            const currentHash = createHash('sha256').update(content).digest('hex');
+            if (currentHash !== d.hash) {
+              d.stale = true;
+              staleCount++;
+            }
+          } catch {
+            d.stale = true;
+            staleCount++;
+          }
+        }
+        d.verifiedAt = now;
+      } else if (d.type === 'vault_entry') {
+        if (vault) {
+          const entry = vault.get(d.path);
+          if (!entry) {
+            d.stale = true;
+            staleCount++;
+          }
+        }
+        d.verifiedAt = now;
+      }
+      // url: skip — just record
+    }
+
+    plan.updatedAt = Date.now();
+    this.save();
+
+    return { verified: staleCount === 0, deliverables, staleCount };
+  }
+
+  // ─── Evidence & Verification ────────────────────────────────────
+
+  /**
+   * Submit evidence for a task acceptance criterion.
+   * Evidence is stored on the task and used by verifyTask() to check completeness.
+   */
+  submitEvidence(
+    planId: string,
+    taskId: string,
+    evidence: { criterion: string; content: string; type: TaskEvidence['type'] },
+  ): PlanTask {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+    if (!task.evidence) task.evidence = [];
+    task.evidence.push({
+      criterion: evidence.criterion,
+      content: evidence.content,
+      type: evidence.type,
+      submittedAt: Date.now(),
+    });
+    task.updatedAt = Date.now();
+    plan.updatedAt = Date.now();
+    this.save();
+    return task;
+  }
+
+  /**
+   * Verify a task — check that evidence exists for all acceptance criteria
+   * and any reviews have passed.
+   * Returns verification status with details.
+   */
+  verifyTask(
+    planId: string,
+    taskId: string,
+  ): {
+    verified: boolean;
+    task: PlanTask;
+    missingCriteria: string[];
+    reviewStatus: 'approved' | 'rejected' | 'needs_changes' | 'no_reviews';
+  } {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    // Check evidence coverage
+    const criteria = task.acceptanceCriteria ?? [];
+    const evidencedCriteria = new Set((task.evidence ?? []).map((e) => e.criterion));
+    const missingCriteria = criteria.filter((c) => !evidencedCriteria.has(c));
+
+    // Check task-level reviews
+    const taskReviews = (plan.reviews ?? []).filter((r) => r.taskId === taskId);
+    let reviewStatus: 'approved' | 'rejected' | 'needs_changes' | 'no_reviews' = 'no_reviews';
+    if (taskReviews.length > 0) {
+      const latest = taskReviews[taskReviews.length - 1];
+      reviewStatus = latest.outcome;
+    }
+
+    const verified =
+      task.status === 'completed' &&
+      missingCriteria.length === 0 &&
+      (reviewStatus === 'approved' || reviewStatus === 'no_reviews');
+
+    if (verified !== task.verified) {
+      task.verified = verified;
+      task.updatedAt = Date.now();
+      plan.updatedAt = Date.now();
+      this.save();
+    }
+
+    return { verified, task, missingCriteria, reviewStatus };
+  }
+
+  /**
+   * Verify an entire plan — check all tasks are in a final state,
+   * all verification-required tasks have evidence, no tasks stuck in_progress.
+   * Returns a validation report.
+   */
+  verifyPlan(planId: string): {
+    valid: boolean;
+    planId: string;
+    issues: Array<{ taskId: string; issue: string }>;
+    summary: {
+      total: number;
+      completed: number;
+      skipped: number;
+      failed: number;
+      pending: number;
+      inProgress: number;
+      verified: number;
+    };
+  } {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+
+    const issues: Array<{ taskId: string; issue: string }> = [];
+    let verified = 0;
+    let completed = 0;
+    let skipped = 0;
+    let failed = 0;
+    let pending = 0;
+    let inProgress = 0;
+
+    for (const task of plan.tasks) {
+      switch (task.status) {
+        case 'completed':
+          completed++;
+          break;
+        case 'skipped':
+          skipped++;
+          break;
+        case 'failed':
+          failed++;
+          break;
+        case 'pending':
+          pending++;
+          break;
+        case 'in_progress':
+          inProgress++;
+          break;
+      }
+
+      if (task.verified) verified++;
+
+      // Check for stuck tasks
+      if (task.status === 'in_progress') {
+        issues.push({ taskId: task.id, issue: 'Task stuck in in_progress state' });
+      }
+      if (task.status === 'pending') {
+        issues.push({ taskId: task.id, issue: 'Task still pending — not started' });
+      }
+
+      // Check evidence for completed tasks with acceptance criteria
+      if (
+        task.status === 'completed' &&
+        task.acceptanceCriteria &&
+        task.acceptanceCriteria.length > 0
+      ) {
+        const evidencedCriteria = new Set((task.evidence ?? []).map((e) => e.criterion));
+        const missing = task.acceptanceCriteria.filter((c) => !evidencedCriteria.has(c));
+        if (missing.length > 0) {
+          issues.push({
+            taskId: task.id,
+            issue: `Missing evidence for ${missing.length} criteria: ${missing.join(', ')}`,
+          });
+        }
+      }
+    }
+
+    const valid = issues.length === 0 && pending === 0 && inProgress === 0;
+
+    return {
+      valid,
+      planId,
+      issues,
+      summary: {
+        total: plan.tasks.length,
+        completed,
+        skipped,
+        failed,
+        pending,
+        inProgress,
+        verified,
+      },
+    };
+  }
+
+  /**
+   * Auto-reconcile a plan — fast path for plans with minimal drift.
+   * Checks all tasks are in final state, generates reconciliation report automatically.
+   * Returns null if drift is too significant for auto-reconciliation (>2 non-completed tasks).
+   */
+  autoReconcile(planId: string): Plan | null {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    if (plan.status !== 'executing' && plan.status !== 'validating')
+      throw new Error(
+        `Cannot auto-reconcile plan in '${plan.status}' status — must be 'executing' or 'validating'`,
+      );
+
+    const completed = plan.tasks.filter((t) => t.status === 'completed').length;
+    const skipped = plan.tasks.filter((t) => t.status === 'skipped').length;
+    const failed = plan.tasks.filter((t) => t.status === 'failed').length;
+    const pending = plan.tasks.filter((t) => t.status === 'pending').length;
+    const inProgress = plan.tasks.filter((t) => t.status === 'in_progress').length;
+
+    // Can't auto-reconcile if tasks are still in progress
+    if (inProgress > 0) return null;
+    // Can't auto-reconcile if too many non-completed tasks
+    if (pending + failed > 2) return null;
+
+    const driftItems: DriftItem[] = [];
+
+    for (const task of plan.tasks) {
+      if (task.status === 'skipped') {
+        driftItems.push({
+          type: 'skipped',
+          description: `Task '${task.title}' was skipped`,
+          impact: 'medium',
+          rationale: 'Task not executed during plan implementation',
+        });
+      } else if (task.status === 'failed') {
+        driftItems.push({
+          type: 'modified',
+          description: `Task '${task.title}' failed`,
+          impact: 'high',
+          rationale: 'Task execution failed',
+        });
+      } else if (task.status === 'pending') {
+        driftItems.push({
+          type: 'skipped',
+          description: `Task '${task.title}' was never started`,
+          impact: 'low',
+          rationale: 'Task left in pending state',
+        });
+      }
+    }
+
+    return this.reconcile(planId, {
+      actualOutcome: `Auto-reconciled: ${completed}/${plan.tasks.length} tasks completed, ${skipped} skipped, ${failed} failed`,
+      driftItems,
+      reconciledBy: 'auto',
+    });
+  }
+
+  /**
+   * Generate a review prompt for spec compliance checking.
+   * Used by subagent dispatch — the controller generates the prompt, a subagent executes it.
+   */
+  generateReviewSpec(
+    planId: string,
+    taskId: string,
+  ): { prompt: string; task: PlanTask; plan: Plan } {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    const criteria = task.acceptanceCriteria?.length
+      ? `\n\nAcceptance Criteria:\n${task.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join('\n')}`
+      : '';
+
+    const prompt = [
+      `# Spec Compliance Review`,
+      ``,
+      `## Task: ${task.title}`,
+      `**Description:** ${task.description}`,
+      `**Plan Objective:** ${plan.objective}${criteria}`,
+      ``,
+      `## Review Checklist`,
+      `1. Does the implementation match the task description?`,
+      `2. Are all acceptance criteria satisfied?`,
+      `3. Does it align with the plan's overall objective?`,
+      `4. Are there any spec deviations?`,
+      ``,
+      `Provide: outcome (approved/rejected/needs_changes) and detailed comments.`,
+    ].join('\n');
+
+    return { prompt, task, plan };
+  }
+
+  /**
+   * Generate a review prompt for code quality checking.
+   */
+  generateReviewQuality(
+    planId: string,
+    taskId: string,
+  ): { prompt: string; task: PlanTask; plan: Plan } {
+    const plan = this.get(planId);
+    if (!plan) throw new Error(`Plan not found: ${planId}`);
+    const task = plan.tasks.find((t) => t.id === taskId);
+    if (!task) throw new Error(`Task not found: ${taskId}`);
+
+    const prompt = [
+      `# Code Quality Review`,
+      ``,
+      `## Task: ${task.title}`,
+      `**Description:** ${task.description}`,
+      ``,
+      `## Quality Checklist`,
+      `1. **Correctness** — Does it work as intended?`,
+      `2. **Security** — No injection, XSS, or OWASP top 10 vulnerabilities?`,
+      `3. **Performance** — No unnecessary allocations, N+1 queries, or blocking calls?`,
+      `4. **Maintainability** — Clear naming, appropriate abstractions, documented intent?`,
+      `5. **Testing** — Adequate test coverage for the changes?`,
+      `6. **Error Handling** — Graceful degradation, no swallowed errors?`,
+      `7. **Conventions** — Follows project coding standards?`,
+      ``,
+      `Provide: outcome (approved/rejected/needs_changes) and detailed comments.`,
+    ].join('\n');
+
+    return { prompt, task, plan };
+  }
+
+  /**
+   * Archive completed plans — transitions them to 'archived' status.
+   * If olderThanDays is provided, only archives plans older than that.
+   * Returns the archived plans.
+   */
+  archive(olderThanDays?: number): Plan[] {
+    const cutoff =
+      olderThanDays !== undefined
+        ? Date.now() - olderThanDays * 24 * 60 * 60 * 1000
+        : Date.now() + 1; // +1ms so archive() with no args archives all completed plans
     const toArchive = this.store.plans.filter(
       (p) => p.status === 'completed' && p.updatedAt < cutoff,
     );
+    for (const plan of toArchive) {
+      plan.status = 'archived';
+      plan.updatedAt = Date.now();
+    }
     if (toArchive.length > 0) {
-      this.store.plans = this.store.plans.filter(
-        (p) => !(p.status === 'completed' && p.updatedAt < cutoff),
-      );
       this.save();
     }
     return toArchive;
@@ -466,7 +1222,16 @@ export class Planner {
     tasksByStatus: Record<TaskStatus, number>;
   } {
     const plans = this.store.plans;
-    const byStatus: Record<PlanStatus, number> = { draft: 0, approved: 0, executing: 0, completed: 0 };
+    const byStatus: Record<PlanStatus, number> = {
+      brainstorming: 0,
+      draft: 0,
+      approved: 0,
+      executing: 0,
+      validating: 0,
+      reconciling: 0,
+      completed: 0,
+      archived: 0,
+    };
     const tasksByStatus: Record<TaskStatus, number> = {
       pending: 0,
       in_progress: 0,
@@ -496,9 +1261,11 @@ export class Planner {
   // ─── Grading ──────────────────────────────────────────────────────
 
   /**
-   * Grade a plan using 6-pass gap analysis with severity-weighted scoring.
+   * Grade a plan using gap analysis with severity-weighted scoring.
    * Ported from Salvador MCP's multi-pass grading engine.
    *
+   * 6 built-in passes + optional custom passes (domain-specific checks).
+   *
    * Scoring:
    * - Each gap has a severity (critical=30, major=15, minor=2, info=0)
    * - Deductions are per-category with optional caps
@@ -590,12 +1357,18 @@ export class Planner {
 
   private gradeToMinScore(grade: PlanGrade): number {
     switch (grade) {
-      case 'A+': return 95;
-      case 'A': return 90;
-      case 'B': return 80;
-      case 'C': return 70;
-      case 'D': return 60;
-      case 'F': return 0;
+      case 'A+':
+        return 95;
+      case 'A':
+        return 90;
+      case 'B':
+        return 80;
+      case 'C':
+        return 70;
+      case 'D':
+        return 60;
+      case 'F':
+        return 0;
     }
   }