@soleri/core 9.2.0 → 9.3.1

package/src/planning/task-complexity-assessor.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect } from 'vitest';
+import {
+  assessTaskComplexity,
+  type AssessmentInput,
+  type AssessmentResult,
+} from './task-complexity-assessor.js';
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function assess(partial: Partial<AssessmentInput> & { prompt: string }): AssessmentResult {
+  return assessTaskComplexity(partial);
+}
+
+function signalByName(result: AssessmentResult, name: string) {
+  return result.signals.find((s) => s.name === name);
+}
+
+// ─── Simple Tasks ───────────────────────────────────────────────────
+
+describe('assessTaskComplexity — simple tasks', () => {
+  it('classifies "rename variable X" as simple', () => {
+    const result = assess({ prompt: 'rename variable X to Y' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies "fix typo in README" as simple', () => {
+    const result = assess({ prompt: 'fix typo in README' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies "add CSS class" as simple', () => {
+    const result = assess({ prompt: 'add CSS class to the header' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies single-file estimate as simple', () => {
+    const result = assess({ prompt: 'update button color', filesEstimated: 1 });
+    expect(result.classification).toBe('simple');
+    expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+  });
+
+  it('classifies task with 2 files as simple', () => {
+    const result = assess({ prompt: 'update two files', filesEstimated: 2 });
+    expect(result.classification).toBe('simple');
+    expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+  });
+});
+
+// ─── Complex Tasks ──────────────────────────────────────────────────
+
+describe('assessTaskComplexity — complex tasks', () => {
+  it('classifies "add authentication" touching multiple files as complex', () => {
+    const result = assess({ prompt: 'add authentication to the API', filesEstimated: 4 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+  });
+
+  it('classifies "refactor the vault module" as complex via cross-cutting when combined with files', () => {
+    const result = assess({ prompt: 'refactor across the vault module', filesEstimated: 5 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+  });
+
+  it('classifies "migrate database schema" touching multiple files as complex', () => {
+    const result = assess({ prompt: 'migrate database schema to v2', filesEstimated: 3 });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(true);
+    expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+  });
+
+  it('classifies many-file task with design decision as complex', () => {
+    const result = assess({ prompt: 'how should we update styles across the app', filesEstimated: 5 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+    expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+  });
+
+  it('classifies task with design decision as complex', () => {
+    const result = assess({
+      prompt: 'how should we structure the new cache layer',
+      filesEstimated: 3,
+    });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'design-decisions-needed')!.triggered).toBe(true);
+  });
+
+  it('classifies task with new dependency as complex', () => {
+    const result = assess({
+      prompt: 'add a new package for rate limiting and install it',
+      filesEstimated: 3,
+    });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'new-dependencies')!.triggered).toBe(true);
+  });
+});
+
+// ─── Edge Cases ─────────────────────────────────────────────────────
+
+describe('assessTaskComplexity — edge cases', () => {
+  it('handles empty prompt as simple', () => {
+    const result = assess({ prompt: '' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBe(0);
+  });
+
+  it('clamps score to 0 minimum (negative weights only)', () => {
+    const result = assess({
+      prompt: 'do the thing',
+      hasParentPlan: true,
+    });
+    expect(result.score).toBe(0);
+    expect(result.classification).toBe('simple');
+  });
+
+  it('clamps score to 100 maximum', () => {
+    const result = assess({
+      prompt: 'add authentication, migrate the DB, install new package, how should we design this, refactor across all modules',
+      filesEstimated: 10,
+      domains: ['vault', 'brain', 'planning'],
+    });
+    expect(result.score).toBeLessThanOrEqual(100);
+    expect(result.score).toBeGreaterThanOrEqual(0);
+  });
+
+  it('parent context reduces complexity', () => {
+    const withoutParent = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+    });
+    const withParent = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+      hasParentPlan: true,
+    });
+    expect(withParent.score).toBeLessThan(withoutParent.score);
+    expect(signalByName(withParent, 'approach-already-described')!.triggered).toBe(true);
+  });
+
+  it('parentIssueContext also reduces complexity', () => {
+    const result = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+      parentIssueContext: 'Use middleware pattern as described in RFC-42',
+    });
+    expect(signalByName(result, 'approach-already-described')!.triggered).toBe(true);
+  });
+
+  it('borderline score at exactly 40 is complex', () => {
+    // file-count (25) + new-dependencies (15) = 40
+    const result = assess({
+      prompt: 'install the redis package',
+      filesEstimated: 3,
+    });
+    expect(result.score).toBe(40);
+    expect(result.classification).toBe('complex');
+  });
+
+  it('borderline score at 39 is simple', () => {
+    // file-count (25) + new-dependencies (15) + approach-described (-15) = 25
+    const result = assess({
+      prompt: 'install the redis package',
+      filesEstimated: 3,
+      hasParentPlan: true,
+    });
+    expect(result.score).toBeLessThan(40);
+    expect(result.classification).toBe('simple');
+  });
+});
+
+// ─── Individual Signals ─────────────────────────────────────────────
+
+describe('assessTaskComplexity — individual signals', () => {
+  describe('file-count signal', () => {
+    it('triggers at 3 files', () => {
+      const result = assess({ prompt: 'task', filesEstimated: 3 });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+      expect(signalByName(result, 'file-count')!.weight).toBe(25);
+    });
+
+    it('does not trigger at 2 files', () => {
+      const result = assess({ prompt: 'task', filesEstimated: 2 });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+    });
+
+    it('does not trigger when no estimate provided', () => {
+      const result = assess({ prompt: 'task' });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+    });
+  });
+
+  describe('cross-cutting-keywords signal', () => {
+    it.each([
+      'add authentication',
+      'implement authorization',
+      'migrate the database',
+      'refactor across modules',
+      'handle cross-cutting concerns',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(true);
+    });
+
+    it('does not trigger for benign text', () => {
+      const result = assess({ prompt: 'fix button alignment' });
+      expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(false);
+    });
+  });
+
+  describe('new-dependencies signal', () => {
+    it.each([
+      'add dependency for caching',
+      'install redis',
+      'new package for validation',
+      'npm install lodash',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'new-dependencies')!.triggered).toBe(true);
+    });
+
+    it('does not trigger for normal text', () => {
+      const result = assess({ prompt: 'update existing code' });
+      expect(signalByName(result, 'new-dependencies')!.triggered).toBe(false);
+    });
+  });
+
+  describe('design-decisions-needed signal', () => {
+    it.each([
+      'how should we handle caching',
+      'which approach for the API',
+      'design decision on storage',
+      'architectural decision for events',
+      'evaluate the trade-off between speed and accuracy',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'design-decisions-needed')!.triggered).toBe(true);
+    });
+  });
+
+  describe('approach-already-described signal', () => {
+    it('triggers with hasParentPlan', () => {
+      const result = assess({ prompt: 'task', hasParentPlan: true });
+      const signal = signalByName(result, 'approach-already-described')!;
+      expect(signal.triggered).toBe(true);
+      expect(signal.weight).toBe(-15);
+    });
+
+    it('triggers with parentIssueContext', () => {
+      const result = assess({ prompt: 'task', parentIssueContext: 'Steps described here' });
+      expect(signalByName(result, 'approach-already-described')!.triggered).toBe(true);
+    });
+
+    it('does not trigger with empty parentIssueContext', () => {
+      const result = assess({ prompt: 'task', parentIssueContext: '   ' });
+      expect(signalByName(result, 'approach-already-described')!.triggered).toBe(false);
+    });
+  });
+
+  describe('multi-domain signal', () => {
+    it('triggers with 2+ domains', () => {
+      const result = assess({ prompt: 'task', domains: ['vault', 'brain'] });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(true);
+      expect(signalByName(result, 'multi-domain')!.weight).toBe(5);
+    });
+
+    it('does not trigger with single domain', () => {
+      const result = assess({ prompt: 'task', domains: ['vault'] });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(false);
+    });
+
+    it('does not trigger with no domains', () => {
+      const result = assess({ prompt: 'task' });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(false);
+    });
+  });
+});
+
+// ─── Reasoning Output ───────────────────────────────────────────────
+
+describe('assessTaskComplexity — reasoning', () => {
+  it('includes signal names in reasoning when triggered', () => {
+    const result = assess({ prompt: 'migrate the database', filesEstimated: 5 });
+    expect(result.reasoning).toContain('cross-cutting-keywords');
+    expect(result.reasoning).toContain('file-count');
+  });
+
+  it('provides fallback reasoning when nothing triggers', () => {
+    const result = assess({ prompt: 'fix typo' });
+    expect(result.reasoning).toContain('No complexity signals detected');
+  });
+
+  it('always returns 6 signals', () => {
+    const result = assess({ prompt: 'anything' });
+    expect(result.signals).toHaveLength(6);
+  });
+});

