@soleri/core 2.12.0 → 8.0.0

package/src/planning/evidence-collector.ts

@@ -0,0 +1,247 @@
+/**
+ * Evidence Collector — cross-references plan tasks against git reality.
+ *
+ * Runs `git diff` to find what actually changed, then matches file changes
+ * against planned tasks to produce an evidence-based drift report.
+ */
+
+import { execFileSync } from 'node:child_process';
+import type { Plan, PlanTask } from './planner.js';
+
+export interface FileChange {
+  path: string;
+  status: 'added' | 'modified' | 'deleted' | 'renamed';
+}
+
+export interface GitTaskEvidence {
+  taskId: string;
+  taskTitle: string;
+  plannedStatus: string;
+  matchedFiles: FileChange[];
+  verdict: 'DONE' | 'PARTIAL' | 'MISSING' | 'SKIPPED';
+}
+
+export interface UnplannedChange {
+  file: FileChange;
+  possibleReason: string;
+}
+
+export interface EvidenceReport {
+  planId: string;
+  planObjective: string;
+  accuracy: number;
+  evidenceSources: string[];
+  taskEvidence: GitTaskEvidence[];
+  unplannedChanges: UnplannedChange[];
+  missingWork: GitTaskEvidence[];
+  summary: string;
+}
+
+/**
+ * Collect git diff evidence for a plan.
+ *
+ * @param plan - The plan to verify
+ * @param projectPath - Project root (must be a git repo)
+ * @param baseBranch - Compare against this branch (default: 'main')
+ */
+export function collectGitEvidence(
+  plan: Plan,
+  projectPath: string,
+  baseBranch: string = 'main',
+): EvidenceReport {
+  const fileChanges = getGitDiff(projectPath, baseBranch);
+  const taskEvidence: GitTaskEvidence[] = [];
+  const matchedFiles = new Set<string>();
+
+  for (const task of plan.tasks) {
+    const matches = findMatchingFiles(task, fileChanges);
+    for (const m of matches) matchedFiles.add(m.path);
+
+    const verdict = determineVerdict(task, matches);
+    taskEvidence.push({
+      taskId: task.id,
+      taskTitle: task.title,
+      plannedStatus: task.status,
+      matchedFiles: matches,
+      verdict,
+    });
+  }
+
+  const unplannedChanges: UnplannedChange[] = fileChanges
+    .filter((f) => !matchedFiles.has(f.path))
+    .map((f) => ({
+      file: f,
+      possibleReason: inferReason(f),
+    }));
+
+  const missingWork = taskEvidence.filter((te) => te.verdict === 'MISSING');
+
+  const totalTasks = taskEvidence.length;
+  const doneTasks = taskEvidence.filter((te) => te.verdict === 'DONE').length;
+  const partialTasks = taskEvidence.filter((te) => te.verdict === 'PARTIAL').length;
+  const skippedTasks = taskEvidence.filter((te) => te.verdict === 'SKIPPED').length;
+  const accuracy =
+    totalTasks > 0
+      ? Math.round(((doneTasks + partialTasks * 0.5 + skippedTasks * 0.25) / totalTasks) * 100)
+      : 100;
+
+  const summary = buildSummary(
+    totalTasks,
+    doneTasks,
+    partialTasks,
+    missingWork.length,
+    unplannedChanges.length,
+  );
+
+  return {
+    planId: plan.id,
+    planObjective: plan.objective,
+    accuracy,
+    evidenceSources: ['git'],
+    taskEvidence,
+    unplannedChanges,
+    missingWork,
+    summary,
+  };
+}
+
+function getGitDiff(projectPath: string, baseBranch: string): FileChange[] {
+  try {
+    const currentBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+
+    const diffTarget = currentBranch === baseBranch ? 'HEAD~10' : baseBranch;
+
+    let output: string;
+    try {
+      output = execFileSync('git', ['diff', '--name-status', `${diffTarget}...HEAD`], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+      });
+    } catch {
+      output = execFileSync('git', ['diff', '--name-status', 'HEAD~5'], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+      });
+    }
+
+    return output
+      .trim()
+      .split('\n')
+      .filter((line) => line.length > 0)
+      .map(parseGitDiffLine)
+      .filter((f): f is FileChange => f !== null);
+  } catch {
+    return [];
+  }
+}
+
+function parseGitDiffLine(line: string): FileChange | null {
+  const match = line.match(/^([AMDRC])\d*\t(.+?)(?:\t(.+))?$/);
+  if (!match) return null;
+
+  const statusChar = match[1];
+  const path = match[3] ?? match[2];
+
+  const statusMap: Record<string, FileChange['status']> = {
+    A: 'added',
+    M: 'modified',
+    D: 'deleted',
+    R: 'renamed',
+    C: 'added',
+  };
+
+  return { path, status: statusMap[statusChar] ?? 'modified' };
+}
+
+function findMatchingFiles(task: PlanTask, files: FileChange[]): FileChange[] {
+  const keywords = extractKeywords(task.title + ' ' + task.description);
+  if (keywords.length === 0) return [];
+
+  return files.filter((f) => {
+    const pathLower = f.path.toLowerCase();
+    return keywords.some((kw) => pathLower.includes(kw));
+  });
+}
+
+function extractKeywords(text: string): string[] {
+  const stopWords = new Set([
+    'the',
+    'and',
+    'for',
+    'with',
+    'that',
+    'this',
+    'from',
+    'into',
+    'add',
+    'create',
+    'implement',
+    'update',
+    'fix',
+    'remove',
+    'delete',
+    'new',
+    'use',
+    'should',
+    'must',
+    'will',
+    'can',
+    'all',
+    'each',
+    'when',
+    'not',
+    'are',
+    'has',
+    'have',
+    'been',
+    'was',
+  ]);
+
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s\-_/.]/g, ' ')
+    .split(/[\s\-_/]+/)
+    .filter((w) => w.length >= 3 && !stopWords.has(w));
+
+  return [...new Set(words)];
+}
+
+function determineVerdict(task: PlanTask, matches: FileChange[]): GitTaskEvidence['verdict'] {
+  if (task.status === 'skipped') return 'SKIPPED';
+  if (matches.length === 0) return 'MISSING';
+  if (task.status === 'completed') return 'DONE';
+  if (matches.length > 0) return 'PARTIAL';
+  return 'MISSING';
+}
+
+function inferReason(file: FileChange): string {
+  const path = file.path.toLowerCase();
+  if (path.includes('index.') || path.includes('barrel')) return 'likely re-export update';
+  if (path.includes('config') || path.includes('.env')) return 'configuration change';
+  if (path.includes('test') || path.includes('spec')) return 'test file';
+  if (path.includes('package.json') || path.includes('lock')) return 'dependency update';
+  if (path.includes('readme') || path.includes('.md')) return 'documentation';
+  if (path.includes('types') || path.includes('.d.ts')) return 'type definition update';
+  return 'unplanned scope';
+}
+
+function buildSummary(
+  total: number,
+  done: number,
+  partial: number,
+  missing: number,
+  unplanned: number,
+): string {
+  const parts: string[] = [];
+  parts.push(`${done}/${total} tasks verified by git evidence`);
+  if (partial > 0) parts.push(`${partial} partially done`);
+  if (missing > 0) parts.push(`${missing} with no file evidence`);
+  if (unplanned > 0) parts.push(`${unplanned} unplanned file changes`);
+  return parts.join(', ');
+}

