@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/intake/classify.mjs

@@ -0,0 +1,278 @@
+/**
+ * lib/intake/classify.mjs — R&D triage classification for intake packets.
+ *
+ * Deterministic, keyword-driven classifier that maps a raw intake signal
+ * onto the R&D loop: intakeType (what kind of work), rdStage (where in
+ * the loop), primaryOwner persona, recommendedChain (handoff sequence),
+ * recommendedAction, risk, requiresApproval, confidence, rationale.
+ *
+ * NO LLM call. The daemon path must remain synchronous and cheap; intent
+ * verification belongs in offline measurement, not inline classification.
+ * Persona names match agents/registry.json (unprefixed).
+ */
+
+import path from 'node:path';
+
+export const INTAKE_TYPES = [
+  'user-signal',
+  'bug',
+  'requirement',
+  'research',
+  'experiment',
+  'eval-finding',
+  'architecture',
+  'incident',
+  'launch-asset',
+  'ops',
+  'security',
+  'legal-compliance',
+  'unknown',
+];
+
+export const RD_STAGES = [
+  'signal',
+  'framing',
+  'hypothesis',
+  'research',
+  'artifact',
+  'design',
+  'implementation',
+  'evaluation',
+  'release',
+  'operations',
+  'unknown',
+];
+
+export const RECOMMENDED_ACTIONS = [
+  'summarize',
+  'clarify',
+  'research',
+  'create-hypothesis',
+  'draft-prd',
+  'draft-rfc',
+  'draft-adr',
+  'create-experiment',
+  'diagnose',
+  'implement',
+  'evaluate',
+  'release-review',
+  'create-runbook',
+  'archive',
+];
+
+/**
+ * Classification table — intakeType → triage spine.
+ * Keyword set drives detection; the rest of the row is the canonical mapping
+ * for that signal class. Order matters for tie-breaking: earlier rows win on
+ * equal raw scores so that high-stakes classes (security, incident) take
+ * precedence over generic ones (research) when keywords overlap.
+ */
+const CLASSIFICATION_TABLE = [
+  {
+    intakeType: 'security',
+    keywords: ['security', 'secret', 'cve', 'vulnerability', 'vuln', 'exploit', 'leak', 'auth bypass', 'privilege escalation', 'sqli', 'xss', 'csrf', 'rce'],
+    rdStage: 'operations',
+    primaryOwner: 'security',
+    recommendedChain: ['security', 'engineer', 'reviewer'],
+    recommendedAction: 'diagnose',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'incident',
+    keywords: ['incident', 'outage', 'slo breach', 'sla breach', 'latency spike', 'availability', 'down', 'p0 ', 'p1 ', 'pagerduty', '5xx', 'oncall'],
+    rdStage: 'operations',
+    primaryOwner: 'sre',
+    recommendedChain: ['sre', 'debugger', 'platform-engineer'],
+    recommendedAction: 'create-runbook',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'legal-compliance',
+    keywords: ['gdpr', 'ccpa', 'hipaa', 'sox', 'soc2', 'license', 'lawsuit', 'dpa', 'data retention', 'pii', 'subpoena', 'compliance audit'],
+    rdStage: 'operations',
+    primaryOwner: 'legal-compliance',
+    recommendedChain: ['legal-compliance', 'security', 'product-manager'],
+    recommendedAction: 'clarify',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'architecture',
+    keywords: ['architecture', 'adr', 'rfc', 'interface', 'tradeoff', 'boundary', 'system design', 'data model', 'api contract', 'migration plan'],
+    rdStage: 'design',
+    primaryOwner: 'architect',
+    recommendedChain: ['architect', 'devil-advocate', 'engineer'],
+    recommendedAction: 'draft-rfc',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'eval-finding',
+    keywords: ['eval', 'evaluation', 'hallucination', 'judge', 'trace', 'score regression', 'recall@', 'precision@', 'mrr', 'ndcg', 'failure case', 'rubric'],
+    rdStage: 'evaluation',
+    primaryOwner: 'evaluator',
+    recommendedChain: ['evaluator', 'ai-engineer', 'trace-reviewer'],
+    recommendedAction: 'evaluate',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'bug',
+    keywords: ['bug', 'broken', 'error', 'stack trace', 'regression', 'crash', 'exception', 'fails', 'failing', 'throws', 'not working', 'reproduce', 'repro:'],
+    rdStage: 'implementation',
+    primaryOwner: 'debugger',
+    recommendedChain: ['debugger', 'engineer', 'qa', 'reviewer'],
+    recommendedAction: 'diagnose',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'experiment',
+    keywords: ['hypothesis', 'experiment', 'spike', 'prototype', 'falsifiable', 'research question', 'a/b test', 'pilot'],
+    rdStage: 'hypothesis',
+    primaryOwner: 'rd-lead',
+    recommendedChain: ['rd-lead', 'researcher', 'evaluator'],
+    recommendedAction: 'create-experiment',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'launch-asset',
+    keywords: ['release', 'changelog', 'version bump', 'ship', 'launch', 'rollout', 'cut a release', 'rc1', 'rc2', 'release candidate'],
+    rdStage: 'release',
+    primaryOwner: 'release-manager',
+    recommendedChain: ['release-manager', 'qa', 'docs-keeper'],
+    recommendedAction: 'release-review',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'research',
+    keywords: ['competitor', 'market', 'pricing', 'positioning', 'industry', 'state of the art', 'literature', 'benchmark study', 'desk research'],
+    rdStage: 'research',
+    primaryOwner: 'business-strategist',
+    recommendedChain: ['business-strategist', 'researcher', 'product-manager'],
+    recommendedAction: 'research',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'user-signal',
+    keywords: ['customer', 'feedback', 'pain point', 'user says', 'user feedback', 'support ticket', 'churn', 'nps', 'usability', 'frustrated'],
+    rdStage: 'signal',
+    primaryOwner: 'product-manager',
+    recommendedChain: ['product-manager', 'ux-researcher', 'researcher'],
+    recommendedAction: 'clarify',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'requirement',
+    keywords: ['acceptance criteria', 'requirement', 'must have', 'should have', 'feature request', 'prd', 'use case', 'success metric'],
+    rdStage: 'framing',
+    primaryOwner: 'product-manager',
+    recommendedChain: ['product-manager', 'architect', 'engineer'],
+    recommendedAction: 'draft-prd',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'ops',
+    keywords: ['runbook', 'cron', 'scheduled job', 'maintenance', 'backup', 'restore', 'capacity plan', 'cost optimization', 'dependency upgrade'],
+    rdStage: 'operations',
+    primaryOwner: 'operations',
+    recommendedChain: ['operations', 'sre', 'engineer'],
+    recommendedAction: 'create-runbook',
+    risk: 'low',
+    requiresApproval: false,
+  },
+];
+
+const UNKNOWN_TRIAGE = {
+  intakeType: 'unknown',
+  rdStage: 'unknown',
+  primaryOwner: 'orchestrator',
+  recommendedChain: ['orchestrator'],
+  recommendedAction: 'summarize',
+  risk: 'low',
+  requiresApproval: false,
+};
+
+function normalize(text) {
+  return String(text || '').toLowerCase();
+}
+
+function countMatches(haystack, keywords) {
+  let hits = 0;
+  const matched = [];
+  for (const kw of keywords) {
+    if (haystack.includes(kw)) {
+      hits += 1;
+      matched.push(kw);
+    }
+  }
+  return { hits, matched };
+}
+
+function buildSignalText({ sourcePath, extractedText, related }) {
+  const basename = sourcePath ? path.basename(sourcePath) : '';
+  const slug = basename.replace(/[._-]/g, ' ');
+  const body = extractedText ? extractedText.slice(0, 4000) : '';
+  const relatedTitles = (related || []).map((r) => r?.title || '').join(' ');
+  return normalize(`${slug} ${body} ${relatedTitles}`);
+}
+
+/**
+ * Classify an R&D intake signal.
+ *
+ * Returns a triage object with: intakeType, rdStage, primaryOwner,
+ * recommendedChain, recommendedAction, risk, requiresApproval, confidence,
+ * rationale. The function is pure and deterministic; same input → same output.
+ */
+export function classifyRdIntake({ sourcePath = '', extractedText = '', related = [] } = {}) {
+  const signal = buildSignalText({ sourcePath, extractedText, related });
+
+  let best = null;
+  for (const entry of CLASSIFICATION_TABLE) {
+    const { hits, matched } = countMatches(signal, entry.keywords);
+    if (hits === 0) continue;
+    if (!best || hits > best.hits) {
+      best = { entry, hits, matched };
+    }
+  }
+
+  if (!best) {
+    return {
+      ...UNKNOWN_TRIAGE,
+      confidence: 0.3,
+      rationale: 'No classification keywords matched filename, content excerpt, or related-doc titles.',
+    };
+  }
+
+  const { entry, hits, matched } = best;
+  const confidence = Math.min(1, 0.4 + 0.2 * hits);
+  const matchedList = matched.slice(0, 4).join(', ');
+  const rationale = `Matched ${hits} keyword${hits === 1 ? '' : 's'} for ${entry.intakeType}: ${matchedList}.`;
+
+  return {
+    intakeType: entry.intakeType,
+    rdStage: entry.rdStage,
+    primaryOwner: entry.primaryOwner,
+    recommendedChain: [...entry.recommendedChain],
+    recommendedAction: entry.recommendedAction,
+    risk: entry.risk,
+    requiresApproval: entry.requiresApproval,
+    confidence,
+    rationale,
+  };
+}
+
+export function formatTriageLine(sourcePath, triage) {
+  const basename = sourcePath ? path.basename(sourcePath) : '(unknown source)';
+  if (!triage || triage.intakeType === 'unknown') {
+    return `${basename} → unclassified · owner: orchestrator · next: summarize`;
+  }
+  return `${basename} → ${triage.intakeType} / ${triage.rdStage} · owner: ${triage.primaryOwner} · next: ${triage.recommendedAction}`;
+}

