@soleri/core 2.12.0 → 8.0.0

package/src/control/intent-router.ts

@@ -16,8 +16,33 @@ import type {
   IntentClassification,
   ModeConfig,
   MorphResult,
+  RoutingAccuracyReport,
 } from './types.js';
 
+// ─── Token Stemming ─────────────────────────────────────────────────
+// Lightweight suffix stripping for intent matching.
+// Handles: "crashes" → "crash", "deploying" → "deploy", "broken" → "broke",
+// "issues" → "issue", "building" → "build", "optimizing" → "optimize"
+
+function stemToken(token: string): string {
+  if (token.length < 4) return token;
+  // Order matters — check longer suffixes first
+  if (token.endsWith('ying')) return token.slice(0, -4) + 'y'; // deploying → deploy
+  if (token.endsWith('izing')) return token.slice(0, -3) + 'e'; // optimizing → optimize
+  if (token.endsWith('ating')) return token.slice(0, -3) + 'e'; // creating → create
+  if (token.endsWith('ting')) return token.slice(0, -4) + 't'; // getting → get (approx)
+  if (token.endsWith('ning')) return token.slice(0, -4) + 'n'; // planning → plan (approx)
+  if (token.endsWith('ing')) return token.slice(0, -3); // fixing → fix, building → build
+  if (token.endsWith('ies')) return token.slice(0, -3) + 'y'; // queries → query
+  if (token.endsWith('shes')) return token.slice(0, -2); // crashes → crash
+  if (token.endsWith('ches')) return token.slice(0, -2); // searches → search
+  if (token.endsWith('ses')) return token.slice(0, -2); // releases → releas (close enough)
+  if (token.endsWith('es') && token.length > 4) return token.slice(0, -1); // issues → issue
+  if (token.endsWith('ed') && token.length > 4) return token.slice(0, -2); // fixed → fix
+  if (token.endsWith('s') && !token.endsWith('ss') && token.length > 3) return token.slice(0, -1); // bugs → bug
+  return token;
+}
+
 // ─── Default Mode Definitions ───────────────────────────────────────
 
 const DEFAULT_MODES: ModeConfig[] = [
@@ -33,7 +58,23 @@ const DEFAULT_MODES: ModeConfig[] = [
     intent: 'fix',
     description: 'Fixing bugs, errors, and broken behavior',
     behaviorRules: ['Identify root cause first', 'Verify fix with tests', 'Check for regressions'],
-    keywords: ['fix', 'bug', 'broken', 'error', 'crash', 'issue', 'debug', 'repair', 'janky'],
+    keywords: [
+      'fix',
+      'bug',
+      'broken',
+      'error',
+      'crash',
+      'issue',
+      'debug',
+      'repair',
+      'janky',
+      'fail',
+      'wrong',
+      'stuck',
+      'regression',
+      'fault',
+      'defect',
+    ],
   },
   {
     mode: 'VALIDATE-MODE',
@@ -128,6 +169,16 @@ export class IntentRouter {
         matched_keywords TEXT NOT NULL DEFAULT '[]',
         created_at TEXT NOT NULL DEFAULT (datetime('now'))
       );
+
+      CREATE TABLE IF NOT EXISTS routing_feedback (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        routing_log_id INTEGER,
+        initial_intent TEXT NOT NULL,
+        actual_intent TEXT NOT NULL,
+        correction INTEGER NOT NULL DEFAULT 0,
+        confidence REAL NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
     `);
   }
 
@@ -152,7 +203,11 @@ export class IntentRouter {
   // ─── Intent Classification ──────────────────────────────────────────
 
   routeIntent(prompt: string): IntentClassification {
-    const tokens = new Set(prompt.toLowerCase().split(/\s+/).filter(Boolean));
+    const rawTokens = prompt.toLowerCase().split(/\s+/).filter(Boolean);
+    // Stem tokens: strip common suffixes for fuzzy matching
+    // "crashes" → "crash", "broken" stays "broken", "deploying" → "deploy"
+    const stemmed = rawTokens.map((t) => stemToken(t));
+    const tokens = new Set([...rawTokens, ...stemmed]);
     const modes = this.getModes();
 
     let bestMode: ModeConfig | null = null;
@@ -270,6 +325,102 @@ export class IntentRouter {
     }
   }
 
+  // ─── Routing Feedback ─────────────────────────────────────────────
+
+  recordRoutingFeedback(input: {
+    routingLogId?: number;
+    initialIntent: string;
+    actualIntent: string;
+    confidence: number;
+    correction: boolean;
+  }): { recorded: boolean; id: number } {
+    const result = this.provider.run(
+      `INSERT INTO routing_feedback (routing_log_id, initial_intent, actual_intent, correction, confidence)
+       VALUES (?, ?, ?, ?, ?)`,
+      [
+        input.routingLogId ?? null,
+        input.initialIntent,
+        input.actualIntent,
+        input.correction ? 1 : 0,
+        input.confidence,
+      ],
+    );
+    return { recorded: true, id: Number(result.lastInsertRowid) };
+  }
+
+  getRoutingAccuracy(periodDays: number = 30): RoutingAccuracyReport {
+    const cutoff = new Date(Date.now() - periodDays * 86400000).toISOString();
+
+    const total = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    const correct = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE initial_intent = actual_intent AND created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    const corrections = this.provider.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM routing_feedback WHERE correction = 1 AND created_at >= ?',
+      [cutoff],
+    )!.count;
+
+    // Common misroutes
+    const misrouteRows = this.provider.all<{
+      from_intent: string;
+      to_intent: string;
+      count: number;
+    }>(
+      `SELECT initial_intent as from_intent, actual_intent as to_intent, COUNT(*) as count
+       FROM routing_feedback
+       WHERE initial_intent != actual_intent AND created_at >= ?
+       GROUP BY initial_intent, actual_intent
+       ORDER BY count DESC
+       LIMIT 10`,
+      [cutoff],
+    );
+
+    // Confidence calibration: group by confidence bucket and check accuracy per bucket
+    const calibrationRows = this.provider.all<{ bucket: string; total: number; correct: number }>(
+      `SELECT
+         CASE
+           WHEN confidence >= 0.8 THEN 'high'
+           WHEN confidence >= 0.4 THEN 'medium'
+           ELSE 'low'
+         END as bucket,
+         COUNT(*) as total,
+         SUM(CASE WHEN initial_intent = actual_intent THEN 1 ELSE 0 END) as correct
+       FROM routing_feedback
+       WHERE created_at >= ?
+       GROUP BY bucket`,
+      [cutoff],
+    );
+
+    const calibration: Record<string, { total: number; correct: number; accuracy: number }> = {};
+    for (const row of calibrationRows) {
+      calibration[row.bucket] = {
+        total: row.total,
+        correct: row.correct,
+        accuracy: row.total > 0 ? Math.round((row.correct / row.total) * 100) : 0,
+      };
+    }
+
+    return {
+      periodDays,
+      total,
+      correct,
+      accuracy: total > 0 ? Math.round((correct / total) * 100) : 100,
+      corrections,
+      commonMisroutes: misrouteRows.map((r) => ({
+        from: r.from_intent,
+        to: r.to_intent,
+        count: r.count,
+      })),
+      confidenceCalibration: calibration,
+    };
+  }
+
   // ─── Analytics ──────────────────────────────────────────────────────
 
   getRoutingStats(): {

package/src/control/types.ts

@@ -100,3 +100,13 @@ export interface MorphResult {
   currentMode: OperationalMode;
   behaviorRules: string[];
 }
+
+export interface RoutingAccuracyReport {
+  periodDays: number;
+  total: number;
+  correct: number;
+  accuracy: number;
+  corrections: number;
+  commonMisroutes: Array<{ from: string; to: string; count: number }>;
+  confidenceCalibration: Record<string, { total: number; correct: number; accuracy: number }>;
+}

package/src/curator/classifier.ts

@@ -0,0 +1,88 @@
+/**
+ * Classifier — LLM-based auto-categorization for vault entries.
+ *
+ * Suggests category, severity, and additional tags based on entry content.
+ * Graceful degradation: returns empty suggestions when LLM is unavailable.
+ */
+
+import type { LLMClient } from '../llm/llm-client.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface ClassificationResult {
+  classified: boolean;
+  suggestedDomain: string | null;
+  suggestedSeverity: string | null;
+  suggestedTags: string[];
+  confidence: number;
+  error?: string;
+}
+
+// ─── Classify ────────────────────────────────────────────────────────
+
+const CLASSIFY_PROMPT = `Classify this knowledge entry. Suggest the best domain, severity, and 3-5 tags.
+
+**Title:** {title}
+**Type:** {type}
+**Current tags:** {tags}
+**Description:** {description}
+
+Respond with ONLY this JSON (no markdown fences):
+{"domain":"string","severity":"critical|warning|suggestion","tags":["tag1","tag2","tag3"],"confidence":0.0-1.0}
+
+Rules:
+- domain: a single word (e.g., architecture, testing, security, design, performance, accessibility)
+- severity: critical = must-know, warning = important, suggestion = nice-to-know
+- tags: lowercase, hyphenated, specific and useful for search
+- confidence: how sure you are about this classification (0.0-1.0)`;
+
+export async function classifyEntry(
+  entry: IntelligenceEntry,
+  llm: LLMClient | null,
+): Promise<ClassificationResult> {
+  const fallback: ClassificationResult = {
+    classified: false,
+    suggestedDomain: null,
+    suggestedSeverity: null,
+    suggestedTags: [],
+    confidence: 0,
+  };
+
+  if (!llm) return fallback;
+
+  const prompt = CLASSIFY_PROMPT.replace('{title}', entry.title)
+    .replace('{type}', entry.type)
+    .replace('{tags}', entry.tags.join(', ') || 'none')
+    .replace('{description}', entry.description);
+
+  try {
+    const result = await llm.complete({
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+      systemPrompt: 'You are a knowledge classifier. Respond only with JSON.',
+      userPrompt: prompt,
+      temperature: 0.1,
+      maxTokens: 300,
+      caller: 'classifier',
+      task: 'classify',
+    });
+
+    const parsed = JSON.parse(result.text) as {
+      domain: string;
+      severity: string;
+      tags: string[];
+      confidence: number;
+    };
+
+    return {
+      classified: true,
+      suggestedDomain: parsed.domain ?? null,
+      suggestedSeverity: parsed.severity ?? null,
+      suggestedTags: parsed.tags ?? [],
+      confidence: parsed.confidence ?? 0.5,
+    };
+  } catch (err) {
+    return { ...fallback, error: (err as Error).message };
+  }
+}

package/src/curator/quality-gate.ts

@@ -0,0 +1,129 @@
+/**
+ * Quality Gate — LLM-based entry quality evaluation.
+ *
+ * Evaluates vault entries on 5 criteria (novelty, actionability, specificity,
+ * relevance, informationDensity). Entries scoring below threshold are rejected.
+ *
+ * Graceful degradation: returns ACCEPT when LLM is unavailable.
+ */
+
+import type { LLMClient } from '../llm/llm-client.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export type QualityVerdict = 'ACCEPT' | 'REJECT';
+
+export interface QualityScores {
+  novelty: number;
+  actionability: number;
+  specificity: number;
+  relevance: number;
+  informationDensity: number;
+}
+
+export interface QualityResult {
+  evaluated: boolean;
+  verdict: QualityVerdict;
+  overallScore: number;
+  scores: QualityScores;
+  reasoning: string;
+  rejectReasons?: string[];
+  error?: string;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────
+
+const REJECT_THRESHOLD = 50;
+const CRITICAL_LOW = 15;
+
+const QUALITY_PROMPT = `You are a strict knowledge base curator deciding whether an entry deserves to be in a high-quality vault.
+
+Your job is to REJECT junk and keep the vault clean. Be ruthless but fair.
+
+## Entry Under Review
+- **Type:** {type}
+- **Title:** {title}
+- **Tags:** {tags}
+- **Description:** {description}
+{why}{example}{context}
+
+## Scoring Criteria (each 0-100)
+
+1. **novelty** — Is this genuinely new knowledge or a truism? ("Write clean code" = 5, "Use driver adapter pattern to avoid Prisma lock-in" = 90)
+2. **actionability** — Can someone act on this? Vague advice = low, specific do/don't = high
+3. **specificity** — Is this specific to a real context or generic fluff?
+4. **relevance** — Does this belong in a technical knowledge vault?
+5. **informationDensity** — Is there real substance or mostly filler?
+
+## Verdict Rules
+- Overall score = average of all 5 criteria
+- **REJECT** if overall < ${REJECT_THRESHOLD}, or if ANY criterion scores <= ${CRITICAL_LOW}
+- **ACCEPT** otherwise
+- When in doubt, REJECT.
+
+Respond with ONLY this JSON (no markdown fences):
+{"verdict":"ACCEPT or REJECT","overallScore":0-100,"scores":{"novelty":N,"actionability":N,"specificity":N,"relevance":N,"informationDensity":N},"reasoning":"2-3 sentences","rejectReasons":["reason1"]}`;
+
+// ─── Evaluate ────────────────────────────────────────────────────────
+
+export async function evaluateQuality(
+  entry: IntelligenceEntry,
+  llm: LLMClient | null,
+): Promise<QualityResult> {
+  const fallback: QualityResult = {
+    evaluated: false,
+    verdict: 'ACCEPT',
+    overallScore: 50,
+    scores: {
+      novelty: 50,
+      actionability: 50,
+      specificity: 50,
+      relevance: 50,
+      informationDensity: 50,
+    },
+    reasoning: 'LLM unavailable — defaulting to accept',
+  };
+
+  if (!llm) return fallback;
+
+  const prompt = QUALITY_PROMPT.replace('{type}', entry.type)
+    .replace('{title}', entry.title)
+    .replace('{tags}', entry.tags.join(', ') || 'none')
+    .replace('{description}', entry.description)
+    .replace('{why}', entry.why ? `- **Why:** ${entry.why}\n` : '')
+    .replace('{example}', entry.example ? `- **Example:** ${entry.example}\n` : '')
+    .replace('{context}', entry.context ? `- **Context:** ${entry.context}\n` : '');
+
+  try {
+    const result = await llm.complete({
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+      systemPrompt: 'You are a knowledge quality evaluator. Respond only with JSON.',
+      userPrompt: prompt,
+      temperature: 0.1,
+      maxTokens: 500,
+      caller: 'quality-gate',
+      task: 'evaluate',
+    });
+
+    const parsed = JSON.parse(result.text) as {
+      verdict: string;
+      overallScore: number;
+      scores: QualityScores;
+      reasoning: string;
+      rejectReasons?: string[];
+    };
+
+    return {
+      evaluated: true,
+      verdict: (parsed.verdict === 'REJECT' ? 'REJECT' : 'ACCEPT') as QualityVerdict,
+      overallScore: parsed.overallScore ?? 50,
+      scores: parsed.scores ?? fallback.scores,
+      reasoning: parsed.reasoning ?? '',
+      rejectReasons: parsed.rejectReasons,
+    };
+  } catch (err) {
+    return { ...fallback, error: (err as Error).message };
+  }
+}

package/src/domain-packs/index.ts

@@ -0,0 +1,27 @@
+export {
+  type DomainPack,
+  type DomainPackManifest,
+  type DomainPackRef,
+  type KnowledgeManifest,
+  type PackSkillDefinition,
+  type ValidateResult,
+  validateDomainPack,
+  SEMANTIC_FACADE_NAMES,
+} from './types.js';
+
+export { loadDomainPack, loadDomainPacksFromConfig, resolveDependencies } from './loader.js';
+
+export { installKnowledge, type KnowledgeInstallResult } from './knowledge-installer.js';
+
+export { installSkills, type SkillsInstallResult } from './skills-installer.js';
+
+export { injectDomainRules, removeDomainRules } from './inject-rules.js';
+
+export {
+  type PackRuntime,
+  type PackProjectContext,
+  type PackCheckContext,
+  createPackRuntime,
+} from './pack-runtime.js';
+
+export { resolveToken, listProjectTokens, buildReverseIndex } from './token-resolver.js';

package/src/domain-packs/inject-rules.ts

@@ -0,0 +1,74 @@
+/**
+ * Domain-level CLAUDE.md injection for domain packs.
+ *
+ * Each pack can inject behavioral rules under its own marker:
+ *   <!-- domain:packName --> ... <!-- /domain:packName -->
+ *
+ * Injection is idempotent — existing content between markers is replaced.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const OPEN_MARKER = (name: string) => `<!-- domain:${name} -->`;
+const CLOSE_MARKER = (name: string) => `<!-- /domain:${name} -->`;
+
+/**
+ * Inject domain rules into a CLAUDE.md file.
+ *
+ * @param filePath - Path to CLAUDE.md
+ * @param packName - Domain pack name (used in markers)
+ * @param rulesContent - Markdown content to inject
+ */
+export function injectDomainRules(filePath: string, packName: string, rulesContent: string): void {
+  if (!rulesContent || rulesContent.trim().length === 0) return;
+
+  const open = OPEN_MARKER(packName);
+  const close = CLOSE_MARKER(packName);
+  const block = `${open}\n${rulesContent.trim()}\n${close}`;
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, block + '\n', 'utf-8');
+    return;
+  }
+
+  let content = readFileSync(filePath, 'utf-8');
+
+  // Replace existing block if present (idempotent)
+  const openIdx = content.indexOf(open);
+  const closeIdx = content.indexOf(close);
+
+  if (openIdx !== -1 && closeIdx !== -1) {
+    const before = content.slice(0, openIdx);
+    const after = content.slice(closeIdx + close.length);
+    content = before + block + after;
+  } else {
+    // Append at end
+    content = content.trimEnd() + '\n\n' + block + '\n';
+  }
+
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Remove domain rules from a CLAUDE.md file.
+ *
+ * @param filePath - Path to CLAUDE.md
+ * @param packName - Domain pack name
+ */
+export function removeDomainRules(filePath: string, packName: string): void {
+  if (!existsSync(filePath)) return;
+
+  const open = OPEN_MARKER(packName);
+  const close = CLOSE_MARKER(packName);
+
+  let content = readFileSync(filePath, 'utf-8');
+  const openIdx = content.indexOf(open);
+  const closeIdx = content.indexOf(close);
+
+  if (openIdx !== -1 && closeIdx !== -1) {
+    const before = content.slice(0, openIdx);
+    const after = content.slice(closeIdx + close.length);
+    content = (before + after).replace(/\n{3,}/g, '\n\n');
+    writeFileSync(filePath, content, 'utf-8');
+  }
+}

package/src/domain-packs/knowledge-installer.ts

@@ -0,0 +1,116 @@
+/**
+ * Three-tier knowledge installer for domain packs.
+ *
+ * Respects KnowledgeManifest tiers:
+ * - canonical/: seed_canonical (immutable, highest authority)
+ * - curated/: import via vault (curator-eligible)
+ * - captured/: import via vault (tier=captured)
+ *
+ * All entries tagged with origin=pack and source=packName.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { DomainPack } from './types.js';
+
+export interface KnowledgeInstallResult {
+  canonical: number;
+  curated: number;
+  captured: number;
+  skipped: number;
+}
+
+/**
+ * Install knowledge from a domain pack into the agent's vault.
+ *
+ * @param pack - The domain pack with knowledge manifest
+ * @param runtime - Agent runtime with vault access
+ * @param rootDir - Absolute path to the pack's root directory
+ */
+export async function installKnowledge(
+  pack: DomainPack,
+  runtime: AgentRuntime,
+  rootDir: string,
+): Promise<KnowledgeInstallResult> {
+  const result: KnowledgeInstallResult = { canonical: 0, curated: 0, captured: 0, skipped: 0 };
+
+  if (!pack.knowledge) return result;
+
+  const { vault } = runtime;
+  const knowledge = pack.knowledge;
+
+  // Tier 1: Canonical (immutable)
+  if (knowledge.canonical) {
+    const dir = resolve(rootDir, knowledge.canonical);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'canonical',
+        origin: 'pack',
+        source: pack.name,
+        immutable: true,
+      });
+      result.canonical = count;
+    }
+  }
+
+  // Tier 2: Curated (grooming-eligible)
+  if (knowledge.curated) {
+    const dir = resolve(rootDir, knowledge.curated);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'curated',
+        origin: 'pack',
+        source: pack.name,
+      });
+      result.curated = count;
+    }
+  }
+
+  // Tier 3: Captured (seed learnings)
+  if (knowledge.captured) {
+    const dir = resolve(rootDir, knowledge.captured);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'captured',
+        origin: 'pack',
+        source: pack.name,
+      });
+      result.captured = count;
+    }
+  }
+
+  return result;
+}
+
+/** Import markdown files from a directory into the vault. */
+function importMarkdownEntries(
+  vault: AgentRuntime['vault'],
+  dir: string,
+  meta: { tier: string; origin: string; source: string; immutable?: boolean },
+): number {
+  const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+  let imported = 0;
+
+  for (const file of files) {
+    const content = readFileSync(join(dir, file), 'utf-8');
+    const id = `pack-${meta.source}-${file.replace(/\.md$/, '')}`;
+
+    // Skip if canonical entry already exists (immutable = never overwrite)
+    if (meta.immutable && vault.get(id)) continue;
+
+    vault.add({
+      id,
+      type: 'pattern',
+      title: file.replace(/\.md$/, '').replace(/-/g, ' '),
+      description: content.slice(0, 200),
+      severity: 'suggestion',
+      tags: [`pack:${meta.source}`, `tier:${meta.tier}`],
+      domain: meta.source,
+      origin: meta.origin as 'pack' | 'agent' | 'user',
+    });
+    imported++;
+  }
+
+  return imported;
+}