@soleri/core 2.4.0 → 2.6.0

package/src/persistence/sqlite-provider.ts

@@ -0,0 +1,115 @@
+/**
+ * SQLite persistence provider backed by better-sqlite3.
+ *
+ * Supports both positional (array) and named (object) parameters.
+ * Exposes getDatabase() for backward-compat consumers that need the raw db.
+ */
+
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  FtsSearchOptions,
+} from './types.js';
+
+export class SQLitePersistenceProvider implements PersistenceProvider {
+  readonly backend = 'sqlite' as const;
+  private db: Database.Database;
+
+  constructor(path: string = ':memory:') {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path);
+    if (path !== ':memory:') {
+      this.db.pragma('cache_size = -64000'); // 64MB
+      this.db.pragma('temp_store = MEMORY');
+      this.db.pragma('mmap_size = 268435456'); // 256MB
+    }
+  }
+
+  execSql(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  run(sql: string, params?: PersistenceParams): RunResult {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.run();
+    if (Array.isArray(params)) return stmt.run(...params);
+    return stmt.run(params);
+  }
+
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.get() as T | undefined;
+    if (Array.isArray(params)) return stmt.get(...params) as T | undefined;
+    return stmt.get(params) as T | undefined;
+  }
+
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.all() as T[];
+    if (Array.isArray(params)) return stmt.all(...params) as T[];
+    return stmt.all(params) as T[];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  ftsSearch<T = Record<string, unknown>>(
+    table: string,
+    query: string,
+    options?: FtsSearchOptions,
+  ): T[] {
+    const ftsTable = `${table}_fts`;
+    const cols = options?.columns?.length ? options.columns.join(', ') : `${table}.*`;
+    const orderBy = options?.orderByRank !== false ? `ORDER BY rank` : '';
+    const limit = options?.limit ? `LIMIT ${options.limit}` : '';
+    const offset = options?.offset ? `OFFSET ${options.offset}` : '';
+
+    const filterClauses: string[] = [];
+    const filterParams: unknown[] = [query];
+
+    if (options?.filters) {
+      for (const [key, value] of Object.entries(options.filters)) {
+        filterClauses.push(`${table}.${key} = ?`);
+        filterParams.push(value);
+      }
+    }
+
+    const filterSql = filterClauses.length ? `AND ${filterClauses.join(' AND ')}` : '';
+
+    const sql = `SELECT ${cols} FROM ${ftsTable} JOIN ${table} ON ${table}.rowid = ${ftsTable}.rowid WHERE ${ftsTable} MATCH ? ${filterSql} ${orderBy} ${limit} ${offset}`;
+
+    return this.all<T>(sql, filterParams);
+  }
+
+  ftsRebuild(table: string): void {
+    const ftsTable = `${table}_fts`;
+    try {
+      this.execSql(`INSERT INTO ${ftsTable}(${ftsTable}) VALUES('rebuild')`);
+    } catch {
+      // Graceful degradation: FTS table may not exist
+    }
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Escape hatch: get the raw better-sqlite3 Database.
+   * Used by modules that need direct db access (ProjectRegistry, BrainIntelligence, etc.).
+   * @deprecated Use provider methods instead.
+   */
+  getDatabase(): Database.Database {
+    if (process.env.NODE_ENV !== 'test' && process.env.VITEST !== 'true') {
+      console.warn(
+        'SQLitePersistenceProvider.getDatabase() is deprecated. Use provider methods instead.',
+      );
+    }
+    return this.db;
+  }
+}

