@wazir-dev/cli 1.2.0 → 1.4.0

package/tooling/src/state/db.js

@@ -11,6 +11,21 @@ function hashDescription(description) {
   return crypto.createHash('sha256').update(description).digest('hex');
 }
 
+/**
+ * Normalize a finding description for clustering.
+ * Strips file paths, line numbers, identifiers to produce a canonical pattern.
+ */
+function canonicalizeFindingText(description) {
+  return description
+    .replace(/[a-zA-Z0-9_\-./]+\.[a-zA-Z]{1,4}(:\d+)?/g, '<FILE>')
+    .replace(/line \d+/gi, 'line <N>')
+    .replace(/['"`][\w.]+['"`]/g, '<ID>')
+    .replace(/[0-9a-f]{7,40}/gi, '<HASH>')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
 function ensureStateSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS learnings (
@@ -67,7 +82,54 @@ function ensureStateSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_findings_finding_hash ON findings(finding_hash);
     CREATE INDEX IF NOT EXISTS idx_audit_history_run_id ON audit_history(run_id);
     CREATE INDEX IF NOT EXISTS idx_usage_aggregate_run_id ON usage_aggregate(run_id);
+
+    CREATE TABLE IF NOT EXISTS finding_clusters (
+      id TEXT PRIMARY KEY,
+      canonical_hash TEXT NOT NULL,
+      category TEXT NOT NULL,
+      pattern_description TEXT NOT NULL,
+      finding_hashes TEXT NOT NULL DEFAULT '[]',
+      run_ids TEXT NOT NULL DEFAULT '[]',
+      occurrence_count INTEGER DEFAULT 1,
+      distinct_runs INTEGER DEFAULT 1,
+      first_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      status TEXT NOT NULL DEFAULT 'tally' CHECK(status IN ('tally','candidate','promoted','active','demoted')),
+      promoted_at TEXT,
+      antipattern_id TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS antipattern_candidates (
+      id TEXT PRIMARY KEY,
+      cluster_id TEXT NOT NULL REFERENCES finding_clusters(id),
+      title TEXT NOT NULL,
+      description TEXT NOT NULL,
+      detection_signal TEXT NOT NULL,
+      severity TEXT NOT NULL CHECK(severity IN ('critical','high','medium','low')),
+      scope_roles TEXT DEFAULT 'reviewer',
+      scope_stacks TEXT DEFAULT 'all',
+      evidence_runs TEXT NOT NULL DEFAULT '[]',
+      evidence_count INTEGER DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'proposed' CHECK(status IN ('proposed','accepted','rejected','expired')),
+      proposed_at TEXT NOT NULL DEFAULT (datetime('now')),
+      reviewed_at TEXT,
+      expires_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_finding_clusters_status ON finding_clusters(status);
+    CREATE INDEX IF NOT EXISTS idx_finding_clusters_canonical_hash ON finding_clusters(canonical_hash);
+    CREATE INDEX IF NOT EXISTS idx_antipattern_candidates_status ON antipattern_candidates(status);
   `);
+
+  // Safe migration: add category column to findings if it doesn't exist
+  try {
+    db.exec(`ALTER TABLE findings ADD COLUMN category TEXT DEFAULT ''`);
+  } catch (_) {
+    // Column already exists — ignore
+  }
+
+  // Index on findings.category (must run after migration adds the column)
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_findings_category ON findings(category)`);
 }
 
 // ---------------------------------------------------------------------------
@@ -171,10 +233,11 @@ export function insertFinding(db, record) {
   const id = crypto.randomUUID();
   const findingHash = record.finding_hash ?? hashDescription(record.description);
   const createdAt = new Date().toISOString();
+  const category = record.category || '';
 
   db.prepare(`
-    INSERT INTO findings (id, run_id, phase, source, severity, description, finding_hash, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO findings (id, run_id, phase, source, severity, description, finding_hash, category, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     record.run_id,
@@ -183,9 +246,19 @@ export function insertFinding(db, record) {
     record.severity,
     record.description,
     findingHash,
+    category,
     createdAt,
   );
 
+  // Auto-tally: cluster the finding for the learning pipeline
+  upsertFindingCluster(db, {
+    canonical_hash: hashDescription(canonicalizeFindingText(record.description)),
+    category,
+    pattern_description: canonicalizeFindingText(record.description),
+    finding_hash: findingHash,
+    run_id: record.run_id,
+  });
+
   return id;
 }
 
@@ -273,6 +346,179 @@ export function getUsageSummary(db) {
   return row;
 }
 
+// ---------------------------------------------------------------------------
+// Finding Clusters (Learning Pipeline)
+// ---------------------------------------------------------------------------
+
+export function upsertFindingCluster(db, record) {
+  const existing = db.prepare(`
+    SELECT * FROM finding_clusters WHERE canonical_hash = ?
+  `).get(record.canonical_hash);
+
+  if (existing) {
+    const hashes = JSON.parse(existing.finding_hashes);
+    if (!hashes.includes(record.finding_hash)) {
+      hashes.push(record.finding_hash);
+    }
+    // Track distinct runs from the DB row, not the incoming record
+    const existingRuns = new Set(JSON.parse(existing.run_ids || '[]'));
+    if (record.run_id) existingRuns.add(record.run_id);
+
+    db.prepare(`
+      UPDATE finding_clusters
+      SET finding_hashes = ?,
+          run_ids = ?,
+          occurrence_count = occurrence_count + 1,
+          distinct_runs = ?,
+          last_seen = datetime('now'),
+          category = COALESCE(NULLIF(?, ''), category)
+      WHERE id = ?
+    `).run(
+      JSON.stringify(hashes),
+      JSON.stringify([...existingRuns]),
+      existingRuns.size,
+      record.category || '',
+      existing.id,
+    );
+
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  db.prepare(`
+    INSERT INTO finding_clusters (id, canonical_hash, category, pattern_description, finding_hashes, run_ids, occurrence_count, distinct_runs)
+    VALUES (?, ?, ?, ?, ?, ?, 1, 1)
+  `).run(
+    id,
+    record.canonical_hash,
+    record.category || 'uncategorized',
+    record.pattern_description,
+    JSON.stringify([record.finding_hash]),
+    JSON.stringify(record.run_id ? [record.run_id] : []),
+  );
+
+  return id;
+}
+
+export function getClustersByStatus(db, status) {
+  return db.prepare(`
+    SELECT * FROM finding_clusters
+    WHERE status = ?
+    ORDER BY occurrence_count DESC
+  `).all(status);
+}
+
+export function getClustersReadyForPromotion(db, minOccurrences = 3, minRuns = 2) {
+  return db.prepare(`
+    SELECT * FROM finding_clusters
+    WHERE status = 'tally'
+      AND occurrence_count >= ?
+      AND distinct_runs >= ?
+    ORDER BY occurrence_count DESC
+  `).all(minOccurrences, minRuns);
+}
+
+export function promoteClusterToCandidate(db, clusterId) {
+  db.prepare(`
+    UPDATE finding_clusters
+    SET status = 'candidate',
+        promoted_at = datetime('now')
+    WHERE id = ?
+  `).run(clusterId);
+}
+
+// ---------------------------------------------------------------------------
+// Antipattern Candidates (Learning Pipeline)
+// ---------------------------------------------------------------------------
+
+export function insertAntipatternCandidate(db, record) {
+  const id = crypto.randomUUID();
+  const expiresAt = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(); // 90-day TTL
+
+  db.prepare(`
+    INSERT INTO antipattern_candidates (id, cluster_id, title, description, detection_signal, severity, scope_roles, scope_stacks, evidence_runs, evidence_count, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    record.cluster_id,
+    record.title,
+    record.description,
+    record.detection_signal,
+    record.severity,
+    record.scope_roles || 'reviewer',
+    record.scope_stacks || 'all',
+    JSON.stringify(Array.isArray(record.evidence_runs) ? record.evidence_runs : []),
+    record.evidence_count || 0,
+    expiresAt,
+  );
+
+  return id;
+}
+
+export function getAntipatternCandidatesByStatus(db, status) {
+  return db.prepare(`
+    SELECT * FROM antipattern_candidates
+    WHERE status = ?
+    ORDER BY proposed_at DESC
+  `).all(status);
+}
+
+export function acceptAntipatternCandidate(db, candidateId) {
+  const now = new Date().toISOString();
+  db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'accepted',
+        reviewed_at = ?
+    WHERE id = ?
+  `).run(now, candidateId);
+}
+
+export function rejectAntipatternCandidate(db, candidateId) {
+  const now = new Date().toISOString();
+  // Get the cluster_id before updating so we can reset the cluster
+  const candidate = db.prepare(`SELECT cluster_id FROM antipattern_candidates WHERE id = ?`).get(candidateId);
+  db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'rejected',
+        reviewed_at = ?
+    WHERE id = ?
+  `).run(now, candidateId);
+  // Reset cluster back to 'tally' so the pattern can be re-proposed if it keeps recurring
+  if (candidate) {
+    db.prepare(`UPDATE finding_clusters SET status = 'tally' WHERE id = ?`).run(candidate.cluster_id);
+  }
+}
+
+export function expireStaleAntipatternCandidates(db) {
+  const now = new Date().toISOString();
+  // Get cluster IDs for candidates about to expire so we can reset them
+  const expiring = db.prepare(`
+    SELECT cluster_id FROM antipattern_candidates
+    WHERE status = 'proposed' AND expires_at < ?
+  `).all(now);
+
+  const result = db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'expired'
+    WHERE status = 'proposed'
+      AND expires_at < ?
+  `).run(now);
+
+  // Reset clusters back to 'tally' so patterns can be re-proposed
+  for (const { cluster_id } of expiring) {
+    db.prepare(`UPDATE finding_clusters SET status = 'tally' WHERE id = ?`).run(cluster_id);
+  }
+
+  return result;
+}
+
+export function getActiveLearningsCount(db) {
+  return db.prepare(`
+    SELECT COUNT(*) AS count FROM antipattern_candidates
+    WHERE status = 'accepted'
+  `).get().count;
+}
+
 // ---------------------------------------------------------------------------
 // Stats (for CLI)
 // ---------------------------------------------------------------------------
@@ -283,5 +529,8 @@ export function getStateCounts(db) {
     finding_count: db.prepare('SELECT COUNT(*) AS count FROM findings').get().count,
     audit_count: db.prepare('SELECT COUNT(*) AS count FROM audit_history').get().count,
     usage_count: db.prepare('SELECT COUNT(*) AS count FROM usage_aggregate').get().count,
+    cluster_count: db.prepare('SELECT COUNT(*) AS count FROM finding_clusters').get().count,
+    candidate_count: db.prepare('SELECT COUNT(*) AS count FROM antipattern_candidates WHERE status = ?').get('proposed').count,
+    active_antipattern_count: db.prepare('SELECT COUNT(*) AS count FROM antipattern_candidates WHERE status = ?').get('accepted').count,
   };
 }

package/tooling/src/state/pipeline-state.js

@@ -0,0 +1,262 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PHASE_ORDER = ['init', 'clarify', 'execute', 'verify', 'review', 'complete'];
+
+const STATE_FILE = 'pipeline-state.json';
+
+// ---------------------------------------------------------------------------
+// Atomic file write — temp + rename to prevent corruption
+// ---------------------------------------------------------------------------
+
+function atomicWriteJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+function statePath(stateRoot) {
+  return path.join(stateRoot, STATE_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// Read / Create
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the current pipeline state. Returns null if no state file exists.
+ */
+export function readPipelineState(stateRoot) {
+  const fp = statePath(stateRoot);
+  if (!fs.existsSync(fp)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a fresh pipeline state for a new run.
+ */
+export function createPipelineState(runId, stateRoot) {
+  const state = {
+    run_id: runId,
+    current_phase: 'init',
+    phase_history: [],
+    allowed_transitions: ['clarify'],
+    stop_hook_active: false,
+    artifacts: {},
+    guardrail_results: {},
+    session_id: crypto.randomUUID(),
+    updated_at: new Date().toISOString(),
+  };
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Transitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a transition from currentPhase to nextPhase is valid.
+ * Only forward, sequential transitions are allowed.
+ */
+export function isTransitionAllowed(currentPhase, nextPhase) {
+  const currentIdx = PHASE_ORDER.indexOf(currentPhase);
+  const nextIdx = PHASE_ORDER.indexOf(nextPhase);
+  if (currentIdx === -1 || nextIdx === -1) return false;
+  return nextIdx === currentIdx + 1;
+}
+
+/**
+ * Transition to the next phase. Validates the transition is legal.
+ * Throws on invalid transition or missing state.
+ */
+export function transitionPhase(stateRoot, nextPhase) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found. Call createPipelineState first.');
+  }
+
+  if (!isTransitionAllowed(state.current_phase, nextPhase)) {
+    throw new Error(
+      `Invalid transition: ${state.current_phase} → ${nextPhase}. ` +
+      `Allowed: ${state.current_phase} → ${PHASE_ORDER[PHASE_ORDER.indexOf(state.current_phase) + 1] ?? 'none'}`,
+    );
+  }
+
+  const now = new Date().toISOString();
+
+  // Record the outgoing phase in history
+  state.phase_history.push({
+    phase: state.current_phase,
+    entered_at: state.phase_entered_at ?? state.updated_at,
+    exited_at: now,
+    status: 'completed',
+  });
+
+  // Move to new phase
+  state.current_phase = nextPhase;
+  state.phase_entered_at = now;
+
+  // Compute next allowed transition
+  const nextIdx = PHASE_ORDER.indexOf(nextPhase);
+  state.allowed_transitions = nextIdx < PHASE_ORDER.length - 1
+    ? [PHASE_ORDER[nextIdx + 1]]
+    : [];
+
+  state.updated_at = now;
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Phase completion (artifact recording)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark the current phase as having produced artifacts.
+ * artifacts: { name: { path: string } }
+ */
+export function completePhase(stateRoot, phase, artifacts = {}) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found.');
+  }
+
+  const now = new Date().toISOString();
+
+  for (const [name, meta] of Object.entries(artifacts)) {
+    const digest = meta.path ? computeArtifactDigest(meta.path) : null;
+    state.artifacts[name] = {
+      path: meta.path,
+      digest,
+      created_at: now,
+    };
+  }
+
+  state.guardrail_results[phase] = { passed: true, checked_at: now };
+  state.updated_at = now;
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Stop hook flag
+// ---------------------------------------------------------------------------
+
+/**
+ * Set or clear the stop_hook_active flag to prevent infinite loops.
+ */
+export function setStopHookActive(stateRoot, active) {
+  const state = readPipelineState(stateRoot);
+  if (!state) {
+    throw new Error('No pipeline state found.');
+  }
+  state.stop_hook_active = !!active;
+  state.updated_at = new Date().toISOString();
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Artifact dependency graph
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical artifact dependency graph for the pipeline.
+ * Each artifact lists the artifacts it requires as inputs.
+ */
+export const ARTIFACT_DEPENDENCY_GRAPH = {
+  'clarification.md': { requires: [] },
+  'spec-hardened.md': { requires: ['clarification.md'] },
+  'design.md': { requires: ['spec-hardened.md'] },
+  'execution-plan.md': { requires: ['design.md'] },
+};
+
+/**
+ * Store artifact dependencies in pipeline state.
+ */
+export function setArtifactDependencies(stateRoot, depGraph) {
+  const state = readPipelineState(stateRoot);
+  if (!state) throw new Error('No pipeline state found.');
+  state.artifact_dependencies = depGraph;
+  state.updated_at = new Date().toISOString();
+  atomicWriteJson(statePath(stateRoot), state);
+  return state;
+}
+
+/**
+ * Compute all artifacts downstream of a changed artifact.
+ * Walks the dependency graph to find everything that transitively requires
+ * the changed artifact.
+ *
+ * @param {string} changedArtifact — the artifact that was modified
+ * @param {object} depGraph — the dependency graph
+ * @returns {string[]} downstream artifact names
+ */
+export function computeDownstreamArtifacts(changedArtifact, depGraph) {
+  const downstream = [];
+  const visited = new Set();
+
+  function walk(target) {
+    for (const [name, meta] of Object.entries(depGraph)) {
+      if (visited.has(name)) continue;
+      if (meta.requires.includes(target)) {
+        visited.add(name);
+        downstream.push(name);
+        walk(name);
+      }
+    }
+  }
+
+  walk(changedArtifact);
+  return downstream;
+}
+
+/**
+ * Classify the mutation level of a changed artifact.
+ *
+ * - L0 (cosmetic): unknown artifact, no graph impact
+ * - L1 (local): leaf artifact with no downstream dependents
+ * - L2 (structural): mid-graph artifact with some downstream dependents
+ * - L3 (fundamental): root artifact — everything downstream is affected
+ *
+ * @param {string} changedArtifact
+ * @param {object} depGraph
+ * @returns {'L0'|'L1'|'L2'|'L3'}
+ */
+export function classifyMutation(changedArtifact, depGraph) {
+  if (!(changedArtifact in depGraph)) return 'L0';
+
+  const downstream = computeDownstreamArtifacts(changedArtifact, depGraph);
+  const entry = depGraph[changedArtifact];
+
+  // Root artifact (no requirements) with downstream dependents
+  if (entry.requires.length === 0 && downstream.length > 0) return 'L3';
+
+  // Mid-graph: has downstream dependents
+  if (downstream.length > 0) return 'L2';
+
+  // Leaf: no downstream dependents
+  return 'L1';
+}
+
+// ---------------------------------------------------------------------------
+// Artifact digest
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute sha256 digest of a file. Returns null if file doesn't exist.
+ */
+export function computeArtifactDigest(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  const hash = crypto.createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}

package/tooling/src/status/command.js

@@ -54,7 +54,12 @@ function success(payload, options = {}) {
     };
   }
 
-  let output = `${payload.run_id} ${payload.phase} ${payload.status}\n`;
+  const parentPhase = payload.parent_phase ?? payload.phase;
+  const workflow = payload.workflow;
+  const phaseLabel = workflow
+    ? `Phase: ${parentPhase} > Workflow: ${workflow}`
+    : `Phase: ${parentPhase}`;
+  let output = `${payload.run_id} ${phaseLabel} ${payload.status}\n`;
 
   if (payload.savings_summary) {
     output += `${payload.savings_summary}\n`;