@soleri/core 9.0.4 → 9.2.0

package/src/planning/plan-lifecycle.test.ts

@@ -0,0 +1,312 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isValidTransition,
+  getValidNextStatuses,
+  shouldExpire,
+  applyTransition,
+  LIFECYCLE_TRANSITIONS,
+  NON_EXPIRING_STATUSES,
+  scoreToGrade,
+  gradeToMinScore,
+  PlanGradeRejectionError,
+  hasCircularDependencies,
+  calculateScore,
+  applyIteration,
+  applySplitTasks,
+  applyTaskStatusUpdate,
+  createPlanObject,
+} from './plan-lifecycle.js';
+import type { PlanStatus } from './plan-lifecycle.js';
+import type { Plan, PlanTask } from './planner-types.js';
+
+describe('plan-lifecycle', () => {
+  describe('isValidTransition', () => {
+    it('allows brainstorming -> draft', () => {
+      expect(isValidTransition('brainstorming', 'draft')).toBe(true);
+    });
+    it('disallows brainstorming -> approved', () => {
+      expect(isValidTransition('brainstorming', 'approved')).toBe(false);
+    });
+    it('allows executing -> validating', () => {
+      expect(isValidTransition('executing', 'validating')).toBe(true);
+    });
+    it('allows validating -> executing (back-transition)', () => {
+      expect(isValidTransition('validating', 'executing')).toBe(true);
+    });
+    it('disallows archived -> any', () => {
+      for (const s of Object.keys(LIFECYCLE_TRANSITIONS) as PlanStatus[]) {
+        expect(isValidTransition('archived', s)).toBe(false);
+      }
+    });
+  });
+
+  describe('getValidNextStatuses', () => {
+    it('returns [draft] for brainstorming', () => {
+      expect(getValidNextStatuses('brainstorming')).toEqual(['draft']);
+    });
+    it('returns empty for archived', () => {
+      expect(getValidNextStatuses('archived')).toEqual([]);
+    });
+  });
+
+  describe('shouldExpire', () => {
+    it('returns false for executing', () => {
+      expect(shouldExpire('executing')).toBe(false);
+    });
+    it('returns true for draft', () => {
+      expect(shouldExpire('draft')).toBe(true);
+    });
+    it('returns true for completed', () => {
+      expect(shouldExpire('completed')).toBe(true);
+    });
+    it('returns false for all non-expiring statuses', () => {
+      for (const s of NON_EXPIRING_STATUSES) {
+        expect(shouldExpire(s)).toBe(false);
+      }
+    });
+  });
+
+  describe('applyTransition', () => {
+    it('returns new status and timestamp for valid transition', () => {
+      const result = applyTransition('draft', 'approved');
+      expect(result.status).toBe('approved');
+      expect(result.updatedAt).toBeGreaterThan(0);
+    });
+    it('throws for invalid transition', () => {
+      expect(() => applyTransition('draft', 'executing')).toThrow('Invalid transition');
+    });
+    it('error message includes valid transitions', () => {
+      expect(() => applyTransition('draft', 'completed')).toThrow('approved');
+    });
+  });
+
+  describe('scoreToGrade', () => {
+    it('maps score thresholds correctly', () => {
+      expect(scoreToGrade(100)).toBe('A+');
+      expect(scoreToGrade(95)).toBe('A+');
+      expect(scoreToGrade(94)).toBe('A');
+      expect(scoreToGrade(90)).toBe('A');
+      expect(scoreToGrade(89)).toBe('B');
+      expect(scoreToGrade(80)).toBe('B');
+      expect(scoreToGrade(79)).toBe('C');
+      expect(scoreToGrade(70)).toBe('C');
+      expect(scoreToGrade(69)).toBe('D');
+      expect(scoreToGrade(60)).toBe('D');
+      expect(scoreToGrade(59)).toBe('F');
+      expect(scoreToGrade(0)).toBe('F');
+    });
+  });
+
+  describe('gradeToMinScore', () => {
+    it('returns correct minimum scores', () => {
+      expect(gradeToMinScore('A+')).toBe(95);
+      expect(gradeToMinScore('A')).toBe(90);
+      expect(gradeToMinScore('B')).toBe(80);
+      expect(gradeToMinScore('C')).toBe(70);
+      expect(gradeToMinScore('D')).toBe(60);
+      expect(gradeToMinScore('F')).toBe(0);
+    });
+  });
+
+  describe('PlanGradeRejectionError', () => {
+    it('contains grade, score, minGrade and gaps', () => {
+      const gaps = [{ id: 'g1', severity: 'critical' as const, category: 'structure',
+        description: 'Missing structure', recommendation: 'Fix it' }];
+      const err = new PlanGradeRejectionError('C', 65, 'A', gaps);
+      expect(err.grade).toBe('C');
+      expect(err.score).toBe(65);
+      expect(err.minGrade).toBe('A');
+      expect(err.gaps).toHaveLength(1);
+      expect(err.message).toContain('below the minimum required grade A');
+      expect(err.name).toBe('PlanGradeRejectionError');
+    });
+    it('includes critical and major gaps in message', () => {
+      const gaps = [
+        { id: 'g1', severity: 'critical' as const, category: 'x', description: 'Crit gap', recommendation: '' },
+        { id: 'g2', severity: 'minor' as const, category: 'x', description: 'Minor gap', recommendation: '' },
+      ];
+      const err = new PlanGradeRejectionError('D', 55, 'A', gaps);
+      expect(err.message).toContain('Crit gap');
+      expect(err.message).not.toContain('Minor gap');
+    });
+  });
+
+  describe('hasCircularDependencies', () => {
+    it('returns false for no dependencies', () => {
+      expect(hasCircularDependencies([
+        { id: 'a' }, { id: 'b' },
+      ])).toBe(false);
+    });
+    it('returns false for linear dependencies', () => {
+      expect(hasCircularDependencies([
+        { id: 'a' }, { id: 'b', dependsOn: ['a'] }, { id: 'c', dependsOn: ['b'] },
+      ])).toBe(false);
+    });
+    it('returns true for direct cycle', () => {
+      expect(hasCircularDependencies([
+        { id: 'a', dependsOn: ['b'] }, { id: 'b', dependsOn: ['a'] },
+      ])).toBe(true);
+    });
+    it('returns true for indirect cycle', () => {
+      expect(hasCircularDependencies([
+        { id: 'a', dependsOn: ['c'] }, { id: 'b', dependsOn: ['a'] }, { id: 'c', dependsOn: ['b'] },
+      ])).toBe(true);
+    });
+    it('returns true for self-dependency', () => {
+      expect(hasCircularDependencies([{ id: 'a', dependsOn: ['a'] }])).toBe(true);
+    });
+  });
+
+  describe('calculateScore', () => {
+    it('returns 100 for no gaps', () => {
+      expect(calculateScore([])).toBe(100);
+    });
+    it('deducts critical gaps at weight 30', () => {
+      const gaps = [{ id: 'g', severity: 'critical' as const, category: 'structure',
+        description: 'x', recommendation: 'y' }];
+      expect(calculateScore(gaps)).toBe(70);
+    });
+    it('treats minor gaps as free on iteration 1', () => {
+      const gaps = [{ id: 'g', severity: 'minor' as const, category: 'clarity',
+        description: 'x', recommendation: 'y' }];
+      expect(calculateScore(gaps, 1)).toBe(100);
+    });
+    it('treats minor gaps at half weight on iteration 2', () => {
+      const gaps = [{ id: 'g', severity: 'minor' as const, category: 'clarity',
+        description: 'x', recommendation: 'y' }];
+      expect(calculateScore(gaps, 2)).toBe(99);
+    });
+    it('treats minor gaps at full weight on iteration 3', () => {
+      const gaps = [{ id: 'g', severity: 'minor' as const, category: 'clarity',
+        description: 'x', recommendation: 'y' }];
+      expect(calculateScore(gaps, 3)).toBe(98);
+    });
+    it('floors at 0', () => {
+      const gaps = Array.from({ length: 5 }, (_, i) => ({
+        id: `g${i}`, severity: 'critical' as const, category: `cat${i}`,
+        description: 'x', recommendation: 'y',
+      }));
+      expect(calculateScore(gaps)).toBe(0);
+    });
+  });
+
+  describe('applyIteration', () => {
+    const makePlan = (): Plan => createPlanObject({ objective: 'test', scope: 'test' });
+
+    it('updates objective and scope', () => {
+      const plan = makePlan();
+      applyIteration(plan, { objective: 'new obj', scope: 'new scope' });
+      expect(plan.objective).toBe('new obj');
+      expect(plan.scope).toBe('new scope');
+    });
+    it('adds tasks with correct IDs', () => {
+      const plan = makePlan();
+      plan.tasks = [{ id: 'task-1', title: 'T1', description: 'd', status: 'pending', updatedAt: 0 }];
+      applyIteration(plan, { addTasks: [{ title: 'T2', description: 'd2' }] });
+      expect(plan.tasks).toHaveLength(2);
+      expect(plan.tasks[1].id).toBe('task-2');
+    });
+    it('removes tasks by ID', () => {
+      const plan = makePlan();
+      plan.tasks = [
+        { id: 'task-1', title: 'T1', description: 'd', status: 'pending', updatedAt: 0 },
+        { id: 'task-2', title: 'T2', description: 'd', status: 'pending', updatedAt: 0 },
+      ];
+      applyIteration(plan, { removeTasks: ['task-1'] });
+      expect(plan.tasks).toHaveLength(1);
+      expect(plan.tasks[0].id).toBe('task-2');
+    });
+  });
+
+  describe('applySplitTasks', () => {
+    it('replaces tasks with new set', () => {
+      const plan = createPlanObject({ objective: 'test', scope: 'test' });
+      applySplitTasks(plan, [
+        { title: 'A', description: 'a' },
+        { title: 'B', description: 'b', dependsOn: ['task-1'] },
+      ]);
+      expect(plan.tasks).toHaveLength(2);
+      expect(plan.tasks[1].dependsOn).toEqual(['task-1']);
+    });
+    it('throws on unknown dependency', () => {
+      const plan = createPlanObject({ objective: 'test', scope: 'test' });
+      expect(() => applySplitTasks(plan, [
+        { title: 'A', description: 'a', dependsOn: ['task-99'] },
+      ])).toThrow('depends on unknown task');
+    });
+    it('preserves acceptance criteria', () => {
+      const plan = createPlanObject({ objective: 'test', scope: 'test' });
+      applySplitTasks(plan, [
+        { title: 'A', description: 'a', acceptanceCriteria: ['cr1', 'cr2'] },
+      ]);
+      expect(plan.tasks[0].acceptanceCriteria).toEqual(['cr1', 'cr2']);
+    });
+  });
+
+  describe('applyTaskStatusUpdate', () => {
+    const makeTask = (): PlanTask => ({
+      id: 'task-1', title: 'T', description: 'd', status: 'pending', updatedAt: 0,
+    });
+
+    it('sets startedAt on first in_progress', () => {
+      const task = makeTask();
+      applyTaskStatusUpdate(task, 'in_progress');
+      expect(task.startedAt).toBeGreaterThan(0);
+      expect(task.status).toBe('in_progress');
+    });
+    it('does not overwrite startedAt on repeated in_progress', () => {
+      const task = makeTask();
+      task.startedAt = 1000;
+      applyTaskStatusUpdate(task, 'in_progress');
+      expect(task.startedAt).toBe(1000);
+    });
+    it('sets completedAt and durationMs on completed', () => {
+      const task = makeTask();
+      task.startedAt = Date.now() - 500;
+      applyTaskStatusUpdate(task, 'completed');
+      expect(task.completedAt).toBeGreaterThan(0);
+      expect(task.metrics?.durationMs).toBeGreaterThanOrEqual(0);
+    });
+    it('sets completedAt on skipped', () => {
+      const task = makeTask();
+      applyTaskStatusUpdate(task, 'skipped');
+      expect(task.completedAt).toBeGreaterThan(0);
+      expect(task.status).toBe('skipped');
+    });
+    it('sets completedAt on failed', () => {
+      const task = makeTask();
+      applyTaskStatusUpdate(task, 'failed');
+      expect(task.completedAt).toBeGreaterThan(0);
+      expect(task.status).toBe('failed');
+    });
+  });
+
+  describe('createPlanObject', () => {
+    it('creates a plan with default draft status', () => {
+      const plan = createPlanObject({ objective: 'Build X', scope: 'API' });
+      expect(plan.status).toBe('draft');
+      expect(plan.objective).toBe('Build X');
+      expect(plan.id).toMatch(/^plan-/);
+      expect(plan.checks).toEqual([]);
+    });
+    it('supports brainstorming initial status', () => {
+      const plan = createPlanObject({ objective: 'x', scope: 'y', initialStatus: 'brainstorming' });
+      expect(plan.status).toBe('brainstorming');
+    });
+    it('creates numbered tasks', () => {
+      const plan = createPlanObject({
+        objective: 'x', scope: 'y',
+        tasks: [{ title: 'A', description: 'a' }, { title: 'B', description: 'b' }],
+      });
+      expect(plan.tasks[0].id).toBe('task-1');
+      expect(plan.tasks[1].id).toBe('task-2');
+      expect(plan.tasks[0].status).toBe('pending');
+    });
+    it('includes optional fields only when provided', () => {
+      const plan = createPlanObject({ objective: 'x', scope: 'y' });
+      expect(plan.approach).toBeUndefined();
+      const planWithApproach = createPlanObject({ objective: 'x', scope: 'y', approach: 'TDD' });
+      expect(planWithApproach.approach).toBe('TDD');
+    });
+  });
+});

