@smartmemory/compose 0.1.0 → 0.1.2-beta

package/server/vision-routes.js

@@ -31,9 +31,24 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { extractFilePaths } from './vision-utils.js';
 import { ArtifactManager } from './artifact-manager.js';
-import { recordIteration, checkCumulativeBudget } from '../lib/budget-ledger.js';
+import { recordIteration, checkCumulativeBudget, readBudget } from '../lib/budget-ledger.js';
+import { SchemaValidator } from './schema-validator.js';
+import { appendPhaseHistory } from './lifecycle-phase-history.js';
+import { emitDecisionEvent, buildPhaseTransitionEvent, buildIterationEvent, buildGateEvent } from './decision-event-emit.js';
+import { emitStatusSnapshot } from './status-emit.js';
+import { computeStatusSnapshot } from './status-snapshot.js';
+import { emitDriftAxes } from './drift-emit.js';
+
+let _schemaValidator = null;
+function getSchemaValidator() {
+  if (!_schemaValidator) _schemaValidator = new SchemaValidator();
+  return _schemaValidator;
+}
 
+import { randomUUID } from 'node:crypto';
 import { getTargetRoot, resolveProjectPath, loadProjectConfig } from './project-root.js';
+import { appendGateLogEntry, readGateLog, mapResolveOutcomeToSchema } from './gate-log-store.js';
+import { addOpenLoop, resolveOpenLoop, listOpenLoops } from './open-loops-store.js';
 
 const PROJECT_ROOT = getTargetRoot();
 
@@ -154,6 +169,19 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
+  // COMP-OBS-STATUS: GET /api/lifecycle/status?featureCode=<FC>
+  // Returns the latest StatusSnapshot for the given featureCode.
+  // Missing or unknown featureCode returns the no-feature snapshot (not 400/404).
+  app.get('/api/lifecycle/status', (req, res) => {
+    try {
+      const fc = req.query.featureCode || null;
+      const snapshot = computeStatusSnapshot(store, fc, new Date().toISOString());
+      res.json({ snapshot });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   app.post('/api/vision/items/:id/lifecycle/start', (req, res) => {
     try {
       const { featureCode } = req.body;
@@ -171,9 +199,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         killedAt: null,
         killReason: null,
       };
+      // COMP-OBS-TIMELINE: populate phaseHistory before storing
+      appendPhaseHistory({ lifecycle }, { from: null, to: 'explore_design', outcome: null, timestamp: now });
       store.updateLifecycle(req.params.id, lifecycle);
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleStarted', itemId: req.params.id, phase: 'explore_design', featureCode, timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode, from: null, to: 'explore_design', outcome: null, timestamp: now }));
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      const startedItem = store.items.get(req.params.id);
+      if (startedItem) emitDriftAxes(broadcastMessage, store, startedItem, projectRoot, now);
+      // COMP-OBS-STATUS: emit status snapshot after lifecycle started
+      emitStatusSnapshot(broadcastMessage, store, featureCode, now);
       res.json(lifecycle);
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -181,6 +217,38 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
+  // COMP-OBS-BRANCH: accept BranchLineage payloads from the CC-session watcher.
+  app.post('/api/vision/items/:id/lifecycle/branch-lineage', (req, res) => {
+    try {
+      const item = store.items.get(req.params.id);
+      if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
+
+      const body = req.body || {};
+      const { valid, errors } = getSchemaValidator().validate('BranchLineage', body);
+      if (!valid) {
+        return res.status(400).json({ error: 'Invalid BranchLineage payload', details: errors });
+      }
+
+      const itemFC = item.lifecycle?.featureCode;
+      if (!itemFC) {
+        return res.status(400).json({ error: 'Item has no lifecycle.featureCode; cannot attach branch lineage.' });
+      }
+      if (body.feature_code !== itemFC) {
+        return res.status(400).json({
+          error: `Lineage feature_code (${body.feature_code}) does not match item featureCode (${itemFC}).`,
+        });
+      }
+
+      store.updateLifecycleExt(req.params.id, 'branch_lineage', body);
+      scheduleBroadcast();
+      broadcastMessage({ type: 'branchLineageUpdate', itemId: req.params.id, ...body });
+      res.json({ ok: true, branch_lineage: body });
+    } catch (err) {
+      const status = err.message.includes('not found') ? 404 : 400;
+      res.status(status).json({ error: err.message });
+    }
+  });
+
   app.post('/api/vision/items/:id/lifecycle/advance', (req, res) => {
     try {
       const { targetPhase, outcome } = req.body;
@@ -192,10 +260,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       item.lifecycle.currentPhase = targetPhase;
-      store.updateLifecycle(req.params.id, item.lifecycle);
+      // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
       const now = new Date().toISOString();
+      appendPhaseHistory(item, { from, to: targetPhase, outcome: outcome ?? null, timestamp: now });
+      store.updateLifecycle(req.params.id, item.lifecycle);
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome, timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome, timestamp: now }));
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+      // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (advance)
+      emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
       res.json({ from, to: targetPhase, outcome });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -215,10 +290,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       item.lifecycle.currentPhase = targetPhase;
-      store.updateLifecycle(req.params.id, item.lifecycle);
+      // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
       const now = new Date().toISOString();
+      appendPhaseHistory(item, { from, to: targetPhase, outcome: 'skipped', timestamp: now });
+      store.updateLifecycle(req.params.id, item.lifecycle);
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome: 'skipped', timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome: 'skipped', timestamp: now }));
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+      // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (skip)
+      emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
       res.json({ from, to: targetPhase, outcome: 'skipped', reason });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -238,10 +320,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       item.lifecycle.currentPhase = 'killed';
       item.lifecycle.killedAt = now;
       item.lifecycle.killReason = reason;
+      // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
+      appendPhaseHistory(item, { from, to: 'killed', outcome: 'killed', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       store.updateItem(req.params.id, { status: 'killed' });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: 'killed', outcome: 'killed', timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: 'killed', outcome: 'killed', timestamp: now }));
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+      // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (kill)
+      emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
       res.json({ phase: from, reason });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -260,10 +349,17 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       const now = new Date().toISOString();
       item.lifecycle.currentPhase = 'complete';
       item.lifecycle.completedAt = now;
+      // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
+      appendPhaseHistory(item, { from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
       store.updateLifecycle(req.params.id, item.lifecycle);
       store.updateItem(req.params.id, { status: 'complete' });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now });
+      emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from: 'ship', to: 'complete', outcome: 'approved', timestamp: now }));
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+      // COMP-OBS-STATUS: emit status snapshot after lifecycle transition (complete)
+      emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
       res.json({ completedAt: now });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -316,6 +412,22 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.updateLifecycle(req.params.id, item.lifecycle);
       scheduleBroadcast();
       broadcastMessage({ type: 'iterationStarted', itemId: req.params.id, loopId: item.lifecycle.iterationState.loopId, loopType, maxIterations: max, timestamp: now, startedAt: now, wallClockTimeout: timeoutMinutes, maxActions: maxActions ?? null });