package/lib/intake/feedback.mjs

@@ -0,0 +1,273 @@
+/**
+ * lib/intake/feedback.mjs — Classification feedback system.
+ *
+ * Allows users to flag incorrect intake classifications. Feedback adjusts
+ * keyword weights, tracks accuracy per intake type, and surfaces patterns.
+ *
+ * Storage:
+ *   .cx/intake/feedback.jsonl — Append-only log of all feedback
+ *   .cx/intake/accuracy.json — Aggregated accuracy metrics by type
+ *
+ * Usage:
+ *   const feedback = createClassificationFeedback({ intakeId, original, corrected, reason });
+ *   await recordFeedback(rootDir, feedback);
+ *   const stats = getAccuracyStats(rootDir);
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLockSync } from '../storage/file-lock.mjs';
+
+const FEEDBACK_FILE = 'feedback.jsonl';
+const ACCURACY_FILE = 'accuracy.json';
+const FEEDBACK_DIR = '.cx/intake';
+
+const VALID_CORRECTION_TYPES = [
+  'intakeType',
+  'rdStage',
+  'primaryOwner',
+  'recommendedChain',
+  'recommendedAction',
+  'risk',
+];
+
+const VALID_REASONS = [
+  'wrong-category',
+  'wrong-stage',
+  'wrong-owner',
+  'wrong-chain',
+  'wrong-action',
+  'wrong-risk',
+  'multiple-errors',
+  'other',
+];
+
+export function createClassificationFeedback({
+  intakeId,
+  original,
+  corrected,
+  reason,
+  userId = null,
+  sessionId = null,
+}) {
+  if (!intakeId) throw new Error('intakeId is required');
+  if (!original || typeof original !== 'object') throw new Error('original classification is required');
+  if (!corrected || typeof corrected !== 'object') throw new Error('corrected classification is required');
+
+  const feedback = {
+    id: `fb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    intakeId,
+    timestamp: new Date().toISOString(),
+    original,
+    corrected,
+    reason: VALID_REASONS.includes(reason) ? reason : 'other',
+    userId,
+    sessionId,
+    applied: false,
+  };
+
+  // Validate that corrections are meaningful
+  const changes = compareClassifications(original, corrected);
+  if (changes.length === 0) {
+    feedback.rejected = true;
+    feedback.rejectionReason = 'No meaningful changes detected';
+  }
+
+  return feedback;
+}
+
+export function compareClassifications(original, corrected) {
+  const changes = [];
+  
+  if (original.intakeType !== corrected.intakeType) {
+    changes.push({ field: 'intakeType', from: original.intakeType, to: corrected.intakeType });
+  }
+  if (original.rdStage !== corrected.rdStage) {
+    changes.push({ field: 'rdStage', from: original.rdStage, to: corrected.rdStage });
+  }
+  if (original.primaryOwner !== corrected.primaryOwner) {
+    changes.push({ field: 'primaryOwner', from: original.primaryOwner, to: corrected.primaryOwner });
+  }
+  if (JSON.stringify(original.recommendedChain) !== JSON.stringify(corrected.recommendedChain)) {
+    changes.push({ field: 'recommendedChain', from: original.recommendedChain, to: corrected.recommendedChain });
+  }
+  if (original.recommendedAction !== corrected.recommendedAction) {
+    changes.push({ field: 'recommendedAction', from: original.recommendedAction, to: corrected.recommendedAction });
+  }
+  if (original.risk !== corrected.risk) {
+    changes.push({ field: 'risk', from: original.risk, to: corrected.risk });
+  }
+  
+  return changes;
+}
+
+export function recordFeedback(rootDir, feedback) {
+  const feedbackPath = path.join(rootDir, FEEDBACK_DIR, FEEDBACK_FILE);
+  
+  // Ensure directory exists
+  fs.mkdirSync(path.dirname(feedbackPath), { recursive: true });
+  
+  // Append to JSONL file
+  const line = JSON.stringify(feedback) + '\n';
+  fs.appendFileSync(feedbackPath, line);
+  
+  // Update accuracy metrics
+  updateAccuracyMetrics(rootDir, feedback);
+  
+  return feedback;
+}
+
+export function updateAccuracyMetrics(rootDir, feedback) {
+  if (feedback.rejected) return;
+  
+  const accuracyPath = path.join(rootDir, FEEDBACK_DIR, ACCURACY_FILE);
+  
+  withFileLockSync(accuracyPath, () => {
+    let metrics = { lastUpdated: new Date().toISOString(), byType: {}, byOwner: {}, total: 0, corrected: 0 };
+    
+    if (fs.existsSync(accuracyPath)) {
+      try {
+        metrics = JSON.parse(fs.readFileSync(accuracyPath, 'utf8'));
+      } catch {
+        // Start fresh if corrupted
+      }
+    }
+    
+    // Update totals
+    metrics.total++;
+    if (!feedback.rejected) metrics.corrected++;
+    
+    // Update by intake type
+    const originalType = feedback.original.intakeType || 'unknown';
+    if (!metrics.byType[originalType]) {
+      metrics.byType[originalType] = { total: 0, corrected: 0 };
+    }
+    metrics.byType[originalType].total++;
+    if (!feedback.rejected) metrics.byType[originalType].corrected++;
+    
+    // Update by owner
+    const originalOwner = feedback.original.primaryOwner || 'unknown';
+    if (!metrics.byOwner[originalOwner]) {
+      metrics.byOwner[originalOwner] = { total: 0, corrected: 0 };
+    }
+    metrics.byOwner[originalOwner].total++;
+    if (!feedback.rejected) metrics.byOwner[originalOwner].corrected++;
+    
+    metrics.lastUpdated = new Date().toISOString();
+    
+    fs.writeFileSync(accuracyPath, JSON.stringify(metrics, null, 2) + '\n');
+  });
+}
+
+export function getAccuracyStats(rootDir) {
+  const accuracyPath = path.join(rootDir, FEEDBACK_DIR, ACCURACY_FILE);
+  
+  if (!fs.existsSync(accuracyPath)) {
+    return {
+      overall: { total: 0, corrected: 0, accuracy: 1.0 },
+      byType: {},
+      byOwner: {},
+      message: 'No feedback recorded yet',
+    };
+  }
+  
+  try {
+    const metrics = JSON.parse(fs.readFileSync(accuracyPath, 'utf8'));
+    
+    const overall = {
+      total: metrics.total || 0,
+      corrected: metrics.corrected || 0,
+      accuracy: metrics.total > 0 ? 1 - (metrics.corrected / metrics.total) : 1.0,
+    };
+    
+    const byType = {};
+    for (const [type, data] of Object.entries(metrics.byType || {})) {
+      byType[type] = {
+        total: data.total,
+        corrected: data.corrected,
+        accuracy: data.total > 0 ? 1 - (data.corrected / data.total) : 1.0,
+      };
+    }
+    
+    const byOwner = {};
+    for (const [owner, data] of Object.entries(metrics.byOwner || {})) {
+      byOwner[owner] = {
+        total: data.total,
+        corrected: data.corrected,
+        accuracy: data.total > 0 ? 1 - (data.corrected / data.total) : 1.0,
+      };
+    }
+    
+    return { overall, byType, byOwner };
+  } catch (err) {
+    return {
+      overall: { total: 0, corrected: 0, accuracy: 1.0 },
+      byType: {},
+      byOwner: {},
+      error: err.message,
+    };
+  }
+}
+
+export function getFeedbackHistory(rootDir, options = {}) {
+  const { limit = 50, intakeId = null, offset = 0 } = options;
+  const feedbackPath = path.join(rootDir, FEEDBACK_DIR, FEEDBACK_FILE);
+  
+  if (!fs.existsSync(feedbackPath)) {
+    return [];
+  }
+  
+  const lines = fs.readFileSync(feedbackPath, 'utf8').trim().split('\n').filter(Boolean);
+  const feedback = [];
+  
+  for (let i = lines.length - 1; i >= 0 && feedback.length < limit + offset; i--) {
+    try {
+      const entry = JSON.parse(lines[i]);
+      
+      if (intakeId && entry.intakeId !== intakeId) continue;
+      
+      if (feedback.length >= offset) {
+        feedback.push(entry);
+      }
+    } catch {
+      // Skip malformed lines
+    }
+  }
+  
+  return feedback;
+}
+
+/**
+ * Get keyword adjustment suggestions based on feedback patterns.
+ * Analyzes which keywords led to misclassifications and suggests weight adjustments.
+ */
+export function getKeywordAdjustments(rootDir) {
+  const feedback = getFeedbackHistory(rootDir, { limit: 200 });
+  const adjustments = [];
+  
+  // Group by original vs corrected intake type
+  const patterns = {};
+  for (const fb of feedback) {
+    if (fb.rejected) continue;
+    
+    const key = `${fb.original.intakeType}->${fb.corrected.intakeType}`;
+    if (!patterns[key]) patterns[key] = [];
+    patterns[key].push(fb);
+  }
+  
+  // Find patterns where certain intake types are frequently confused
+  for (const [pattern, cases] of Object.entries(patterns)) {
+    if (cases.length >= 3) {
+      const [from, to] = pattern.split('->');
+      adjustments.push({
+        pattern,
+        fromType: from,
+        toType: to,
+        frequency: cases.length,
+        suggestion: `Review keywords for ${from} — frequently confused with ${to}`,
+      });
+    }
+  }
+  
+  return adjustments.sort((a, b) => b.frequency - a.frequency);
+}