@soleri/core 2.1.0 → 2.5.0

package/dist/planning/planner.js

@@ -1,10 +1,112 @@
 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.
+ *
+ * - Minor gaps: weight=0 on iteration 1 (free sketching), weight=1 on iteration 2, full weight on 3+
+ * - Per-category deductions are capped before summing (prevents one category from tanking the score)
+ * - Score = max(0, 100 - totalDeductions)
+ */
+export function calculateScore(gaps, iteration = 1) {
+    const categoryTotals = new Map();
+    for (const gap of gaps) {
+        let weight = SEVERITY_WEIGHTS[gap.severity];
+        // Iteration leniency for minor gaps
+        if (gap.severity === 'minor') {
+            if (iteration === 1)
+                weight = 0;
+            else if (iteration === 2)
+                weight = 1;
+            // iteration 3+: full weight (2)
+        }
+        const category = gap.category;
+        categoryTotals.set(category, (categoryTotals.get(category) ?? 0) + weight);
+    }
+    let deductions = 0;
+    for (const [category, total] of categoryTotals) {
+        const cap = CATEGORY_PENALTY_CAPS[category];
+        deductions += cap !== undefined ? Math.min(total, cap) : total;
+    }
+    return Math.max(0, 100 - deductions);
+}
 export class Planner {
     filePath;
     store;
-    constructor(filePath) {
+    gapOptions;
+    constructor(filePath, gapOptions) {
         this.filePath = filePath;
+        this.gapOptions = gapOptions;
         this.store = this.load();
     }
     load() {
@@ -13,7 +115,12 @@ export class Planner {
         }
         try {
             const data = readFileSync(this.filePath, 'utf-8');
-            return JSON.parse(data);
+            const store = JSON.parse(data);
+            // Backward compatibility: ensure every plan has a checks array
+            for (const plan of store.plans) {
+                plan.checks = plan.checks ?? [];
+            }
+            return store;
         }
         catch {
             return { version: '1.0', plans: [] };
@@ -29,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}`,
@@ -38,6 +145,13 @@ 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,
         };
@@ -51,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;
     }
@@ -66,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;
     }
@@ -77,33 +210,828 @@ 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.
+     * Only allowed on plans in 'draft' status.
+     */
+    iterate(planId, changes) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        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) {
+            const removeSet = new Set(changes.removeTasks);
+            plan.tasks = plan.tasks.filter((t) => !removeSet.has(t.id));
+        }
+        // Add new tasks
+        if (changes.addTasks && changes.addTasks.length > 0) {
+            const maxIndex = plan.tasks.reduce((max, t) => {
+                const num = parseInt(t.id.replace('task-', ''), 10);
+                return isNaN(num) ? max : Math.max(max, num);
+            }, 0);
+            for (let i = 0; i < changes.addTasks.length; i++) {
+                plan.tasks.push({
+                    id: `task-${maxIndex + i + 1}`,
+                    title: changes.addTasks[i].title,
+                    description: changes.addTasks[i].description,
+                    status: 'pending',
+                    updatedAt: now,
+                });
+            }
+        }
+        plan.updatedAt = now;
+        this.save();
+        return plan;
+    }
+    /**
+     * Split a plan's tasks into sub-tasks with dependency tracking.
+     * Replaces existing tasks with a new set that includes dependency references.
+     * Only allowed on 'draft' or 'approved' plans.
+     */
+    splitTasks(planId, tasks) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        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}`,
+            title: t.title,
+            description: t.description,
+            status: 'pending',
+            dependsOn: t.dependsOn,
+            ...(t.acceptanceCriteria && { acceptanceCriteria: t.acceptanceCriteria }),
+            updatedAt: now,
+        }));
+        // Validate dependency references
+        const taskIds = new Set(plan.tasks.map((t) => t.id));
+        for (const task of plan.tasks) {
+            if (task.dependsOn) {
+                for (const dep of task.dependsOn) {
+                    if (!taskIds.has(dep)) {
+                        throw new Error(`Task '${task.id}' depends on unknown task '${dep}'`);
+                    }
+                }
+            }
+        }
+        plan.updatedAt = now;
+        this.save();
+        return plan;
+    }
+    /**
+     * Reconcile a plan — compare what was planned vs what actually happened.
+     * 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 !== 'validating' &&
+            plan.status !== 'reconciling')
+            throw new Error(`Cannot reconcile plan in '${plan.status}' status — must be 'executing', 'validating', or 'reconciling'`);
+        const driftItems = report.driftItems ?? [];
+        // Impact-weighted drift scoring (ported from Salvador)
+        const accuracy = calculateDriftScore(driftItems);
+        plan.reconciliation = {
+            planId,
+            accuracy,
+            driftItems,
+            summary: report.actualOutcome,
+            reconciledAt: Date.now(),
+        };
+        // 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;
+    }
+    /**
+     * Add review evidence to a plan or specific task.
+     */
+    addReview(planId, review) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        if (review.taskId) {
+            const task = plan.tasks.find((t) => t.id === review.taskId);
+            if (!task)
+                throw new Error(`Task not found: ${review.taskId}`);
+        }
+        if (!plan.reviews)
+            plan.reviews = [];
+        plan.reviews.push({
+            planId,
+            taskId: review.taskId,
+            reviewer: review.reviewer,
+            outcome: review.outcome,
+            comments: review.comments,
+            reviewedAt: Date.now(),
+        });
+        plan.updatedAt = Date.now();
+        this.save();
+        return plan;
+    }
+    /**
+     * Get dispatch instructions for a specific task — returns the task and its
+     * unmet dependencies so a subagent knows what to work on and what to wait for.
+     */
+    getDispatch(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 unmetDependencies = [];
+        if (task.dependsOn) {
+            for (const depId of task.dependsOn) {
+                const dep = plan.tasks.find((t) => t.id === depId);
+                if (dep && dep.status !== 'completed') {
+                    unmetDependencies.push(dep);
+                }
+            }
+        }
+        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;
+    }
+    /**
+     * 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 = 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.save();
+        }
+        return toArchive;
+    }
+    /**
+     * Get statistics about all plans.
+     */
+    stats() {
+        const plans = this.store.plans;
+        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,
+            completed: 0,
+            skipped: 0,
+            failed: 0,
+        };
+        let totalTasks = 0;
+        for (const p of plans) {
+            byStatus[p.status]++;
+            totalTasks += p.tasks.length;
+            for (const t of p.tasks) {
+                tasksByStatus[t.status]++;
+            }
+        }
+        return {
+            total: plans.length,
+            byStatus,
+            avgTasksPerPlan: plans.length > 0 ? Math.round((totalTasks / plans.length) * 100) / 100 : 0,
+            totalTasks,
+            tasksByStatus,
+        };
+    }
+    // ─── Grading ──────────────────────────────────────────────────────
+    /**
+     * 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
+     * - Iteration leniency: minor gaps free on iter 1, half on iter 2, full on 3+
+     * - Score = max(0, 100 - deductions)
+     *
+     * Grade thresholds: A+=95, A=90, B=80, C=70, D=60, F=<60
+     */
+    grade(planId) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        // Run 6-pass gap analysis
+        const gaps = runGapAnalysis(plan, this.gapOptions);
+        // Add circular dependency check (structural, not covered by gap-analysis passes)
+        if (this.hasCircularDependencies(plan)) {
+            gaps.push({
+                id: `gap_${Date.now()}_circ`,
+                severity: 'critical',
+                category: 'structure',
+                description: 'Circular dependencies detected among tasks.',
+                recommendation: 'Remove circular dependency chains so tasks can be executed in order.',
+                location: 'tasks',
+                _trigger: 'circular_dependencies',
+            });
+        }
+        // Iteration = number of previous checks + 1
+        const iteration = plan.checks.length + 1;
+        const score = calculateScore(gaps, iteration);
+        const grade = this.scoreToGrade(score);
+        const check = {
+            checkId: `chk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            planId,
+            grade,
+            score,
+            gaps,
+            iteration,
+            checkedAt: Date.now(),
+        };
+        plan.checks.push(check);
+        plan.latestCheck = check;
+        plan.updatedAt = Date.now();
+        this.save();
+        return check;
+    }
+    /**
+     * Get the latest check for a plan.
+     */
+    getLatestCheck(planId) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        return plan.latestCheck ?? null;
+    }
+    /**
+     * Get all checks for a plan (history).
+     */
+    getCheckHistory(planId) {
+        const plan = this.get(planId);
+        if (!plan)
+            throw new Error(`Plan not found: ${planId}`);
+        return [...plan.checks];
+    }
+    /**
+     * Auto-grade: grade the plan and return whether it meets a target grade.
+     */
+    meetsGrade(planId, targetGrade) {
+        const check = this.grade(planId);
+        const targetScore = this.gradeToMinScore(targetGrade);
+        return { meets: check.score >= targetScore, check };
+    }
+    // ─── Grading Helpers ──────────────────────────────────────────────
+    scoreToGrade(score) {
+        if (score >= 95)
+            return 'A+';
+        if (score >= 90)
+            return 'A';
+        if (score >= 80)
+            return 'B';
+        if (score >= 70)
+            return 'C';
+        if (score >= 60)
+            return 'D';
+        return 'F';
+    }
+    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;
+        }
+    }
+    hasCircularDependencies(plan) {
+        const visited = new Set();
+        const inStack = new Set();
+        const taskMap = new Map(plan.tasks.map((t) => [t.id, t]));
+        const dfs = (taskId) => {
+            if (inStack.has(taskId))
+                return true;
+            if (visited.has(taskId))
+                return false;
+            visited.add(taskId);
+            inStack.add(taskId);
+            const task = taskMap.get(taskId);
+            if (task?.dependsOn) {
+                for (const dep of task.dependsOn) {
+                    if (dfs(dep))
+                        return true;
+                }
+            }
+            inStack.delete(taskId);
+            return false;
+        };
+        for (const task of plan.tasks) {
+            if (dfs(task.id))
+                return true;
+        }
+        return false;
     }
 }
 //# sourceMappingURL=planner.js.map