package/src/persistence/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Abstract persistence layer.
+ *
+ * Decouples Vault (and future modules) from any specific database engine.
+ * The default implementation is SQLitePersistenceProvider (better-sqlite3).
+ */
+
+export type PersistenceParams = unknown[] | Record<string, unknown>;
+
+export interface RunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+/**
+ * Minimal database provider interface.
+ *
+ * Supports both positional (`?`) and named (`@param`) parameter styles.
+ * Implementations must handle both array and object params.
+ */
+export interface PersistenceProvider {
+  /** Run raw SQL (DDL, multi-statement). No return value. */
+  execSql(sql: string): void;
+
+  /** Run a parameterized statement (INSERT, UPDATE, DELETE). */
+  run(sql: string, params?: PersistenceParams): RunResult;
+
+  /** Get a single row. Returns undefined if no match. */
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined;
+
+  /** Get all matching rows. */
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[];
+
+  /** Run a function inside a transaction. Commits on success, rolls back on error. */
+  transaction<T>(fn: () => T): T;
+
+  /** Identifies the backend engine. */
+  readonly backend: 'sqlite' | 'postgres';
+
+  /** Full-text search abstraction. */
+  ftsSearch<T = Record<string, unknown>>(
+    table: string,
+    query: string,
+    options?: FtsSearchOptions,
+  ): T[];
+
+  /** Rebuild FTS index for a table. */
+  ftsRebuild(table: string): void;
+
+  /** Close the connection. */
+  close(): void;
+}
+
+export interface PersistenceConfig {
+  type: 'sqlite' | 'postgres';
+  path: string;
+  /** PostgreSQL connection string. */
+  connectionString?: string;
+  /** PostgreSQL pool size. */
+  poolSize?: number;
+}
+
+export interface FtsSearchOptions {
+  /** Columns to search (default: all FTS columns). */
+  columns?: string[];
+  /** Max results. */
+  limit?: number;
+  /** Skip N results. */
+  offset?: number;
+  /** Additional WHERE conditions on the base table. */
+  filters?: Record<string, unknown>;
+  /** Order by FTS relevance rank (default: true). */
+  orderByRank?: boolean;
+}

package/src/planning/gap-analysis.ts

@@ -1,17 +1,23 @@
 /**
- * 6-pass gap analysis engine for plan grading.
- * Ported from Salvador MCP's plan-gap-content.ts / plan-gap-technical.ts.
+ * Gap analysis engine for plan grading.
+ * Ported from Salvador MCP's plan-gap-content.ts / plan-gap-technical.ts /
+ * plan-gap-domain.ts / plan-gap-antipattern.ts.
  *
- * Passes:
+ * 6 built-in passes (always run):
  *   1. Structure     — required fields present and sufficiently long
  *   2. Completeness  — measurable objectives, decision rationale, scope exclusions
  *   3. Feasibility   — overly broad scope, missing dependency awareness
  *   4. Risk          — breaking changes without mitigation, missing verification
  *   5. Clarity       — ambiguous language, vague criteria
  *   6. Semantic Quality — generic objectives, shallow rationale, non-concrete approach
+ *
+ * Opt-in pass factories (registered via customPasses):
+ *   - createToolFeasibilityPass  — validates tool_chain entries and ordering
+ *   - createFlowAlignmentPass    — validates flow and target_mode against registries
+ *   - createAntiPatternPass      — detects content anti-patterns and vague criteria
  */
 
