@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/utils/event-renderer.js

@@ -0,0 +1,521 @@
+/**
+ * @fileoverview Event Renderer — pure fold over the event log
+ *
+ * Replays `.caws/events.jsonl` into the same view shape that
+ * `working-state.loadState(specId)` produces today. This module is
+ * a pure function: same events in → same view out, no filesystem
+ * side effects, no writes.
+ *
+ * The fold logic is a verbatim port of the three pure helpers in
+ * `working-state.js` (`computePhase`, `computeBlockers`,
+ * `computeNextActions`) — they already operated on a state object,
+ * so we simply apply them to the rolling fold result after each event.
+ *
+ * Phase 1 reads the event log *in addition to* the state layer, not
+ * instead of it. The parity test in
+ * `tests/integration/event-log-parity.test.js` asserts the two paths
+ * produce equivalent views for the fields iterate/status/sidecar/gates
+ * actually consume.
+ *
+ * @author @darianrosebrook
+ */
+
+const { readEvents } = require('./event-log');
+
+// Must match working-state.js for parity.
+const STATE_SCHEMA_VERSION = 'caws.state.v1';
+const MAX_HISTORY = 20;
+
+// ---------------------------------------------------------------------------
+// Shape: empty state (mirrors working-state.initializeState)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an empty default view for a spec that has no events yet.
+ * @param {string} specId
+ * @returns {object}
+ */
+function emptyView(specId) {
+  return {
+    schema: STATE_SCHEMA_VERSION,
+    spec_id: specId,
+    updated_at: null,
+    phase: 'not-started',
+    files_touched: [],
+    validation: null,
+    evaluation: null,
+    gates: null,
+    acceptance_criteria: null,
+    blockers: [],
+    next_actions: [],
+    history: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Derived-field computation (verbatim port from working-state.js:334-474)
+//
+// These functions operate on the fold result, not on persisted state.
+// They must stay byte-equivalent to the originals until Phase 3 removes
+// the state layer entirely.
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the current workflow phase from the folded state.
+ * Identical semantics to `working-state.computePhase`.
+ * @param {object} state
+ * @returns {string}
+ */
+function computePhase(state) {
+  const v = state.validation;
+  const e = state.evaluation;
+  const g = state.gates;
+  const ac = state.acceptance_criteria;
+
+  // Closed specs stay closed regardless of prior artifacts.
+  if (state.phase === 'closed') return 'closed';
+
+  // Nothing has run yet
+  if (!v && !e && !g && !ac) return 'not-started';
+
+  // Validation failed or evaluation below 70% → still authoring the spec
+  if (v && !v.passed) return 'spec-authoring';
+  if (e && e.percentage < 70) return 'spec-authoring';
+
+  // All ACs pass, all gates pass, evaluation >= 90% → complete
+  if (
+    ac && ac.total > 0 && ac.fail === 0 && ac.unchecked === 0 &&
+    g && g.passed &&
+    e && e.percentage >= 90
+  ) {
+    return 'complete';
+  }
+
+  // All ACs pass, gates have been run → verification phase
+  if (ac && ac.total > 0 && ac.fail === 0 && ac.unchecked === 0 && g) {
+    return 'verification';
+  }
+
+  // Otherwise: implementation
+  return 'implementation';
+}
+
+/**
+ * Extract active blockers from the folded state.
+ * Identical semantics to `working-state.computeBlockers`.
+ * @param {object} state
+ * @returns {object[]}
+ */
+function computeBlockers(state) {
+  // Closed specs have no active blockers. This is a Phase 1 divergence
+  // from working-state.computeBlockers, which predates the spec_closed
+  // event. See EVLOG-001 acceptance criterion A5 and design doc §8.2:
+  // closed specs must render with phase=closed and no blockers, without
+  // touching the filesystem.
+  if (state.phase === 'closed') return [];
+
+  const blockers = [];
+  const now = new Date().toISOString();
+
+  if (state.validation && !state.validation.passed) {
+    blockers.push({
+      type: 'validation_failure',
+      message: `Validation failed with ${state.validation.error_count} error(s)`,
+      since: state.validation.last_run || now,
+    });
+  }
+
+  if (state.gates && state.gates.results) {
+    for (const g of state.gates.results) {
+      if (g.status === 'fail' && g.mode === 'block') {
+        blockers.push({
+          type: 'gate_failure',
+          gate: g.name,
+          message: `Gate "${g.name}" is blocking`,
+          since: state.gates.last_run || now,
+        });
+      }
+    }
+  }
+
+  if (state.acceptance_criteria && state.acceptance_criteria.fail > 0) {
+    const failingIds = (state.acceptance_criteria.results || [])
+      .filter((r) => r.status === 'FAIL')
+      .map((r) => r.id);
+    blockers.push({
+      type: 'ac_failure',
+      message: `${state.acceptance_criteria.fail} acceptance criteria failing${failingIds.length ? ': ' + failingIds.join(', ') : ''}`,
+      since: state.acceptance_criteria.last_run || now,
+    });
+  }
+
+  return blockers;
+}
+
+/**
+ * Compute ordered next actions from the folded state.
+ * Identical semantics to `working-state.computeNextActions`.
+ * @param {object} state
+ * @returns {string[]}
+ */
+function computeNextActions(state) {
+  const actions = [];
+
+  // Closed specs have no next actions.
+  if (state.phase === 'closed') return [];
+
+  if (state.validation && !state.validation.passed) {
+    actions.push('Fix validation errors, then run: caws validate');
+  }
+
+  if (state.gates && state.gates.results) {
+    for (const g of state.gates.results) {
+      if (g.status === 'fail' && g.mode === 'block') {
+        actions.push(`Fix gate violation: ${g.name}`);
+      }
+    }
+  }
+
+  if (state.acceptance_criteria) {
+    const failing = (state.acceptance_criteria.results || [])
+      .filter((r) => r.status === 'FAIL')
+      .map((r) => r.id);
+    if (failing.length > 0) {
+      actions.push(`Fix failing acceptance criteria: ${failing.join(', ')}`);
+    }
+
+    const unchecked = state.acceptance_criteria.unchecked || 0;
+    if (unchecked > 0) {
+      actions.push(`Add tests for ${unchecked} unchecked acceptance criteria`);
+    }
+  }
+
+  if (state.evaluation && state.evaluation.percentage < 80) {
+    actions.push(
+      `Improve spec quality (currently ${state.evaluation.percentage}%), run: caws evaluate`
+    );
+  }
+
+  if (!state.validation) {
+    actions.push('Run: caws validate');
+  }
+
+  if (!state.evaluation) {
+    actions.push('Run: caws evaluate');
+  }
+
+  if (!state.acceptance_criteria) {
+    actions.push('Run: caws verify-acs');
+  }
+
+  if (actions.length === 0) {
+    actions.push(
+      'All checks passing. Ready for merge. Run: caws verify-acs --run for final verification.'
+    );
+  }
+
+  return actions;
+}
+
+// ---------------------------------------------------------------------------
+// Fold: apply a single event to a per-spec view
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply one event to the given per-spec view. Mutates and returns the view.
+ * This mirrors the merge semantics of `working-state.updateState`:
+ *   - replace-merge for validation/evaluation/gates/acceptance_criteria
+ *   - set-union merge for files_touched
+ *   - append-then-cap history
+ *
+ * @param {object} view
+ * @param {object} event
+ * @returns {object} The mutated view (returned for chaining)
+ */
+function applyEvent(view, event) {
+  const { event: type, data = {}, ts } = event;
+
+  switch (type) {
+    case 'spec_created': {
+      // No state fields to set here; the spec registry is the source of truth
+      // for type/title/risk_tier/mode. We record it in history so the renderer
+      // can distinguish "never touched" from "created but not yet worked".
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.create',
+        summary: `Created ${data.type || 'spec'}: ${data.title || data.id || view.spec_id}`,
+      });
+      break;
+    }
+
+    case 'spec_closed': {
+      view.phase = 'closed';
+      view.blockers = [];
+      view.next_actions = [];
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.close',
+        summary: `Closed (prior status: ${data.prior_status || 'unknown'})`,
+      });
+      break;
+    }
+
+    case 'spec_deleted': {
+      // A deleted spec shouldn't typically be rendered; if we do see it,
+      // mark the view as terminal but leave a trace in history.
+      view.phase = 'closed';
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.delete',
+        summary: 'Deleted',
+      });
+      break;
+    }
+
+    case 'validation_completed': {
+      view.validation = {
+        last_run: ts,
+        passed: !!data.passed,
+        compliance_score: data.compliance_score ?? null,
+        grade: data.grade ?? null,
+        error_count: data.error_count ?? 0,
+        warning_count: data.warning_count ?? 0,
+      };
+      const summaryText = data.passed
+        ? `Passed (Grade ${view.validation.grade || '?'})`
+        : `Failed — ${view.validation.error_count} error(s)`;
+      view.history.push({
+        timestamp: ts,
+        command: 'validate',
+        summary: summaryText,
+      });
+      break;
+    }
+
+    case 'evaluation_completed': {
+      view.evaluation = {
+        last_run: ts,
+        score: data.score,
+        max_score: data.max_score,
+        percentage: data.percentage,
+        grade: data.grade,
+        checks_passed: data.checks_passed,
+        checks_total: data.checks_total,
+      };
+      view.history.push({
+        timestamp: ts,
+        command: 'evaluate',
+        summary: `${data.score}/${data.max_score} (${data.percentage}%) Grade ${data.grade}`,
+      });
+      break;
+    }
+
+    case 'gates_evaluated': {
+      view.gates = {
+        last_run: ts,
+        context: data.context || 'cli',
+        passed: !!data.passed,
+        summary: data.summary || {},
+        results: (data.gates || []).map((g) => ({
+          name: g.name,
+          status: g.status,
+          mode: g.mode,
+        })),
+      };
+      const { blocked = 0, warned = 0, passed = 0 } = data.summary || {};
+      view.history.push({
+        timestamp: ts,
+        command: 'gates',
+        summary: `${passed} passed, ${blocked} blocked, ${warned} warned`,
+      });
+      break;
+    }
+
+    case 'verify_acs_completed': {
+      view.acceptance_criteria = {
+        last_run: ts,
+        total: data.total,
+        pass: data.pass,
+        fail: data.fail,
+        unchecked: data.unchecked,
+        results: (data.results || []).map((r) => ({
+          id: r.id,
+          status: r.status,
+        })),
+      };
+      view.history.push({
+        timestamp: ts,
+        command: 'verify-acs',
+        summary: `${data.pass}/${data.total} pass, ${data.fail} fail, ${data.unchecked} unchecked`,
+      });
+      break;
+    }
+
+    case 'session_ended': {
+      // A session can touch files without calling any spec-scoped command.
+      // When the session ends, merge its file list into this spec's view.
+      // Only applies if the event carries our spec_id (the caller filters).
+      if (Array.isArray(data.files_touched) && data.files_touched.length > 0) {
+        const merged = new Set([...view.files_touched, ...data.files_touched]);
+        view.files_touched = [...merged];
+        view.history.push({
+          timestamp: ts,
+          command: 'session',
+          summary: `+${data.files_touched.length} file(s) touched`,
+        });
+      }
+      break;
+    }
+
+    default:
+      // Unknown or non-spec-scoped event type — ignore for this fold.
+      break;
+  }
+
+  // Derived fields recomputed on every applicable event.
+  view.blockers = computeBlockers(view);
+  view.next_actions = computeNextActions(view);
+  view.phase = computePhase(view);
+  view.updated_at = ts;
+
+  // Cap history at MAX_HISTORY (matches working-state.updateState).
+  if (view.history.length > MAX_HISTORY) {
+    view.history = view.history.slice(-MAX_HISTORY);
+  }
+
+  return view;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold an event stream into the view for a single spec.
+ *
+ * Pure function: the same events + specId always produce the same view.
+ * No filesystem access. No writes.
+ *
+ * Events are filtered to those that are either scoped to this spec via
+ * `spec_id`, or session-level events whose `data.spec_id` matches.
+ *
+ * @param {object[]} events — the full event stream (from readEvents)
+ * @param {string} specId
+ * @returns {object} view matching the shape of working-state.loadState
+ */
+function renderSpecState(events, specId) {
+  if (!specId || typeof specId !== 'string') {
+    throw new Error('event-renderer.renderSpecState: specId is required');
+  }
+  const view = emptyView(specId);
+  for (const event of events) {
+    if (!isEventForSpec(event, specId)) continue;
+    applyEvent(view, event);
+  }
+  return view;
+}
+
+/**
+ * Fold an event stream into a Map of specId → view for every spec that
+ * has at least one event in the stream.
+ *
+ * @param {object[]} events
+ * @returns {Map<string, object>}
+ */
+function renderAllSpecStates(events) {
+  const views = new Map();
+  for (const event of events) {
+    const specId = getEventSpecId(event);
+    if (!specId) continue;
+    if (!views.has(specId)) {
+      views.set(specId, emptyView(specId));
+    }
+    applyEvent(views.get(specId), event);
+  }
+  return views;
+}
+
+/**
+ * Convenience: read the event log and render a single spec's view.
+ * Equivalent to calling `loadState(specId)` but backed by the event log.
+ *
+ * **Contract parity with `working-state.loadState`**: returns `null` when
+ * there are zero events for this spec, matching `loadState`'s behavior of
+ * returning `null` when the state file does not exist. This is load-bearing
+ * for Phase 2 read flips — call sites like `status.js`'s
+ * `loadState(id) || null` coalesce depend on it, and `iterate.js`'s
+ * `if (workingState) { ... }` guard would otherwise always be truthy under
+ * the event-log path even for untouched specs.
+ *
+ * `renderSpecState` itself stays pure and always returns a view object
+ * (possibly empty). The null translation only happens here, at the
+ * `loadState`-compatible boundary.
+ *
+ * @param {string} specId
+ * @param {object} [options]
+ * @param {string} [options.projectRoot]
+ * @returns {object|null}
+ */
+function loadStateFromEvents(specId, options = {}) {
+  const events = readEvents(options);
+  // If no events match this spec, return null to match loadState's contract.
+  let hasMatch = false;
+  for (const event of events) {
+    if (isEventForSpec(event, specId)) {
+      hasMatch = true;
+      break;
+    }
+  }
+  if (!hasMatch) return null;
+  return renderSpecState(events, specId);
+}
+
+/**
+ * Determine whether an event is scoped to a given spec.
+ * @param {object} event
+ * @param {string} specId
+ * @returns {boolean}
+ */
+function isEventForSpec(event, specId) {
+  if (event.spec_id === specId) return true;
+  // Session events may carry their own spec_id inside data.
+  if (event.event === 'session_ended' && event.data && event.data.spec_id === specId) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Extract the spec_id an event refers to, if any. Used by
+ * renderAllSpecStates to group events by spec.
+ * @param {object} event
+ * @returns {string|null}
+ */
+function getEventSpecId(event) {
+  if (event.spec_id) return event.spec_id;
+  if (event.data && event.data.spec_id) return event.data.spec_id;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  renderSpecState,
+  renderAllSpecStates,
+  loadStateFromEvents,
+  emptyView,
+
+  // Exposed for tests only.
+  _internal: {
+    applyEvent,
+    computePhase,
+    computeBlockers,
+    computeNextActions,
+    isEventForSpec,
+    getEventSpecId,
+    STATE_SCHEMA_VERSION,
+    MAX_HISTORY,
+  },
+};

package/dist/utils/finalization.js

@@ -95,7 +95,7 @@ async function finalizeProject(projectName, options, answers) {
       ],
       prompts: Object.keys(answers),
       commit: null, // Will be set after git init
-      artifacts: ['.caws/working-spec.yaml'],
+      artifacts: ['.caws/specs/', '.caws/working-spec.yaml'],
       results: {
         project_id: answers.projectId,
         project_title: answers.projectTitle,
@@ -212,13 +212,14 @@ function continueToSuccess() {
   }
 
   console.log(chalk.bold('\nNext steps:'));
-  console.log('1. Customize .caws/working-spec.yaml');
-  console.log('2. Review added CAWS tools and documentation');
+  console.log('1. Customize .caws/specs/<spec-id>.yaml');
+  console.log('2. Treat .caws/working-spec.yaml as a compatibility mirror');
+  console.log('3. Review added CAWS tools and documentation');
   if (!isCurrentDir) {
-    console.log('3. Move CAWS files to your main project if needed');
+    console.log('4. Move CAWS files to your main project if needed');
   }
-  console.log('4. npm install (if using Node.js)');
-  console.log('5. Set up your CI/CD pipeline');
+  console.log('5. npm install (if using Node.js)');
+  console.log('6. Set up your CI/CD pipeline');
   console.log(chalk.blue('\nFor help: caws --help'));
 }
 

package/dist/utils/gitignore-updater.js

@@ -58,6 +58,9 @@ caws-debug.log*
 caws.local.*
 .caws/local.*
 
+# CAWS working state (runtime, not committed)
+.caws/state/
+
 # CAWS Worktrees (local, should not be tracked)
 .caws/worktrees/
 .caws/worktrees.json

package/dist/utils/lifecycle-events.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Governance Lifecycle Events
+ *
+ * A lightweight event system for governance-significant moments in CAWS.
+ * Events fire synchronously within command execution and are consumed by
+ * the working-state layer, feedback enrichment, and future sidecar flows.
+ *
+ * This is NOT the same as IDE hooks (shell scripts in .claude/hooks/).
+ * These are internal CAWS events emitted by CLI commands and gates.
+ *
+ * @author @darianrosebrook
+ */
+
+const { EventEmitter } = require('events');
+
+/**
+ * Singleton lifecycle event emitter.
+ * @type {EventEmitter}
+ */
+const lifecycle = new EventEmitter();
+lifecycle.setMaxListeners(20);
+
+/**
+ * Event name constants.
+ *
+ * @typedef {Object} GatesBlockedPayload
+ * @property {string|null} specId
+ * @property {string} gateName
+ * @property {string} mode
+ * @property {string[]} messages
+ * @property {string} context - cli | commit | edit
+ * @property {string} timestamp - ISO 8601
+ *
+ * @typedef {Object} GatesPassedPayload
+ * @property {string|null} specId
+ * @property {Object} summary - { blocked, warned, passed, skipped, waived }
+ * @property {string} context
+ * @property {string} timestamp
+ *
+ * @typedef {Object} ValidationFailedPayload
+ * @property {string} specId
+ * @property {Object[]} errors
+ * @property {number} errorCount
+ * @property {number} warningCount
+ * @property {string} timestamp
+ *
+ * @typedef {Object} ValidationPassedPayload
+ * @property {string} specId
+ * @property {string} grade
+ * @property {number} complianceScore
+ * @property {string} timestamp
+ *
+ * @typedef {Object} BudgetPressurePayload
+ * @property {string|null} specId
+ * @property {number} filesUsed
+ * @property {number} filesLimit
+ * @property {number} locUsed
+ * @property {number} locLimit
+ * @property {number} percentUsed
+ * @property {string} timestamp
+ *
+ * @typedef {Object} PhaseTransitionPayload
+ * @property {string} specId
+ * @property {string} oldPhase
+ * @property {string} newPhase
+ * @property {string} timestamp
+ *
+ * @typedef {Object} MergePrePayload
+ * @property {string} worktreeName
+ * @property {string} branch
+ * @property {string} baseBranch
+ * @property {string[]} conflicts
+ * @property {string} timestamp
+ *
+ * @typedef {Object} MergePostPayload
+ * @property {string} worktreeName
+ * @property {string} branch
+ * @property {string} baseBranch
+ * @property {boolean} merged
+ * @property {string[]} conflicts
+ * @property {string} timestamp
+ */
+const EVENTS = {
+  GATES_BLOCKED: 'gates:blocked',
+  GATES_PASSED: 'gates:passed',
+  VALIDATION_FAILED: 'validation:failed',
+  VALIDATION_PASSED: 'validation:passed',
+  BUDGET_PRESSURE: 'budget:pressure',
+  PHASE_TRANSITION: 'phase:transition',
+  MERGE_PRE: 'merge:pre',
+  MERGE_POST: 'merge:post',
+};
+
+module.exports = { lifecycle, EVENTS };