package/src/planning/planner.ts

@@ -385,6 +385,17 @@ export class Planner {
     return [...this.store.plans];
   }
 
+  /**
+   * Permanently remove a plan by ID. Returns true if found and removed.
+   */
+  remove(planId: string): boolean {
+    const idx = this.store.plans.findIndex((p) => p.id === planId);
+    if (idx < 0) return false;
+    this.store.plans.splice(idx, 1);
+    this.save();
+    return true;
+  }
+
   /**
    * Transition a plan to a new status using the typed FSM.
    * Validates that the transition is allowed before applying it.

package/src/playbooks/generic/onboarding.ts

@@ -0,0 +1,79 @@
+/**
+ * Generic Playbook: New User Onboarding
+ *
+ * Guides first-time users through the agent's capabilities.
+ * Activates when vault is empty or user asks "what can you do?"
+ */
+
+import type { PlaybookDefinition } from '../playbook-types.js';
+
+export const onboardingPlaybook: PlaybookDefinition = {
+  id: 'generic-onboarding',
+  tier: 'generic',
+  title: 'New User Onboarding',
+  trigger:
+    'Use when the user is new (vault is empty, no session history) or when they ask "what can you do?", "how do I use you?", "help", "getting started", "what is this?", "features", "capabilities".',
+  description:
+    "Walks a new user through the agent's capabilities in a friendly, progressive way. Shows what's available, demonstrates the 5-step rhythm with a quick example, and suggests next actions based on the user's goals.",
+  steps: `1. INTRODUCE — Explain who you are
+   - Your name, role, and current domains (from activation context)
+   - What makes you different: you learn, remember, and improve
+   - Your installed packs and what they enable
+
+2. SHOW CAPABILITIES — Walk through what you can do
+   - Vault: "I search my knowledge base before every decision"
+   - Planning: "I create structured plans with approval gates"
+   - Brain: "I learn from past sessions and recommend patterns"
+   - Memory: "I remember across conversations and projects"
+   - Domains: list each domain and what it covers
+   - If packs are missing: "You can add more capabilities with soleri pack install"
+
+3. DEMONSTRATE — Quick live example
+   - Run a vault search on something relevant to the user's project
+   - Show the result: "This is what I already know about your domain"
+   - If vault is empty: "Let's capture our first pattern together"
+
+4. ORIENT — Help the user find their starting point
+   - Ask: "What are you working on?" or "What problem are you trying to solve?"
+   - Based on their answer, suggest the right workflow:
+     - Building something new → "Let me create a plan"
+     - Fixing a bug → "Let me search for known patterns"
+     - Learning the codebase → "Let me explore and capture what I find"
+     - Setting up → "Let me run a health check: op:admin_health"
+
+5. HANDOFF — Set expectations
+   - "From now on, just describe what you need — I'll figure out the workflow"
+   - "If you want me to remember something, say 'capture this' or 'remember'"
+   - "Say 'what do you know about X?' to search my vault anytime"`,
+  expectedOutcome:
+    'User understands what the agent can do, has seen a live demonstration, and has a clear first task to work on. The agent transitions from onboarding to productive work.',
+  category: 'methodology',
+  tags: ['onboarding', 'getting-started', 'help', 'capabilities', 'generic'],
+  matchIntents: ['PLAN'],
+  matchKeywords: [
+    'what can you do',
+    'help',
+    'getting started',
+    'how do I use',
+    'features',
+    'capabilities',
+    'onboarding',
+    'introduce',
+    'what is this',
+    'new here',
+    'first time',
+  ],
+  gates: [],
+  taskTemplates: [],
+  toolInjections: [
+    'op:activate — show current capabilities and system status',
+    'op:admin_health — demonstrate health check',
+    'op:search_intelligent — live demo of vault search',
+    'op:brain_recommend — show brain recommendations',
+  ],
+  verificationCriteria: [
+    'User received a clear overview of agent capabilities',
+    'User saw a live demonstration of at least one capability',
+    'User expressed a first task or area of interest',
+  ],
+};

