@smartmemory/compose 0.1.0 → 0.1.2-beta

package/server/drift-axes.js

@@ -0,0 +1,365 @@
+/**
+ * drift-axes.js — COMP-OBS-DRIFT axis computation.
+ *
+ * `computeDriftAxes(item, projectRoot, now)` returns DriftAxis[3] conforming to
+ * the COMP-OBS-CONTRACT schema v0.2.4. All three axes always present; individual
+ * axes fall back to `threshold: null` (disabled) when source is unavailable.
+ *
+ * Thresholds (Decision 2):
+ *   path_drift        0.30  (30% of touched files outside the plan)
+ *   contract_drift    0.20  (20% field churn since plan anchor)
+ *   review_debt_drift 0.40  (40% unresolved STRAT-REV findings)
+ *
+ * Git invocations are synchronous / shell-out (mirrors BRANCH's inline pattern).
+ * No shared git-utils.js exists in the shipped tree. All errors are caught; the
+ * axis returns threshold:null rather than throwing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { diffContracts } from './contract-diff.js';
+
+// ── Threshold constants (Decision 2) ─────────────────────────────────────────
+
+const THRESHOLD_PATH_DRIFT = 0.30;
+const THRESHOLD_CONTRACT_DRIFT = 0.20;
+const THRESHOLD_REVIEW_DEBT_DRIFT = 0.40;
+
+// ── Git helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Resolve an ISO timestamp to the nearest commit before that point.
+ * Returns null on any error (no git, no repo, timestamp before first commit).
+ *
+ * @param {string} projectRoot
+ * @param {string} isoTimestamp
+ * @returns {string|null} commit sha1
+ */
+function resolveAnchorCommit(projectRoot, isoTimestamp) {
+  try {
+    const sha = execSync(
+      `git rev-list -1 --before="${isoTimestamp}" HEAD`,
+      { cwd: projectRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return sha || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the UNION of three git file sets (committed changes since anchor,
+ * uncommitted modifications, untracked new files). Deduplicates paths.
+ *
+ * @param {string} projectRoot
+ * @param {string} anchorCommit
+ * @returns {Set<string>} relative paths
+ */
+function touchedFilesSince(projectRoot, anchorCommit) {
+  const paths = new Set();
+  const run = (cmd) => {
+    try {
+      const out = execSync(cmd, { cwd: projectRoot, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+      for (const line of out.split('\n')) {
+        const p = line.trim();
+        if (p) paths.add(p);
+      }
+    } catch {
+      // silent — partial results preferred over complete failure
+    }
+  };
+
+  run(`git diff --name-only ${anchorCommit}..HEAD`);
+  run('git diff --name-only HEAD');
+  run('git ls-files --others --exclude-standard');
+  return paths;
+}
+
+/**
+ * Extract backtick-quoted paths from a text file (plan.md / blueprint.md).
+ * Returns empty Set on missing/unparseable file.
+ *
+ * @param {string} filePath — absolute path
+ * @returns {Set<string>}
+ */
+function extractDeclaredPaths(filePath) {
+  const paths = new Set();
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    // Match backtick-quoted strings that look like file paths (contain / or .)
+    const regex = /`([^`]+)`/g;
+    let m;
+    while ((m = regex.exec(content)) !== null) {
+      const candidate = m[1].trim();
+      // Include if it looks like a file path (has / or extension)
+      if (candidate.includes('/') || /\.\w+$/.test(candidate)) {
+        paths.add(candidate);
+      }
+    }
+  } catch {
+    // Missing file — return empty set; caller handles threshold:null
+  }
+  return paths;
+}
+
+// ── Anchor resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Find the MOST RECENT phaseHistory entry where to === 'plan'.
+ * Returns { timestamp } or null if no such entry exists.
+ *
+ * Design notes:
+ *   - We intentionally do NOT require outcome === 'approved' because the shipped
+ *     lifecycle writer frequently stores outcome: null on plain advances.
+ *   - We use the LAST plan entry, not the first, because the lifecycle allows
+ *     returning from verification back to plan (a replan). Drift should be
+ *     measured against the freshest plan baseline, not a stale one — otherwise
+ *     stale alerts persist across replans.
+ *
+ * @param {object} item
+ * @returns {{ timestamp: string }|null}
+ */
+function findPlanAnchor(item) {
+  const history = item?.lifecycle?.phaseHistory;
+  if (!Array.isArray(history)) return null;
+  let lastPlan = null;
+  for (const entry of history) {
+    if (entry.to === 'plan') lastPlan = entry;
+  }
+  return lastPlan ? { timestamp: lastPlan.timestamp } : null;
+}
+
+// ── Axis computation ──────────────────────────────────────────────────────────
+
+function buildAxis(axis_id, name, numerator, denominator, threshold, computed_at, explanation) {
+  const ratio = denominator > 0 ? numerator / denominator : 0;
+  const breached = threshold != null && ratio >= threshold;
+  return {
+    axis_id,
+    name,
+    numerator,
+    denominator,
+    ratio,
+    threshold,
+    breached,
+    computed_at,
+    explanation,
+    breach_started_at: null,
+    breach_event_id: null,
+  };
+}
+
+/**
+ * Compute path_drift.
+ *
+ * @param {object} item
+ * @param {string} projectRoot
+ * @param {string} featurePath — absolute path to docs/features/<FC>/
+ * @param {string} now — ISO timestamp
+ * @returns {DriftAxis}
+ */
+function computePathDrift(item, projectRoot, featurePath, now) {
+  const axis_id = 'path_drift';
+  const name = 'Path drift';
+  const explanation = 'Ratio of files touched since plan-approval that are not declared in plan.md or blueprint.md.';
+
+  const anchor = findPlanAnchor(item);
+  if (!anchor) {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  const anchorCommit = resolveAnchorCommit(projectRoot, anchor.timestamp);
+  if (!anchorCommit) {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  const touched = touchedFilesSince(projectRoot, anchorCommit);
+  if (touched.size === 0) {
+    return buildAxis(axis_id, name, 0, 0, THRESHOLD_PATH_DRIFT, now, explanation);
+  }
+
+  // Collect declared paths from plan.md and blueprint.md
+  const declared = new Set();
+  for (const fname of ['plan.md', 'blueprint.md']) {
+    const filePath = path.join(featurePath, fname);
+    for (const p of extractDeclaredPaths(filePath)) {
+      declared.add(p);
+    }
+  }
+
+  // Count touched files NOT in declared set
+  let undeclared = 0;
+  for (const t of touched) {
+    // Normalize: strip leading ./ if present
+    const norm = t.replace(/^\.\//, '');
+    // Check whether any declared path matches as a suffix (last segment or subpath)
+    const isDeclared = [...declared].some(d => {
+      const dn = d.replace(/^\.\//, '');
+      return norm === dn || norm.endsWith('/' + dn) || norm.endsWith(dn);
+    });
+    if (!isDeclared) undeclared++;
+  }
+
+  return buildAxis(axis_id, name, undeclared, touched.size, THRESHOLD_PATH_DRIFT, now, explanation);
+}
+
+/**
+ * Compute contract_drift.
+ *
+ * @param {object} item
+ * @param {string} projectRoot
+ * @param {string} featurePath — absolute path to docs/features/<FC>/
+ * @param {string} now
+ * @returns {DriftAxis}
+ */
+function computeContractDrift(item, projectRoot, featurePath, now) {
+  const axis_id = 'contract_drift';
+  const name = 'Contract drift';
+  const explanation = 'Ratio of JSON schema fields added, removed, or retyped since plan-approval vs. total current fields.';
+
+  const anchor = findPlanAnchor(item);
+  if (!anchor) {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  const anchorCommit = resolveAnchorCommit(projectRoot, anchor.timestamp);
+  if (!anchorCommit) {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  // Locate JSON schema files in featurePath
+  let headPaths = [];
+  try {
+    headPaths = fs.readdirSync(featurePath)
+      .filter(f => f.endsWith('.json'))
+      .map(f => path.join(featurePath, f));
+  } catch {
+    // Feature folder missing — axis disabled
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  if (headPaths.length === 0) {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  const { added, removed, retyped, total } = diffContracts(anchorCommit, headPaths, projectRoot);
+  const numerator = added + removed + retyped;
+
+  if (total === 0) {
+    return buildAxis(axis_id, name, numerator, total, THRESHOLD_CONTRACT_DRIFT, now, explanation);
+  }
+
+  return buildAxis(axis_id, name, numerator, total, THRESHOLD_CONTRACT_DRIFT, now, explanation);
+}
+
+/**
+ * Compute review_debt_drift.
+ *
+ * Reads docs/features/<FC>/review*.json (or strat-rev/*.json as fallback).
+ * Missing / unparseable files → threshold: null (not ratio: 0 — to avoid
+ * marking unreviewed features as "clean").
+ *
+ * @param {string} featurePath
+ * @param {string} now
+ * @returns {DriftAxis}
+ */
+function computeReviewDebtDrift(featurePath, now) {
+  const axis_id = 'review_debt_drift';
+  const name = 'Review debt drift';
+  const explanation = 'Ratio of unresolved STRAT-REV findings to total findings for this feature.';
+
+  const RESOLVED_STATUSES = new Set(['resolved', 'closed', 'fixed']);
+
+  // Scan for review JSON files
+  let reviewFiles = [];
+  try {
+    reviewFiles = fs.readdirSync(featurePath)
+      .filter(f => f.startsWith('review') && f.endsWith('.json'))
+      .map(f => path.join(featurePath, f));
+  } catch {
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  // Fallback: strat-rev/ subfolder
+  if (reviewFiles.length === 0) {
+    try {
+      const stratRevDir = path.join(featurePath, 'strat-rev');
+      const subFiles = fs.readdirSync(stratRevDir)
+        .filter(f => f.endsWith('.json'))
+        .map(f => path.join(stratRevDir, f));
+      reviewFiles = subFiles;
+    } catch {
+      // No strat-rev/ either
+    }
+  }
+
+  if (reviewFiles.length === 0) {
+    // No review files — axis disabled (not "clean")
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  let totalFindings = 0;
+  let unresolvedFindings = 0;
+  let parsedAny = false;
+
+  for (const filePath of reviewFiles) {
+    try {
+      const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (!content || typeof content !== 'object') continue;
+      const findings = Array.isArray(content.findings) ? content.findings : [];
+      // Mark as parsed at file level — an empty findings array IS a valid review
+      parsedAny = true;
+      for (const f of findings) {
+        totalFindings++;
+        if (!RESOLVED_STATUSES.has(f.status)) {
+          unresolvedFindings++;
+        }
+      }
+    } catch {
+      // Skip unparseable files
+    }
+  }
+
+  if (!parsedAny) {
+    // All files were unparseable — axis disabled
+    return buildAxis(axis_id, name, 0, 0, null, now, explanation);
+  }
+
+  return buildAxis(axis_id, name, unresolvedFindings, totalFindings, THRESHOLD_REVIEW_DEBT_DRIFT, now, explanation);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Compute all three drift axes for the given item.
+ *
+ * @param {object} item — vision item with item.lifecycle.featureCode and phaseHistory
+ * @param {string} projectRoot — absolute path to the project root (used for git)
+ * @param {string} now — ISO timestamp for computed_at
+ * @returns {DriftAxis[3]} always returns exactly 3 axes (path / contract / review_debt)
+ */
+export function computeDriftAxes(item, projectRoot, now) {
+  const featureCode = item?.lifecycle?.featureCode;
+  if (!featureCode) {
+    // No feature code — all axes disabled
+    const ts = now || new Date().toISOString();
+    return [
+      buildAxis('path_drift', 'Path drift', 0, 0, null, ts, 'No feature code on item.'),
+      buildAxis('contract_drift', 'Contract drift', 0, 0, null, ts, 'No feature code on item.'),
+      buildAxis('review_debt_drift', 'Review debt drift', 0, 0, null, ts, 'No feature code on item.'),
+    ];
+  }
+
+  const ts = now || new Date().toISOString();
+
+  // Resolve the docs/features/<FC> directory
+  // projectRoot/docs/features/<FC>
+  const featurePath = path.join(projectRoot, 'docs', 'features', featureCode);
+
+  const pathAxis = computePathDrift(item, projectRoot, featurePath, ts);
+  const contractAxis = computeContractDrift(item, projectRoot, featurePath, ts);
+  const reviewAxis = computeReviewDebtDrift(featurePath, ts);
+
+  return [pathAxis, contractAxis, reviewAxis];
+}

package/server/drift-emit.js

@@ -0,0 +1,121 @@
+/**
+ * drift-emit.js — COMP-OBS-DRIFT broadcast dispatcher.
+ *
+ * Single choke point: emitDriftAxes(broadcastMessage, store, item, projectRoot, now)
+ *
+ *   1. Compute new axes via computeDriftAxes.
+ *   2. Read prior persisted axes from item.lifecycle.lifecycle_ext.drift_axes[].
+ *   3. For axes that were ALREADY breached: copy breach_started_at + breach_event_id forward.
+ *   4. For axes that are NEWLY breached: assign fresh breach_started_at + breach_event_id.
+ *   5. For axes that are NEWLY UNBREACHED: clear both fields to null.
+ *   6. Persist merged axes via store.updateLifecycleExt.
+ *   7. Broadcast { type: 'driftAxesUpdate', itemId, drift_axes }.
+ *   8. Emit DecisionEvent[kind=drift_threshold] for each newly-breached axis (rising edge only).
+ *
+ * v1 always populates breach_started_at and breach_event_id (even when null) on
+ * every DriftAxis so consumers have a consistent shape.
+ *
+ * Falling-edge → no DecisionEvent. Steady-state breached → no new DecisionEvent.
+ */
+
+import { computeDriftAxes } from './drift-axes.js';
+import { driftThresholdDecisionEventId } from './decision-event-id.js';
+import { emitDecisionEvent, buildDriftThresholdEvent } from './decision-event-emit.js';
+
+/**
+ * Compute, persist, and broadcast drift axes for a single item.
+ * Emits rising-edge DecisionEvents when an axis newly breaches its threshold.
+ *
+ * @param {function} broadcastMessage — fn(msg) WS broadcast
+ * @param {object}   store — VisionStore (must expose updateLifecycleExt)
+ * @param {object}   item — vision item (pre-loaded; must have lifecycle.featureCode)
+ * @param {string}   projectRoot — absolute path of the project root (for git)
+ * @param {string}   [now] — ISO timestamp (defaults to Date.now())
+ * @returns {DriftAxis[]} the merged axes that were persisted
+ */
+export function emitDriftAxes(broadcastMessage, store, item, projectRoot, now) {
+  if (!item?.lifecycle?.featureCode) return [];
+
+  const ts = now || new Date().toISOString();
+  const featureCode = item.lifecycle.featureCode;
+
+  // 1. Compute fresh axes
+  let newAxes;
+  try {
+    newAxes = computeDriftAxes(item, projectRoot, ts);
+  } catch (err) {
+    // Computation failure must not crash the event loop — log and skip
+    console.warn(`[drift-emit] computeDriftAxes failed for ${featureCode}: ${err.message}`);
+    return [];
+  }
+
+  // 2. Read prior persisted axes (indexed by axis_id for O(1) lookup)
+  const prior = item.lifecycle.lifecycle_ext?.drift_axes ?? [];
+  const priorByAxisId = new Map(prior.map(a => [a.axis_id, a]));
+
+  // 3–5. Merge breach-edge metadata; collect newly-breached axes for event emission
+  const newlyBreached = [];
+
+  const mergedAxes = newAxes.map(axis => {
+    const priorAxis = priorByAxisId.get(axis.axis_id);
+    const wasBreached = priorAxis?.breached === true;
+    const isBreached = axis.breached === true;
+
+    let breach_started_at = null;
+    let breach_event_id = null;
+
+    if (isBreached) {
+      if (wasBreached && priorAxis.breach_started_at && priorAxis.breach_event_id) {
+        // Steady breach — preserve the original breach-edge metadata
+        breach_started_at = priorAxis.breach_started_at;
+        breach_event_id = priorAxis.breach_event_id;
+      } else if (!wasBreached) {
+        // Rising edge — assign fresh breach-edge metadata
+        breach_started_at = ts;
+        breach_event_id = driftThresholdDecisionEventId(featureCode, axis.axis_id, ts);
+        newlyBreached.push({ ...axis, breach_started_at, breach_event_id });
+      } else {
+        // wasBreached but prior metadata is missing (edge case: upgraded from old schema)
+        breach_started_at = priorAxis.breach_started_at || ts;
+        breach_event_id = priorAxis.breach_event_id || driftThresholdDecisionEventId(featureCode, axis.axis_id, breach_started_at);
+      }
+    }
+    // Falling edge or never breached: both stay null (already null from buildAxis)
+
+    return { ...axis, breach_started_at, breach_event_id };
+  });
+
+  // 6. Persist merged axes
+  try {
+    store.updateLifecycleExt(item.id, 'drift_axes', mergedAxes);
+  } catch (err) {
+    console.warn(`[drift-emit] updateLifecycleExt failed for ${featureCode}: ${err.message}`);
+    return mergedAxes;
+  }
+
+  // 7. Broadcast driftAxesUpdate
+  try {
+    broadcastMessage({ type: 'driftAxesUpdate', itemId: item.id, drift_axes: mergedAxes });
+  } catch (err) {
+    console.warn(`[drift-emit] broadcast failed for ${featureCode}: ${err.message}`);
+  }
+
+  // 8. Emit DecisionEvent for each newly-breached axis
+  for (const axis of newlyBreached) {
+    try {
+      const event = buildDriftThresholdEvent({
+        featureCode,
+        axisId: axis.axis_id,
+        ratio: axis.ratio,
+        threshold: axis.threshold,
+        breachStartedAt: axis.breach_started_at,
+        breachEventId: axis.breach_event_id,
+      });
+      emitDecisionEvent(broadcastMessage, event);
+    } catch (err) {
+      console.warn(`[drift-emit] DecisionEvent emit failed for ${featureCode}/${axis.axis_id}: ${err.message}`);
+    }
+  }
+
+  return mergedAxes;
+}

package/server/gate-log-store.js

@@ -0,0 +1,102 @@
+/**
+ * gate-log-store.js — COMP-OBS-GATELOG persistence layer.
+ *
+ * Persists GateLogEntry records to <projectDataDir>/gate-log.jsonl (append-only).
+ * Project-scoped, NOT COMPOSE_HOME-scoped — gate decisions belong to the
+ * project they were made in, otherwise gate_load_24h and `compose gates report`
+ * would bleed across repos.
+ * Never rewrites entries in place; idempotent on duplicate id.
+ *
+ * Storage: one JSON object per line (JSONL). Tolerates malformed lines (skips + warns).
+ *
+ * Decision 1a outcome map: route outcome → schema enum
+ *   approve → approve
+ *   revise  → interrupt
+ *   kill    → deny
+ *
+ * Decision 1b featureless gates: callers are responsible for skipping when
+ * gate.itemId is null or item lacks lifecycle.featureCode; this module does
+ * not enforce that — it trusts the caller (vision-routes.js).
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from './project-root.js';
+
+// Gate log is project-scoped (mirrors sessions.json, active-build.json etc).
+// COMPOSE_GATE_LOG env var overrides the path — read dynamically so tests can inject it.
+function getGateLogPath() {
+  return process.env.COMPOSE_GATE_LOG || join(getDataDir(), 'gate-log.jsonl');
+}
+
+/** Translate route outcome vocabulary → schema GateLogEntry.decision enum. */
+export function mapResolveOutcomeToSchema(outcome) {
+  if (outcome === 'approve') return 'approve';
+  if (outcome === 'revise')  return 'interrupt';
+  if (outcome === 'kill')    return 'deny';
+  // Passthrough for already-normalized values (shouldn't happen in practice)
+  return outcome;
+}
+
+/**
+ * Append one GateLogEntry to disk.
+ * Idempotent: if an entry with the same `id` already exists, the write is skipped.
+ * @param {object} entry — a GateLogEntry object (must have .id)
+ */
+export function appendGateLogEntry(entry) {
+  const filePath = getGateLogPath();
+  const dataDir = join(filePath, '..');
+  mkdirSync(dataDir, { recursive: true });
+
+  // Idempotency check: scan existing entries for this id.
+  // Volume is bounded (gate resolution is rare) so a linear scan is fine.
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, 'utf8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const obj = JSON.parse(trimmed);
+        if (obj.id === entry.id) return; // already written
+      } catch {
+        // malformed line — skip
+      }
+    }
+  }
+
+  appendFileSync(filePath, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+/**
+ * Read GateLogEntry records from disk with optional filters.
+ *
+ * @param {{ since?: number, featureCode?: string, logPath?: string }} opts
+ *   - since:       optional epoch ms — only entries with timestamp >= since are returned
+ *   - featureCode: optional string  — filter to a specific feature
+ *   - logPath:     optional path override for tests
+ * @returns {GateLogEntry[]}
+ */
+export function readGateLog({ since, featureCode, logPath } = {}) {
+  const filePath = logPath || getGateLogPath();
+  if (!existsSync(filePath)) return [];
+
+  const raw = readFileSync(filePath, 'utf8');
+  const entries = [];
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch {
+      console.warn('[gate-log-store] malformed line skipped:', trimmed.slice(0, 80));
+      continue;
+    }
+    if (since !== undefined && Date.parse(obj.timestamp) < since) continue;
+    if (featureCode !== undefined && obj.feature_code !== featureCode) continue;
+    entries.push(obj);
+  }
+
+  return entries;
+}

package/server/lifecycle-phase-history.js

@@ -0,0 +1,44 @@
+/**
+ * lifecycle-phase-history.js — Populate lifecycle.phaseHistory[].
+ *
+ * COMP-OBS-TIMELINE: plugs project_lifecycle_phasehistory_gap (memory note).
+ * This module is the SOLE WRITER for lifecycle.phaseHistory[].
+ *
+ * Entries carry BOTH the legacy shape (`phase`, `step`, `enteredAt`, `exitedAt`,
+ * `outcome`) consumed by `ItemDetailPanel.jsx`, `ContextPipelineDots.jsx`, and
+ * `session-routes.js`, AND the new shape (`from`, `to`, `outcome`, `timestamp`)
+ * consumed by `decision-events-snapshot.js`. Legacy `enteredAt` is the same
+ * instant as the new `timestamp`. The previous entry's `exitedAt` is closed out
+ * to the new entry's `enteredAt` (legacy semantic: a phase exits when its
+ * successor begins).
+ */
+
+/**
+ * Append one phase transition entry to item.lifecycle.phaseHistory and close
+ * out the prior entry's `exitedAt`.
+ *
+ * @param {object} item — vision store item (mutated in place)
+ * @param {{ from: string|null, to: string, outcome: string|null, timestamp: string }} params
+ */
+export function appendPhaseHistory(item, { from, to, outcome, timestamp }) {
+  if (!Array.isArray(item.lifecycle.phaseHistory)) {
+    item.lifecycle.phaseHistory = [];
+  }
+  const history = item.lifecycle.phaseHistory;
+  const prior = history[history.length - 1];
+  if (prior && prior.exitedAt == null) {
+    prior.exitedAt = timestamp;
+  }
+  history.push({
+    // Legacy shape (preserves existing readers in ItemDetailPanel, ContextPipelineDots, session-routes)
+    phase: to,
+    step: to,
+    enteredAt: timestamp,
+    exitedAt: null,
+    // New shape (consumed by decision-events-snapshot.js)
+    from: from ?? null,
+    to,
+    outcome: outcome ?? null,
+    timestamp,
+  });
+}