@smartergpt/lexrunner 1.0.0

package/src/learning/prompts.ts

@@ -0,0 +1,107 @@
+/**
+ * Interactive Prompts for Counter-Example Classification - LR-TSF-003
+ *
+ * Provides user prompts for classifying failures as counter-examples.
+ */
+
+import * as readline from "readline";
+import type {
+  CounterExampleClassification,
+  CounterExampleClassificationType,
+} from "./counter-example.js";
+
+/**
+ * Prompt for user input
+ */
+function prompt(question: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Prompt user to classify a failure as a counter-example
+ *
+ * Returns null if user chooses to skip recording
+ */
+export async function promptCounterExampleClassification(
+  gateName: string,
+  errorMessage: string
+): Promise<CounterExampleClassification | null> {
+  console.log("\n❌ Gate Failure Detected\n");
+  console.log(`Gate: ${gateName}`);
+  console.log(
+    `Error: ${errorMessage.substring(0, 200)}${errorMessage.length > 200 ? "..." : ""}\n`
+  );
+  console.log("Would you like to record this failure as a counter-example?");
+  console.log("This helps improve future constraint derivation.\n");
+  console.log("[1] Yes - Transient failure (don't learn from this)");
+  console.log("[2] Yes - Constraint gap (should have caught this)");
+  console.log("[3] Yes - False positive (constraint too strict)");
+  console.log("[4] No - Skip recording\n");
+
+  const choice = await prompt("Choose option [1-4]: ");
+
+  switch (choice) {
+    case "1": {
+      const description = await prompt(
+        "Briefly describe why this is transient (e.g., 'flaky network'): "
+      );
+      return {
+        type: "transient",
+        description: description || "Transient failure",
+      };
+    }
+
+    case "2": {
+      const description = await prompt(
+        "Describe what constraint gap this reveals (e.g., 'missing mock setup'): "
+      );
+      const suggestedAction = await prompt("Suggested action (optional): ");
+      return {
+        type: "gap",
+        description: description || "Constraint gap identified",
+        suggestedAction: suggestedAction || undefined,
+      };
+    }
+
+    case "3": {
+      const description = await prompt(
+        "Describe why this is a false positive (e.g., 'test is too strict'): "
+      );
+      const suggestedAction = await prompt("Suggested action (optional): ");
+      return {
+        type: "false-positive",
+        description: description || "False positive detected",
+        suggestedAction: suggestedAction || undefined,
+      };
+    }
+
+    case "4":
+      console.log("Skipping counter-example recording.");
+      return null;
+
+    default:
+      console.log("Invalid choice. Skipping counter-example recording.");
+      return null;
+  }
+}
+
+/**
+ * Simplified prompt for auto-recording mode
+ * Always records as 'unknown' type
+ */
+export function createAutoRecordClassification(errorMessage: string): CounterExampleClassification {
+  return {
+    type: "unknown",
+    description: `Auto-recorded failure: ${errorMessage.substring(0, 100)}`,
+  };
+}

package/src/learning/storage.ts

@@ -0,0 +1,230 @@
+/**
+ * Storage Management for Counter-Examples - LR-TSF-003
+ *
+ * Handles persisting counter-examples to disk and maintaining an index.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { CounterExample } from "./counter-example.js";
+import { canonicalJSONStringify } from "../util/canonicalJson.js";
+
+/**
+ * Counter-example index entry
+ */
+export interface CounterExampleIndexEntry {
+  id: string;
+  timestamp: string;
+  failureType: string;
+  target: string;
+  classificationType: string;
+  shouldLearn: boolean;
+  filePath: string;
+}
+
+/**
+ * Counter-example index
+ */
+export interface CounterExampleIndex {
+  version: string;
+  entries: CounterExampleIndexEntry[];
+}
+
+/**
+ * Get the counter-examples directory path
+ */
+export function getCounterExamplesDir(baseDir: string = process.cwd()): string {
+  return path.join(baseDir, ".lexrunner", "counter-examples");
+}
+
+/**
+ * Ensure counter-examples directory exists
+ */
+function ensureCounterExamplesDir(baseDir: string = process.cwd()): string {
+  const dir = getCounterExamplesDir(baseDir);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Get the index file path
+ */
+function getIndexPath(baseDir: string = process.cwd()): string {
+  return path.join(getCounterExamplesDir(baseDir), "index.json");
+}
+
+/**
+ * Load the counter-example index
+ */
+function loadIndex(baseDir: string = process.cwd()): CounterExampleIndex {
+  const indexPath = getIndexPath(baseDir);
+  if (!fs.existsSync(indexPath)) {
+    return {
+      version: "1.0.0",
+      entries: [],
+    };
+  }
+
+  try {
+    const content = fs.readFileSync(indexPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    console.warn(`Failed to load counter-example index: ${error}`);
+    return {
+      version: "1.0.0",
+      entries: [],
+    };
+  }
+}
+
+/**
+ * Save the counter-example index
+ */
+function saveIndex(index: CounterExampleIndex, baseDir: string = process.cwd()): void {
+  const indexPath = getIndexPath(baseDir);
+  const content = canonicalJSONStringify(index);
+  fs.writeFileSync(indexPath, content, "utf-8");
+}
+
+/**
+ * Generate a filename for a counter-example
+ * Sanitizes the target to prevent path traversal
+ */
+function generateFileName(counterExample: CounterExample): string {
+  const date = new Date(counterExample.timestamp).toISOString().split("T")[0];
+  // Sanitize target: remove all non-alphanumeric characters except hyphens
+  const target = counterExample.failure.target
+    .replace(/[^a-z0-9-]/gi, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase()
+    .substring(0, 50); // Limit length
+  const type = counterExample.failure.type;
+  return `${date}-${target}-${type}.json`;
+}
+
+/**
+ * Store a counter-example to disk
+ */
+export function storeCounterExample(
+  counterExample: CounterExample,
+  baseDir: string = process.cwd()
+): string {
+  // Ensure directory exists
+  const dir = ensureCounterExamplesDir(baseDir);
+
+  // Generate filename
+  const fileName = generateFileName(counterExample);
+  const filePath = path.join(dir, fileName);
+
+  // Write counter-example file
+  const content = canonicalJSONStringify(counterExample);
+  fs.writeFileSync(filePath, content, "utf-8");
+
+  // Update index
+  const index = loadIndex(baseDir);
+  const indexEntry: CounterExampleIndexEntry = {
+    id: counterExample.id,
+    timestamp: counterExample.timestamp,
+    failureType: counterExample.failure.type,
+    target: counterExample.failure.target,
+    classificationType: counterExample.classification.type,
+    shouldLearn: counterExample.shouldLearn,
+    filePath: fileName,
+  };
+
+  // Remove existing entry with same ID if present
+  index.entries = index.entries.filter((e) => e.id !== counterExample.id);
+  index.entries.push(indexEntry);
+
+  // Sort entries by timestamp (newest first)
+  index.entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+  saveIndex(index, baseDir);
+
+  console.log(`✓ Recorded counter-example: ${counterExample.classification.type}`);
+  console.log(`  Stored in: ${filePath}`);
+
+  return filePath;
+}
+
+/**
+ * List all counter-examples
+ */
+export function listCounterExamples(baseDir: string = process.cwd()): CounterExampleIndexEntry[] {
+  const index = loadIndex(baseDir);
+  return index.entries;
+}
+
+/**
+ * Load a specific counter-example by ID
+ */
+export function loadCounterExample(
+  id: string,
+  baseDir: string = process.cwd()
+): CounterExample | null {
+  const index = loadIndex(baseDir);
+  const entry = index.entries.find((e) => e.id === id);
+
+  if (!entry) {
+    return null;
+  }
+
+  const filePath = path.join(getCounterExamplesDir(baseDir), entry.filePath);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    console.warn(`Failed to load counter-example ${id}: ${error}`);
+    return null;
+  }
+}
+
+/**
+ * Export counter-examples in various formats
+ */
+export function exportCounterExamples(
+  format: "json" | "csv",
+  baseDir: string = process.cwd()
+): string {
+  const index = loadIndex(baseDir);
+
+  if (format === "json") {
+    return canonicalJSONStringify(index);
+  }
+
+  // CSV format with proper escaping
+  const lines: string[] = [
+    "ID,Timestamp,Failure Type,Target,Classification,Should Learn,File Path",
+  ];
+
+  for (const entry of index.entries) {
+    // Escape CSV fields: quote and escape internal quotes
+    const escapeCsv = (field: string): string => {
+      if (field.includes(",") || field.includes('"') || field.includes("\n")) {
+        return `"${field.replace(/"/g, '""')}"`;
+      }
+      return field;
+    };
+
+    lines.push(
+      [
+        escapeCsv(entry.id),
+        escapeCsv(entry.timestamp),
+        escapeCsv(entry.failureType),
+        escapeCsv(entry.target),
+        escapeCsv(entry.classificationType),
+        entry.shouldLearn.toString(),
+        escapeCsv(entry.filePath),
+      ].join(",")
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/lexsona/client.ts

@@ -0,0 +1,367 @@
+/**
+ * LexSona Client Module
+ *
+ * Wraps LexSona for use in LexRunner shadow governance mode.
+ * Implements Version Contract v0.1: Shadow mode only, no enforcement.
+ *
+ * This module is "dumb plumbing" - it calls LexSona and returns results.
+ * No policy decisions are made here.
+ */
+
+import { ulid } from "ulid";
+import chalk from "chalk";
+import type {
+  LexSonaMode,
+  LexSonaEnvConfig,
+  LexSonaWorkflowContext,
+  LexSonaShadowResult,
+  LexSonaConstraintSnapshot,
+} from "./types.js";
+import type { RunnerGovernanceSignals } from "./logger.js";
+
+// Debug logging helper (QOL-006)
+const DEBUG_ENABLED = process.env.LEXSONA_DEBUG === "1";
+
+function debugLog(...args: unknown[]): void {
+  if (DEBUG_ENABLED) {
+    console.error("[lexsona:debug]", ...args);
+  }
+}
+
+// Dynamic import to handle cases where LexSona isn't installed
+// NOTE: LexSona is an optional dependency. CI/typecheck must succeed even when
+// '@smartergpt/lexsona' is not installed.
+//
+// To avoid TS2307 in environments without LexSona, do NOT reference it in type
+// positions (e.g. `typeof import(...)`) and avoid literal-module-specifier
+// dynamic imports (e.g. `import("@smartergpt/lexsona")`).
+//
+// Instead, define the minimal shape we need and load the module via a runtime
+// string variable.
+type LexSonaDeriveContext = {
+  /** Workflow / domain identifier */
+  domain: string;
+  /** Module / step identifier (LexSona convention) */
+  module_id: string;
+  /** Optional task type hint */
+  taskType?: string;
+};
+
+type LexSonaConstraintSet = {
+  personaId: string;
+  principles: Array<{ id: string; description: string }>;
+  constraints: Array<{
+    rule_id: string;
+    text: string;
+    severity: string;
+    confidence: number;
+    category: string;
+  }>;
+  metadata: {
+    rulesConsidered: number;
+    rulesFiltered: number;
+    confidenceThreshold: number;
+    offlineMode: boolean;
+    confidenceCeiling?: number;
+  };
+};
+
+type LexSonaInstance = {
+  deriveConstraints: (ctx: LexSonaDeriveContext) => Promise<LexSonaConstraintSet>;
+};
+
+type LexSonaModuleLike = {
+  LexSona: {
+    connect: (opts: {
+      lexDb?: string;
+      persona: string;
+      domain: string;
+    }) => Promise<LexSonaInstance>;
+  };
+};
+
+let LexSonaModule: LexSonaModuleLike | null = null;
+
+/**
+ * Lazily load LexSona module
+ */
+async function getLexSonaModule(): Promise<LexSonaModuleLike | null> {
+  if (LexSonaModule !== null) {
+    return LexSonaModule;
+  }
+  try {
+    const moduleName = "@smartergpt/lexsona";
+    LexSonaModule = (await import(moduleName)) as unknown as LexSonaModuleLike;
+    return LexSonaModule;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read LexSona configuration from environment
+ */
+export function getLexSonaConfig(): LexSonaEnvConfig {
+  const modeRaw = process.env.LEXSONA_MODE ?? "off";
+  const mode: LexSonaMode = modeRaw === "shadow" ? "shadow" : "off";
+  const personaId = process.env.LEXSONA_PERSONA ?? null;
+  const hasLexConnection = process.env.LEX_DB_PATH !== undefined;
+
+  return { mode, personaId, hasLexConnection };
+}
+
+/**
+ * Check if LexSona shadow mode is enabled for a workflow
+ */
+export function isLexSonaEnabled(config: LexSonaEnvConfig): boolean {
+  return config.mode === "shadow" && config.personaId !== null;
+}
+
+/**
+ * Convert LexSona ConstraintSet to a snapshot for logging
+ */
+function toConstraintSnapshot(constraintSet: {
+  personaId: string;
+  principles: Array<{ id: string; description: string }>;
+  constraints: Array<{
+    rule_id: string;
+    text: string;
+    severity: string;
+    confidence: number;
+    category: string;
+  }>;
+  metadata: {
+    rulesConsidered: number;
+    rulesFiltered: number;
+    confidenceThreshold: number;
+    offlineMode: boolean;
+    confidenceCeiling?: number;
+  };
+}): LexSonaConstraintSnapshot {
+  // Sort by confidence descending, take top 10
+  const sorted = [...constraintSet.constraints].sort((a, b) => b.confidence - a.confidence);
+  const topConstraints = sorted.slice(0, 10).map((c) => ({
+    id: c.rule_id,
+    description: c.text,
+    severity: c.severity,
+    confidence: c.confidence,
+  }));
+
+  return {
+    constraintCount: constraintSet.constraints.length,
+    topConstraints,
+    principleCount: constraintSet.principles.length,
+    metadata: constraintSet.metadata,
+  };
+}
+
+/**
+ * Call LexSona to derive constraints for a workflow context (QOL-006: Debug mode)
+ *
+ * This is the main entry point for shadow governance.
+ * Returns a result even on failure (for logging purposes).
+ */
+export async function deriveShadowConstraints(
+  context: LexSonaWorkflowContext,
+  config?: LexSonaEnvConfig
+): Promise<LexSonaShadowResult> {
+  const cfg = config ?? getLexSonaConfig();
+  const derivedAt = new Date().toISOString();
+
+  debugLog("deriveShadowConstraints() called");
+  debugLog("  Context:", JSON.stringify(context, null, 2));
+  debugLog("  Config:", JSON.stringify(cfg, null, 2));
+
+  // If disabled, return early
+  if (!isLexSonaEnabled(cfg)) {
+    debugLog("LexSona disabled (mode=off or no persona)");
+    return {
+      success: false,
+      personaId: cfg.personaId,
+      constraintSet: null,
+      error: "LexSona disabled (mode=off or no persona)",
+      offlineMode: !cfg.hasLexConnection,
+      derivedAt,
+    };
+  }
+
+  debugLog("Loading LexSona module...");
+
+  // Try to load LexSona
+  const lexsona = await getLexSonaModule();
+  if (!lexsona) {
+    debugLog("LexSona module not available");
+    return {
+      success: false,
+      personaId: cfg.personaId,
+      constraintSet: null,
+      error: "LexSona module not available",
+      offlineMode: !cfg.hasLexConnection,
+      derivedAt,
+    };
+  }
+
+  debugLog("LexSona module loaded successfully");
+
+  try {
+    debugLog(`Connecting to LexSona with persona: ${cfg.personaId}`);
+    debugLog(`  Lex DB: ${process.env.LEX_DB_PATH ?? "(none - offline mode)"}`);
+    debugLog(`  Domain: ${context.workflowId}`);
+
+    // Create LexSona instance via static factory
+    const instance = await lexsona.LexSona.connect({
+      lexDb: process.env.LEX_DB_PATH,
+      persona: cfg.personaId!,
+      domain: context.workflowId,
+    });
+
+    debugLog("LexSona instance created");
+
+    // Build derive context from workflow context
+    const deriveContext: LexSonaDeriveContext = {
+      domain: context.workflowId,
+      module_id: context.stepKind,
+      taskType: context.hints?.task as string | undefined,
+    };
+
+    debugLog("Deriving constraints with context:", deriveContext);
+
+    // Derive constraints
+    const constraintSet = await instance.deriveConstraints(deriveContext);
+
+    debugLog("Constraints derived successfully");
+    debugLog(`  Total constraints: ${constraintSet.constraints.length}`);
+    debugLog(`  Rules considered: ${constraintSet.metadata.rulesConsidered}`);
+    debugLog(`  Rules filtered: ${constraintSet.metadata.rulesFiltered}`);
+    debugLog(`  Confidence threshold: ${constraintSet.metadata.confidenceThreshold}`);
+    debugLog(`  Offline mode: ${constraintSet.metadata.offlineMode}`);
+
+    // Log each constraint
+    if (constraintSet.constraints.length > 0) {
+      debugLog("Constraints:");
+      for (const c of constraintSet.constraints) {
+        debugLog(`  - [${c.severity}] ${c.text} (confidence: ${(c.confidence * 100).toFixed(0)}%)`);
+      }
+    } else {
+      debugLog("No constraints derived");
+    }
+
+    // Convert to snapshot
+    const snapshot = toConstraintSnapshot(constraintSet);
+
+    debugLog("Final snapshot:", JSON.stringify(snapshot, null, 2));
+
+    return {
+      success: true,
+      personaId: cfg.personaId,
+      constraintSet: snapshot,
+      offlineMode: constraintSet.metadata.offlineMode,
+      confidenceCeiling: constraintSet.metadata.confidenceCeiling,
+      derivedAt,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    debugLog("Error during derivation:", errorMessage);
+    debugLog("Stack:", error instanceof Error ? error.stack : "(no stack)");
+
+    // Check for PersonaRequiresMemoryError
+    const isMemoryError = errorMessage.includes("requires_memory");
+    if (isMemoryError) {
+      debugLog("Detected PersonaRequiresMemoryError");
+    }
+
+    return {
+      success: false,
+      personaId: cfg.personaId,
+      constraintSet: null,
+      error: errorMessage,
+      offlineMode: !cfg.hasLexConnection,
+      derivedAt,
+    };
+  }
+}
+
+/**
+ * Generate a unique ID for governance comparison logs
+ */
+export function generateGovernanceLogId(): string {
+  return `gov-${ulid()}`;
+}
+
+/**
+ * Format a shadow governance result as a console summary
+ *
+ * Returns a colored string showing:
+ * - Persona ID
+ * - Constraint count
+ * - Agreement/disagreement with runner
+ * - Top constraints (if any)
+ */
+export function formatShadowGovernanceSummary(
+  shadowResult: LexSonaShadowResult,
+  runnerSignals: RunnerGovernanceSignals,
+  opts: { noColor?: boolean } = {}
+): string {
+  const lines: string[] = [];
+
+  if (!shadowResult.success) {
+    const prefix = opts.noColor ? "[LexSona shadow]" : chalk.yellow("[LexSona shadow]");
+    lines.push(`${prefix} ${shadowResult.personaId ?? "unknown"}: ERROR - ${shadowResult.error}`);
+    return lines.join("\n");
+  }
+
+  const constraintCount = shadowResult.constraintSet?.constraintCount ?? 0;
+  const runnerEligible = runnerSignals.mergeEligible ?? false;
+  const lexsonaBlocking = constraintCount > 0;
+
+  // Determine agreement status
+  let statusText: string;
+  let statusColor: (text: string) => string;
+  if (runnerEligible && !lexsonaBlocking) {
+    statusText = "AGREES";
+    statusColor = opts.noColor ? (t) => t : chalk.green;
+  } else if (runnerEligible && lexsonaBlocking) {
+    statusText = "WOULD BLOCK";
+    statusColor = opts.noColor ? (t) => t : chalk.yellow;
+  } else if (!runnerEligible && lexsonaBlocking) {
+    statusText = "AGREES (both block)";
+    statusColor = opts.noColor ? (t) => t : chalk.green;
+  } else {
+    statusText = "DISAGREES (runner blocks, LexSona allows)";
+    statusColor = opts.noColor ? (t) => t : chalk.cyan;
+  }
+
+  // Main status line
+  const prefix = opts.noColor ? "[LexSona shadow]" : chalk.blue("[LexSona shadow]");
+  const persona = shadowResult.personaId ?? "unknown";
+  const runnerStatus = runnerEligible ? "allow" : "block";
+
+  lines.push(
+    `${prefix} ${persona}: ${constraintCount} constraints, ${statusColor(
+      statusText
+    )} (runner: ${runnerStatus})`
+  );
+
+  // Show top constraints if any
+  if (constraintCount > 0 && shadowResult.constraintSet) {
+    const topConstraints = shadowResult.constraintSet.topConstraints.slice(0, 3);
+    for (const constraint of topConstraints) {
+      const confStr = (constraint.confidence * 100).toFixed(0);
+      lines.push(`  - "${constraint.description.slice(0, 60)}" (confidence: ${confStr}%)`);
+    }
+    if (constraintCount > 3) {
+      lines.push(`  ... and ${constraintCount - 3} more`);
+    }
+  }
+
+  // Show offline mode warning if applicable
+  if (shadowResult.offlineMode && shadowResult.constraintSet?.metadata.offlineMode) {
+    const warning = opts.noColor
+      ? "(offline mode - no Lex DB)"
+      : chalk.dim("(offline mode - no Lex DB)");
+    lines.push(`  ${warning}`);
+  }
+
+  return lines.join("\n");
+}