@soleri/core 9.0.3 → 9.2.0

package/src/planning/rationalization-detector.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import { detectRationalizations } from './rationalization-detector.js';
+
+const CRITERIA = [
+  'All API endpoints return proper error codes',
+  'Unit test coverage above 80%',
+  'Database migrations are reversible',
+];
+
+describe('detectRationalizations', () => {
+  // ─── Positive cases: each pattern detected ──────────────────
+
+  it('detects "out of scope" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Database migrations are out of scope for this task.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items).toHaveLength(1);
+    expect(report.items[0].pattern).toBe('out-of-scope');
+  });
+
+  it('detects "follow-up ticket" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Error codes will be addressed in a follow-up issue.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items).toHaveLength(1);
+    expect(report.items[0].pattern).toBe('follow-up-ticket');
+  });
+
+  it('detects "follow-up PR" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Test coverage bump deferred to follow-up PR.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('follow-up-ticket');
+  });
+
+  it('detects "pre-existing issue" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'The missing error codes are a pre-existing bug in the codebase.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('pre-existing-issue');
+  });
+
+  it('detects "over-engineering" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Making migrations reversible would be over-engineering at this stage.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('over-engineering');
+  });
+
+  it('detects "separate PR" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Test coverage improvements will go in a separate PR.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('separate-pr');
+  });
+
+  it('detects "too complex for this task" pattern', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Reversible migrations are too complex for this task, deferring.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('too-complex');
+  });
+
+  // ─── Negative cases: clean completion ───────────────────────
+
+  it('returns no detection for clean completion claim', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'All endpoints return proper error codes. Test coverage is at 85%. Migrations are reversible.',
+    );
+    expect(report.detected).toBe(false);
+    expect(report.items).toHaveLength(0);
+  });
+
+  it('returns no detection for unrelated text', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Implemented the feature, ran all tests, everything passes.',
+    );
+    expect(report.detected).toBe(false);
+    expect(report.items).toHaveLength(0);
+  });
+
+  // ─── Case-insensitive matching ──────────────────────────────
+
+  it('matches case-insensitively (uppercase)', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'This is OUT OF SCOPE for the current work.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('out-of-scope');
+  });
+
+  it('matches case-insensitively (mixed case)', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'That is a Pre-Existing Issue we inherited.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items[0].pattern).toBe('pre-existing-issue');
+  });
+
+  // ─── Empty/skip cases ──────────────────────────────────────
+
+  it('skips detection when acceptance criteria are empty', () => {
+    const report = detectRationalizations(
+      [],
+      'This is out of scope and a pre-existing issue.',
+    );
+    expect(report.detected).toBe(false);
+    expect(report.items).toHaveLength(0);
+  });
+
+  it('skips detection when completion claim is empty', () => {
+    const report = detectRationalizations(CRITERIA, '');
+    expect(report.detected).toBe(false);
+    expect(report.items).toHaveLength(0);
+  });
+
+  it('skips detection when completion claim is whitespace only', () => {
+    const report = detectRationalizations(CRITERIA, '   ');
+    expect(report.detected).toBe(false);
+    expect(report.items).toHaveLength(0);
+  });
+
+  // ─── Multiple rationalizations ─────────────────────────────
+
+  it('detects multiple rationalizations in one claim', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'Error codes are out of scope. Test coverage will go in a separate PR. ' +
+        'Reversible migrations are too complex for this task.',
+    );
+    expect(report.detected).toBe(true);
+    expect(report.items.length).toBeGreaterThanOrEqual(3);
+
+    const patterns = report.items.map((i) => i.pattern);
+    expect(patterns).toContain('out-of-scope');
+    expect(patterns).toContain('separate-pr');
+    expect(patterns).toContain('too-complex');
+  });
+
+  // ─── Suggestion is always present ──────────────────────────
+
+  it('provides actionable suggestions for each item', () => {
+    const report = detectRationalizations(
+      CRITERIA,
+      'This is out of scope and over-engineering.',
+    );
+    expect(report.detected).toBe(true);
+    for (const item of report.items) {
+      expect(item.suggestion).toBeTruthy();
+      expect(item.suggestion.length).toBeGreaterThan(10);
+    }
+  });
+});

package/src/planning/rationalization-detector.ts

