@soleri/core 2.4.0 → 2.5.0

package/dist/planning/planner.js

@@ -1,7 +1,75 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
 import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS } from './gap-types.js';
 import { runGapAnalysis } from './gap-analysis.js';
+/**
+ * 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 = {
+    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 = [
+    'brainstorming',
+    'executing',
+    'validating',
+    'reconciling',
+];
+/**
+ * Validate a lifecycle status transition.
+ * Returns true if the transition is valid, false otherwise.
+ */
+export function isValidTransition(from, to) {
+    return LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+/**
+ * Get the valid next statuses for a given status.
+ */
+export function getValidNextStatuses(status) {
+    return LIFECYCLE_TRANSITIONS[status];
+}
+/**
+ * Check if a status should have TTL expiration.
+ * Plans in executing/reconciling states persist indefinitely.
+ */
+export function shouldExpire(status) {
+    return !NON_EXPIRING_STATUSES.includes(status);
+}
+/**
+ * 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 = {
+    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) {
+    let deductions = 0;
+    for (const item of items) {
+        deductions += DRIFT_WEIGHTS[item.impact];
+    }
+    return Math.max(0, 100 - deductions);
+}
 /**
  * Calculate score from gaps with severity-weighted deductions and iteration leniency.
  * Ported from Salvador MCP's plan-grading.ts.
@@ -68,7 +136,7 @@ export class Planner {
             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}`,
@@ -77,6 +145,12 @@ export class Planner {
                 status: 'pending',
                 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,
@@ -91,14 +165,36 @@ export class Planner {
     list() {
         return [...this.store.plans];
     }
+    /**
+     * Transition a plan to a new status using the typed FSM.
+     * Validates that the transition is allowed before applying it.
+     */
+    transition(plan, to) {
+        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) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        this.transition(plan, 'draft');
+        this.save();
+        return plan;
+    }
     approve(planId) {
         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;
     }
@@ -106,10 +202,7 @@ export class Planner {
         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;
     }
@@ -117,33 +210,79 @@ export class Planner {
         const plan = this.get(planId);
         if (!plan)
             throw new Error(`Plan not found: ${planId}`);
-        if (plan.status !== 'executing')
-            throw new Error(`Cannot update tasks on plan in '${plan.status}' status — must be 'executing'`);
+        if (plan.status !== 'executing' && plan.status !== 'validating')
+            throw new Error(`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) {
+        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) {
+        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) {
         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() {
-        return this.store.plans.filter((p) => p.status === 'executing');
+        return this.store.plans.filter((p) => p.status === 'executing' || p.status === 'validating');
     }
     getActive() {
-        return this.store.plans.filter((p) => p.status === 'draft' || p.status === 'approved' || p.status === 'executing');
+        return this.store.plans.filter((p) => p.status === 'brainstorming' ||
+            p.status === 'draft' ||
+            p.status === 'approved' ||
+            p.status === 'executing' ||
+            p.status === 'validating' ||
+            p.status === 'reconciling');
     }
     /**
      * Iterate on a draft plan — modify objective, scope, decisions, or tasks.
@@ -153,8 +292,8 @@ export class Planner {
         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;
@@ -162,6 +301,18 @@ export class Planner {
             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) {
             const removeSet = new Set(changes.removeTasks);
@@ -196,8 +347,8 @@ export class Planner {
         const plan = this.get(planId);
         if (!plan)
             throw new Error(`Plan not found: ${planId}`);
-        if (plan.status !== 'draft' && plan.status !== 'approved')
-            throw new Error(`Cannot split tasks on plan in '${plan.status}' status — must be 'draft' or '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 'brainstorming', 'draft', or 'approved'`);
         const now = Date.now();
         plan.tasks = tasks.map((t, i) => ({
             id: `task-${i + 1}`,
@@ -205,6 +356,7 @@ export class Planner {
             description: t.description,
             status: 'pending',
             dependsOn: t.dependsOn,
+            ...(t.acceptanceCriteria && { acceptanceCriteria: t.acceptanceCriteria }),
             updatedAt: now,
         }));
         // Validate dependency references
@@ -224,29 +376,37 @@ 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, report) {
         const plan = this.get(planId);
         if (!plan)
             throw new Error(`Plan not found: ${planId}`);
-        if (plan.status !== 'executing' && plan.status !== 'completed')
-            throw new Error(`Cannot reconcile plan in '${plan.status}' status — must be 'executing' or 'completed'`);
+        if (plan.status !== 'executing' &&
+            plan.status !== 'validating' &&
+            plan.status !== 'reconciling')
+            throw new Error(`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;
@@ -297,17 +457,405 @@ export class Planner {
                 }
             }
         }
-        return { task, unmetDependencies, ready: unmetDependencies.length === 0 };
+        const result = {
+            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 ──────────────────────────
+    /**
+     * Compute aggregate execution summary from per-task metrics.
+     * Called from reconcile() and complete() to populate plan.executionSummary.
+     */
+    computeExecutionSummary(plan) {
+        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, taskId, deliverable) {
+        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 = {
+            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;
     }
     /**
-     * Archive completed plans older than the given number of days.
-     * Removes them from the active store and returns the archived plans.
+     * 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, taskId, vault) {
+        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, taskId, evidence) {
+        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, taskId) {
+        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 = '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) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        const issues = [];
+        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) {
+        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 = [];
+        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, taskId) {
+        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, taskId) {
+        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) {
-        const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+        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;
@@ -317,7 +865,16 @@ export class Planner {
      */
     stats() {
         const plans = this.store.plans;
-        const byStatus = { draft: 0, approved: 0, executing: 0, completed: 0 };
+        const byStatus = {
+            brainstorming: 0,
+            draft: 0,
+            approved: 0,
+            executing: 0,
+            validating: 0,
+            reconciling: 0,
+            completed: 0,
+            archived: 0,
+        };
         const tasksByStatus = {
             pending: 0,
             in_progress: 0,
@@ -343,9 +900,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
@@ -433,12 +992,18 @@ export class Planner {
     }
     gradeToMinScore(grade) {
         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;
         }
     }
     hasCircularDependencies(plan) {