-import type { Plan } from './planner.js';
+import type { Plan, PlanDecision } from './planner.js';
 import type { PlanGap, GapSeverity, GapCategory } from './gap-types.js';
 import {
   generateGapId,
@@ -46,6 +52,16 @@ 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). */
+function decisionText(d: string | PlanDecision): string {
+  return typeof d === 'string' ? d : `${d.decision} ${d.rationale}`;
+}
+
+/** Combine all decisions into a single text blob. */
+function decisionsText(plan: Plan): string {
+  return plan.decisions.map(decisionText).join(' ');
+}
+
 /** Check if text contains any of the given patterns (case-insensitive). */
 function containsAny(text: string, patterns: string[]): boolean {
   const lower = text.toLowerCase();
@@ -118,7 +134,16 @@ const METRIC_PATTERNS = [
   /benchmark/i,
 ];
 
-const EXCLUSION_KEYWORDS = ['not', 'exclude', 'outside', 'beyond', 'limit', 'except', 'won\'t', 'will not'];
+const EXCLUSION_KEYWORDS = [
+  'not',
+  'exclude',
+  'outside',
+  'beyond',
+  'limit',
+  'except',
+  "won't",
+  'will not',
+];
 
 function analyzeCompleteness(plan: Plan): PlanGap[] {
   const gaps: PlanGap[] = [];
@@ -141,12 +166,13 @@ function analyzeCompleteness(plan: Plan): PlanGap[] {
   if (plan.decisions.length > 0) {
     for (let i = 0; i < plan.decisions.length; i++) {
       const d = plan.decisions[i];
-      if (d.trim().length < MIN_DECISION_LENGTH) {
+      const text = decisionText(d);
+      if (text.trim().length < MIN_DECISION_LENGTH) {
         gaps.push(
           gap(
             'major',
             'completeness',
-            `Decision ${i + 1} is too short (${d.trim().length} chars) — lacks rationale.`,
+            `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',
@@ -185,7 +211,14 @@ const OVERLY_BROAD_PATTERNS = [
   'rewrite everything',
 ];
 
-const DEPENDENCY_KEYWORDS = ['depends', 'dependency', 'prerequisite', 'requires', 'blocked', 'before'];
+const DEPENDENCY_KEYWORDS = [
+  'depends',
+  'dependency',
+  'prerequisite',
+  'requires',
+  'blocked',
+  'before',
+];
 
 function analyzeFeasibility(plan: Plan): PlanGap[] {
   const gaps: PlanGap[] = [];
@@ -251,14 +284,26 @@ const MITIGATION_KEYWORDS = [
   'blue-green',
 ];
 
-const VERIFICATION_KEYWORDS = ['test', 'verify', 'validate', 'check', 'assert', 'confirm', 'spec', 'coverage'];
+const VERIFICATION_KEYWORDS = [
+  'test',
+  'verify',
+  'validate',
+  'check',
+  'assert',
+  'confirm',
+  'spec',
+  'coverage',
+];
 
 function analyzeRisk(plan: Plan): PlanGap[] {
   const gaps: PlanGap[] = [];
-  const allText = `${plan.objective} ${plan.scope} ${taskText(plan)} ${plan.decisions.join(' ')}`;
+  const allText = `${plan.objective} ${plan.scope} ${taskText(plan)} ${decisionsText(plan)}`;
 
   // Breaking changes without mitigation
-  if (containsAny(allText, BREAKING_CHANGE_KEYWORDS) && !containsAny(allText, MITIGATION_KEYWORDS)) {
+  if (
+    containsAny(allText, BREAKING_CHANGE_KEYWORDS) &&
+    !containsAny(allText, MITIGATION_KEYWORDS)
+  ) {
     gaps.push(
       gap(
         'major',
@@ -310,7 +355,7 @@ const AMBIGUOUS_WORDS = [
 
 function analyzeClarity(plan: Plan): PlanGap[] {
   const gaps: PlanGap[] = [];
-  const allText = `${plan.objective} ${plan.scope} ${plan.decisions.join(' ')}`;
+  const allText = `${plan.objective} ${plan.scope} ${decisionsText(plan)}`;
   const lower = allText.toLowerCase();
 
   // Ambiguous language
@@ -333,9 +378,7 @@ function analyzeClarity(plan: Plan): PlanGap[] {
   }
 
   // Tasks with very short or missing descriptions
-  const shortTasks = plan.tasks.filter(
-    (t) => !t.description || t.description.trim().length < 10,
-  );
+  const shortTasks = plan.tasks.filter((t) => !t.description || t.description.trim().length < 10);
   if (shortTasks.length > 0) {
     gaps.push(
       gap(
@@ -360,7 +403,15 @@ const GENERIC_OBJECTIVE_PATTERNS = [
   /^update\s+\w+$/i,
 ];
 
-const RATIONALE_INDICATORS = ['because', 'since', 'due to', 'in order to', 'so that', 'given that', 'as a result'];
+const RATIONALE_INDICATORS = [
+  'because',
+  'since',
+  'due to',
+  'in order to',
+  'so that',
+  'given that',
+  'as a result',
+];
 const SHALLOW_INDICATORS = ['better', 'good', 'best', 'nice', 'great', 'improved'];
 
 function analyzeSemanticQuality(plan: Plan): PlanGap[] {
@@ -412,7 +463,7 @@ function analyzeSemanticQuality(plan: Plan): PlanGap[] {
 
   // Decisions with shallow rationale (uses "better/good" without "because/since")
   for (let i = 0; i < plan.decisions.length; i++) {
-    const d = plan.decisions[i];
+    const d = decisionText(plan.decisions[i]);
     const hasShallow = containsAny(d, SHALLOW_INDICATORS);
     const hasRationale = containsAny(d, RATIONALE_INDICATORS);
     if (hasShallow && !hasRationale) {
@@ -476,6 +527,224 @@ export interface GapAnalysisOptions {
   customPasses?: GapAnalysisPass[];
 }
 
+// ─── Opt-In Pass Factories ──────────────────────────────────────
+// Ported from Salvador's plan-gap-technical.ts, plan-gap-domain.ts,
+// and plan-gap-antipattern.ts. These are parameterized factories that
+// agents register via customPasses.
+
+/**
+ * Factory: tool chain feasibility pass.
+ * Validates that tool_chain entries are known and ordering rules are respected.
+ * Ported from Salvador's analyzeToolFeasibility.
+ *
+ * @param validTools - Set of valid tool names for this agent
+ * @param orderingRules - Ordering constraints (e.g., search before create)
+ */
+export function createToolFeasibilityPass(
+  validTools: Set<string>,
+  orderingRules?: Array<{ before: string; after: string; reason: string }>,
+): GapAnalysisPass {
+  return (plan: Plan) => {
+    const gaps: PlanGap[] = [];
+    const toolChain = plan.tool_chain;
+    if (!toolChain || toolChain.length === 0) return gaps;
+
+    // Validate tool names
+    const invalidTools = toolChain.filter((t) => !validTools.has(t));
+    if (invalidTools.length > 0) {
+      gaps.push(
+        gap(
+          'critical',
+          'tool-feasibility',
+          `Invalid tool names in tool_chain: ${invalidTools.join(', ')}`,
+          'Use valid tool names. Check available tools for this agent.',
+          'tool_chain',
+          `invalid_tools:${invalidTools.join(',')}`,
+        ),
+      );
+    }
+
+    // Validate ordering rules
+    if (orderingRules) {
+      for (const rule of orderingRules) {
+        const beforeIndex = toolChain.indexOf(rule.before);
+        const afterIndex = toolChain.indexOf(rule.after);
+        if (beforeIndex !== -1 && afterIndex !== -1 && beforeIndex > afterIndex) {
+          gaps.push(
+            gap(
+              'major',
+              'tool-feasibility',
+              `Tool ordering violation: ${rule.before} must come before ${rule.after}`,
+              rule.reason,
+              'tool_chain',
+              `ordering:${rule.before}>${rule.after}`,
+            ),
+          );
+        }
+      }
+    }
+
+    return gaps;
+  };
+}
+
+/**
+ * Factory: flow and mode alignment pass.
+ * Validates flow and target_mode against known values and intent alignment.
+ * Ported from Salvador's analyzeFlowAlignment.
+ *
+ * @param validFlows - Set of valid flow names for this agent
+ * @param validModes - Set of valid operational modes for this agent
+ * @param intentFlowMap - Maps detected intents to expected flows
+ */
+export function createFlowAlignmentPass(
+  validFlows: Set<string>,
+  validModes: Set<string>,
+  intentFlowMap?: Record<string, string[]>,
+): GapAnalysisPass {
+  return (plan: Plan) => {
+    const gaps: PlanGap[] = [];
+
+    if (plan.flow && !validFlows.has(plan.flow)) {
+      gaps.push(
+        gap(
+          'major',
+          'flow-alignment',
+          `Invalid flow: ${plan.flow}`,
+          `Valid flows are: ${Array.from(validFlows).join(', ')}`,
+          'flow',
+          `invalid_flow:${plan.flow}`,
+        ),
+      );
+    }
+
+    if (plan.target_mode && !validModes.has(plan.target_mode)) {
+      gaps.push(
+        gap(
+          'major',
+          'flow-alignment',
+          `Invalid target_mode: ${plan.target_mode}`,
+          `Valid modes are: ${Array.from(validModes).join(', ')}`,
+          'target_mode',
+          `invalid_mode:${plan.target_mode}`,
+        ),
+      );
+    }
+
+    // Intent-flow alignment (optional)
+    if (intentFlowMap && plan.flow) {
+      const objectiveLower = (plan.objective || '').toLowerCase();
+      let detectedIntent: string | null = null;
+
+      if (/\b(create|build|implement|add|new)\b/.test(objectiveLower)) {
+        detectedIntent = 'CREATE';
+      } else if (/\b(fix|debug|repair|resolve|bug)\b/.test(objectiveLower)) {
+        detectedIntent = 'FIX';
+      } else if (/\b(review|audit|check|validate|inspect)\b/.test(objectiveLower)) {
+        detectedIntent = 'REVIEW';
+      } else if (/\b(plan|design|architect|structure)\b/.test(objectiveLower)) {
+        detectedIntent = 'PLAN';
+      } else if (/\b(enhance|improve|refactor|optimize)\b/.test(objectiveLower)) {
+        detectedIntent = 'ENHANCE';
+      } else if (/\b(deliver|package|publish|deploy|release)\b/.test(objectiveLower)) {
+        detectedIntent = 'DELIVER';
+      }
+
+      if (detectedIntent) {
+        const expectedFlows = intentFlowMap[detectedIntent] || [];
+        if (expectedFlows.length > 0 && !expectedFlows.includes(plan.flow)) {
+          gaps.push(
+            gap(
+              'minor',
+              'flow-alignment',
+              `Flow '${plan.flow}' may not align with detected intent '${detectedIntent}'`,
+              `Consider using flow: ${expectedFlows.join(' or ')}`,
+              'flow',
+              `intent_flow_mismatch:${detectedIntent}->${plan.flow}`,
+            ),
+          );
+        }
+      }
+    }
+
+    return gaps;
+  };
+}
+
+/**
+ * Factory: content anti-pattern pass.
+ * Detects common anti-patterns in plan content.
+ * Ported from Salvador's analyzeContentAntiPatterns.
+ *
+ * @param antiPatterns - Regex patterns to check against approach text
+ * @param mitigationPatterns - Patterns that indicate the plan is already mitigating
+ */
+export function createAntiPatternPass(
+  antiPatterns?: Array<{
+    pattern: RegExp;
+    severity: GapSeverity;
+    description: string;
+    recommendation: string;
+  }>,
+  mitigationPatterns?: RegExp[],
+): GapAnalysisPass {
+  const VAGUE_CRITERIA_PATTERNS: RegExp[] = [
+    /^it (looks?|works?|is) (good|nice|fine|great|ok|correct)/i,
+    /^(looks?|works?) (good|nice|fine|great|ok)/i,
+    /^it('s| is) (done|complete|finished)/i,
+    /\bmy machine\b/i,
+  ];
+
+  return (plan: Plan) => {
+    const gaps: PlanGap[] = [];
+    const approach = (plan.approach || '').toLowerCase();
+    const criteria = plan.success_criteria || [];
+    const fullText = [approach, ...criteria].join(' ').toLowerCase();
+
+    // Check if plan is actively mitigating known anti-patterns
+    const isMitigating = mitigationPatterns
+      ? mitigationPatterns.some((p) => p.test(fullText))
+      : false;
+
+    // Custom anti-pattern checks
+    if (!isMitigating && antiPatterns) {
+      for (const ap of antiPatterns) {
+        if (ap.pattern.test(approach)) {
+          gaps.push(
+            gap(
+              ap.severity,
+              'anti-pattern',
+              ap.description,
+              ap.recommendation,
+              'approach',
+              `anti_pattern:${ap.description}`,
+            ),
+          );
+        }
+      }
+    }
+
+    // Vague success criteria (generic — always checked)
+    for (const criterion of criteria) {
+      const isVague = VAGUE_CRITERIA_PATTERNS.some((p) => p.test(criterion));
+      if (isVague) {
+        gaps.push(
+          gap(
+            'minor',
+            'anti-pattern',
+            `Success criterion is not measurable: "${criterion}"`,
+            'Rewrite as a verifiable assertion: "Component renders X", "All Y pass Z", "No A in B".',
+            'success_criteria',
+            `vague_criterion:${criterion}`,
+          ),
+        );
+      }
+    }
+
+    return gaps;
+  };
+}
+
 // ─── Orchestrator ────────────────────────────────────────────────
 
 /**

package/src/planning/gap-types.ts

@@ -13,7 +13,10 @@ export type GapCategory =
   | 'feasibility'
   | 'risk'
   | 'clarity'
-  | 'semantic-quality';
+  | 'semantic-quality'
+  | 'tool-feasibility'
+  | 'flow-alignment'
+  | 'anti-pattern';
 
 export interface PlanGap {
   id: string;