@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/sidecars/provenance-summary.js

@@ -0,0 +1,238 @@
+/**
+ * @fileoverview Provenance Summarization Sidecar
+ * Compact summary of all work performed on a spec: files touched,
+ * commands run, validation/evaluation progression, gate results over time.
+ * Used for merge readiness assessment or handoff.
+ * @author @darianrosebrook
+ */
+
+const path = require('path');
+const { createSidecarOutput, createNoStateOutput } = require('./schema');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Group file paths by their top-level directory.
+ * e.g. "src/auth/login.js" -> "src/", "README.md" -> "./"
+ * @param {string[]} files
+ * @returns {Object<string, number>}
+ */
+function groupByDirectory(files) {
+  const groups = {};
+  for (const f of files) {
+    const dir = path.dirname(f);
+    const topLevel = dir === '.' ? './' : dir.split(path.sep)[0] + '/';
+    groups[topLevel] = (groups[topLevel] || 0) + 1;
+  }
+  return groups;
+}
+
+/**
+ * Count commands from history entries.
+ * @param {Array<{command: string}>} history
+ * @returns {Object<string, number>}
+ */
+function countCommands(history) {
+  const counts = {};
+  for (const entry of history) {
+    if (entry.command) {
+      counts[entry.command] = (counts[entry.command] || 0) + 1;
+    }
+  }
+  return counts;
+}
+
+/**
+ * Parse evaluation summary strings like "85/100 (85%) Grade B".
+ * @param {string} summary
+ * @returns {{ percentage: number, grade: string } | null}
+ */
+function parseEvalSummary(summary) {
+  if (!summary) return null;
+  const m = summary.match(/(\d+)\/\d+ \((\d+)%\) Grade (\w+)/);
+  if (!m) return null;
+  return { percentage: Number(m[2]), grade: m[3] };
+}
+
+/**
+ * Parse validation summary — "passed" or "failed with N errors".
+ * @param {string} summary
+ * @returns {{ passed: boolean } | null}
+ */
+function parseValidationSummary(summary) {
+  if (!summary) return null;
+  const lower = summary.toLowerCase();
+  if (lower.startsWith('passed') || lower === 'pass') return { passed: true };
+  if (lower.startsWith('failed') || lower === 'fail') return { passed: false };
+  return null;
+}
+
+/**
+ * Parse gates summary — "5 passed, 2 blocked".
+ * @param {string} summary
+ * @returns {{ blocked: number } | null}
+ */
+function parseGatesSummary(summary) {
+  if (!summary) return null;
+  const m = summary.match(/(\d+)\s+passed,\s+(\d+)\s+blocked/);
+  if (!m) return null;
+  return { blocked: Number(m[2]) };
+}
+
+/**
+ * Extract progression arrays from history entries.
+ * @param {Array<{command: string, summary: string, timestamp: string}>} history
+ * @returns {object}
+ */
+function extractProgression(history) {
+  const validation = [];
+  const evaluation = [];
+  const gates = [];
+
+  for (const entry of history) {
+    const ts = entry.timestamp;
+    if (entry.command === 'validate') {
+      const parsed = parseValidationSummary(entry.summary);
+      if (parsed) validation.push({ timestamp: ts, ...parsed });
+    } else if (entry.command === 'evaluate') {
+      const parsed = parseEvalSummary(entry.summary);
+      if (parsed) evaluation.push({ timestamp: ts, ...parsed });
+    } else if (entry.command === 'gates') {
+      const parsed = parseGatesSummary(entry.summary);
+      if (parsed) gates.push({ timestamp: ts, ...parsed });
+    }
+  }
+
+  return { validation, evaluation, gates };
+}
+
+/**
+ * Build the current status snapshot from top-level state fields.
+ * @param {object} state
+ * @returns {object}
+ */
+function buildCurrentStatus(state) {
+  const status = {};
+  if (state.validation) {
+    status.validation = {
+      passed: !!state.validation.passed,
+      grade: state.validation.grade || null,
+      compliance_score: state.validation.compliance_score != null ? state.validation.compliance_score : null,
+    };
+  }
+  if (state.evaluation) {
+    status.evaluation = {
+      percentage: state.evaluation.percentage != null ? state.evaluation.percentage : null,
+      grade: state.evaluation.grade || null,
+    };
+  }
+  if (state.gates) {
+    status.gates = {
+      passed: !!state.gates.passed,
+      blocked_count: state.gates.blocked_count != null ? state.gates.blocked_count : 0,
+    };
+  }
+  if (state.acceptance_criteria) {
+    const ac = state.acceptance_criteria;
+    status.acceptance_criteria = {
+      total: ac.total || 0,
+      pass: ac.pass || 0,
+      fail: ac.fail || 0,
+      unchecked: ac.unchecked || 0,
+    };
+  }
+  return status;
+}
+
+/**
+ * Compute merge readiness and list of missing items.
+ * @param {object} state
+ * @returns {{ ready: boolean, missing: string[] }}
+ */
+function computeMergeReadiness(state) {
+  const missing = [];
+
+  if (!state.validation || !state.validation.passed) {
+    missing.push('Validation not passing');
+  }
+
+  const evalPct = state.evaluation ? state.evaluation.percentage : null;
+  if (evalPct == null || evalPct < 90) {
+    missing.push(evalPct != null ? `Evaluation at ${evalPct}% (need 90%)` : 'No evaluation run');
+  }
+
+  if (state.acceptance_criteria) {
+    if (state.acceptance_criteria.fail > 0) {
+      missing.push(`${state.acceptance_criteria.fail} ACs failing`);
+    }
+    if (state.acceptance_criteria.unchecked > 0) {
+      missing.push(`${state.acceptance_criteria.unchecked} ACs unchecked`);
+    }
+  } else {
+    missing.push('No AC verification run');
+  }
+
+  if (!state.gates || !state.gates.passed) {
+    missing.push('Gates not passing');
+  }
+
+  const ready = state.phase === 'complete' && missing.length === 0;
+  return { ready, missing };
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarize provenance for a spec's working state.
+ * @param {object|null} state - Working state from loadState()
+ * @param {object} [spec] - The resolved spec (for id/title)
+ * @returns {object} Sidecar output envelope
+ */
+function summarizeProvenance(state, spec) {
+  if (!state) {
+    return createNoStateOutput('provenance', (spec && spec.id) || 'unknown');
+  }
+
+  const specId = (spec && spec.id) || state.spec_id || 'unknown';
+  const specTitle = (spec && spec.title) || '';
+  const files = state.files_touched || [];
+  const history = state.history || [];
+
+  const filesTouched = {
+    total: files.length,
+    by_directory: groupByDirectory(files),
+  };
+
+  const commandHistory = countCommands(history);
+  const progression = extractProgression(history);
+  const currentStatus = buildCurrentStatus(state);
+  const mergeReadiness = computeMergeReadiness(state);
+
+  const totalCommands = history.length;
+  const evalPct = state.evaluation ? state.evaluation.percentage : null;
+  const summaryParts = [`${files.length} files touched`, `${totalCommands} commands run`];
+  if (evalPct != null) summaryParts.push(`evaluation at ${evalPct}%`);
+  if (mergeReadiness.missing.length > 0) {
+    summaryParts.push(mergeReadiness.missing[0].toLowerCase());
+  }
+
+  const data = {
+    spec_id: specId,
+    spec_title: specTitle,
+    phase: state.phase || 'unknown',
+    files_touched: filesTouched,
+    command_history: commandHistory,
+    progression,
+    current_status: currentStatus,
+    merge_readiness: mergeReadiness,
+    summary: summaryParts.join(', '),
+  };
+
+  return createSidecarOutput('provenance', specId, data);
+}
+
+module.exports = { summarizeProvenance };

package/dist/sidecars/quality-gaps.js

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Quality-Gap Diagnosis Sidecar
+ * Identifies specific gaps preventing phase advancement: validation failures,
+ * low evaluation scores, failing/unchecked ACs, blocking gates.
+ * @author @darianrosebrook
+ */
+
+const { computePhase } = require('../utils/working-state');
+const { createSidecarOutput, createNoStateOutput } = require('./schema');
+
+// ---------------------------------------------------------------------------
+// Phase progression
+// ---------------------------------------------------------------------------
+
+const PHASE_ORDER = [
+  'not-started',
+  'spec-authoring',
+  'implementation',
+  'verification',
+  'complete',
+];
+
+function nextPhase(current) {
+  const idx = PHASE_ORDER.indexOf(current);
+  if (idx < 0 || idx >= PHASE_ORDER.length - 1) return null;
+  return PHASE_ORDER[idx + 1];
+}
+
+// ---------------------------------------------------------------------------
+// Gap detection per transition
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the list of gap objects for advancing from `current` to `target`.
+ * @param {object} state
+ * @param {string} target
+ * @returns {object[]}
+ */
+function detectGaps(state, target) {
+  const gaps = [];
+  const v = state.validation;
+  const e = state.evaluation;
+  const g = state.gates;
+  const ac = state.acceptance_criteria;
+
+  if (target === 'spec-authoring') {
+    // Need any command to have run
+    if (!v && !e && !g && !ac) {
+      gaps.push({
+        category: 'no_evaluation',
+        severity: 'warning',
+        message: 'No commands have been run yet',
+        remediation: 'caws validate',
+      });
+    }
+    return gaps;
+  }
+
+  if (target === 'implementation') {
+    if (v && !v.passed) {
+      gaps.push({
+        category: 'validation_failure',
+        severity: 'blocker',
+        message: `Validation failed with ${v.error_count || 0} error(s)`,
+        remediation: 'caws validate',
+      });
+    }
+    if (!v) {
+      gaps.push({
+        category: 'validation_failure',
+        severity: 'blocker',
+        message: 'Validation has not been run',
+        remediation: 'caws validate',
+      });
+    }
+    if (e && e.percentage < 70) {
+      gaps.push({
+        category: 'low_evaluation',
+        severity: 'blocker',
+        message: `Evaluation score ${e.percentage}% is below 70% threshold`,
+        remediation: 'caws evaluate',
+      });
+    }
+    if (!e) {
+      gaps.push({
+        category: 'no_evaluation',
+        severity: 'warning',
+        message: 'No evaluation has been run',
+        remediation: 'caws evaluate',
+      });
+    }
+    return gaps;
+  }
+
+  if (target === 'verification') {
+    if (ac && ac.fail > 0) {
+      gaps.push({
+        category: 'ac_failure',
+        severity: 'blocker',
+        message: `${ac.fail} acceptance criteria failing`,
+        remediation: 'caws ac check',
+      });
+    }
+    if (ac && ac.unchecked > 0) {
+      gaps.push({
+        category: 'ac_unchecked',
+        severity: 'warning',
+        message: `${ac.unchecked} acceptance criteria unchecked`,
+        remediation: 'caws ac check',
+      });
+    }
+    if (!ac || ac.total === 0) {
+      gaps.push({
+        category: 'no_acs',
+        severity: 'warning',
+        message: 'No acceptance criteria have been defined or checked',
+        remediation: 'caws ac check',
+      });
+    }
+    if (!g) {
+      gaps.push({
+        category: 'no_gates',
+        severity: 'warning',
+        message: 'Gates have not been run',
+        remediation: 'caws gates',
+      });
+    }
+    return gaps;
+  }
+
+  if (target === 'complete') {
+    if (ac && ac.fail > 0) {
+      gaps.push({
+        category: 'ac_failure',
+        severity: 'blocker',
+        message: `${ac.fail} acceptance criteria failing`,
+        remediation: 'caws ac check',
+      });
+    }
+    if (ac && ac.unchecked > 0) {
+      gaps.push({
+        category: 'ac_unchecked',
+        severity: 'warning',
+        message: `${ac.unchecked} acceptance criteria unchecked`,
+        remediation: 'caws ac check',
+      });
+    }
+    if (g && !g.passed) {
+      gaps.push({
+        category: 'gate_failure',
+        severity: 'blocker',
+        message: 'Gates are not passing',
+        remediation: 'caws gates',
+      });
+    }
+    if (!g) {
+      gaps.push({
+        category: 'no_gates',
+        severity: 'warning',
+        message: 'Gates have not been run',
+        remediation: 'caws gates',
+      });
+    }
+    if (e && e.percentage < 90) {
+      gaps.push({
+        category: 'low_evaluation',
+        severity: 'blocker',
+        message: `Evaluation score ${e.percentage}% is below 90% threshold`,
+        remediation: 'caws evaluate',
+      });
+    }
+    if (!e) {
+      gaps.push({
+        category: 'no_evaluation',
+        severity: 'warning',
+        message: 'No evaluation has been run',
+        remediation: 'caws evaluate',
+      });
+    }
+    return gaps;
+  }
+
+  return gaps;
+}
+
+// ---------------------------------------------------------------------------
+// Phase requirements snapshot
+// ---------------------------------------------------------------------------
+
+function buildPhaseRequirements(state, target) {
+  const v = state.validation;
+  const e = state.evaluation;
+  const g = state.gates;
+  const ac = state.acceptance_criteria;
+
+  const reqs = {
+    validation_passed: v ? v.passed === true : false,
+    evaluation_pct: e ? e.percentage : null,
+    evaluation_required: target === 'complete' ? 90 : (target === 'implementation' ? 70 : null),
+    all_acs_pass: ac ? (ac.fail === 0 && ac.unchecked === 0 && ac.total > 0) : false,
+    gates_run: !!g,
+    gates_passed: g ? g.passed === true : false,
+  };
+  return reqs;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Diagnose quality gaps preventing phase advancement.
+ * @param {object|null} state - Working state
+ * @param {object} [spec] - Spec object
+ * @returns {object} Sidecar envelope
+ */
+function diagnoseQualityGaps(state, spec) {
+  if (!state) {
+    return createNoStateOutput('gaps', spec?.id || 'unknown');
+  }
+
+  const currentPhase = computePhase(state, spec);
+  const target = nextPhase(currentPhase);
+
+  if (!target) {
+    // Already complete
+    return createSidecarOutput('gaps', spec?.id || 'unknown', {
+      current_phase: currentPhase,
+      next_phase: null,
+      gaps: [],
+      phase_requirements: buildPhaseRequirements(state, currentPhase),
+      summary: 'No gaps — all phases complete',
+    });
+  }
+
+  const gaps = detectGaps(state, target);
+  // Sort blockers before warnings
+  gaps.sort((a, b) => {
+    if (a.severity === b.severity) return 0;
+    return a.severity === 'blocker' ? -1 : 1;
+  });
+
+  const blockerCount = gaps.filter(g => g.severity === 'blocker').length;
+  const totalCount = gaps.length;
+  const summary = totalCount === 0
+    ? `No gaps blocking advancement to ${target}`
+    : `${totalCount} gap${totalCount !== 1 ? 's' : ''} (${blockerCount} blocker${blockerCount !== 1 ? 's' : ''}) blocking advancement to ${target}`;
+
+  return createSidecarOutput('gaps', spec?.id || 'unknown', {
+    current_phase: currentPhase,
+    next_phase: target,
+    gaps,
+    phase_requirements: buildPhaseRequirements(state, target),
+    summary,
+  });
+}
+
+module.exports = { diagnoseQualityGaps };

package/dist/sidecars/schema.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Shared output schema for governance sidecars.
+ * All sidecars return a consistent envelope with type, specId, timestamp,
+ * status, data (sidecar-specific), and meta.
+ * @author @darianrosebrook
+ */
+
+const chalk = require('chalk');
+
+// ---------------------------------------------------------------------------
+// Envelope constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a sidecar output envelope.
+ * If data contains a `status` field, it is hoisted to the top-level status.
+ * @param {string} type - Sidecar type (e.g. 'drift', 'gaps')
+ * @param {string} specId - The spec this output relates to
+ * @param {object} data - Sidecar-specific payload
+ * @param {object} [meta={}] - Additional metadata
+ * @returns {object} Sidecar output envelope
+ */
+function createSidecarOutput(type, specId, data, meta = {}) {
+  const status = data && data.status ? data.status : 'ok';
+  const cleanData = { ...data };
+  delete cleanData.status;
+
+  return {
+    type: `sidecar:${type}`,
+    specId,
+    timestamp: new Date().toISOString(),
+    status,
+    data: cleanData,
+    meta: { duration_ms: 0, ...meta },
+  };
+}
+
+/**
+ * Shorthand for when the sidecar has no working state to analyze.
+ * @param {string} type - Sidecar type
+ * @param {string} specId - The spec id
+ * @returns {object} Sidecar output envelope with status 'no-state'
+ */
+function createNoStateOutput(type, specId) {
+  return createSidecarOutput(type, specId, {
+    status: 'no-state',
+    message: 'No working state found for this spec',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Per-type text formatters
+// ---------------------------------------------------------------------------
+
+function formatDrift(data) {
+  const lines = [];
+  lines.push(chalk.bold('Drift Analysis'));
+  lines.push(`  Drift detected: ${data.drift_detected ? chalk.red('yes') : chalk.green('no')}`);
+  if (data.out_of_scope_files && data.out_of_scope_files.length > 0) {
+    lines.push(chalk.yellow(`  Out-of-scope files (${data.out_of_scope_files.length}):`));
+    data.out_of_scope_files.forEach(f => lines.push(`    - ${f}`));
+  }
+  if (data.missing_evidence && data.missing_evidence.length > 0) {
+    lines.push(chalk.yellow(`  Missing AC evidence (${data.missing_evidence.length}):`));
+    data.missing_evidence.forEach(ac => lines.push(`    - ${ac.id}: ${ac.description}`));
+  }
+  if (data.failing_criteria && data.failing_criteria.length > 0) {
+    lines.push(chalk.red(`  Failing criteria (${data.failing_criteria.length}):`));
+    data.failing_criteria.forEach(ac => lines.push(`    - ${ac.id}: ${ac.description}`));
+  }
+  if (data.scope_creep_files && data.scope_creep_files.length > 0) {
+    lines.push(chalk.yellow(`  Unmatched files (${data.scope_creep_files.length}):`));
+    data.scope_creep_files.forEach(f => lines.push(`    - ${f}`));
+  }
+  if (data.summary) lines.push(`  ${data.summary}`);
+  return lines.join('\n');
+}
+
+function formatGaps(data) {
+  const lines = [];
+  lines.push(chalk.bold('Phase Gaps'));
+  if (data.current_phase) lines.push(`  Current phase: ${data.current_phase}`);
+  if (data.target_phase) lines.push(`  Target phase:  ${data.target_phase}`);
+  if (data.gaps && data.gaps.length > 0) {
+    data.gaps.forEach(g => {
+      const sev = g.severity === 'blocker' ? chalk.red(g.severity) : chalk.yellow(g.severity);
+      lines.push(`  - [${sev}] ${g.message || g.category}`);
+      if (g.remediation) lines.push(`    Fix: ${g.remediation}`);
+    });
+  }
+  return lines.join('\n');
+}
+
+function formatWaiverDraft(data) {
+  const lines = [];
+  lines.push(chalk.bold('Waiver Drafts'));
+  if (data.drafts && data.drafts.length > 0) {
+    data.drafts.forEach(d => {
+      lines.push(`  ${chalk.cyan(d.gate || d.id)}:`);
+      if (d.yaml) lines.push(`    ${chalk.dim(d.yaml.replace(/\n/g, '\n    '))}`);
+    });
+  }
+  return lines.join('\n');
+}
+
+function formatProvenance(data) {
+  const lines = [];
+  lines.push(chalk.bold('Provenance'));
+  if (data.file_stats) lines.push(`  Files: ${data.file_stats.total || 0} touched`);
+  if (data.command_history) lines.push(`  Commands: ${data.command_history.length || 0} recorded`);
+  if (data.progression) lines.push(`  Progression: ${data.progression}`);
+  if (data.merge_readiness != null) {
+    const ready = data.merge_readiness ? chalk.green('ready') : chalk.red('not ready');
+    lines.push(`  Merge readiness: ${ready}`);
+  }
+  return lines.join('\n');
+}
+
+const TYPE_FORMATTERS = {
+  'sidecar:drift': formatDrift,
+  'sidecar:gaps': formatGaps,
+  'sidecar:waiver-draft': formatWaiverDraft,
+  'sidecar:provenance': formatProvenance,
+};
+
+// ---------------------------------------------------------------------------
+// Main text formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Render any sidecar output envelope as human-readable text.
+ * Dispatches to per-type formatters; falls back to JSON dump for unknown types.
+ * @param {object} output - Sidecar output envelope
+ * @returns {string} Formatted text
+ */
+function formatSidecarText(output) {
+  if (output.status === 'no-state') {
+    return chalk.dim(output.data.message || 'No working state found');
+  }
+  const formatter = TYPE_FORMATTERS[output.type];
+  if (formatter) return formatter(output.data);
+  return JSON.stringify(output.data, null, 2);
+}
+
+module.exports = {
+  createSidecarOutput,
+  createNoStateOutput,
+  formatSidecarText,
+};