@@ -0,0 +1,138 @@
+/**
+ * Rationalization detector — identifies completion claims that rationalize
+ * away unmet acceptance criteria instead of genuinely completing them.
+ *
+ * Used by orchestrate_complete to gate auto-completion.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export interface RationalizationItem {
+  /** The acceptance criterion being rationalized away. */
+  criterion: string;
+  /** The phrase in the completion claim that triggered detection. */
+  phrase: string;
+  /** The pattern name that matched. */
+  pattern: string;
+  /** Actionable suggestion for the user. */
+  suggestion: string;
+}
+
+export interface RationalizationReport {
+  /** Whether any rationalizations were detected. */
+  detected: boolean;
+  /** Individual rationalization items found. */
+  items: RationalizationItem[];
+}
+
+// ─── Patterns ───────────────────────────────────────────────────
+
+interface RationalizationPattern {
+  name: string;
+  regex: RegExp;
+  suggestion: string;
+}
+
+const PATTERNS: RationalizationPattern[] = [
+  {
+    name: 'out-of-scope',
+    regex: /out\s+of\s+scope/i,
+    suggestion: 'If it was in the acceptance criteria, it is in scope. Remove from criteria or complete it.',
+  },
+  {
+    name: 'follow-up-ticket',
+    regex: /follow[- ]?up\s+(ticket|issue|pr|task)/i,
+    suggestion: 'Deferring to a follow-up means the criterion is unmet. Complete it now or revise the plan.',
+  },
+  {
+    name: 'pre-existing-issue',
+    regex: /pre[- ]?existing\s+(issue|bug|problem)/i,
+    suggestion: 'Pre-existing or not, the criterion expects it resolved. Fix it or remove the criterion.',
+  },
+  {
+    name: 'over-engineering',
+    regex: /over[- ]?engineering/i,
+    suggestion: 'Meeting acceptance criteria is not over-engineering. Implement what was agreed upon.',
+  },
+  {
+    name: 'separate-pr',
+    regex: /separate\s+(pr|task|ticket|issue)/i,
+    suggestion: 'Splitting into a separate PR defers the work. Complete the criterion or update the plan.',
+  },
+  {
+    name: 'too-complex',
+    regex: /too\s+complex\s+for\s+this\s+(task|pr|ticket|issue|scope)/i,
+    suggestion: 'Complexity was known at planning time. Revisit the plan or complete the criterion.',
+  },
+];
+
+// ─── Detector ───────────────────────────────────────────────────
+
+/**
+ * Scan a completion claim against acceptance criteria for rationalization
+ * language — phrases that excuse unmet criteria rather than completing them.
+ *
+ * @param acceptanceCriteria - The plan/task acceptance criteria
+ * @param completionClaim - The completion summary to scan
+ * @returns A report with detected rationalization items
+ */
+export function detectRationalizations(
+  acceptanceCriteria: string[],
+  completionClaim: string,
+): RationalizationReport {
+  if (!acceptanceCriteria.length || !completionClaim.trim()) {
+    return { detected: false, items: [] };
+  }
+
+  const items: RationalizationItem[] = [];
+
+  for (const pattern of PATTERNS) {
+    const match = pattern.regex.exec(completionClaim);
+    if (!match) continue;
+
+    // Find which criterion is being rationalized (nearest mention)
+    const criterion = findRelatedCriterion(
+      acceptanceCriteria,
+      completionClaim,
+      match.index,
+    );
+
+    items.push({
+      criterion,
+      phrase: match[0],
+      pattern: pattern.name,
+      suggestion: pattern.suggestion,
+    });
+  }
+
+  return { detected: items.length > 0, items };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────
+
+/**
+ * Find the acceptance criterion most related to the rationalization phrase
+ * by checking which criterion text appears closest to the match position.
+ */
+function findRelatedCriterion(
+  criteria: string[],
+  claim: string,
+  matchIndex: number,
+): string {
+  const claimLower = claim.toLowerCase();
+  let bestCriterion = criteria[0];
+  let bestDistance = Infinity;
+
+  for (const c of criteria) {
+    const idx = claimLower.indexOf(c.toLowerCase());
+    if (idx !== -1) {
+      const dist = Math.abs(idx - matchIndex);
+      if (dist < bestDistance) {
+        bestDistance = dist;
+        bestCriterion = c;
+      }
+    }
+  }
+
+  return bestCriterion;
+}

package/src/planning/reconciliation-engine.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import {
+  DRIFT_WEIGHTS,
+  calculateDriftScore,
+  computeExecutionSummary,
+  buildReconciliationReport,
+  buildAutoReconcileInput,
+} from './reconciliation-engine.js';
+import type { DriftItem, PlanTask } from './planner-types.js';
+
+describe('reconciliation-engine', () => {
+  describe('DRIFT_WEIGHTS', () => {
+    it('has correct weights', () => {
+      expect(DRIFT_WEIGHTS.high).toBe(20);
+      expect(DRIFT_WEIGHTS.medium).toBe(10);
+      expect(DRIFT_WEIGHTS.low).toBe(5);
+    });
+  });
+
+  describe('calculateDriftScore', () => {
+    it('returns 100 for no drift items', () => {
+      expect(calculateDriftScore([])).toBe(100);
+    });
+    it('deducts by impact weight', () => {
+      const items: DriftItem[] = [
+        { type: 'skipped', description: 'x', impact: 'medium', rationale: 'r' },
+      ];
+      expect(calculateDriftScore(items)).toBe(90);
+    });
+    it('accumulates multiple items', () => {
+      const items: DriftItem[] = [
+        { type: 'skipped', description: 'x', impact: 'high', rationale: 'r' },
+        { type: 'modified', description: 'y', impact: 'low', rationale: 'r' },
+      ];
+      expect(calculateDriftScore(items)).toBe(75);
+    });
+    it('floors at 0', () => {
+      const items: DriftItem[] = Array.from({ length: 10 }, () => ({
+        type: 'skipped' as const, description: 'x', impact: 'high' as const, rationale: 'r',
+      }));
+      expect(calculateDriftScore(items)).toBe(0);
+    });
+  });
+
+  describe('computeExecutionSummary', () => {
+    it('returns zeros for empty tasks', () => {
+      const summary = computeExecutionSummary([]);
+      expect(summary.totalDurationMs).toBe(0);
+      expect(summary.tasksCompleted).toBe(0);
+      expect(summary.avgTaskDurationMs).toBe(0);
+    });
+    it('counts task statuses correctly', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: '', description: '', status: 'completed', updatedAt: 0 },
+        { id: 't2', title: '', description: '', status: 'skipped', updatedAt: 0 },
+        { id: 't3', title: '', description: '', status: 'failed', updatedAt: 0 },
+        { id: 't4', title: '', description: '', status: 'pending', updatedAt: 0 },
+      ];
+      const summary = computeExecutionSummary(tasks);
+      expect(summary.tasksCompleted).toBe(1);
+      expect(summary.tasksSkipped).toBe(1);
+      expect(summary.tasksFailed).toBe(1);
+    });
+    it('computes average duration from tasks with metrics', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: '', description: '', status: 'completed', updatedAt: 0, metrics: { durationMs: 100 } },
+        { id: 't2', title: '', description: '', status: 'completed', updatedAt: 0, metrics: { durationMs: 200 } },
+        { id: 't3', title: '', description: '', status: 'completed', updatedAt: 0 }, // no metrics
+      ];
+      const summary = computeExecutionSummary(tasks);
+      expect(summary.totalDurationMs).toBe(300);
+      expect(summary.avgTaskDurationMs).toBe(150);
+    });
+  });
+
+  describe('buildReconciliationReport', () => {
+    it('builds a report with accuracy score', () => {
+      const report = buildReconciliationReport('plan-1', {
+        actualOutcome: 'Done',
+        driftItems: [{ type: 'skipped', description: 'x', impact: 'low', rationale: 'r' }],
+      });
+      expect(report.planId).toBe('plan-1');
+      expect(report.accuracy).toBe(95);
+      expect(report.driftItems).toHaveLength(1);
+      expect(report.summary).toBe('Done');
+      expect(report.reconciledAt).toBeGreaterThan(0);
+    });
+    it('defaults to empty drift items', () => {
+      const report = buildReconciliationReport('plan-2', { actualOutcome: 'OK' });
+      expect(report.accuracy).toBe(100);
+      expect(report.driftItems).toEqual([]);
+    });
+  });
+
+  describe('buildAutoReconcileInput', () => {
+    it('allows auto-reconcile when all tasks completed', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: 'A', description: '', status: 'completed', updatedAt: 0 },
+        { id: 't2', title: 'B', description: '', status: 'completed', updatedAt: 0 },
+      ];
+      const result = buildAutoReconcileInput(tasks);
+      expect(result.canAutoReconcile).toBe(true);
+      expect(result.input?.actualOutcome).toContain('2/2 tasks completed');
+    });
+    it('rejects when tasks are in progress', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: 'A', description: '', status: 'in_progress', updatedAt: 0 },
+      ];
+      expect(buildAutoReconcileInput(tasks).canAutoReconcile).toBe(false);
+    });
+    it('rejects when too many pending/failed tasks', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: 'A', description: '', status: 'failed', updatedAt: 0 },
+        { id: 't2', title: 'B', description: '', status: 'failed', updatedAt: 0 },
+        { id: 't3', title: 'C', description: '', status: 'pending', updatedAt: 0 },
+      ];
+      expect(buildAutoReconcileInput(tasks).canAutoReconcile).toBe(false);
+    });
+    it('generates drift items for skipped and failed tasks', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: 'A', description: '', status: 'completed', updatedAt: 0 },
+        { id: 't2', title: 'B', description: '', status: 'skipped', updatedAt: 0 },
+        { id: 't3', title: 'C', description: '', status: 'failed', updatedAt: 0 },
+      ];
+      const result = buildAutoReconcileInput(tasks);
+      expect(result.canAutoReconcile).toBe(true);
+      expect(result.input?.driftItems).toHaveLength(2);
+      expect(result.input?.driftItems?.[0].type).toBe('skipped');
+      expect(result.input?.driftItems?.[1].type).toBe('modified');
+    });
+    it('generates drift items for pending tasks', () => {
+      const tasks: PlanTask[] = [
+        { id: 't1', title: 'Done', description: '', status: 'completed', updatedAt: 0 },
+        { id: 't2', title: 'Not started', description: '', status: 'pending', updatedAt: 0 },
+      ];
+      const result = buildAutoReconcileInput(tasks);
+      expect(result.canAutoReconcile).toBe(true);
+      expect(result.input?.driftItems?.[0].impact).toBe('low');
+    });
+  });
+});