package/src/planning/task-complexity-assessor.ts

@@ -0,0 +1,183 @@
+/**
+ * Task Complexity Assessor — pure function that classifies tasks as simple or complex.
+ *
+ * Used by the planning module to decide whether a decomposed GH issue
+ * needs a full plan or can be executed directly.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export interface AssessmentInput {
+  /** User's task description. */
+  prompt: string;
+  /** Estimated number of files to touch. */
+  filesEstimated?: number;
+  /** GH issue body if available. */
+  parentIssueContext?: string;
+  /** Whether the approach is already described in a parent plan. */
+  hasParentPlan?: boolean;
+  /** Which domains are involved. */
+  domains?: string[];
+}
+
+export interface AssessmentSignal {
+  name: string;
+  weight: number;
+  triggered: boolean;
+  detail: string;
+}
+
+export interface AssessmentResult {
+  classification: 'simple' | 'complex';
+  /** 0-100 complexity score. Threshold at 40. */
+  score: number;
+  signals: AssessmentSignal[];
+  /** One-line explanation. */
+  reasoning: string;
+}
+
+// ─── Signal Detectors ───────────────────────────────────────────────
+
+const CROSS_CUTTING_PATTERNS = [
+  /\bauth(?:entication|orization)?\b/i,
+  /\bmigrat(?:e|ion|ing)\b/i,
+  /\brefactor(?:ing)?\s+across\b/i,
+  /\bcross[- ]cutting\b/i,
+];
+
+const NEW_DEPENDENCY_PATTERNS = [
+  /\badd\s+dep(?:endency|endencies)?\b/i,
+  /\binstall\b/i,
+  /\bnew\s+package\b/i,
+  /\bnpm\s+install\b/i,
+  /\badd\s+(?:a\s+)?(?:new\s+)?(?:npm\s+)?package\b/i,
+];
+
+const DESIGN_DECISION_PATTERNS = [
+  /\bhow\s+should\b/i,
+  /\bwhich\s+approach\b/i,
+  /\bdesign\s+decision\b/i,
+  /\barchitectur(?:e|al)\s+(?:decision|choice)\b/i,
+  /\btrade[- ]?off/i,
+];
+
+function detectFileCount(input: AssessmentInput): AssessmentSignal {
+  const files = input.filesEstimated ?? 0;
+  const triggered = files >= 3;
+  return {
+    name: 'file-count',
+    weight: 25,
+    triggered,
+    detail: triggered
+      ? `Estimated ${files} files (≥3 threshold)`
+      : files > 0
+        ? `Estimated ${files} file${files === 1 ? '' : 's'} (under threshold)`
+        : 'No file estimate provided',
+  };
+}
+
+function detectCrossCutting(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = CROSS_CUTTING_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'cross-cutting-keywords',
+    weight: 20,
+    triggered: !!match,
+    detail: match
+      ? `Detected cross-cutting keyword: "${text.match(match)?.[0]}"`
+      : 'No cross-cutting keywords detected',
+  };
+}
+
+function detectNewDependencies(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = NEW_DEPENDENCY_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'new-dependencies',
+    weight: 15,
+    triggered: !!match,
+    detail: match
+      ? `Detected dependency signal: "${text.match(match)?.[0]}"`
+      : 'No new dependency signals detected',
+  };
+}
+
+function detectDesignDecisions(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = DESIGN_DECISION_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'design-decisions-needed',
+    weight: 20,
+    triggered: !!match,
+    detail: match
+      ? `Detected design decision signal: "${text.match(match)?.[0]}"`
+      : 'No design decision signals detected',
+  };
+}
+
+function detectApproachDescribed(input: AssessmentInput): AssessmentSignal {
+  const hasContext = !!(input.hasParentPlan || input.parentIssueContext?.trim());
+  return {
+    name: 'approach-already-described',
+    weight: -15,
+    triggered: hasContext,
+    detail: hasContext
+      ? 'Approach already described in parent plan or issue'
+      : 'No pre-existing approach context',
+  };
+}
+
+function detectMultiDomain(input: AssessmentInput): AssessmentSignal {
+  const domains = input.domains ?? [];
+  const triggered = domains.length >= 2;
+  return {
+    name: 'multi-domain',
+    weight: 5,
+    triggered,
+    detail: triggered
+      ? `Involves ${domains.length} domains: ${domains.join(', ')}`
+      : domains.length === 1
+        ? `Single domain: ${domains[0]}`
+        : 'No domains specified',
+  };
+}
+
+// ─── Assessor ───────────────────────────────────────────────────────
+
+const COMPLEXITY_THRESHOLD = 40;
+
+/**
+ * Assess task complexity from structured input.
+ *
+ * Returns a classification (`simple` | `complex`), a numeric score (0-100),
+ * the individual signals that contributed, and a one-line reasoning string.
+ *
+ * Pure function — no side effects, no DB, no MCP calls.
+ */
+export function assessTaskComplexity(input: AssessmentInput): AssessmentResult {
+  const signals: AssessmentSignal[] = [
+    detectFileCount(input),
+    detectCrossCutting(input),
+    detectNewDependencies(input),
+    detectDesignDecisions(input),
+    detectApproachDescribed(input),
+    detectMultiDomain(input),
+  ];
+
+  const rawScore = signals.reduce(
+    (sum, s) => sum + (s.triggered ? s.weight : 0),
+    0,
+  );
+
+  // Clamp to 0-100
+  const score = Math.max(0, Math.min(100, rawScore));
+  const classification = score >= COMPLEXITY_THRESHOLD ? 'complex' : 'simple';
+
+  const triggered = signals.filter((s) => s.triggered);
+  const reasoning =
+    triggered.length === 0
+      ? 'No complexity signals detected — treating as simple task'
+      : `${classification === 'complex' ? 'Complex' : 'Simple'}: ${triggered.map((s) => s.name).join(', ')} (score ${score})`;
+
+  return { classification, score, signals, reasoning };
+}