package/src/playbooks/playbook-registry.ts

@@ -23,6 +23,7 @@ import { codeReviewPlaybook } from './generic/code-review.js';
 import { subagentExecutionPlaybook } from './generic/subagent-execution.js';
 import { systematicDebuggingPlaybook } from './generic/systematic-debugging.js';
 import { verificationPlaybook } from './generic/verification.js';
+import { onboardingPlaybook } from './generic/onboarding.js';
 
 // =============================================================================
 // SCORING WEIGHTS
@@ -49,6 +50,7 @@ const BUILTIN_PLAYBOOKS: PlaybookDefinition[] = [
   subagentExecutionPlaybook,
   systematicDebuggingPlaybook,
   verificationPlaybook,
+  onboardingPlaybook,
 ];
 
 /**

package/src/queue/job-queue.ts

@@ -0,0 +1,281 @@
+/**
+ * Job Queue — SQLite-backed FIFO queue with DAG dependencies and retries.
+ *
+ * Generic infrastructure — not curator-specific. Reusable by agency, intake, etc.
+ *
+ * Features:
+ * - Persistent jobs (survive process restarts)
+ * - DAG dependency resolution (job B waits for job A)
+ * - Pipeline grouping (group related jobs under one ID)
+ * - Configurable retries with max limit
+ * - Status tracking: pending → running → completed | failed
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { PersistenceProvider } from '../persistence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type JobStatus = 'pending' | 'running' | 'completed' | 'failed';
+
+export interface Job {
+  id: string;
+  type: string;
+  status: JobStatus;
+  entryId: string | null;
+  payload: Record<string, unknown>;
+  dependsOn: string[];
+  pipelineId: string | null;
+  retryCount: number;
+  maxRetries: number;
+  result: unknown | null;
+  error: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+
+export interface JobQueueStats {
+  pending: number;
+  running: number;
+  completed: number;
+  failed: number;
+  total: number;
+}
+
+export interface EnqueueOptions {
+  entryId?: string;
+  payload?: Record<string, unknown>;
+  dependsOn?: string[];
+  pipelineId?: string;
+  maxRetries?: number;
+}
+
+// ─── Class ───────────────────────────────────────────────────────────
+
+export class JobQueue {
+  private provider: PersistenceProvider;
+
+  constructor(provider: PersistenceProvider) {
+    this.provider = provider;
+    this.initializeTable();
+  }
+
+  private initializeTable(): void {
+    this.provider.execSql(`
+      CREATE TABLE IF NOT EXISTS job_queue (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        entry_id TEXT,
+        payload TEXT DEFAULT '{}',
+        depends_on TEXT DEFAULT '[]',
+        pipeline_id TEXT,
+        retry_count INTEGER DEFAULT 0,
+        max_retries INTEGER DEFAULT 3,
+        result TEXT,
+        error TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        started_at TEXT,
+        completed_at TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_job_queue_status ON job_queue(status);
+      CREATE INDEX IF NOT EXISTS idx_job_queue_pipeline ON job_queue(pipeline_id);
+    `);
+  }
+
+  /**
+   * Enqueue a new job. Returns the job ID.
+   */
+  enqueue(type: string, options?: EnqueueOptions): string {
+    const id = randomUUID().slice(0, 12);
+    this.provider.run(
+      `INSERT INTO job_queue (id, type, entry_id, payload, depends_on, pipeline_id, max_retries)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        type,
+        options?.entryId ?? null,
+        JSON.stringify(options?.payload ?? {}),
+        JSON.stringify(options?.dependsOn ?? []),
+        options?.pipelineId ?? null,
+        options?.maxRetries ?? 3,
+      ],
+    );
+    return id;
+  }
+
+  /**
+   * Dequeue the oldest pending job with all dependencies completed.
+   * Marks it as running. Returns null if no ready jobs.
+   */
+  dequeue(): Job | null {
+    const ready = this.dequeueReady(1);
+    return ready.length > 0 ? ready[0] : null;
+  }
+
+  /**
+   * Dequeue up to `limit` pending jobs whose dependencies are all completed.
+   */
+  dequeueReady(limit: number = 10): Job[] {
+    const rows = this.provider.all<JobRow>(
+      "SELECT * FROM job_queue WHERE status = 'pending' ORDER BY created_at ASC LIMIT ?",
+      [limit * 3], // Over-fetch to filter by deps
+    );
+
+    const ready: Job[] = [];
+    for (const row of rows) {
+      if (ready.length >= limit) break;
+      const deps = JSON.parse(row.depends_on) as string[];
+      if (deps.length === 0 || this.allDepsCompleted(deps)) {
+        this.provider.run(
+          "UPDATE job_queue SET status = 'running', started_at = datetime('now') WHERE id = ?",
+          [row.id],
+        );
+        const job = rowToJob(row);
+        job.status = 'running';
+        ready.push(job);
+      }
+    }
+    return ready;
+  }
+
+  /**
+   * Mark a job as completed with an optional result.
+   */
+  complete(jobId: string, result?: unknown): void {
+    this.provider.run(
+      "UPDATE job_queue SET status = 'completed', completed_at = datetime('now'), result = ? WHERE id = ?",
+      [result !== undefined ? JSON.stringify(result) : null, jobId],
+    );
+  }
+
+  /**
+   * Mark a job as failed with an error message.
+   */
+  fail(jobId: string, error: string): void {
+    this.provider.run(
+      "UPDATE job_queue SET status = 'failed', completed_at = datetime('now'), error = ? WHERE id = ?",
+      [error, jobId],
+    );
+  }
+
+  /**
+   * Retry a failed job (resets to pending). Returns false if max retries exceeded.
+   */
+  retry(jobId: string): boolean {
+    const row = this.provider.get<JobRow>('SELECT * FROM job_queue WHERE id = ?', [jobId]);
+    if (!row) return false;
+    if (row.retry_count >= row.max_retries) return false;
+
+    this.provider.run(
+      "UPDATE job_queue SET status = 'pending', retry_count = retry_count + 1, error = NULL, started_at = NULL, completed_at = NULL WHERE id = ?",
+      [jobId],
+    );
+    return true;
+  }
+
+  /**
+   * Get queue statistics.
+   */
+  getStats(): JobQueueStats {
+    const rows = this.provider.all<{ status: string; count: number }>(
+      'SELECT status, COUNT(*) as count FROM job_queue GROUP BY status',
+    );
+    const byStatus: Record<string, number> = {};
+    let total = 0;
+    for (const row of rows) {
+      byStatus[row.status] = row.count;
+      total += row.count;
+    }
+    return {
+      pending: byStatus['pending'] ?? 0,
+      running: byStatus['running'] ?? 0,
+      completed: byStatus['completed'] ?? 0,
+      failed: byStatus['failed'] ?? 0,
+      total,
+    };
+  }
+
+  /**
+   * Get all jobs for a pipeline.
+   */
+  getByPipeline(pipelineId: string): Job[] {
+    const rows = this.provider.all<JobRow>(
+      'SELECT * FROM job_queue WHERE pipeline_id = ? ORDER BY created_at ASC',
+      [pipelineId],
+    );
+    return rows.map(rowToJob);
+  }
+
+  /**
+   * Get a single job by ID.
+   */
+  get(jobId: string): Job | null {
+    const row = this.provider.get<JobRow>('SELECT * FROM job_queue WHERE id = ?', [jobId]);
+    return row ? rowToJob(row) : null;
+  }
+
+  /**
+   * Purge completed/failed jobs older than N days.
+   */
+  purge(olderThanDays: number = 30): number {
+    const result = this.provider.run(
+      "DELETE FROM job_queue WHERE status IN ('completed', 'failed') AND completed_at < datetime('now', ?)",
+      [`-${olderThanDays} days`],
+    );
+    return result.changes;
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────
+
+  private allDepsCompleted(deps: string[]): boolean {
+    for (const depId of deps) {
+      const row = this.provider.get<{ status: string }>(
+        'SELECT status FROM job_queue WHERE id = ?',
+        [depId],
+      );
+      if (!row || row.status !== 'completed') return false;
+    }
+    return true;
+  }
+}
+
+// ─── Row Types ───────────────────────────────────────────────────────
+
+interface JobRow {
+  id: string;
+  type: string;
+  status: string;
+  entry_id: string | null;
+  payload: string;
+  depends_on: string;
+  pipeline_id: string | null;
+  retry_count: number;
+  max_retries: number;
+  result: string | null;
+  error: string | null;
+  created_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+}
+
+function rowToJob(row: JobRow): Job {
+  return {
+    id: row.id,
+    type: row.type,
+    status: row.status as JobStatus,
+    entryId: row.entry_id,
+    payload: JSON.parse(row.payload) as Record<string, unknown>,
+    dependsOn: JSON.parse(row.depends_on) as string[],
+    pipelineId: row.pipeline_id,
+    retryCount: row.retry_count,
+    maxRetries: row.max_retries,
+    result: row.result ? JSON.parse(row.result) : null,
+    error: row.error,
+    createdAt: row.created_at,
+    startedAt: row.started_at,
+    completedAt: row.completed_at,
+  };
+}