@structured-vibe-coding/core 0.17.1 → 0.18.0

package/dist/{chunk-72QJHR53.js → chunk-LHSR7JG2.js}

@@ -1,4 +1,5 @@
 import {
+  ChangeMetaSchema,
   activeStages,
   buildContext,
   changeDirName,
@@ -13,38 +14,118 @@ import {
   setActiveChange,
   shouldAutoSkip,
   uniqueChangeDirName
-} from "./chunk-A752UVPF.js";
-import {
-  ChangeMetaSchema
-} from "./chunk-67AUAGNV.js";
+} from "./chunk-QHV5KZKX.js";
 import {
   archiveDir,
   changeMetaPath,
   changePath,
   changesDir,
-  memoryDir,
-  templatesDir
-} from "./chunk-7MJYPJMR.js";
-import {
   copyDir,
+  displayArchivePath,
   ensureDir,
   listDirs,
+  memoryDir,
   pathExists,
   readText,
   readYaml,
   removePath,
+  templatesDir,
   writeText,
   writeYaml
-} from "./chunk-EPFURATC.js";
+} from "./chunk-O5SP6X5R.js";
 
 // src/greenfield.ts
-import { join as join3 } from "pathe";
+import { join as join4 } from "pathe";
 
 // src/artifacts.ts
