@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/sidecars/listeners.js

@@ -1,40 +0,0 @@
-/**
- * @fileoverview Sidecar Lifecycle Listeners
- * Registers lightweight event handlers that print hints to run sidecars
- * at governance-significant moments. Non-blocking, non-fatal.
- * @author @darianrosebrook
- */
-
-const { lifecycle, EVENTS } = require('../utils/lifecycle-events');
-
-/**
- * Register sidecar hint listeners on the lifecycle emitter.
- * Call once during CLI startup.
- */
-function registerSidecarListeners() {
-  // On gate blocked → suggest waiver draft
-  lifecycle.on(EVENTS.GATES_BLOCKED, (payload) => {
-    try {
-      if (process.env.CAWS_QUIET === '1') return;
-      const specFlag = payload.specId ? ` --spec-id ${payload.specId}` : '';
-      const gateFlag = payload.gateName ? ` --gate ${payload.gateName}` : '';
-      console.log(
-        `\n  [Sidecar] Waiver draft available: caws sidecar waiver-draft${specFlag}${gateFlag}`
-      );
-    } catch { /* non-fatal */ }
-  });
-
-  // On phase transition (non-complete) → suggest quality gap analysis
-  lifecycle.on(EVENTS.PHASE_TRANSITION, (payload) => {
-    try {
-      if (process.env.CAWS_QUIET === '1') return;
-      if (payload.newPhase === 'complete') return;
-      const specFlag = payload.specId ? ` --spec-id ${payload.specId}` : '';
-      console.log(
-        `\n  [Sidecar] Phase changed to ${payload.newPhase}. Run: caws sidecar gaps${specFlag}`
-      );
-    } catch { /* non-fatal */ }
-  });
-}
-
-module.exports = { registerSidecarListeners };

package/dist/sidecars/provenance-summary.js

@@ -1,238 +0,0 @@
-/**
- * @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

@@ -1,258 +0,0 @@
-/**
- * @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

@@ -1,149 +0,0 @@
-/**
- * @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,
-};