package/src/planning/reconciliation-engine.ts

@@ -0,0 +1,162 @@
+/**
+ * Reconciliation engine — drift detection, accuracy scoring, and auto-reconciliation.
+ * Extracted from planner.ts. All functions are pure (no persistence side-effects).
+ */
+
+import type {
+  DriftItem,
+  ReconciliationReport,
+  ExecutionSummary,
+  PlanTask,
+} from './planner-types.js';
+
+// ─── Drift Scoring ───────────────────────────────────────────────
+
+/**
+ * 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: Record<DriftItem['impact'], number> = {
+  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: ReadonlyArray<DriftItem>): number {
+  let deductions = 0;
+  for (const item of items) {
+    deductions += DRIFT_WEIGHTS[item.impact];
+  }
+  return Math.max(0, 100 - deductions);
+}
+
+// ─── Execution Summary ───────────────────────────────────────────
+
+/**
+ * Compute aggregate execution summary from per-task metrics.
+ * Pure function — does not mutate state.
+ */
+export function computeExecutionSummary(tasks: ReadonlyArray<PlanTask>): ExecutionSummary {
+  let totalDurationMs = 0;
+  let tasksCompleted = 0;
+  let tasksSkipped = 0;
+  let tasksFailed = 0;
+  let tasksWithDuration = 0;
+
+  for (const task of 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,
+  };
+}
+
+// ─── Reconciliation ──────────────────────────────────────────────
+
+export interface ReconcileInput {
+  actualOutcome: string;
+  driftItems?: DriftItem[];
+  /** Who initiated the reconciliation. */
+  reconciledBy?: 'human' | 'auto';
+}
+
+/**
+ * Build a reconciliation report from drift items and outcome.
+ * Pure function — returns report without mutating state.
+ */
+export function buildReconciliationReport(
+  planId: string,
+  input: ReconcileInput,
+): ReconciliationReport {
+  const driftItems = input.driftItems ?? [];
+  const accuracy = calculateDriftScore(driftItems);
+
+  return {
+    planId,
+    accuracy,
+    driftItems,
+    summary: input.actualOutcome,
+    reconciledAt: Date.now(),
+  };
+}
+
+// ─── Auto-Reconciliation ────────────────────────────────────────
+
+export interface AutoReconcileResult {
+  canAutoReconcile: boolean;
+  input?: ReconcileInput;
+}
+
+/**
+ * Determine if a plan can be auto-reconciled and build the reconciliation input.
+ * Returns null input if auto-reconciliation is not possible.
+ *
+ * Rules:
+ * - Can't auto-reconcile if tasks are still in progress
+ * - Can't auto-reconcile if too many non-completed tasks (>2 pending + failed)
+ */
+export function buildAutoReconcileInput(tasks: ReadonlyArray<PlanTask>): AutoReconcileResult {
+  const completed = tasks.filter((t) => t.status === 'completed').length;
+  const skipped = tasks.filter((t) => t.status === 'skipped').length;
+  const failed = tasks.filter((t) => t.status === 'failed').length;
+  const pending = tasks.filter((t) => t.status === 'pending').length;
+  const inProgress = tasks.filter((t) => t.status === 'in_progress').length;
+
+  if (inProgress > 0) return { canAutoReconcile: false };
+  if (pending + failed > 2) return { canAutoReconcile: false };
+
+  const driftItems: DriftItem[] = [];
+
+  for (const task of 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 {
+    canAutoReconcile: true,
+    input: {
+      actualOutcome: `Auto-reconciled: ${completed}/${tasks.length} tasks completed, ${skipped} skipped, ${failed} failed`,
+      driftItems,
+      reconciledBy: 'auto',
+    },
+  };
+}