+var PLACEHOLDER_WORD = /^(?:TBD|TODO|N\/A|NA|none|tbd|todo|n\/a|\.{3}|…|-|—|–|_|\*)$/i;
+function isPlaceholderCell(cell) {
+  const text = cell.trim();
+  if (!text) return true;
+  if (/^\d+$/.test(text)) return true;
+  if (PLACEHOLDER_WORD.test(text)) return true;
+  if (/^[-–—_.:]+$/.test(text)) return true;
+  return false;
+}
+function isTableRow(line) {
+  const trimmed = line.trim();
+  return trimmed.includes("|") && /^\|.*\|$/.test(trimmed);
+}
+function isSeparatorRow(line) {
+  if (!isTableRow(line)) return false;
+  const cells = line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+  return cells.length > 0 && cells.every((cell) => /^:?-+:?$/.test(cell));
+}
+function tableRowToText(line) {
+  const cells = line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+  return cells.filter((cell) => !isPlaceholderCell(cell)).join(" ");
+}
+function isInstructionalLine(line) {
+  const text = line.replace(/^\s*(?:[-*+]|\d+\.)\s+/, "").replace(/^\[[ xX]\]\s*/, "").replace(/\*\*/g, "").trim();
+  if (!text) return true;
+  if (PLACEHOLDER_WORD.test(text)) return true;
+  if (/^[-–—_.*\s]+$/.test(text)) return true;
+  if (/^\{\{[^}]+\}\}$/.test(text)) return true;
+  if (/^<[^>\n]+>$/.test(text)) return true;
+  if (/^<!--/.test(text)) return true;
+  if (/^[^:]{1,48}:\s*$/.test(text)) return true;
+  if (/^(?:Q|A):\s*$/i.test(text)) return true;
+  if (/^(?:Approve(?: with conditions)?|Reject|Promote to feature change|Abandon|Needs more research)$/i.test(
+    text
+  )) {
+    return true;
+  }
+  if (/^No blocking unknowns remain\b/i.test(text)) return true;
+  if (/\?\s*$/.test(text) && text.length < 140) return true;
+  if (/^(?:As a|I want|So that)\b/i.test(text) && /…|\.\.\./.test(text)) return true;
+  if (/^sdd (?:skip|backlog)\b/i.test(text)) return true;
+  if (/^Optional stage\b/i.test(text)) return true;
+  if (/^skip if nothing is ambiguous\b/i.test(text)) return true;
+  if (/^Copy the block below\b/i.test(text)) return true;
+  if (/^Keep Status\b/i.test(text)) return true;
+  if (/^Each feature should fit\b/i.test(text)) return true;
+  if (/^Greenfield —/i.test(text)) return true;
+  if (/^MVP only\b/i.test(text)) return true;
+  if (/^US-\d+:/i.test(text) && /…|\.\.\./.test(text)) return true;
+  if (/^F-\d+:\s*</i.test(text)) return true;
+  if (/^(?:Status|Priority|Workflow|Summary|Requirements|Notes):\s*$/i.test(text)) return true;
+  if (/^(?:Status|Priority|Workflow):\s*(?:planned|must|should|could|feature|hotfix|patch|spike)\s*$/i.test(
+    text
+  )) {
+    return true;
+  }
+  if (/^Summary:\s*One or two sentences\b/i.test(text)) return true;
+  if (/^Requirements:\s*R-\d+\s*$/i.test(text)) return true;
+  if (/^One or two sentences\b/i.test(text)) return true;
+  if (/^R-\d+$/i.test(text)) return true;
+  if (/^(?:planned|must|should|feature)$/i.test(text)) return true;
+  if (/^How to write a feature$/i.test(text)) return true;
+  if (/^paste local commands$/i.test(text)) return true;
+  return false;
+}
 function isSubstantiveArtifactContent(content) {
-  const stripped = content.replace(/<!--[\s\S]*?-->/g, "").replace(/^#{1,6}\s+.*$/gm, "").replace(/^>\s.*$/gm, "").replace(/^\s*[-*+]\s*$/gm, "").replace(/^\s*[-*+]\s*\.\.\.\s*$/gm, "").replace(/^\s*[-*+]\s*TBD\s*$/gim, "").replace(/^\s*[-*+]\s*TODO\s*$/gim, "").replace(/^\s*\|.*\|\s*$/gm, "").replace(/`+/g, "").trim();
+  const withoutComments = content.replace(/<!--[\s\S]*?-->/g, "");
+  const rawLines = withoutComments.split(/\r?\n/);
+  const lines = [];
+  for (let i = 0; i < rawLines.length; i++) {
+    const line = rawLines[i]?.replace(/`+/g, "") ?? "";
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^#{1,6}\s+/.test(trimmed)) continue;
+    if (/^>\s/.test(trimmed)) continue;
+    if (isTableRow(trimmed)) {
+      const next = rawLines[i + 1]?.replace(/`+/g, "").trim() ?? "";
+      if (isSeparatorRow(trimmed) || isSeparatorRow(next)) continue;
+      const kept = tableRowToText(trimmed);
+      if (kept) lines.push(kept);
+      continue;
+    }
+    if (isInstructionalLine(line)) continue;
+    lines.push(line);
+  }
+  const stripped = lines.join("\n").trim();
   if (stripped.length < 48) return false;
-  const meaningful = stripped.replace(/[-–—_.\s]/g, "").replace(/\b(TBD|TODO|N\/A|none|n\/a)\b/gi, "");
+  const meaningful = stripped.replace(/[-–—_.\s|#*`]/g, "").replace(/\{\{[^}]*\}\}/g, "").replace(/\b(TBD|TODO|N\/A|none|n\/a)\b/gi, "");
   return meaningful.length >= 32;
 }
 function incompleteArtifactReason(path, content) {
@@ -68,22 +149,402 @@ function incompleteArtifactReason(path, content) {
 }
 
 // src/change.ts
-import { join as join2 } from "pathe";
+import { join as join3 } from "pathe";
+
+// src/metrics.ts
+import { createReadStream } from "fs";
+import { stat } from "fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import { createInterface } from "readline";
+import { z } from "zod";
+var UtcTimestampSchema = z.string().datetime();
+var PhaseMetricSchema = z.object({
+  phase: z.string().min(1),
+  startedAt: UtcTimestampSchema,
+  endedAt: UtcTimestampSchema.optional()
+}).refine((phase) => !phase.endedAt || Date.parse(phase.endedAt) >= Date.parse(phase.startedAt));
+var TokenUsageMetricSchema = z.object({
+  provider: z.enum(["claude-code", "codex", "grok"]),
+  model: z.string().min(1).nullable().optional(),
+  requestId: z.string().min(1),
+  phase: z.string().min(1),
+  startedAt: UtcTimestampSchema,
+  inputTokens: z.number().int().nonnegative().nullable(),
+  cacheReadTokens: z.number().int().nonnegative().nullable(),
+  cacheWriteTokens: z.number().int().nonnegative().nullable(),
+  outputTokens: z.number().int().nonnegative().nullable(),
+  measured: z.literal(true)
+});
+var ChangeMetricsSchema = z.object({
+  version: z.literal(1),
+  phases: z.array(PhaseMetricSchema),
+  requests: z.array(TokenUsageMetricSchema)
+});
+var MODEL_ID = /^[A-Za-z0-9._:/-]+$/;
+function metricsPath(projectRoot, config, changeId) {
+  return `${changePath(projectRoot, config, changeId)}/metrics.json`;
+}
+function emptyChangeMetrics() {
+  return { version: 1, phases: [], requests: [] };
+}
+async function readChangeMetrics(projectRoot, config, changeId) {
+  const path = metricsPath(projectRoot, config, changeId);
+  if (!await pathExists(path)) return emptyChangeMetrics();
+  return ChangeMetricsSchema.parse(JSON.parse(await readText(path)));
+}
+async function writeChangeMetrics(projectRoot, config, changeId, metrics) {
+  const path = metricsPath(projectRoot, config, changeId);
+  const validated = ChangeMetricsSchema.parse(metrics);
+  await writeText(path, `${JSON.stringify(validated, null, 2)}
+`);
+}
+async function startPhase(projectRoot, config, changeId, phase, startedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  if (!config.metrics.enabled) return;
+  const metrics = await readChangeMetrics(projectRoot, config, changeId);
+  const current = metrics.phases.at(-1);
+  if (current && !current.endedAt) {
+    throw new Error(`Cannot start phase "${phase}" while "${current.phase}" is still open.`);
+  }
+  metrics.phases.push({ phase, startedAt });
+  await writeChangeMetrics(projectRoot, config, changeId, metrics);
+}
+async function transitionPhase(projectRoot, config, changeId, fromPhase, toPhase, at = (/* @__PURE__ */ new Date()).toISOString(), fromStartedAt = at) {
+  if (!config.metrics.enabled || fromPhase === toPhase) return;
+  const metrics = await readChangeMetrics(projectRoot, config, changeId);
+  const current = metrics.phases.at(-1);
+  if (current && !current.endedAt) {
+    if (current.phase !== fromPhase) {
+      if (current.phase === toPhase) return;
+      throw new Error(
+        `Cannot leave phase "${fromPhase}" while metrics phase "${current.phase}" is open.`
+      );
+    }
+    current.endedAt = at;
+  } else {
+    metrics.phases.push({ phase: fromPhase, startedAt: fromStartedAt, endedAt: at });
+  }
+  if (toPhase) metrics.phases.push({ phase: toPhase, startedAt: at });
+  await writeChangeMetrics(projectRoot, config, changeId, metrics);
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function tokenCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function isoTimestamp(value) {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) return null;
+  return new Date(value).toISOString();
+}
+function stringId(...values) {
+  const value = values.find((item) => typeof item === "string" && item.trim().length > 0);
+  return typeof value === "string" ? value : null;
+}
+function parseClaudeUsage(record) {
+  const message = asObject(record.message);
+  const usage = asObject(message?.usage);
+  const requestId = stringId(record.requestId, message?.id);
+  const startedAt = isoTimestamp(record.timestamp ?? message?.timestamp);
+  if (!usage || !requestId || !startedAt) return null;
+  return {
+    provider: "claude-code",
+    requestId,
+    startedAt,
+    inputTokens: tokenCount(usage.input_tokens),
+    cacheReadTokens: tokenCount(usage.cache_read_input_tokens),
+    cacheWriteTokens: tokenCount(usage.cache_creation_input_tokens),
+    outputTokens: tokenCount(usage.output_tokens)
+  };
+}
+function parseCodexUsage(record, state) {
+  const payload = asObject(record.payload);
+  const payloadType = payload?.type;
+  const timestamp = isoTimestamp(record.timestamp);
+  if (record.type === "event_msg" && (payloadType === "task_started" || payloadType === "turn_started")) {
+    if (timestamp) state.turnStartedAt = timestamp;
+    state.messageId = void 0;
+    return null;
+  }
+  if (record.type === "response_item" && payloadType === "message" && payload?.role === "assistant") {
+    state.messageId = stringId(payload.id, record.id) ?? void 0;
+    return null;
+  }
+  if (record.type !== "event_msg" || payloadType !== "token_count") return null;
+  const info = asObject(payload?.info);
+  const usage = asObject(info?.last_token_usage);
+  const totalInput = tokenCount(usage?.input_tokens);
+  const cachedInput = tokenCount(usage?.cached_input_tokens);
+  const requestId = stringId(payload?.request_id, info?.request_id, state.messageId);
+  const startedAt = state.turnStartedAt;
+  if (!usage || !requestId || !startedAt) return null;
+  state.turnStartedAt = void 0;
+  state.messageId = void 0;
+  return {
+    provider: "codex",
+    requestId,
+    startedAt,
+    inputTokens: totalInput === null ? null : Math.max(0, totalInput - (cachedInput ?? 0)),
+    cacheReadTokens: cachedInput,
+    cacheWriteTokens: null,
+    outputTokens: tokenCount(usage.output_tokens)
+  };
+}
+function phaseAt(metrics, timestamp) {
+  const requestTime = Date.parse(timestamp);
+  return metrics.phases.find((phase) => {
+    const start = Date.parse(phase.startedAt);
+    const end = phase.endedAt ? Date.parse(phase.endedAt) : Number.POSITIVE_INFINITY;
+    return requestTime >= start && requestTime < end;
+  });
+}
+function toForwardSlashes(value) {
+  let out = "";
+  for (const ch of value) out += ch === "\\" ? "/" : ch;
+  return out;
+}
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
+function stripLeadingDotSlash(value) {
+  let out = value;
+  while (out.startsWith("./")) out = out.slice(2);
+  return out;
+}
+function prefixLooksAbsolute(prefix) {
+  if (prefix.startsWith("/") || prefix.startsWith("\\")) return true;
+  const first = prefix.charCodeAt(0);
+  const letter = first >= 65 && first <= 90 || first >= 97 && first <= 122;
+  return letter && prefix.charCodeAt(1) === 58;
+}
+function normalizeExcludePrefix(prefix) {
+  if (isAbsolute(prefix) || prefixLooksAbsolute(prefix)) {
+    throw new Error("metrics.exclude prefix is invalid.");
+  }
+  const slashed = stripLeadingDotSlash(toForwardSlashes(prefix));
+  if (prefixLooksAbsolute(slashed)) throw new Error("metrics.exclude prefix is invalid.");
+  const trimmed = stripTrailingSlashes(slashed);
+  if (!trimmed) throw new Error("metrics.exclude prefix is invalid.");
+  for (const segment of trimmed.split("/")) {
+    if (segment === "" || segment === "." || segment === "..") {
+      throw new Error("metrics.exclude prefix is invalid.");
+    }
+  }
+  return trimmed;
+}
+function assertSessionLogAllowed(projectRoot, prefixes, sessionLogPath) {
+  const normalized = prefixes.map(normalizeExcludePrefix);
+  const root = resolve(projectRoot);
+  const absLog = resolve(root, sessionLogPath);
+  const rel = relative(root, absLog);
+  if (rel.startsWith("..") || isAbsolute(rel)) return;
+  const relPosix = rel.split(sep).join("/");
+  for (const prefix of normalized) {
+    if (relPosix === prefix || relPosix.startsWith(`${prefix}/`)) {
+      throw new Error(`Refusing to import a session log under excluded prefix "${prefix}".`);
+    }
+  }
+}
+function recordParsed(metrics, requestIds, result, parsed) {
+  const phase = phaseAt(metrics, parsed.startedAt);
+  if (!phase) {
+    result.unmatched += 1;
+    return;
+  }
+  const key = `${parsed.provider}\0${parsed.requestId}`;
+  if (requestIds.has(key)) {
+    result.duplicates += 1;
+    return;
+  }
+  requestIds.add(key);
+  const request = {
+    provider: parsed.provider,
+    requestId: parsed.requestId,
+    phase: phase.phase,
+    startedAt: parsed.startedAt,
+    inputTokens: parsed.inputTokens,
+    cacheReadTokens: parsed.cacheReadTokens,
+    cacheWriteTokens: parsed.cacheWriteTokens,
+    outputTokens: parsed.outputTokens,
+    measured: true
+  };
+  if (parsed.model) request.model = parsed.model;
+  metrics.requests.push(request);
+  result.imported += 1;
+}
+async function readTurnStarts(directory) {
+  const starts = /* @__PURE__ */ new Map();
+  const path = join(directory, "events.jsonl");
+  if (!await pathExists(path)) return starts;
+  const lines = createInterface({
+    input: createReadStream(path),
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let record = null;
+    try {
+      record = asObject(JSON.parse(line));
+    } catch {
+      continue;
+    }
+    if (!record || record.type !== "turn_started") continue;
+    const turnNumber = tokenCount(record.turn_number);
+    const timestamp = isoTimestamp(record.ts);
+    if (turnNumber === null || turnNumber < 1 || !timestamp || starts.has(turnNumber)) continue;
+    starts.set(turnNumber, timestamp);
+  }
+  return starts;
+}
+function grokBucket(value) {
+  const bucket = asObject(value);
+  if (!bucket) return null;
+  const input = tokenCount(bucket.inputTokens);
+  const cacheRead = tokenCount(bucket.cachedReadTokens);
+  const cacheWrite = tokenCount(bucket.cacheCreationTokens);
+  const output = tokenCount(bucket.outputTokens);
+  if (input === null || cacheRead === null || cacheWrite === null || output === null) return null;
+  return { input, cacheRead, cacheWrite, output };
+}
+async function importGrokUsage(filePath, metrics, requestIds, providers, result) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readText(filePath));
+  } catch {
+    throw new Error("usage.json is not a Grok usage file.");
+  }
+  const document = asObject(parsed);
+  const sessionId = document?.sessionId;
+  const turns = document?.turns;
+  if (!document || typeof sessionId !== "string" || sessionId.length === 0 || !Array.isArray(turns)) {
+    throw new Error("usage.json is not a Grok usage file.");
+  }
+  providers.add("grok");
+  const session = asObject(document.session);
+  if (session?.usageIsIncomplete === true) result.incomplete = true;
+  const turnStarts = await readTurnStarts(dirname(filePath));
+  for (const turnValue of turns) {
+    const turn = asObject(turnValue);
+    if (!turn) {
+      result.ignored += 1;
+      continue;
+    }
+    if (turn.usageIsIncomplete === true) result.incomplete = true;
+    const turnNumber = tokenCount(turn.turnNumber);
+    const modelUsage = asObject(turn.modelUsage);
+    const entries = modelUsage ? Object.entries(modelUsage) : [];
+    if (turnNumber === null || turnNumber < 1) {
+      result.ignored += 1;
+      continue;
+    }
+    const startedAt = turnStarts.get(turnNumber) ?? isoTimestamp(turn.endedAt);
+    if (!startedAt) {
+      result.ignored += entries.length;
+      continue;
+    }
+    for (const [model, bucketValue] of entries) {
+      if (!MODEL_ID.test(model)) {
+        result.ignored += 1;
+        continue;
+      }
+      const bucket = grokBucket(bucketValue);
+      if (!bucket) {
+        result.ignored += 1;
+        continue;
+      }
+      recordParsed(metrics, requestIds, result, {
+        provider: "grok",
+        model,
+        requestId: `${sessionId}:${turnNumber}:${model}`,
+        startedAt,
+        inputTokens: Math.max(0, bucket.input - bucket.cacheRead - bucket.cacheWrite),
+        cacheReadTokens: bucket.cacheRead,
+        cacheWriteTokens: bucket.cacheWrite,
+        outputTokens: bucket.output
+      });
+    }
+  }
+}
+async function importJsonlUsage(sessionLogPath, metrics, requestIds, providers, result) {
+  const codexState = {};
+  const lines = createInterface({
+    input: createReadStream(sessionLogPath),
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let record = null;
+    try {
+      record = asObject(JSON.parse(line));
+    } catch {
+      result.ignored += 1;
+      continue;
+    }
+    if (!record) {
+      result.ignored += 1;
+      continue;
+    }
+    const message = asObject(record.message);
+    const claudeCandidate = record.type === "assistant" && Boolean(asObject(message?.usage));
+    const codexCandidate = record.type === "event_msg" && asObject(record.payload)?.type === "token_count";
+    const parsed = claudeCandidate ? parseClaudeUsage(record) : parseCodexUsage(record, codexState);
+    if (claudeCandidate) providers.add("claude-code");
+    else if (codexCandidate) providers.add("codex");
+    if (!parsed) {
+      if (claudeCandidate || codexCandidate) result.ignored += 1;
+      continue;
+    }
+    recordParsed(metrics, requestIds, result, parsed);
+  }
+}
+async function grokUsagePath(sessionLogPath) {
+  const info = await stat(sessionLogPath);
+  if (info.isDirectory()) {
+    const filePath = join(sessionLogPath, "usage.json");
+    if (!await pathExists(filePath)) throw new Error("Grok usage.json is missing.");
+    return filePath;
+  }
+  return basename(sessionLogPath) === "usage.json" ? sessionLogPath : null;
+}
+async function importSessionMetrics(projectRoot, config, changeId, sessionLogPath) {
+  if (!config.metrics.enabled) throw new Error("Metrics are disabled in .sdd/config.yaml.");
+  assertSessionLogAllowed(projectRoot, config.metrics.exclude, sessionLogPath);
+  const metrics = await readChangeMetrics(projectRoot, config, changeId);
+  const requestIds = new Set(
+    metrics.requests.map((request) => `${request.provider}\0${request.requestId}`)
+  );
+  const providers = /* @__PURE__ */ new Set();
+  const result = {
+    imported: 0,
+    duplicates: 0,
+    ignored: 0,
+    unmatched: 0,
+    providers: [],
+    incomplete: false
+  };
+  const grokPath = await grokUsagePath(sessionLogPath);
+  if (grokPath) await importGrokUsage(grokPath, metrics, requestIds, providers, result);
+  else await importJsonlUsage(sessionLogPath, metrics, requestIds, providers, result);
+  result.providers = [...providers].sort();
+  if (result.imported) await writeChangeMetrics(projectRoot, config, changeId, metrics);
+  return result;
+}
 
 // src/stage-gates.ts
-import { join } from "pathe";
+import { join as join2 } from "pathe";
 async function checkRequiredArtifacts(changePath2, stageId, artifacts) {
   const errors = [];
   for (const artifact of artifacts) {
     if (!artifact.required) continue;
     if (artifact.path.endsWith("/")) {
-      const target2 = join(changePath2, artifact.path);
+      const target2 = join2(changePath2, artifact.path);
       if (!await pathExists(target2)) {
         errors.push(`Missing required directory: ${artifact.path} (stage ${stageId})`);
       }
       continue;
     }
-    const target = join(changePath2, artifact.path);
+    const target = join2(changePath2, artifact.path);
     if (!await pathExists(target)) {
       errors.push(incompleteArtifactReason(artifact.path, null));
       continue;
@@ -146,7 +607,10 @@ async function canLeaveStage(ctx, config) {
   }
   const requiredCmds = stage.verify?.commands?.filter((c) => c.required) ?? [];
   if (requiredCmds.length) {
-    const verifyOk = ctx.meta.verify_results?.[stage.id]?.ok === true;
+    const lastRun = ctx.meta.verify_results?.[stage.id];
+    const verifyOk = requiredCmds.every(
+      (c) => lastRun?.results?.some((r) => r.name === c.name && r.exitCode === 0)
+    );
     const humanOverride = gateState?.status === "waived" || gateState?.status === "approved";
     if (!verifyOk && !humanOverride) {
       errors.push(
@@ -216,6 +680,9 @@ async function createChange(input) {
     stage: workflow.stages[0].id,
     domain: input.domain,
     branch: input.branch,
+    epic: input.epic,
+    story: input.story,
+    depends: input.depends ?? [],
     flags: input.flags ?? {},
     overrides: {
       skip_stages: [],
@@ -232,10 +699,11 @@ async function createChange(input) {
     throw new Error(`Workflow ${workflowName} has no active stages`);
   }
   await writeYaml(changeMetaPath(projectRoot, config, id), meta);
+  await startPhase(projectRoot, config, id, startId, meta.created);
   await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
   await setActiveChange(projectRoot, config, id);
   try {
-    const { refreshActiveAgentContext } = await import("./agents-CLTJJVOD.js");
+    const { refreshActiveAgentContext } = await import("./agents-AKSUXQHN.js");
     await refreshActiveAgentContext(projectRoot);
   } catch {
   }
@@ -246,7 +714,7 @@ async function materializeStageArtifacts(projectRoot, config, changeId, workflow
   const dir = changePath(projectRoot, config, changeId);
   const tdir = templatesDir(projectRoot);
   for (const artifact of stage.artifacts) {
-    const target = join2(dir, artifact.path);
+    const target = join3(dir, artifact.path);
     if (await pathExists(target)) continue;
     if (artifact.path.endsWith("/")) {
       await ensureDir(target);
@@ -255,11 +723,11 @@ async function materializeStageArtifacts(projectRoot, config, changeId, workflow
     }
     let content = defaultArtifactContent(artifact.id, meta, stage, workflow);
     if (artifact.template) {
-      const templatePath = join2(tdir, artifact.template.replace(/^templates\//, ""));
+      const templatePath = join3(tdir, artifact.template.replace(/^templates\//, ""));
       const candidates = [
-        join2(tdir, artifact.template),
+        join3(tdir, artifact.template),
         templatePath,
-        join2(tdir, `${artifact.id}.md`)
+        join3(tdir, `${artifact.id}.md`)
       ];
       for (const c of candidates) {
         if (await pathExists(c)) {
@@ -270,7 +738,7 @@ async function materializeStageArtifacts(projectRoot, config, changeId, workflow
         }
       }
     } else {
-      const fallback = join2(tdir, `${artifact.id}.md`);
+      const fallback = join3(tdir, `${artifact.id}.md`);
       if (await pathExists(fallback)) {
         content = interpolate(await readText(fallback), meta, stage, workflow, {
           idea: String(meta.flags?.idea ?? meta.title ?? "")
@@ -289,7 +757,7 @@ function interpolate(template, meta, stage, workflow, extra) {
 function defaultArtifactContent(artifactId, meta, stage, workflow) {
   return `# ${artifactId}
 
-> Change: **${meta.title}** (\`${meta.id}\`)  
+> Change: **${meta.title}** (\`${meta.id}\`)
 > Workflow: \`${workflow.name}\` \xB7 Stage: \`${stage.id}\`
 
 ## Summary
@@ -311,6 +779,16 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     const fallback = await fallbackIncompleteStageId(ctx);
     if (fallback && fallback !== ctx.meta.stage) {
       const from2 = ctx.meta.stage;
+      const at2 = nowIso();
+      await transitionPhase(
+        projectRoot,
+        config,
+        changeId,
+        from2,
+        fallback,
+        at2,
+        ctx.meta.updated ?? ctx.meta.created
+      );
       ctx.meta.stage = fallback;
       await saveChangeMeta(projectRoot, config, ctx.meta);
       const stage2 = getStage(ctx.workflow, ctx.meta, fallback);
@@ -323,7 +801,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
         stage2
       );
       try {
-        const { refreshActiveAgentContext } = await import("./agents-CLTJJVOD.js");
+        const { refreshActiveAgentContext } = await import("./agents-AKSUXQHN.js");
         await refreshActiveAgentContext(projectRoot);
       } catch {
       }
@@ -358,6 +836,16 @@ async function advanceStage(projectRoot, config, changeId, opts) {
       warnings: [...warnings, "No further stages. Run `sdd complete` when ready."]
     };
   }
+  const at = nowIso();
+  await transitionPhase(
+    projectRoot,
+    config,
+    changeId,
+    from,
+    next,
+    at,
+    ctx.meta.updated ?? ctx.meta.created
+  );
   ctx.meta.stage = next;
   await saveChangeMeta(projectRoot, config, ctx.meta);
   const stage = getStage(ctx.workflow, ctx.meta, next);
@@ -370,7 +858,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     stage
   );
   try {
-    const { refreshActiveAgentContext } = await import("./agents-CLTJJVOD.js");
+    const { refreshActiveAgentContext } = await import("./agents-AKSUXQHN.js");
     await refreshActiveAgentContext(projectRoot);
   } catch {
   }
@@ -406,6 +894,16 @@ async function skipStage(projectRoot, config, changeId, stageId, reason) {
   if (ctx.meta.stage === stageId) {
     const next = nextStageId(ctx.workflow, ctx.meta);
     if (next) {
+      const at = nowIso();
+      await transitionPhase(
+        projectRoot,
+        config,
+        changeId,
+        stageId,
+        next,
+        at,
+        ctx.meta.updated ?? ctx.meta.created
+      );
       ctx.meta.stage = next;
       const nextStage = getStage(ctx.workflow, ctx.meta, next);
       if (nextStage) {
@@ -431,11 +929,24 @@ async function switchWorkflow(projectRoot, config, changeId, workflowName, reaso
       `Workflow "${workflowName}" is not in allowed_workflows: ${config.allowed_workflows.join(", ")}`
     );
   }
+  const previousStage = ctx.meta.stage;
   ctx.meta.workflow = workflowName;
   const hasStage = workflow.stages.some((s) => s.id === ctx.meta.stage);
   if (!hasStage) {
     ctx.meta.stage = workflow.stages[0].id;
   }
+  if (ctx.meta.stage !== previousStage) {
+    const at = nowIso();
+    await transitionPhase(
+      projectRoot,
+      config,
+      changeId,
+      previousStage,
+      ctx.meta.stage,
+      at,
+      ctx.meta.updated ?? ctx.meta.created
+    );
+  }
   if (reason) {
     ctx.meta.flags = {
       ...ctx.meta.flags,
@@ -465,13 +976,22 @@ async function completeChange(projectRoot, config, changeId) {
   if (!check.ok) {
     throw new Error(check.errors.join("\n"));
   }
+  await transitionPhase(
+    projectRoot,
+    config,
+    changeId,
+    ctx.meta.stage,
+    null,
+    nowIso(),
+    ctx.meta.updated ?? ctx.meta.created
+  );
   ctx.meta.status = "completed";
   ctx.meta.completed_at = nowIso();
   await saveChangeMeta(projectRoot, config, ctx.meta);
   let promoted;
   if (ctx.meta.workflow === "greenfield" || ctx.meta.flags?.greenfield === true) {
     try {
-      const { promoteGreenfieldToMemory: promoteGreenfieldToMemory2 } = await import("./greenfield-QQJH3XL3.js");
+      const { promoteGreenfieldToMemory: promoteGreenfieldToMemory2 } = await import("./greenfield-I5S5OS2D.js");
       promoted = await promoteGreenfieldToMemory2(projectRoot, config, changeId);
     } catch {
     }
@@ -480,7 +1000,7 @@ async function completeChange(projectRoot, config, changeId) {
   let archivedTo = null;
   const shouldArchive = config.persistence.archive_on_complete && ctx.workflow.on_complete?.archive !== false;
   if (shouldArchive) {
-    const dest = join2(archiveDir(projectRoot, config), changeId);
+    const dest = join3(archiveDir(projectRoot, config), changeId);
     if (await pathExists(dest)) {
       throw new Error(`Archive already exists for change: ${changeId}`);
     }
@@ -490,13 +1010,14 @@ async function completeChange(projectRoot, config, changeId) {
     archivedTo = dest;
   }
   if (archivedTo) {
-    const meta = ChangeMetaSchema.parse(await readYaml(join2(archivedTo, "meta.yaml")));
+    const meta = ChangeMetaSchema.parse(await readYaml(join3(archivedTo, "meta.yaml")));
     return {
       archivedTo,
       promoted,
       ctx: {
         id: changeId,
         path: archivedTo,
+        displayPath: displayArchivePath(config, changeId),
         meta,
         workflow: ctx.workflow,
         stages: ctx.stages,
@@ -528,7 +1049,7 @@ async function startGreenfield(input) {
     workflowName: "greenfield",
     flags: { greenfield: true, idea }
   });
-  const visionPath = join3(ctx.path, "vision.md");
+  const visionPath = join4(ctx.path, "vision.md");
   if (await pathExists(visionPath)) {
     let body = await readText(visionPath);
     if (body.includes("{{idea}}")) {
@@ -597,18 +1118,18 @@ function parseFeaturesBacklog(markdown, sourcePath) {
   return features;
 }
 async function findFeaturesBacklogPath(projectRoot, config) {
-  const mem = join3(memoryDir(projectRoot, config), "features.md");
+  const mem = join4(memoryDir(projectRoot, config), "features.md");
   if (await pathExists(mem)) return mem;
-  const { getActiveChangeId: getActiveChangeId2 } = await import("./change-context-W4HDO2IK.js");
+  const { getActiveChangeId: getActiveChangeId2 } = await import("./change-context-REE7UKU7.js");
   const active = await getActiveChangeId2(projectRoot, config);
   if (active) {
-    const p = join3(changePath(projectRoot, config, active), "features.md");
+    const p = join4(changePath(projectRoot, config, active), "features.md");
     if (await pathExists(p)) return p;
   }
   const ids = (await listDirs(changesDir(projectRoot, config))).sort().reverse();
   for (const id of ids) {
     try {
-      const p = join3(changePath(projectRoot, config, id), "features.md");
+      const p = join4(changePath(projectRoot, config, id), "features.md");
       if (await pathExists(p)) {
         const body = await readText(p);
         if (parseFeaturesBacklog(body, p).length) return p;
@@ -663,7 +1184,7 @@ async function startFeatureFromBacklog(input) {
   const stage = ctx.workflow.stages.find((s) => s.id === ctx.meta.stage);
   const art = stage?.artifacts.find((a) => a.required) ?? stage?.artifacts[0];
   if (art) {
-    const artPath = join3(ctx.path, art.path);
+    const artPath = join4(ctx.path, art.path);
     if (await pathExists(artPath)) {
       let body = await readText(artPath);
       if (!isSubstantiveArtifactContent(body)) {
@@ -719,11 +1240,11 @@ async function promoteGreenfieldToMemory(projectRoot, config, changeId) {
   ];
   const written = [];
   for (const { from, to } of map) {
-    const src = join3(dir, from);
+    const src = join4(dir, from);
     if (!await pathExists(src)) continue;
     const body = await readText(src);
     if (!isSubstantiveArtifactContent(body)) continue;
-    const dest = join3(mem, to);
+    const dest = join4(mem, to);
     await writeText(
       dest,
       body.includes("Promoted from greenfield") ? body : `${body.trim()}
@@ -733,9 +1254,9 @@ async function promoteGreenfieldToMemory(projectRoot, config, changeId) {
 _Promoted from greenfield change \`${changeId}\`._
 `
     );
-    written.push(join3(config.memory_path, to));
+    written.push(join4(config.memory_path, to));
   }
-  const indexPath = join3(mem, "index.md");
+  const indexPath = join4(mem, "index.md");
   if (await pathExists(indexPath)) {
     let index = await readText(indexPath);
     if (!index.includes("features.md")) {
@@ -751,6 +1272,15 @@ _Promoted from greenfield change \`${changeId}\`._
 }
 
 export {
+  PhaseMetricSchema,
+  TokenUsageMetricSchema,
+  ChangeMetricsSchema,
+  emptyChangeMetrics,
+  readChangeMetrics,
+  startPhase,
+  transitionPhase,
+  assertSessionLogAllowed,
+  importSessionMetrics,
   isSubstantiveArtifactContent,
   incompletePriorStageErrors,
   canLeaveStage,