package/src/planning/plan-lifecycle.ts

@@ -0,0 +1,346 @@
+/**
+ * Plan lifecycle FSM — state transitions, grade thresholds, and structural validation.
+ * Extracted from planner.ts to isolate pure lifecycle logic from persistence.
+ */
+
+import type { PlanGap } from './gap-types.js';
+import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS, CATEGORY_BONUS_CAPS } from './gap-types.js';
+
+// ─── Plan Status FSM ─────────────────────────────────────────────
+
+/**
+ * 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);
+}
+
+/**
+ * Apply an FSM transition to a plan status.
+ * Throws if the transition is invalid. Returns the new status and timestamp.
+ * Does NOT mutate the plan — caller applies the result.
+ */
+export function applyTransition(
+  currentStatus: PlanStatus,
+  targetStatus: PlanStatus,
+): { status: PlanStatus; updatedAt: number } {
+  if (!isValidTransition(currentStatus, targetStatus)) {
+    const valid = getValidNextStatuses(currentStatus);
+    throw new Error(
+      `Invalid transition: '${currentStatus}' → '${targetStatus}'. ` +
+        `Valid transitions from '${currentStatus}': ${valid.length > 0 ? valid.join(', ') : 'none'}`,
+    );
+  }
+  return { status: targetStatus, updatedAt: Date.now() };
+}
+
+// ─── Grading ─────────────────────────────────────────────────────
+
+export type PlanGrade = 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
+
+/**
+ * Convert a numeric score to a letter grade.
+ * Thresholds: A+=95, A=90, B=80, C=70, D=60, F=<60
+ */
+export function scoreToGrade(score: number): PlanGrade {
+  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';
+}
+
+/**
+ * Convert a letter grade to the minimum score required.
+ */
+export function 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;
+  }
+}
+
+/**
+ * Error thrown when a plan's grade is below the minimum required for approval.
+ */
+export class PlanGradeRejectionError extends Error {
+  readonly grade: PlanGrade;
+  readonly score: number;
+  readonly minGrade: PlanGrade;
+  readonly gaps: PlanGap[];
+
+  constructor(grade: PlanGrade, score: number, minGrade: PlanGrade, gaps: PlanGap[]) {
+    const gapSummary = gaps
+      .filter((g) => g.severity === 'critical' || g.severity === 'major')
+      .map((g) => `- [${g.severity}] ${g.description}`)
+      .join('\n');
+    super(
+      `Plan grade ${grade} (${score}/100) is below the minimum required grade ${minGrade} for approval. ` +
+        `Iterate on the plan to address gaps before approving.\n${gapSummary}`,
+    );
+    this.name = 'PlanGradeRejectionError';
+    this.grade = grade;
+    this.score = score;
+    this.minGrade = minGrade;
+    this.gaps = gaps;
+  }
+}
+
+// ─── Score Calculation ───────────────────────────────────────────
+
+/**
+ * Calculate score from gaps with severity-weighted deductions and iteration leniency.
+ */
+export function calculateScore(gaps: PlanGap[], iteration: number = 1): number {
+  const categoryDeductions = new Map<string, number>();
+  const categoryBonuses = new Map<string, number>();
+  for (const gap of gaps) {
+    let weight: number = SEVERITY_WEIGHTS[gap.severity];
+    if (gap.severity === 'minor') {
+      if (iteration === 1) weight = 0;
+      else if (iteration === 2) weight = 1;
+    }
+    const category = gap.category;
+    if (weight < 0) {
+      categoryBonuses.set(category, (categoryBonuses.get(category) ?? 0) + Math.abs(weight));
+    } else {
+      categoryDeductions.set(category, (categoryDeductions.get(category) ?? 0) + weight);
+    }
+  }
+  let deductions = 0;
+  for (const [category, total] of categoryDeductions) {
+    const cap = CATEGORY_PENALTY_CAPS[category];
+    deductions += cap !== undefined ? Math.min(total, cap) : total;
+  }
+  let bonuses = 0;
+  for (const [category, total] of categoryBonuses) {
+    const cap = CATEGORY_BONUS_CAPS[category];
+    bonuses += cap !== undefined ? Math.min(total, cap) : total;
+  }
+  return Math.max(0, Math.min(100, 100 - deductions + bonuses));
+}
+
+// ─── Structural Validation ───────────────────────────────────────
+
+/**
+ * Detect circular dependencies among tasks.
+ * Uses DFS with in-stack tracking.
+ */
+export function hasCircularDependencies(
+  tasks: ReadonlyArray<{ id: string; dependsOn?: string[] }>,
+): boolean {
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+  const taskMap = new Map(tasks.map((t) => [t.id, t]));
+
+  const dfs = (taskId: string): boolean => {
+    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 tasks) {
+    if (dfs(task.id)) return true;
+  }
+  return false;
+}
+
+// ─── Plan Mutation Helpers ───────────────────────────────────────
+
+import type { PlanTask, TaskStatus, Plan, PlanDecision } from './planner-types.js';
+
+export interface IterateChanges {
+  objective?: string; scope?: 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;
+}
+
+/**
+ * Apply iteration changes to a plan (mutates in place).
+ * Caller is responsible for status validation and persistence.
+ */
+export function applyIteration(plan: Plan, changes: IterateChanges): void {
+  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;
+  if (changes.removeTasks?.length) {
+    const removeSet = new Set(changes.removeTasks);
+    plan.tasks = plan.tasks.filter((t) => !removeSet.has(t.id));
+  }
+  if (changes.addTasks?.length) {
+    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' as TaskStatus, updatedAt: now,
+      });
+    }
+  }
+  plan.updatedAt = now;
+}
+
+/**
+ * Replace plan tasks with a new split set, validating dependency references.
+ * Caller is responsible for status validation and persistence.
+ */
+/**
+ * Apply a task status update with auto-metrics (startedAt, completedAt, durationMs).
+ * Caller is responsible for plan status validation and persistence.
+ */
+export function applyTaskStatusUpdate(task: PlanTask, status: TaskStatus): void {
+  const now = Date.now();
+  if (status === 'in_progress' && !task.startedAt) task.startedAt = now;
+  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 = now;
+}
+
+/**
+ * Create a new Plan object (factory). Does not persist.
+ */
+export function createPlanObject(params: {
+  objective: string; scope: 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;
+  alternatives?: import('./planner-types.js').PlanAlternative[];
+  initialStatus?: 'brainstorming' | 'draft';
+}): Plan {
+  const now = Date.now();
+  return {
+    id: `plan-${now}-${Math.random().toString(36).slice(2, 8)}`,
+    objective: params.objective, scope: params.scope,
+    status: params.initialStatus ?? 'draft',
+    decisions: params.decisions ?? [],
+    tasks: (params.tasks ?? []).map((t, i) => ({
+      id: `task-${i + 1}`, title: t.title, description: t.description,
+      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 }),
+    ...(params.alternatives !== undefined && { alternatives: params.alternatives }),
+    checks: [], createdAt: now, updatedAt: now,
+  };
+}
+
+export function applySplitTasks(
+  plan: Plan,
+  tasks: Array<{ title: string; description: string; dependsOn?: string[]; acceptanceCriteria?: string[] }>,
+): void {
+  const now = Date.now();
+  plan.tasks = tasks.map((t, i) => ({
+    id: `task-${i + 1}`, title: t.title, description: t.description,
+    status: 'pending' as TaskStatus, dependsOn: t.dependsOn,
+    ...(t.acceptanceCriteria && { acceptanceCriteria: t.acceptanceCriteria }), updatedAt: now,
+  }));
+  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;
+}