package/src/planning/task-verifier.test.ts

@@ -11,8 +11,12 @@ import {
 import type { PlanTask, TaskEvidence, TaskDeliverable, ReviewEvidence } from './planner-types.js';
 
 const makeTask = (overrides: Partial<PlanTask> = {}): PlanTask => ({
-  id: 'task-1', title: 'Test task', description: 'Do something',
-  status: 'pending', updatedAt: 0, ...overrides,
+  id: 'task-1',
+  title: 'Test task',
+  description: 'Do something',
+  status: 'pending',
+  updatedAt: 0,
+  ...overrides,
 });
 
 describe('task-verifier', () => {
@@ -21,7 +25,11 @@ describe('task-verifier', () => {
       const existing: TaskEvidence[] = [
         { criterion: 'cr1', content: 'result', type: 'description', submittedAt: 100 },
       ];
-      const result = createEvidence(existing, { criterion: 'cr2', content: 'output', type: 'command_output' });
+      const result = createEvidence(existing, {
+        criterion: 'cr2',
+        content: 'output',
+        type: 'command_output',
+      });
       expect(result).toHaveLength(2);
       expect(result[1].criterion).toBe('cr2');
       expect(result[1].submittedAt).toBeGreaterThan(0);
@@ -66,22 +74,50 @@ describe('task-verifier', () => {
     it('returns verified=true when task has approved review', () => {
       const task = makeTask({ status: 'completed' });
       const reviews: ReviewEvidence[] = [
-        { planId: 'p1', taskId: 'task-1', reviewer: 'r', outcome: 'approved', comments: '', reviewedAt: 0 },
+        {
+          planId: 'p1',
+          taskId: 'task-1',
+          reviewer: 'r',
+          outcome: 'approved',
+          comments: '',
+          reviewedAt: 0,
+        },
       ];
       expect(verifyTaskLogic(task, reviews).verified).toBe(true);
     });
     it('returns verified=false when task has rejected review', () => {
       const task = makeTask({ status: 'completed' });
       const reviews: ReviewEvidence[] = [
-        { planId: 'p1', taskId: 'task-1', reviewer: 'r', outcome: 'rejected', comments: '', reviewedAt: 0 },
+        {
+          planId: 'p1',
+          taskId: 'task-1',
+          reviewer: 'r',
+          outcome: 'rejected',
+          comments: '',
+          reviewedAt: 0,
+        },
       ];
       expect(verifyTaskLogic(task, reviews).verified).toBe(false);
     });
     it('uses latest review outcome', () => {
       const task = makeTask({ status: 'completed' });
       const reviews: ReviewEvidence[] = [
-        { planId: 'p1', taskId: 'task-1', reviewer: 'r', outcome: 'rejected', comments: '', reviewedAt: 0 },
-        { planId: 'p1', taskId: 'task-1', reviewer: 'r', outcome: 'approved', comments: '', reviewedAt: 1 },
+        {
+          planId: 'p1',
+          taskId: 'task-1',
+          reviewer: 'r',
+          outcome: 'rejected',
+          comments: '',
+          reviewedAt: 0,
+        },
+        {
+          planId: 'p1',
+          taskId: 'task-1',
+          reviewer: 'r',
+          outcome: 'approved',
+          comments: '',
+          reviewedAt: 1,
+        },
       ];
       expect(verifyTaskLogic(task, reviews).verified).toBe(true);
     });
@@ -110,9 +146,13 @@ describe('task-verifier', () => {
       expect(result.issues[0].issue).toContain('pending');
     });
     it('flags missing evidence for completed tasks with acceptance criteria', () => {
-      const tasks: PlanTask[] = [makeTask({
-        status: 'completed', acceptanceCriteria: ['cr1'], evidence: [],
-      })];
+      const tasks: PlanTask[] = [
+        makeTask({
+          status: 'completed',
+          acceptanceCriteria: ['cr1'],
+          evidence: [],
+        }),
+      ];
       const result = verifyPlanLogic('plan-1', tasks);
       expect(result.issues[0].issue).toContain('Missing evidence');
     });
@@ -138,35 +178,27 @@ describe('task-verifier', () => {
       expect(result.staleCount).toBe(0);
     });
     it('marks file deliverables as stale when file does not exist', () => {
-      const deliverables: TaskDeliverable[] = [
-        { type: 'file', path: '/nonexistent/path/file.ts' },
-      ];
+      const deliverables: TaskDeliverable[] = [{ type: 'file', path: '/nonexistent/path/file.ts' }];
       const result = verifyDeliverablesLogic(deliverables);
       expect(result.verified).toBe(false);
       expect(result.staleCount).toBe(1);
       expect(result.deliverables[0].stale).toBe(true);
     });
     it('marks vault_entry deliverables as stale when vault returns null', () => {
-      const deliverables: TaskDeliverable[] = [
-        { type: 'vault_entry', path: 'entry-123' },
-      ];
+      const deliverables: TaskDeliverable[] = [{ type: 'vault_entry', path: 'entry-123' }];
       const vault = { get: () => null };
       const result = verifyDeliverablesLogic(deliverables, vault);
       expect(result.staleCount).toBe(1);
     });
     it('marks vault_entry deliverables as valid when vault returns non-null', () => {
-      const deliverables: TaskDeliverable[] = [
-        { type: 'vault_entry', path: 'entry-123' },
-      ];
+      const deliverables: TaskDeliverable[] = [{ type: 'vault_entry', path: 'entry-123' }];
       const vault = { get: () => ({ id: 'entry-123' }) };
       const result = verifyDeliverablesLogic(deliverables, vault);
       expect(result.verified).toBe(true);
       expect(result.staleCount).toBe(0);
     });
     it('skips url deliverables (no verification)', () => {
-      const deliverables: TaskDeliverable[] = [
-        { type: 'url', path: 'https://example.com' },
-      ];
+      const deliverables: TaskDeliverable[] = [{ type: 'url', path: 'https://example.com' }];
       const result = verifyDeliverablesLogic(deliverables);
       expect(result.verified).toBe(true);
     });
@@ -214,17 +246,17 @@ describe('task-verifier', () => {
       expect(prompt).toContain('2. No regressions');
     });
     it('omits criteria section when empty', () => {
-      const prompt = buildSpecReviewPrompt(
-        { title: 'T', description: 'd' },
-        'Objective',
-      );
+      const prompt = buildSpecReviewPrompt({ title: 'T', description: 'd' }, 'Objective');
       expect(prompt).not.toContain('Acceptance Criteria');
     });
   });
 
   describe('buildQualityReviewPrompt', () => {
     it('includes task info and quality checklist', () => {
-      const prompt = buildQualityReviewPrompt({ title: 'Refactor X', description: 'Clean up code' });
+      const prompt = buildQualityReviewPrompt({
+        title: 'Refactor X',
+        description: 'Clean up code',
+      });
       expect(prompt).toContain('Refactor X');
       expect(prompt).toContain('Clean up code');
       expect(prompt).toContain('Code Quality Review');