@soleri/core 9.0.3 → 9.2.0

package/src/planning/gap-patterns.test.ts

@@ -0,0 +1,320 @@
+/**
+ * Tests for gap-patterns.ts — helpers, constants, and passes 1-4.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { Plan } from './planner.js';
+import {
+  gap,
+  taskText,
+  decisionText,
+  decisionsText,
+  containsAny,
+  analyzeStructure,
+  analyzeCompleteness,
+  analyzeFeasibility,
+  analyzeRisk,
+  METRIC_PATTERNS,
+  EXCLUSION_KEYWORDS,
+  OVERLY_BROAD_PATTERNS,
+  DEPENDENCY_KEYWORDS,
+  BREAKING_CHANGE_KEYWORDS,
+  MITIGATION_KEYWORDS,
+  VERIFICATION_KEYWORDS,
+} from './gap-patterns.js';
+
+function makePlan(overrides: Partial<Plan> = {}): Plan {
+  return {
+    id: 'plan-test',
+    objective: 'Implement user authentication with JWT tokens and session management',
+    scope: 'Auth module, middleware, and user service. Does not include OAuth providers.',
+    status: 'draft',
+    decisions: [
+      { decision: 'Use JWT for stateless auth', rationale: 'Because it scales horizontally without shared session store' },
+    ],
+    tasks: [
+      { id: 'task-1', title: 'Add JWT signing', description: 'Implement JWT sign/verify using built-in crypto module', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-2', title: 'Add auth middleware', description: 'Create Express middleware that validates JWT from Authorization header', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-3', title: 'Add login endpoint', description: 'POST /auth/login returns JWT after verifying credentials', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-4', title: 'Add test coverage', description: 'Test JWT signing, middleware rejection, and login flow end-to-end', status: 'pending', updatedAt: Date.now() },
+    ],
+    checks: [],
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe('Helper functions', () => {
+  describe('gap()', () => {
+    it('creates a PlanGap with auto-generated id', () => {
+      const result = gap('critical', 'structure', 'desc', 'rec');
+      expect(result.id).toMatch(/^gap_/);
+      expect(result.severity).toBe('critical');
+      expect(result.category).toBe('structure');
+      expect(result.description).toBe('desc');
+      expect(result.recommendation).toBe('rec');
+    });
+
+    it('includes location when provided', () => {
+      const result = gap('minor', 'clarity', 'd', 'r', 'objective');
+      expect(result.location).toBe('objective');
+    });
+
+    it('excludes location when undefined', () => {
+      const result = gap('minor', 'clarity', 'd', 'r');
+      expect(result).not.toHaveProperty('location');
+    });
+
+    it('includes _trigger when provided', () => {
+      const result = gap('minor', 'clarity', 'd', 'r', undefined, 'test_trigger');
+      expect(result._trigger).toBe('test_trigger');
+    });
+
+    it('excludes _trigger when undefined', () => {
+      const result = gap('minor', 'clarity', 'd', 'r');
+      expect(result).not.toHaveProperty('_trigger');
+    });
+  });
+
+  describe('taskText()', () => {
+    it('combines task titles and descriptions', () => {
+      const plan = makePlan();
+      const text = taskText(plan);
+      expect(text).toContain('Add JWT signing');
+      expect(text).toContain('Implement JWT sign/verify');
+    });
+
+    it('returns empty string for plan with no tasks', () => {
+      const plan = makePlan({ tasks: [] });
+      expect(taskText(plan)).toBe('');
+    });
+  });
+
+  describe('decisionText()', () => {
+    it('extracts text from string decision', () => {
+      expect(decisionText('Use JWT')).toBe('Use JWT');
+    });
+
+    it('extracts text from structured decision', () => {
+      const result = decisionText({ decision: 'Use JWT', rationale: 'scales well' });
+      expect(result).toBe('Use JWT scales well');
+    });
+  });
+
+  describe('decisionsText()', () => {
+    it('combines all decisions', () => {
+      const plan = makePlan();
+      const text = decisionsText(plan);
+      expect(text).toContain('Use JWT for stateless auth');
+      expect(text).toContain('scales horizontally');
+    });
+  });
+
+  describe('containsAny()', () => {
+    it('returns true when text contains a pattern', () => {
+      expect(containsAny('rewrite everything from scratch', ['from scratch'])).toBe(true);
+    });
+
+    it('is case-insensitive', () => {
+      expect(containsAny('FROM SCRATCH', ['from scratch'])).toBe(true);
+    });
+
+    it('returns false when no patterns match', () => {
+      expect(containsAny('simple change', ['everything', 'rewrite'])).toBe(false);
+    });
+
+    it('returns false for empty text', () => {
+      expect(containsAny('', ['test'])).toBe(false);
+    });
+
+    it('returns false for empty patterns', () => {
+      expect(containsAny('hello world', [])).toBe(false);
+    });
+  });
+});
+
+describe('Pattern constants', () => {
+  it('METRIC_PATTERNS matches numbers', () => {
+    expect(METRIC_PATTERNS.some((p) => p.test('reduce latency by 50%'))).toBe(true);
+  });
+
+  it('EXCLUSION_KEYWORDS includes common exclusion words', () => {
+    expect(EXCLUSION_KEYWORDS).toContain('exclude');
+    expect(EXCLUSION_KEYWORDS).toContain('not');
+  });
+
+  it('OVERLY_BROAD_PATTERNS includes dangerous scope terms', () => {
+    expect(OVERLY_BROAD_PATTERNS).toContain('complete rewrite');
+  });
+
+  it('DEPENDENCY_KEYWORDS includes ordering terms', () => {
+    expect(DEPENDENCY_KEYWORDS).toContain('depends');
+    expect(DEPENDENCY_KEYWORDS).toContain('prerequisite');
+  });
+
+  it('BREAKING_CHANGE_KEYWORDS includes migration terms', () => {
+    expect(BREAKING_CHANGE_KEYWORDS).toContain('breaking change');
+    expect(BREAKING_CHANGE_KEYWORDS).toContain('database migration');
+  });
+
+  it('MITIGATION_KEYWORDS includes safety terms', () => {
+    expect(MITIGATION_KEYWORDS).toContain('rollback');
+    expect(MITIGATION_KEYWORDS).toContain('feature flag');
+  });
+
+  it('VERIFICATION_KEYWORDS includes testing terms', () => {
+    expect(VERIFICATION_KEYWORDS).toContain('test');
+    expect(VERIFICATION_KEYWORDS).toContain('coverage');
+  });
+});
+
+describe('Pass 1: Structure', () => {
+  it('returns no gaps for a well-structured plan', () => {
+    const gaps = analyzeStructure(makePlan());
+    expect(gaps).toHaveLength(0);
+  });
+
+  it('returns critical gap for missing objective', () => {
+    const gaps = analyzeStructure(makePlan({ objective: '' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_objective')).toBe(true);
+    expect(gaps.find((g) => g._trigger === 'missing_or_short_objective')?.severity).toBe('critical');
+  });
+
+  it('returns critical gap for short objective', () => {
+    const gaps = analyzeStructure(makePlan({ objective: 'Fix' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_objective')).toBe(true);
+  });
+
+  it('returns critical gap for missing scope', () => {
+    const gaps = analyzeStructure(makePlan({ scope: '' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_scope')).toBe(true);
+  });
+
+  it('returns critical gap for no tasks', () => {
+    const gaps = analyzeStructure(makePlan({ tasks: [] }));
+    expect(gaps.some((g) => g._trigger === 'no_tasks')).toBe(true);
+  });
+
+  it('returns multiple gaps for completely empty plan', () => {
+    const gaps = analyzeStructure(makePlan({ objective: '', scope: '', tasks: [] }));
+    expect(gaps.length).toBe(3);
+    expect(gaps.every((g) => g.severity === 'critical')).toBe(true);
+  });
+});
+
+describe('Pass 2: Completeness', () => {
+  it('flags objective without measurable metrics', () => {
+    const plan = makePlan({ objective: 'Improve the login experience for all users globally' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_metrics_in_objective')).toBe(true);
+  });
+
+  it('does not flag objective with numbers', () => {
+    const plan = makePlan({ objective: 'Reduce login latency to under 200ms for 95% of users' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_metrics_in_objective')).toBe(false);
+  });
+
+  it('flags short decisions', () => {
+    const plan = makePlan({ decisions: [{ decision: 'JWT', rationale: '' }] });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'short_decision')).toBe(true);
+  });
+
+  it('flags scope without exclusions', () => {
+    const plan = makePlan({ scope: 'Auth module and middleware for the API layer' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_exclusions_in_scope')).toBe(true);
+  });
+
+  it('does not flag scope with exclusion keywords', () => {
+    const plan = makePlan({ scope: 'Auth module. Does not include OAuth providers.' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_exclusions_in_scope')).toBe(false);
+  });
+});
+
+describe('Pass 3: Feasibility', () => {
+  it('flags overly broad scope', () => {
+    const plan = makePlan({ scope: 'Complete rewrite of the entire codebase' });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'overly_broad_scope')).toBe(true);
+  });
+
+  it('does not flag reasonable scope', () => {
+    const plan = makePlan();
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'overly_broad_scope')).toBe(false);
+  });
+
+  it('flags missing dependencies for 4+ tasks', () => {
+    const plan = makePlan();
+    // Default plan has 4 tasks, no dependency keywords
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(true);
+  });
+
+  it('does not flag when tasks have dependsOn', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Setup', description: 'Setup project', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Build', description: 'Build feature', status: 'pending', dependsOn: ['t1'], updatedAt: Date.now() },
+        { id: 't3', title: 'Test', description: 'Test feature', status: 'pending', dependsOn: ['t2'], updatedAt: Date.now() },
+        { id: 't4', title: 'Deploy', description: 'Deploy to prod', status: 'pending', dependsOn: ['t3'], updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(false);
+  });
+
+  it('does not flag when 3 or fewer tasks', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Task 1', description: 'Do something', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Task 2', description: 'Do another thing', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(false);
+  });
+});
+
+describe('Pass 4: Risk', () => {
+  it('flags breaking changes without mitigation', () => {
+    const plan = makePlan({
+      objective: 'Database migration to new schema with breaking changes',
+      scope: 'All tables and models. Does not include frontend.',
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'breaking_without_mitigation')).toBe(true);
+  });
+
+  it('does not flag when mitigation is mentioned', () => {
+    const plan = makePlan({
+      objective: 'Database migration with breaking changes and rollback plan',
+      scope: 'All tables. Not including frontend.',
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'breaking_without_mitigation')).toBe(false);
+  });
+
+  it('flags missing verification', () => {
+    const plan = makePlan({
+      objective: 'Refactor the authentication module for better performance',
+      scope: 'Auth module only. Not including user service.',
+      decisions: [{ decision: 'Use new pattern', rationale: 'Because it is cleaner code' }],
+      tasks: [
+        { id: 't1', title: 'Refactor auth', description: 'Change the auth flow implementation', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'no_verification_mentioned')).toBe(true);
+  });
+
+  it('does not flag when testing is mentioned', () => {
+    const plan = makePlan(); // default plan has "test" in task descriptions
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'no_verification_mentioned')).toBe(false);
+  });
+});

package/src/planning/gap-patterns.ts

@@ -0,0 +1,234 @@
+/**
+ * Gap analysis helpers, pattern constants, and structural passes (1-4).
+ * Contains shared utilities and the first four analysis passes that check
+ * structure, completeness, feasibility, and risk.
+ */
+
+import type { Plan, PlanDecision } from './planner.js';
+import type { PlanGap, GapSeverity, GapCategory } from './gap-types.js';
+import {
+  generateGapId,
+  MIN_OBJECTIVE_LENGTH,
+  MIN_SCOPE_LENGTH,
+  MIN_DECISION_LENGTH,
+} from './gap-types.js';
+
+// ─── Helper Functions ────────────────────────────────────────────
+
+/** Create a PlanGap with auto-generated ID. */
+export function gap(
+  severity: GapSeverity,
+  category: GapCategory,
+  description: string,
+  recommendation: string,
+  location?: string,
+  trigger?: string,
+): PlanGap {
+  return {
+    id: generateGapId(),
+    severity,
+    category,
+    description,
+    recommendation,
+    ...(location ? { location } : {}),
+    ...(trigger ? { _trigger: trigger } : {}),
+  };
+}
+
+/** Combine all task descriptions + titles into a single text blob for analysis. */
+export function taskText(plan: Plan): string {
+  return plan.tasks.map((t) => `${t.title} ${t.description}`).join(' ');
+}
+
+/** Extract text from a decision (supports both string and structured format). */
+export function decisionText(d: string | PlanDecision): string {
+  return typeof d === 'string' ? d : `${d.decision} ${d.rationale}`;
+}
+
+/** Combine all decisions into a single text blob. */
+export function decisionsText(plan: Plan): string {
+  return plan.decisions.map(decisionText).join(' ');
+}
+
+/** Check if text contains any of the given patterns (case-insensitive). */
+export function containsAny(text: string, patterns: string[]): boolean {
+  const lower = text.toLowerCase();
+  return patterns.some((p) => lower.includes(p.toLowerCase()));
+}
+
+// ─── Pattern Constants (Passes 1-4) ─────────────────────────────
+
+export const METRIC_PATTERNS = [
+  /\d+/, /percent/i, /reduce/i, /increase/i, /measure/i,
+  /target/i, /goal/i, /kpi/i, /metric/i, /benchmark/i,
+];
+
+export const EXCLUSION_KEYWORDS = [
+  'not', 'exclude', 'outside', 'beyond', 'limit', 'except', "won't", 'will not',
+];
+
+export const OVERLY_BROAD_PATTERNS = [
+  'everything', 'all systems', 'entire codebase', 'complete rewrite',
+  'from scratch', 'total overhaul', 'rewrite everything',
+];
+
+export const DEPENDENCY_KEYWORDS = [
+  'depends', 'dependency', 'prerequisite', 'requires', 'blocked', 'before',
+];
+
+export const BREAKING_CHANGE_KEYWORDS = [
+  'breaking change', 'breaking', 'migration', 'deprecate',
+  'remove api', 'remove endpoint', 'schema change', 'database migration',
+];
+
+export const MITIGATION_KEYWORDS = [
+  'rollback', 'backward compatible', 'backwards compatible', 'feature flag',
+  'gradual', 'phased', 'fallback', 'backup', 'canary', 'blue-green',
+];
+
+export const VERIFICATION_KEYWORDS = [
+  'test', 'verify', 'validate', 'check', 'assert', 'confirm', 'spec', 'coverage',
+];
+
+// ─── Pass 1: Structure ───────────────────────────────────────────
+
+export function analyzeStructure(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+
+  if (!plan.objective || plan.objective.trim().length < MIN_OBJECTIVE_LENGTH) {
+    gaps.push(
+      gap(
+        'critical', 'structure',
+        plan.objective
+          ? `Objective too short (${plan.objective.trim().length} chars, need ${MIN_OBJECTIVE_LENGTH}+).`
+          : 'Plan has no objective.',
+        'Add a clear objective describing what this plan achieves.',
+        'objective', 'missing_or_short_objective',
+      ),
+    );
+  }
+
+  if (!plan.scope || plan.scope.trim().length < MIN_SCOPE_LENGTH) {
+    gaps.push(
+      gap(
+        'critical', 'structure',
+        plan.scope
+          ? `Scope too short (${plan.scope.trim().length} chars, need ${MIN_SCOPE_LENGTH}+).`
+          : 'Plan has no scope defined.',
+        'Define the scope — what is included and excluded.',
+        'scope', 'missing_or_short_scope',
+      ),
+    );
+  }
+
+  if (plan.tasks.length === 0) {
+    gaps.push(
+      gap('critical', 'structure', 'Plan has no tasks.',
+        'Add at least one task to make the plan actionable.',
+        'tasks', 'no_tasks'),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 2: Completeness ────────────────────────────────────────
+
+export function analyzeCompleteness(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+
+  if (plan.objective && !METRIC_PATTERNS.some((p) => p.test(plan.objective))) {
+    gaps.push(
+      gap('minor', 'completeness',
+        'Objective has no measurable targets or metrics.',
+        'Include quantifiable success criteria (numbers, percentages, concrete outcomes).',
+        'objective', 'no_metrics_in_objective'),
+    );
+  }
+
+  if (plan.decisions.length > 0) {
+    for (let i = 0; i < plan.decisions.length; i++) {
+      const d = plan.decisions[i];
+      const text = decisionText(d);
+      if (text.trim().length < MIN_DECISION_LENGTH) {
+        gaps.push(
+          gap('major', 'completeness',
+            `Decision ${i + 1} is too short (${text.trim().length} chars) — lacks rationale.`,
+            'Expand each decision to include the reasoning (why this choice over alternatives).',
+            `decisions[${i}]`, 'short_decision'),
+        );
+      }
+    }
+  }
+
+  if (plan.scope && !containsAny(plan.scope, EXCLUSION_KEYWORDS)) {
+    gaps.push(
+      gap('minor', 'completeness',
+        'Scope does not mention what is excluded.',
+        'Add explicit exclusions to prevent scope creep (e.g., "does NOT include…").',
+        'scope', 'no_exclusions_in_scope'),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 3: Feasibility ─────────────────────────────────────────
+
+export function analyzeFeasibility(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const scopeAndTasks = `${plan.scope} ${taskText(plan)}`;
+
+  if (containsAny(scopeAndTasks, OVERLY_BROAD_PATTERNS)) {
+    gaps.push(
+      gap('major', 'feasibility',
+        'Scope contains overly broad indicators — risk of unrealistic delivery.',
+        'Narrow the scope to a well-defined subset. Prefer incremental delivery over big-bang rewrites.',
+        'scope', 'overly_broad_scope'),
+    );
+  }
+
+  if (plan.tasks.length > 3 && !containsAny(scopeAndTasks, DEPENDENCY_KEYWORDS)) {
+    const hasDeps = plan.tasks.some((t) => t.dependsOn && t.dependsOn.length > 0);
+    if (!hasDeps) {
+      gaps.push(
+        gap('minor', 'feasibility',
+          `${plan.tasks.length} tasks with no dependency mentions — execution order unclear.`,
+          'Identify dependencies between tasks or add explicit ordering notes.',
+          'tasks', 'no_dependency_awareness'),
+      );
+    }
+  }
+
+  return gaps;
+}
+
+// ─── Pass 4: Risk ────────────────────────────────────────────────
+
+export function analyzeRisk(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const allText = `${plan.objective} ${plan.scope} ${taskText(plan)} ${decisionsText(plan)}`;
+
+  if (
+    containsAny(allText, BREAKING_CHANGE_KEYWORDS) &&
+    !containsAny(allText, MITIGATION_KEYWORDS)
+  ) {
+    gaps.push(
+      gap('major', 'risk',
+        'Plan involves breaking changes but mentions no mitigation strategy.',
+        'Add a rollback plan, feature flags, or phased migration approach.',
+        undefined, 'breaking_without_mitigation'),
+    );
+  }
+
+  if (plan.tasks.length > 0 && !containsAny(allText, VERIFICATION_KEYWORDS)) {
+    gaps.push(
+      gap('minor', 'risk',
+        'No verification or testing mentioned in the plan.',
+        'Add at least one task or note about testing/validation.',
+        'tasks', 'no_verification_mentioned'),
+    );
+  }
+
+  return gaps;
+}

package/src/planning/gap-types.ts

@@ -15,9 +15,11 @@ export type GapCategory =
   | 'clarity'
   | 'semantic-quality'
   | 'knowledge-depth'
+  | 'alternative-analysis'
   | 'tool-feasibility'
   | 'flow-alignment'
-  | 'anti-pattern';
+  | 'anti-pattern'
+  | 'rationalization';
 
 export interface PlanGap {
   id: string;
@@ -48,6 +50,7 @@ export const SEVERITY_WEIGHTS: Record<GapSeverity, number> = {
  */
 export const CATEGORY_PENALTY_CAPS: Record<string, number> = {
   clarity: 10,
+  'alternative-analysis': 15,
 };
 
 /**