@soleri/core 9.0.3 → 9.2.0

package/src/planning/planner-types.ts

@@ -0,0 +1,215 @@
+/**
+ * Shared type definitions for the planning module.
+ * Extracted to avoid circular imports between planner.ts and its extracted modules.
+ */
+
+import type { PlanStatus, PlanGrade } from './plan-lifecycle.js';
+import type { PlanGap } from './gap-types.js';
+import type { GapAnalysisOptions } from './gap-analysis.js';
+
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed';
+
+export interface TaskEvidence {
+  /** What the evidence proves (maps to an acceptance criterion). */
+  criterion: string;
+  /** Evidence content — command output, URL, file path, description. */
+  content: string;
+  /** Evidence type. */
+  type: 'command_output' | 'url' | 'file' | 'description';
+  submittedAt: number;
+}
+
+export interface TaskMetrics {
+  durationMs?: number;
+  iterations?: number;
+  toolCalls?: number;
+  modelTier?: string;
+  estimatedCostUsd?: number;
+}
+
+export interface TaskDeliverable {
+  type: 'file' | 'vault_entry' | 'url';
+  path: string;
+  hash?: string;
+  verifiedAt?: number;
+  stale?: boolean;
+}
+
+export interface ExecutionSummary {
+  totalDurationMs: number;
+  tasksCompleted: number;
+  tasksSkipped: number;
+  tasksFailed: number;
+  avgTaskDurationMs: number;
+}
+
+export interface VerificationFinding {
+  /** What was found (bug, issue, code smell). */
+  description: string;
+  /** How severe the finding is. */
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  /** Whether the finding was proven reproducible before fixing. */
+  proven: boolean;
+  /** How the finding was proven (test case, reproduction steps, stack trace). */
+  proof?: string;
+}
+
+export interface TaskVerification {
+  /** Findings that motivated changes to existing code. */
+  findings: VerificationFinding[];
+}
+
+export interface PlanTask {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  /** Optional dependency IDs — tasks that must complete before this one. */
+  dependsOn?: string[];
+  /** Evidence submitted for task acceptance criteria. */
+  evidence?: TaskEvidence[];
+  /** Whether this task has been verified (all evidence checked + reviews passed). */
+  verified?: boolean;
+  /** Task-level acceptance criteria (for verification checking). */
+  acceptanceCriteria?: string[];
+  /** Timestamp when task was first moved to in_progress. */
+  startedAt?: number;
+  /** Timestamp when task reached a terminal state (completed/skipped/failed). */
+  completedAt?: number;
+  /** Per-task execution metrics. */
+  metrics?: TaskMetrics;
+  /** Deliverables produced by this task. */
+  deliverables?: TaskDeliverable[];
+  /** Verification findings for tasks that modify existing code. Advisory only. */
+  verification?: TaskVerification;
+  updatedAt: number;
+}
+
+export interface DriftItem {
+  /** Type of drift */
+  type: 'skipped' | 'added' | 'modified' | 'reordered';
+  /** What drifted */
+  description: string;
+  /** How much this affected the plan */
+  impact: 'low' | 'medium' | 'high';
+  /** Why the drift occurred */
+  rationale: string;
+}
+
+export interface ReconciliationReport {
+  planId: string;
+  /** Accuracy score: 100 = perfect execution, 0 = total drift. Impact-weighted. */
+  accuracy: number;
+  driftItems: DriftItem[];
+  /** Human-readable summary of the drift */
+  summary: string;
+  reconciledAt: number;
+}
+
+export interface ReviewEvidence {
+  planId: string;
+  taskId?: string;
+  reviewer: string;
+  outcome: 'approved' | 'rejected' | 'needs_changes';
+  comments: string;
+  reviewedAt: number;
+}
+
+export interface PlanCheck {
+  checkId: string;
+  planId: string;
+  grade: PlanGrade;
+  score: number; // 0-100
+  gaps: PlanGap[];
+  iteration: number;
+  checkedAt: number;
+}
+
+/**
+ * A structured decision with rationale.
+ * Ported from Salvador's PlanContent.decisions.
+ */
+export interface PlanDecision {
+  decision: string;
+  rationale: string;
+}
+
+/**
+ * A rejected alternative approach considered during planning.
+ * Plans with 2+ alternatives score higher — forced alternative analysis
+ * prevents tunnel vision and strengthens decision rationale.
+ */
+export interface PlanAlternative {
+  approach: string;
+  pros: string[];
+  cons: string[];
+  rejected_reason: string;
+}
+
+export interface Plan {
+  id: string;
+  objective: string;
+  scope: string;
+  status: PlanStatus;
+  /**
+   * Decisions can be flat strings (backward compat) or structured {decision, rationale}.
+   * New plans should prefer PlanDecision[].
+   */
+  decisions: (string | PlanDecision)[];
+  tasks: PlanTask[];
+  /** High-level approach description. Ported from Salvador's PlanContent. */
+  approach?: string;
+  /** Additional context for the plan. */
+  context?: string;
+  /** Measurable success criteria. */
+  success_criteria?: string[];
+  /** Tools to use in execution order. */
+  tool_chain?: string[];
+  /** Flow definition to follow (e.g., 'developer', 'reviewer', 'designer'). */
+  flow?: string;
+  /** Target operational mode (e.g., 'build', 'review', 'fix'). */
+  target_mode?: string;
+  /** Rejected alternative approaches — plans with 2+ alternatives score higher. */
+  alternatives?: PlanAlternative[];
+  /** Reconciliation report — populated by reconcile(). */
+  reconciliation?: ReconciliationReport;
+  /** Review evidence — populated by addReview(). */
+  reviews?: ReviewEvidence[];
+  /** Latest grading check. */
+  latestCheck?: PlanCheck;
+  /** All check history. */
+  checks: PlanCheck[];
+  /** Matched playbook info (set by orchestration layer via playbook_match). */
+  playbookMatch?: {
+    label: string;
+    genericId?: string;
+    domainId?: string;
+  };
+  /** Source GitHub issue this plan was created from (e.g., #NNN in prompt). */
+  githubIssue?: { owner: string; repo: string; number: number };
+  /** GitHub issue projection — populated by orchestrate_project_to_github. */
+  githubProjection?: {
+    repo: string;
+    milestone?: number;
+    issues: Array<{
+      taskId: string;
+      issueNumber: number;
+    }>;
+    projectedAt: number;
+  };
+  /** Aggregate execution metrics — populated by reconcile() and complete(). */
+  executionSummary?: ExecutionSummary;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlanStore {
+  version: string;
+  plans: Plan[];
+}
+
+export interface PlannerOptions {
+  gapOptions?: GapAnalysisOptions;
+  /** Minimum grade required for plan approval. Default: 'A'. Set to undefined to disable. */
+  minGradeForApproval?: PlanGrade;
+}

package/src/{__tests__ → planning}/planner.test.ts

@@ -1,11 +1,18 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { Planner } from '../planning/planner.js';
-import type { PlanGap } from '../planning/gap-types.js';
-import { generateGapId } from '../planning/gap-types.js';
+import { Planner, PlanGradeRejectionError } from './planner.js';
+import type { PlanGap } from './gap-types.js';
+import type { PlanAlternative } from './planner.js';
+import { generateGapId } from './gap-types.js';
 import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
+/** Two well-structured alternatives to satisfy pass 8. */
+const TWO_ALTERNATIVES: PlanAlternative[] = [
+  { approach: 'Use alternative A', pros: ['Pro A'], cons: ['Con A'], rejected_reason: 'Not suitable for our use case' },
+  { approach: 'Use alternative B', pros: ['Pro B'], cons: ['Con B'], rejected_reason: 'Too complex for the scope' },
+];
+
 describe('Planner', () => {
   let tempDir: string;
   let planner: Planner;
@@ -101,6 +108,135 @@ describe('Planner', () => {
     it('should throw for unknown plan', () => {
       expect(() => planner.approve('plan-xxx')).toThrow('not found');
     });
+
+    it('should approve a plan with A+ grade', () => {
+      const plan = planner.create({
+        objective: 'Well-graded plan',
+        scope: 'test',
+        tasks: [
+          { title: 'Task 1', description: 'A well-described task for implementation' },
+          { title: 'Task 2', description: 'Another well-described task for testing' },
+        ],
+        decisions: ['Use TypeScript for type safety'],
+      });
+      // Grade the plan — set an A+ grade check
+      const p = planner.get(plan.id)!;
+      p.latestCheck = {
+        checkId: 'chk-test-aplus',
+        planId: plan.id,
+        grade: 'A+',
+        score: 98,
+        gaps: [],
+        iteration: 1,
+        checkedAt: Date.now(),
+      };
+      p.checks = [p.latestCheck];
+      const approved = planner.approve(plan.id);
+      expect(approved.status).toBe('approved');
+    });
+
+    it('should reject approval when grade is below A', () => {
+      const plan = planner.create({
+        objective: 'Bad plan',
+        scope: 'test',
+      });
+      // Manually set a B grade check on the plan
+      const p = planner.get(plan.id)!;
+      p.latestCheck = {
+        checkId: 'chk-test',
+        planId: plan.id,
+        grade: 'B',
+        score: 82,
+        gaps: [
+          {
+            id: 'gap-1',
+            severity: 'major',
+            category: 'completeness',
+            description: 'Missing tasks',
+            recommendation: 'Add tasks',
+            location: 'tasks',
+          },
+        ],
+        iteration: 1,
+        checkedAt: Date.now(),
+      };
+      p.checks = [p.latestCheck];
+      expect(() => planner.approve(plan.id)).toThrow(PlanGradeRejectionError);
+    });
+
+    it('should approve a plan with no grade check (backward compatibility)', () => {
+      const plan = planner.create({ objective: 'No grade plan', scope: 'test' });
+      // No grade() call — latestCheck is undefined
+      const approved = planner.approve(plan.id);
+      expect(approved.status).toBe('approved');
+    });
+
+    it('should respect configurable minGradeForApproval threshold', () => {
+      const lenientPlanner = new Planner(join(tempDir, 'lenient-plans.json'), {
+        minGradeForApproval: 'B',
+      });
+      const plan = lenientPlanner.create({ objective: 'B-grade plan', scope: 'test' });
+      // Set a B grade check
+      const p = lenientPlanner.get(plan.id)!;
+      p.latestCheck = {
+        checkId: 'chk-test-b',
+        planId: plan.id,
+        grade: 'B',
+        score: 82,
+        gaps: [],
+        iteration: 1,
+        checkedAt: Date.now(),
+      };
+      p.checks = [p.latestCheck];
+      // B grade should pass with B threshold
+      const approved = lenientPlanner.approve(plan.id);
+      expect(approved.status).toBe('approved');
+    });
+
+    it('should reject with PlanGradeRejectionError containing gap details', () => {
+      const plan = planner.create({ objective: 'Gap details', scope: 'test' });
+      const p = planner.get(plan.id)!;
+      const testGaps = [
+        {
+          id: 'gap-crit',
+          severity: 'critical' as const,
+          category: 'structure',
+          description: 'Missing critical structure',
+          recommendation: 'Fix structure',
+          location: 'tasks',
+        },
+        {
+          id: 'gap-maj',
+          severity: 'major' as const,
+          category: 'completeness',
+          description: 'Incomplete scope',
+          recommendation: 'Add scope details',
+          location: 'scope',
+        },
+      ];
+      p.latestCheck = {
+        checkId: 'chk-test-gaps',
+        planId: plan.id,
+        grade: 'C',
+        score: 65,
+        gaps: testGaps,
+        iteration: 1,
+        checkedAt: Date.now(),
+      };
+      p.checks = [p.latestCheck];
+      try {
+        planner.approve(plan.id);
+        expect.unreachable('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(PlanGradeRejectionError);
+        const rejection = err as PlanGradeRejectionError;
+        expect(rejection.grade).toBe('C');
+        expect(rejection.score).toBe(65);
+        expect(rejection.minGrade).toBe('A');
+        expect(rejection.gaps).toHaveLength(2);
+        expect(rejection.message).toContain('below the minimum required grade A');
+      }
+    });
   });
 
   describe('startExecution', () => {
@@ -187,16 +323,31 @@ describe('Planner', () => {
       expect(completed.status).toBe('completed');
     });
 
-    it('should throw when completing from executing (must go through reconciling)', () => {
-      const plan = planner.create({ objective: 'Not reconciling', scope: 'test' });
+    it('should auto-reconcile when completing from executing state', () => {
+      const plan = planner.create({ objective: 'Auto reconcile', scope: 'test' });
       planner.approve(plan.id);
       planner.startExecution(plan.id);
-      expect(() => planner.complete(plan.id)).toThrow('Invalid transition');
+      const completed = planner.complete(plan.id);
+      expect(completed.status).toBe('completed');
+      expect(completed.reconciliation).toBeDefined();
+      expect(completed.reconciliation!.summary).toBe('All tasks completed');
+      expect(completed.reconciliation!.reconciledAt).toBeGreaterThan(0);
+    });
+
+    it('should auto-reconcile when completing from validating state', () => {
+      const plan = planner.create({ objective: 'Auto reconcile from validating', scope: 'test' });
+      planner.approve(plan.id);
+      planner.startExecution(plan.id);
+      planner.startValidation(plan.id);
+      const completed = planner.complete(plan.id);
+      expect(completed.status).toBe('completed');
+      expect(completed.reconciliation).toBeDefined();
+      expect(completed.reconciliation!.summary).toBe('All tasks completed');
     });
 
     it('should throw when completing from draft', () => {
       const plan = planner.create({ objective: 'Not executing', scope: 'test' });
-      expect(() => planner.complete(plan.id)).toThrow('Invalid transition');
+      expect(() => planner.complete(plan.id)).toThrow();
     });
   });
 
@@ -264,6 +415,7 @@ describe('Planner', () => {
           },
           { title: 'Add monitoring', description: 'Track and verify cache hit rate metrics' },
         ],
+        alternatives: TWO_ALTERNATIVES,
       });
       const check = planner.grade(plan.id);
       // Iteration 1: minor gaps are free, so well-formed plan scores very high
@@ -283,15 +435,15 @@ describe('Planner', () => {
     });
 
     it('should use severity-weighted scoring', () => {
-      // Plan with 1 critical gap (missing tasks) = -30 points
+      // Plan with 1 critical gap (missing tasks) = -30, 1 major (no alternatives) = -15
       const plan = planner.create({
         objective: 'Good objective with some detail',
         scope: 'Narrow scope that excludes nothing important',
       });
       const check = planner.grade(plan.id);
-      // No tasks = critical (-30), but also minor gaps from completeness/semantic
-      // On iteration 1, minor gaps are free, so only critical gap counts
-      expect(check.score).toBe(70); // 100 - 30 (no tasks)
+      // No tasks = critical (-30), no alternatives = major (-15)
+      // On iteration 1, minor gaps are free, so only critical + major count
+      expect(check.score).toBe(55); // 100 - 30 (no tasks) - 15 (no alternatives)
     });
 
     it('should detect duplicate task titles', () => {
@@ -359,6 +511,7 @@ describe('Planner', () => {
           },
           { title: 'Write auth tests', description: 'Integration tests for all auth endpoints' },
         ],
+        alternatives: TWO_ALTERNATIVES,
       });
 
       // Iteration 1: minor gaps free → score should be 100
@@ -442,11 +595,12 @@ describe('Planner', () => {
 
     it('should use correct grade thresholds: A+=95, A=90, B=80, C=70, D=60', () => {
       // We can verify by creating plans with known gap profiles
-      // Plan with 1 major gap = score 85 → grade B (80-89)
+      // Plan with 2 major gaps = score 70 → grade C (70-79)
       const plan = planner.create({
         objective: 'Test threshold plan with a good objective description',
         scope: 'Narrow scope, does not include anything beyond testing',
         decisions: [], // no decisions = major gap from semantic-quality (-15)
+        // no alternatives = major gap from alternative-analysis (-15)
         tasks: [
           { title: 'Task 1', description: 'First detailed task description' },
           { title: 'Task 2', description: 'Second detailed task description' },
@@ -454,9 +608,9 @@ describe('Planner', () => {
         ],
       });
       const check = planner.grade(plan.id);
-      // 1 major gap (no decisions for 3 tasks) = -15, iter 1 minor gaps free
-      expect(check.score).toBe(85);
-      expect(check.grade).toBe('B');
+      // 2 major gaps: no decisions (-15) + no alternatives (-15) = -30, iter 1 minor gaps free
+      expect(check.score).toBe(70);
+      expect(check.grade).toBe('C');
     });
   });