+      // COMP-OBS-TIMELINE: emit iteration DecisionEvent at loop start
+      if (item.lifecycle.featureCode) {
+        emitDecisionEvent(broadcastMessage, buildIterationEvent({
+          featureCode: item.lifecycle.featureCode,
+          loopId: item.lifecycle.iterationState.loopId,
+          loopType,
+          stage: 'start',
+          attempt: null,
+          outcome: 'retry',
+          timestamp: now,
+        }));
+        // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+        emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+        // COMP-OBS-STATUS: emit status snapshot after iteration started
+        emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      }
       res.json(item.lifecycle.iterationState);
     } catch (err) {
       res.status(400).json({ error: err.message });
@@ -375,8 +487,31 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         const completeMsg = { type: 'iterationComplete', itemId: req.params.id, loopId: iter.loopId, loopType: iter.loopType, outcome: iter.outcome, finalCount: iter.count, timestamp: now };
         if (iter.elapsedMinutes != null) completeMsg.elapsedMinutes = iter.elapsedMinutes;
         broadcastMessage(completeMsg);
+        // COMP-OBS-TIMELINE: emit iteration DecisionEvent at loop complete (not per-attempt)
+        if (item.lifecycle.featureCode) {
+          emitDecisionEvent(broadcastMessage, buildIterationEvent({
+            featureCode: item.lifecycle.featureCode,
+            loopId: iter.loopId,
+            loopType: iter.loopType,
+            stage: 'complete',
+            attempt: iter.count,
+            outcome: iter.outcome,
+            timestamp: now,
+          }));
+          // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+          emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+          // COMP-OBS-STATUS: emit status snapshot after iteration complete
+          emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+        }
       } else {
+        // per-attempt update: NO DecisionEvent (Decision 2 — would flood strip)
         broadcastMessage({ type: 'iterationUpdate', itemId: req.params.id, loopId: iter.loopId, loopType: iter.loopType, count: iter.count, maxIterations: iter.maxIterations, exitCriteriaMet: false, findingsCount: result.findings?.length ?? 0, timestamp: now });
+        // COMP-OBS-STATUS: STATUS broadcasts on iterationUpdate per Decision 4 (TIMELINE does not)
+        if (item.lifecycle.featureCode) {
+          // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+          emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+          emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+        }
       }
       res.json({ continue: shouldContinue, count: iter.count, maxIterations: iter.maxIterations, outcome: iter.outcome });
     } catch (err) {
@@ -405,6 +540,22 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.updateLifecycle(req.params.id, item.lifecycle);
       scheduleBroadcast();
       broadcastMessage({ type: 'iterationComplete', itemId: req.params.id, loopId: iter.loopId, loopType: iter.loopType, outcome: 'aborted', finalCount: iter.count, timestamp: now });
+      // COMP-OBS-TIMELINE: emit iteration DecisionEvent on abort (outcome maps to 'fail')
+      if (item.lifecycle.featureCode) {
+        emitDecisionEvent(broadcastMessage, buildIterationEvent({
+          featureCode: item.lifecycle.featureCode,
+          loopId: iter.loopId,
+          loopType: iter.loopType,
+          stage: 'complete',
+          attempt: iter.count,
+          outcome: 'aborted',
+          timestamp: now,
+        }));
+        // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+        emitDriftAxes(broadcastMessage, store, item, projectRoot, now);
+        // COMP-OBS-STATUS: emit status snapshot after iteration abort
+        emitStatusSnapshot(broadcastMessage, store, item.lifecycle.featureCode, now);
+      }
       res.json({ aborted: true });
     } catch (err) {
       res.status(400).json({ error: err.message });
@@ -511,6 +662,15 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.createGate(gate);
       scheduleBroadcast();
       broadcastMessage({ type: 'gateCreated', gateId: id, itemId: itemId || null, timestamp: gate.createdAt });
+      // COMP-OBS-STATUS: emit status snapshot after gate created
+      if (itemId) {
+        const gateItem = store.items.get(itemId);
+        if (gateItem?.lifecycle?.featureCode) {
+          // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+          emitDriftAxes(broadcastMessage, store, gateItem, projectRoot, gate.createdAt);
+          emitStatusSnapshot(broadcastMessage, store, gateItem.lifecycle.featureCode, gate.createdAt);
+        }
+      }
       res.status(201).json(gate);
     } catch (err) {
       res.status(400).json({ error: err.message });
@@ -540,8 +700,21 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // Normalize legacy outcome values
       const outcomeMap = { approved: 'approve', killed: 'kill', revised: 'revise' };
       const outcome = outcomeMap[rawOutcome] || rawOutcome;
+      // Whitelist — anything outside the route vocabulary is rejected so we
+      // can't persist contract-invalid GateLogEntry.decision values.
+      const VALID_RESOLVE_OUTCOMES = new Set(['approve', 'revise', 'kill']);
+      if (!VALID_RESOLVE_OUTCOMES.has(outcome)) {
+        return res.status(400).json({ error: `outcome must be one of: approve, revise, kill (got '${rawOutcome}')` });
+      }
       const gate = store.gates.get(req.params.id);
       if (!gate) return res.status(404).json({ error: `Gate not found: ${req.params.id}` });
+      // Lazy expiry parity with GET — expired gates can't be resolved or audited.
+      const gateTimeout = Number(process.env.COMPOSE_GATE_TIMEOUT) || 30 * 60 * 1000;
+      if (gate.status === 'pending' && (Date.now() - new Date(gate.createdAt).getTime()) > gateTimeout) {
+        gate.status = 'expired';
+        store._save();
+        return res.status(409).json({ error: `Gate ${req.params.id} has expired and cannot be resolved` });
+      }
       // Idempotent: already-resolved gates return 200
       if (gate.status !== 'pending') {
         return res.status(200).json({ gateId: req.params.id, gateOutcome: gate.outcome });
@@ -551,7 +724,60 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.resolveGate(req.params.id, { outcome, comment, resolvedBy });
 
       scheduleBroadcast();
-      broadcastMessage({ type: 'gateResolved', gateId: req.params.id, itemId: gate.itemId, outcome, timestamp: new Date().toISOString() });
+      const resolvedAt = new Date().toISOString();
+      broadcastMessage({ type: 'gateResolved', gateId: req.params.id, itemId: gate.itemId, outcome, timestamp: resolvedAt });
+
+      // COMP-OBS-GATELOG: persist audit entry + emit gate DecisionEvent (Decision 3 — emit-first-then-append).
+      // Skip when gate has no resolvable feature_code (Decision 1b).
+      const gateLogItem = gate.itemId ? store.items.get(gate.itemId) : null;
+      const gateFeatureCode = gateLogItem?.lifecycle?.featureCode ?? null;
+      if (gateFeatureCode) {
+        const entryId = randomUUID();
+        const schemaDecision = mapResolveOutcomeToSchema(outcome);
+        const createdAtMs = gate.createdAt ? Date.parse(gate.createdAt) : Date.parse(resolvedAt);
+        const durationMs = Date.parse(resolvedAt) - createdAtMs;
+
+        const gateEvent = buildGateEvent({
+          featureCode: gateFeatureCode,
+          gateLogEntryId: entryId,
+          gateId: req.params.id,
+          decision: outcome,
+          timestamp: resolvedAt,
+        });
+
+        // Emit first — if it throws, we still write but with decision_event_id: null
+        let emittedEventId = null;
+        try {
+          emitDecisionEvent(broadcastMessage, gateEvent);
+          emittedEventId = gateEvent.id;
+        } catch (emitErr) {
+          console.warn('[vision-routes] gate DecisionEvent emit failed:', emitErr.message);
+        }
+
+        /** @type {import('./gate-log-store.js').GateLogEntry} */
+        const entry = {
+          id: entryId,
+          gate_id: req.params.id,
+          decision: schemaDecision,
+          operator: gate.resolvedBy ?? null,
+          duration_to_decide_ms: durationMs >= 0 ? durationMs : null,
+          timestamp: resolvedAt,
+          feature_code: gateFeatureCode,
+          decision_event_id: emittedEventId,
+        };
+        appendGateLogEntry(entry);
+      }
+      // else: featureless gate — skip both writes (Decision 1b)
+
+      // COMP-OBS-STATUS: emit status snapshot after gate resolved
+      if (gate.itemId) {
+        const resolvedItem = store.items.get(gate.itemId);
+        if (resolvedItem?.lifecycle?.featureCode) {
+          // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+          emitDriftAxes(broadcastMessage, store, resolvedItem, projectRoot, resolvedAt);
+          emitStatusSnapshot(broadcastMessage, store, resolvedItem.lifecycle.featureCode, resolvedAt);
+        }
+      }
       res.json({ gateId: req.params.id, gateOutcome: outcome });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
@@ -559,6 +785,94 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
+  // ── COMP-OBS-LOOPS routes ─────────────────────────────────────────────────
+
+  // GET /api/vision/items/:id/loops — list open loops for an item
+  app.get('/api/vision/items/:id/loops', (req, res) => {
+    try {
+      const item = store.items.get(req.params.id);
+      if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
+      const includeResolved = req.query.includeResolved === 'true';
+      const loops = listOpenLoops(item, { includeResolved });
+      res.json({ loops });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/vision/items/:id/loops — add a new open loop
+  app.post('/api/vision/items/:id/loops', (req, res) => {
+    try {
+      const item = store.items.get(req.params.id);
+      if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
+      if (!item.lifecycle?.featureCode) {
+        return res.status(400).json({ error: 'item has no lifecycle.featureCode — cannot create feature-scoped open loop' });
+      }
+      const { kind, summary, parent_branch, ttl_days } = req.body;
+      // Schema-aligned validation (CONTRACT v0.2.3 OpenLoop)
+      const VALID_KINDS = new Set(['deferred', 'blocked', 'open_question']);
+      if (!kind) return res.status(400).json({ error: 'kind is required' });
+      if (!VALID_KINDS.has(kind)) {
+        return res.status(400).json({ error: `kind must be one of: deferred, blocked, open_question (got '${kind}')` });
+      }
+      if (typeof summary !== 'string' || summary.length === 0) {
+        return res.status(400).json({ error: 'summary is required (non-empty string)' });
+      }
+      if (summary.length > 280) {
+        return res.status(400).json({ error: 'summary exceeds 280-char schema limit' });
+      }
+      if (ttl_days !== undefined && (!Number.isInteger(ttl_days) || ttl_days < 0)) {
+        return res.status(400).json({ error: 'ttl_days must be a non-negative integer' });
+      }
+
+      const { loop, nextLoops } = addOpenLoop(item, { kind, summary, parent_branch, ttl_days });
+      store.updateLifecycleExt(item.id, 'open_loops', nextLoops);
+
+      const updatedItem = store.items.get(item.id);
+      broadcastMessage({ type: 'openLoopsUpdate', itemId: item.id, loops: nextLoops });
+      const featureCode = updatedItem.lifecycle.featureCode;
+      const now = new Date().toISOString();
+      // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+      emitDriftAxes(broadcastMessage, store, updatedItem, projectRoot, now);
+      emitStatusSnapshot(broadcastMessage, store, featureCode, now);
+
+      res.status(201).json({ loop });
+    } catch (err) {
+      const status = err.status || (err.message.includes('not found') ? 404 : 400);
+      res.status(status).json({ error: err.message });
+    }
+  });
+
+  // POST /api/vision/items/:id/loops/:loopId/resolve — resolve a loop
+  app.post('/api/vision/items/:id/loops/:loopId/resolve', (req, res) => {
+    try {
+      const item = store.items.get(req.params.id);
+      if (!item) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
+      const { note, resolved_by } = req.body;
+
+      const { loop, nextLoops } = resolveOpenLoop(item, req.params.loopId, {
+        note,
+        resolved_by: resolved_by || process.env.USER || 'unknown',
+      });
+      store.updateLifecycleExt(item.id, 'open_loops', nextLoops);
+
+      broadcastMessage({ type: 'openLoopsUpdate', itemId: item.id, loops: nextLoops });
+      const featureCode = item.lifecycle?.featureCode;
+      if (featureCode) {
+        const now = new Date().toISOString();
+        // COMP-OBS-DRIFT: emit drift axes before status so STATUS reads fresh drift_axes
+        const resolvedLoopItem = store.items.get(item.id);
+        if (resolvedLoopItem) emitDriftAxes(broadcastMessage, store, resolvedLoopItem, projectRoot, now);
+        emitStatusSnapshot(broadcastMessage, store, featureCode, now);
+      }
+
+      res.json({ loop });
+    } catch (err) {
+      const status = err.status || (err.message.includes('not found') ? 404 : 400);
+      res.status(status).json({ error: err.message });
+    }
+  });
+
   // GET /api/vision/summary — structured board summary
   app.get('/api/vision/summary', (_req, res) => {
     const { items, connections } = store.getState();
@@ -635,6 +949,20 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     res.json({ ok: true });
   });
 
+  // GET /api/lifecycle/budget?featureCode=<FC> — COMP-OBS-STEPDETAIL
+  // Returns per-loop-type budget breakdown from ledger + settings.
+  // v1 limitation: usedIterations is feature-wide (ledger doesn't split by loopType).
+  app.get('/api/lifecycle/budget', (req, res) => {
+    const { featureCode } = req.query;
+    if (!featureCode) {
+      return res.status(400).json({ error: 'featureCode query param is required' });
+    }
+    const composeDir = path.join(projectRoot, '.compose');
+    const settings = settingsStore?.get();
+    const budget = readBudget(composeDir, featureCode, settings);
+    res.json(budget);
+  });
+
   // POST /api/plan/parse — extract file paths from plan/spec markdown
   app.post('/api/plan/parse', (req, res) => {
     const { filePath, itemId } = req.body || {};

package/server/vision-server.js

@@ -18,13 +18,17 @@ import { AgentRegistry } from './agent-registry.js';
 import { HealthMonitor } from './agent-health.js';
 import { WorktreeGC } from './worktree-gc.js';
 import { attachVisionRoutes } from './vision-routes.js';
+import { deriveDecisionEvents } from './decision-events-snapshot.js';
+import { CCSessionWatcher } from './cc-session-watcher.js';
+import { emitStatusSnapshot } from './status-emit.js';
+import { emitDriftAxes } from './drift-emit.js';
+import { SchemaValidator } from './schema-validator.js';
 import { attachSessionRoutes } from './session-routes.js';
 import { attachActivityRoutes } from './activity-routes.js';
 import { SettingsStore } from './settings-store.js';
 import { attachSettingsRoutes } from './settings-routes.js';
 import { attachDesignRoutes } from './design-routes.js';
 import { DesignSessionManager } from './design-session.js';
-import { ClaudeSDKConnector } from './connectors/claude-sdk-connector.js';
 import { attachPipelineRoutes } from './pipeline-routes.js';
 import { attachIdeaboxRoutes } from './ideabox-routes.js';
 import { CoalescingBuffer } from './coalescing-buffer.js';
@@ -126,8 +130,6 @@ export class VisionServer {
     // Re-resolve on every call so project switches get fresh instances.
     let _designSessionManager = null;
     let _designDataDir = null;
-    let _designConnector = null;
-    let _designCwd = null;
 
     attachDesignRoutes(app, {
       getSessionManager: () => {
@@ -139,14 +141,6 @@ export class VisionServer {
         }
         return _designSessionManager;
       },
-      getConnector: () => {
-        const cwd = getTargetRoot();
-        if (cwd !== _designCwd) {
-          _designConnector = new ClaudeSDKConnector({ cwd });
-          _designCwd = cwd;
-        }
-        return _designConnector;
-      },
       getProjectRoot: () => getTargetRoot(),
     });
 
@@ -244,6 +238,81 @@ export class VisionServer {
       });
     }
 
+    // ── COMP-OBS-BRANCH: CC-session watcher (opt-in) ──────────────────────
+    // Default OFF. Enable by setting `capabilities.cc_session_watcher: true` in compose.json
+    // or by setting the `CC_SESSION_WATCHER=1` env var. When enabled, Forge reads
+    // `~/.claude/projects/**/*.jsonl` and emits BranchLineage + DecisionEvents tied to the
+    // current feature via sessions.json's transcriptPath basename.
+    const ccWatcherEnabled =
+      this._config.capabilities?.cc_session_watcher === true ||
+      process.env.CC_SESSION_WATCHER === '1';
+    if (ccWatcherEnabled) {
+      try {
+        const projectsRoot = process.env.CC_PROJECTS_ROOT ||
+          path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude', 'projects');
+        const sessionsFile = this.sessionManager?.sessionsFile || path.join(getDataDir(), 'sessions.json');
+        const featureRoot = path.join(getTargetRoot(), 'docs', 'features');
+
+        const findItemIdByFeatureCode = (fc) => {
+          for (const it of this.store.items.values()) {
+            if (it.lifecycle?.featureCode === fc) return it.id;
+          }
+          return null;
+        };
+
+        const schemaValidator = new SchemaValidator();
+        const postBranchLineage = async (itemId, lineage) => {
+          // Validate at the producer boundary — the watcher path bypasses the HTTP
+          // route, so we must re-check here to guarantee contract conformance.
+          const { valid, errors } = schemaValidator.validate('BranchLineage', lineage);
+          if (!valid) {
+            throw new Error(`Invalid BranchLineage payload: ${JSON.stringify(errors)}`);
+          }
+          const item = this.store.items.get(itemId);
+          const itemFC = item?.lifecycle?.featureCode;
+          if (!itemFC || itemFC !== lineage.feature_code) {
+            throw new Error(
+              `feature_code mismatch: lineage=${lineage.feature_code} item=${itemFC || '<none>'}`
+            );
+          }
+          this.store.updateLifecycleExt(itemId, 'branch_lineage', lineage);
+          this.scheduleBroadcast();
+          this.broadcastMessage({ type: 'branchLineageUpdate', itemId, ...lineage });
+        };
+
+        this._ccWatcher = new CCSessionWatcher({
+          projectsRoot,
+          sessionsFile,
+          featureRoot,
+          findItemIdByFeatureCode,
+          postBranchLineage,
+          broadcastMessage: (msg) => this.broadcastMessage(msg),
+          // COMP-OBS-STATUS: inject emitStatusSnapshot for post-lineage status broadcast
+          emitStatusSnapshot,
+          getState: () => this.store,
+          // COMP-OBS-DRIFT: inject emitDriftAxes for post-lineage drift broadcast
+          emitDriftAxes,
+          projectRoot: getTargetRoot(),
+        });
+
+        // Seed emitted_event_ids from any existing lineage so startup doesn't replay.
+        for (const it of this.store.items.values()) {
+          const l = it.lifecycle?.lifecycle_ext?.branch_lineage;
+          if (l?.feature_code && Array.isArray(l.emitted_event_ids)) {
+            this._ccWatcher.seedEmittedEventIds(l.feature_code, l.emitted_event_ids);
+          }
+        }
+
+        this._ccWatcher.fullScan().catch(err => {
+          console.warn('[vision] cc-session-watcher initial scan failed:', err.message);
+        });
+        this._ccWatcher.start();
+        console.log(`[vision] cc-session-watcher enabled (projectsRoot=${projectsRoot})`);
+      } catch (err) {
+        console.warn('[vision] cc-session-watcher failed to start:', err.message);
+      }
+    }
+
     // ── Haiku summary broadcast ─────────────────────────────────────────────
     if (this.sessionManager) {
       this.sessionManager.onSummary((summary) => {
@@ -307,10 +376,33 @@ export class VisionServer {
       if ('type' in state) {
         throw new Error('store.getState() must not include a `type` field — would collide with hydrate envelope');
       }
+
+      // COMP-OBS-TIMELINE: derive DecisionEvents for the active feature
+      // (derive from all features present in state — client filters by featureCode)
+      let decisionEventsSnapshot = [];
+      try {
+        const internalState = this.store;
+        // Use internal items Map for deriveDecisionEvents (avoids serialization round-trip)
+        const featureCodes = new Set();
+        for (const item of (internalState.items?.values?.() || [])) {
+          if (item?.lifecycle?.featureCode) featureCodes.add(item.lifecycle.featureCode);
+        }
+        for (const fc of featureCodes) {
+          decisionEventsSnapshot = decisionEventsSnapshot.concat(
+            deriveDecisionEvents(internalState, fc)
+          );
+        }
+      } catch (snapshotErr) {
+        console.error('[vision] decisionEventsSnapshot derivation error:', snapshotErr.message);
+      }
+
       const snapshot = Object.assign(
         { type: 'hydrate' },
         state,
-        { sessions: this.sessionManager?.getRecentSessions?.() || [] }
+        {
+          sessions: this.sessionManager?.getRecentSessions?.() || [],
+          decisionEventsSnapshot,
+        }
       );
       ws.send(JSON.stringify(snapshot));
     } catch (err) {

package/server/vision-store.js

@@ -217,7 +217,13 @@ export class VisionStore {
   updateLifecycle(id, lifecycle) {
     const item = this.items.get(id);
     if (!item) throw new Error(`Item not found: ${id}`);
+    const priorExt = item.lifecycle?.lifecycle_ext;
     item.lifecycle = lifecycle;
+    // Preserve lifecycle_ext across partial-update callers (Wave 6 additive slot).
+    // A caller that truly wants to clear it passes `lifecycle_ext: {}` or `null` explicitly.
+    if (priorExt && lifecycle && !('lifecycle_ext' in lifecycle)) {
+      item.lifecycle.lifecycle_ext = priorExt;
+    }
     // Re-derive group when lifecycle gains a featureCode
     if (lifecycle?.featureCode && !item.group) {
       item.group = deriveGroup(item.title, lifecycle.featureCode);
@@ -228,6 +234,21 @@ export class VisionStore {
     return item;
   }
 
+  /** Merge a single lifecycle_ext.<key> = value slot without touching other extension keys.
+   *  Wave 6 callers (BRANCH, OPEN-LOOPS, DRIFT, STATUS) use this rather than reaching into
+   *  item.lifecycle.lifecycle_ext directly. */
+  updateLifecycleExt(id, key, value) {
+    const item = this.items.get(id);
+    if (!item) throw new Error(`Item not found: ${id}`);
+    if (!item.lifecycle) item.lifecycle = {};
+    if (!item.lifecycle.lifecycle_ext) item.lifecycle.lifecycle_ext = {};
+    item.lifecycle.lifecycle_ext[key] = value;
+    item.updatedAt = new Date().toISOString();
+    this.items.set(id, item);
+    this._save();
+    return item;
+  }
+
   /** Delete an item and all its connections and gates */
   deleteItem(id) {
     if (!this.items.has(id)) throw new Error(`Item not found: ${id}`);

package/dist/assets/channel-DGElom1e.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./index-DReRlzZI.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dist/assets/classDiagram-6PBFFD2Q-KqWP9wWZ.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-DE0WBDkj.js";import{_ as i}from"./index-DReRlzZI.js";import"./chunk-FMBD7UC4-CTDIPA3p.js";import"./chunk-YZCP3GAM-ojGkzcZK.js";import"./chunk-55IACEB6-CE1EXenG.js";import"./chunk-EDXVE4YY-DA7Ana6H.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};