@structured-vibe-coding/core 0.17.2 → 0.19.0

package/dist/chunk-2FJBFYVJ.js

@@ -0,0 +1,1576 @@
+import {
+  WORK_TYPES,
+  getHeadSha,
+  gitUserName,
+  loadConfig,
+  readTeamConfig
+} from "./chunk-TGRV6WGS.js";
+import {
+  ChangeMetaSchema,
+  activeStages,
+  buildContext,
+  changeDirName,
+  clearActiveIf,
+  firstActiveStageId,
+  getActiveChangeId,
+  getStage,
+  isStageSkipped,
+  loadWorkflow,
+  nextStageId,
+  nowIso,
+  saveChangeMeta,
+  setActiveChange,
+  shouldAutoSkip,
+  uniqueChangeDirName
+} from "./chunk-HG7TPW5V.js";
+import {
+  archiveDir,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  copyDir,
+  displayArchivePath,
+  ensureDir,
+  listDirs,
+  listFiles,
+  memoryDir,
+  pathExists,
+  readText,
+  readYaml,
+  removePath,
+  templatesDir,
+  writeText,
+  writeYaml
+} from "./chunk-O5SP6X5R.js";
+
+// src/greenfield.ts
+import { join as join6 } 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 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(/\{\{[^}]*\}\}/g, "").replace(/\b(TBD|TODO|N\/A|none|n\/a)\b/gi, "");
+  return meaningful.length >= 32;
+}
+function incompleteArtifactReason(path, content) {
+  if (content == null) {
+    return `Missing required artifact: ${path}`;
+  }
+  if (!isSubstantiveArtifactContent(content)) {
+    return [
+      `Required artifact still incomplete (looks like empty template/stub): ${path}`,
+      ``,
+      `Open that file and replace the template with a few real sentences, for example:`,
+      `  - What is broken or missing?`,
+      `  - What will you change?`,
+      `  - How will you know it worked?`,
+      ``,
+      `Then run: sdd next`,
+      `Optional stages only: sdd skip <stage> -r "not needed"`
+    ].join("\n");
+  }
+  return null;
+}
+
+// src/change.ts
+import { join as join5 } 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 DecisionMetricSchema = z.object({
+  workType: z.enum(WORK_TYPES),
+  kind: z.enum(["reason", "decide"]),
+  provider: z.enum(["command", "ollama"]),
+  model: z.string().min(1).nullable(),
+  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()
+});
+var ChangeMetricsSchema = z.object({
+  version: z.literal(1),
+  phases: z.array(PhaseMetricSchema),
+  requests: z.array(TokenUsageMetricSchema),
+  decisions: z.array(DecisionMetricSchema).optional()
+});
+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 recordDecisionMetric(projectRoot, config, changeId, draft) {
+  if (!config.metrics.enabled) return;
+  const metrics = await readChangeMetrics(projectRoot, config, changeId);
+  const decisions = [...metrics.decisions ?? [], DecisionMetricSchema.parse(draft)];
+  await writeChangeMetrics(projectRoot, config, changeId, { ...metrics, decisions });
+}
+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 as join3 } from "pathe";
+
+// src/role/signoff.ts
+import { appendFile } from "fs/promises";
+import { join as join2 } from "pathe";
+function ok(stdout) {
+  return { exitCode: 0, stdout };
+}
+function fail(stdout) {
+  return { exitCode: 1, stdout };
+}
+function oneLine(note, empty, broken) {
+  const raw = note ?? "";
+  if (raw.includes("\n") || raw.includes("\r")) return fail(broken);
+  const words = raw.trim();
+  if (!words) return fail(empty);
+  return words;
+}
+function safeStageId(stage) {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(stage);
+}
+function signoffFileName(stage, sha) {
+  return `reviews/${stage}-${sha}.md`;
+}
+function renderSignoff(record) {
+  return [
+    "---",
+    `kind: ${record.kind}`,
+    `sha: ${record.sha}`,
+    `reviewer: ${record.reviewer}`,
+    `verdict: ${record.verdict}`,
+    "---",
+    record.evidence,
+    ""
+  ].join("\n");
+}
+function parseSignoff(raw) {
+  const lines = raw.split("\n");
+  if (lines[0] !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end <= 1) return null;
+  const fields = /* @__PURE__ */ new Map();
+  for (const line of lines.slice(1, end)) {
+    const split = line.indexOf(":");
+    if (split <= 0) return null;
+    fields.set(line.slice(0, split).trim(), line.slice(split + 1).trim());
+  }
+  const kind = fields.get("kind") ?? "";
+  const sha = fields.get("sha") ?? "";
+  const reviewer = fields.get("reviewer") ?? "";
+  const verdict = fields.get("verdict") ?? "";
+  const evidence = lines.slice(end + 1).join("\n").trim();
+  if (!kind || !sha || !reviewer || !verdict || !evidence) return null;
+  return { kind, sha, reviewer, verdict, evidence };
+}
+async function headSha(root) {
+  try {
+    const sha = await getHeadSha(root);
+    if (!sha) return fail("Cannot sign off: Git HEAD is unavailable in this project.");
+    return sha;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Git HEAD is unavailable.";
+    return fail(message);
+  }
+}
+async function openChange(root, change) {
+  const config = await loadConfig(root);
+  const requested = change?.trim() ?? "";
+  const changeId = requested || await getActiveChangeId(root, config);
+  if (!changeId) return fail("No active change.");
+  try {
+    const ctx = await buildContext(root, config, changeId);
+    return { path: ctx.path, stage: ctx.meta.stage };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Change not found.";
+    return fail(message);
+  }
+}
+function isFailure(value) {
+  return "exitCode" in value;
+}
+async function recordSignoff(root, input) {
+  const words = oneLine(input.note, "A sign-off needs a note.", "A sign-off note is one line.");
+  if (typeof words !== "string") return words;
+  const opened = await openChange(root, input.change);
+  if (isFailure(opened)) return opened;
+  const stage = (input.stage?.trim() || opened.stage).trim();
+  if (!safeStageId(stage)) return fail("A stage id is not valid.");
+  const team = await readTeamConfig(root);
+  if ("error" in team) return fail(team.error);
+  const sha = await headSha(root);
+  if (typeof sha !== "string") return sha;
+  const gitUser = gitUserName(root);
+  if (!gitUser) return fail("Git user.name is not set.");
+  if (!team.team.humans.some((human) => human.name === gitUser)) {
+    return fail("Git user.name is not a human approver.");
+  }
+  const file = join2(opened.path, signoffFileName(stage, sha));
+  const existing = await pathExists(file) ? parseSignoff(await readText(file)) : null;
+  const same = existing !== null && existing.kind === stage && existing.sha === sha && existing.reviewer === gitUser && existing.verdict === "accept";
+  if (!same) {
+    await writeText(
+      file,
+      renderSignoff({ kind: stage, sha, reviewer: gitUser, verdict: "accept", evidence: words })
+    );
+  }
+  await appendFile(
+    join2(opened.path, "decisions.md"),
+    `${nowIso()} sign-off ${stage} ${sha} ${gitUser} accept ${words}
+`
+  );
+  return ok(`Signed ${stage} at ${sha}.`);
+}
+async function recordDecisionRequest(root, input) {
+  const words = oneLine(input.note, "A decision needs a note.", "A decision note is one line.");
+  if (typeof words !== "string") return words;
+  const opened = await openChange(root, input.change);
+  if (isFailure(opened)) return opened;
+  await appendFile(join2(opened.path, "decisions.md"), `${nowIso()} decision-needed ${words}
+`);
+  return ok("Decision needed.");
+}
+async function checkHumanSignoff(root, changePath2, stageId) {
+  if (!safeStageId(stageId)) return { ok: false, message: "A stage id is not valid." };
+  const team = await readTeamConfig(root);
+  if ("error" in team) return { ok: false, message: team.error };
+  let sha;
+  try {
+    sha = await getHeadSha(root);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Git HEAD is unavailable.";
+    return { ok: false, message };
+  }
+  if (!sha) {
+    return {
+      ok: false,
+      message: `Cannot leave stage "${stageId}": Git HEAD is unavailable, so a human sign-off cannot be checked.`
+    };
+  }
+  const file = join2(changePath2, signoffFileName(stageId, sha));
+  if (!await pathExists(file)) {
+    return {
+      ok: false,
+      message: `Hard gate on stage "${stageId}" needs a human sign-off for this commit. Run \`sdd team signoff\`.`
+    };
+  }
+  const parsed = parseSignoff(await readText(file));
+  const listed = parsed !== null && parsed.kind === stageId && parsed.sha === sha && parsed.verdict === "accept" && team.team.humans.some((human) => human.name === parsed.reviewer);
+  if (!listed) {
+    return { ok: false, message: `Sign-off for stage "${stageId}" does not match this commit.` };
+  }
+  return { ok: true };
+}
+
+// src/stage-gates.ts
+async function checkRequiredArtifacts(changePath2, stageId, artifacts) {
+  const errors = [];
+  for (const artifact of artifacts) {
+    if (!artifact.required) continue;
+    if (artifact.path.endsWith("/")) {
+      const target2 = join3(changePath2, artifact.path);
+      if (!await pathExists(target2)) {
+        errors.push(`Missing required directory: ${artifact.path} (stage ${stageId})`);
+      }
+      continue;
+    }
+    const target = join3(changePath2, artifact.path);
+    if (!await pathExists(target)) {
+      errors.push(incompleteArtifactReason(artifact.path, null));
+      continue;
+    }
+    const content = await readText(target);
+    const reason = incompleteArtifactReason(artifact.path, content);
+    if (reason) {
+      errors.push(`${reason} (stage ${stageId})`);
+    }
+  }
+  return errors;
+}
+async function incompletePriorStageErrors(ctx) {
+  const errors = [];
+  const stages = activeStages(ctx.workflow, ctx.meta);
+  const currentIdx = stages.findIndex((s) => s.id === ctx.meta.stage);
+  if (currentIdx <= 0) return errors;
+  for (let i = 0; i < currentIdx; i++) {
+    const stage = stages[i];
+    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
+      continue;
+    }
+    const required = stage.artifacts.filter((a) => a.required);
+    if (!required.length && stage.optional) continue;
+    const stageErrors = await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts);
+    if (stageErrors.length) {
+      errors.push(
+        `Prior stage "${stage.id}" is not complete \u2014 finish it or \`sdd skip ${stage.id} -r "\u2026"\` if optional.`
+      );
+      errors.push(...stageErrors);
+    }
+  }
+  return errors;
+}
+async function canLeaveStage(ctx, config, projectRoot) {
+  const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
+  const errors = [];
+  const warnings = [];
+  if (!stage) {
+    return { ok: false, errors: [`Unknown stage: ${ctx.meta.stage}`], warnings };
+  }
+  errors.push(...await incompletePriorStageErrors(ctx));
+  errors.push(...await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts));
+  const declared = stage.gate?.type ?? "soft";
+  let effectiveGate = declared;
+  if (config.policy.gates === "hard" && declared === "soft") {
+    effectiveGate = "hard";
+  }
+  const gateState = ctx.meta.gates?.[stage.id];
+  const humanGate = effectiveGate === "hard" && (stage.gate?.approvers?.includes("human") ?? false);
+  if (humanGate) {
+    if (gateState?.status === "failed") {
+      errors.push(
+        `Hard gate on stage "${stage.id}" is not approved. Run \`sdd gate approve\` or complete the checklist.`
+      );
+    } else if (gateState?.status !== "waived") {
+      if (!projectRoot) {
+        errors.push(
+          `Cannot leave stage "${stage.id}": the project root is required to check a human sign-off.`
+        );
+      } else {
+        const signed = await checkHumanSignoff(projectRoot, ctx.path, stage.id);
+        if (!signed.ok) errors.push(signed.message);
+      }
+    }
+  } else if (effectiveGate === "hard") {
+    if (!gateState || gateState.status !== "approved" && gateState.status !== "waived") {
+      errors.push(
+        `Hard gate on stage "${stage.id}" is not approved. Run \`sdd gate approve\` or complete the checklist.`
+      );
+    }
+  } else if (effectiveGate === "soft" && stage.gate?.checklist?.length) {
+    if (!gateState || gateState.status === "pending") {
+      warnings.push(`Soft gate checklist not signed off on "${stage.id}" (proceeding allowed).`);
+    }
+  }
+  const requiredCmds = stage.verify?.commands?.filter((c) => c.required) ?? [];
+  if (requiredCmds.length) {
+    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(
+        `Required local verify commands have not passed for "${stage.id}". Run \`sdd verify\` (or \`sdd gate approve/waive\` with a note).`
+      );
+    } else if (!verifyOk && humanOverride) {
+      warnings.push(
+        `Stage "${stage.id}" gate signed off without a successful required verify run.`
+      );
+    }
+  }
+  if (stage.optional || stage.kind === "clarify" || stage.kind === "brainstorm") {
+    warnings.push(
+      `Stage "${stage.id}" is optional (${stage.kind ?? "optional"}). Skip with: sdd skip ${stage.id} -r "not needed"`
+    );
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+async function fallbackIncompleteStageId(ctx) {
+  const stages = activeStages(ctx.workflow, ctx.meta);
+  for (const stage of stages) {
+    if (stage.id === ctx.meta.stage) break;
+    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
+      continue;
+    }
+    const required = stage.artifacts.filter((a) => a.required);
+    if (!required.length && stage.optional) continue;
+    const errs = await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts);
+    if (errs.length) return stage.id;
+  }
+  return null;
+}
+async function approveGate(projectRoot, config, changeId, stageId, note, status = "approved") {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const id = stageId ?? ctx.meta.stage;
+  ctx.meta.gates = {
+    ...ctx.meta.gates,
+    [id]: { status, note, at: nowIso() }
+  };
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  return buildContext(projectRoot, config, changeId);
+}
+
+// src/stage-items.ts
+import { join as join4 } from "pathe";
+import { z as z2 } from "zod";
+var itemSchema = z2.object({
+  id: z2.string().trim().min(1),
+  stage: z2.string().trim().min(1),
+  source: z2.string().trim().min(1),
+  status: z2.enum(["open", "done"])
+}).strict();
+var itemsSchema = z2.array(itemSchema);
+function itemSourcePattern(pattern) {
+  if (pattern.includes("..") || pattern.startsWith("/") || pattern.includes("\\")) return null;
+  const slash = pattern.lastIndexOf("/");
+  if (slash <= 0) return null;
+  const dir = pattern.slice(0, slash);
+  const file = pattern.slice(slash + 1);
+  if (!/^[A-Za-z0-9._-]+$/.test(dir) || dir.includes("*")) return null;
+  const star = file.indexOf("*");
+  if (star < 0 || file.indexOf("*", star + 1) !== -1) return null;
+  return { dir, prefix: file.slice(0, star), suffix: file.slice(star + 1) };
+}
+function matches(name, prefix, suffix) {
+  if (!name.startsWith(prefix) || !name.endsWith(suffix)) return false;
+  return name.length > prefix.length + suffix.length;
+}
+function itemId(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return name;
+  return name.slice(0, dot);
+}
+async function syncStageItems(changeDir, stage) {
+  if (!stage.items_from) return [];
+  const pattern = itemSourcePattern(stage.items_from);
+  if (!pattern) throw new Error("items_from is invalid");
+  const names = (await listFiles(join4(changeDir, pattern.dir))).filter((name) => matches(name, pattern.prefix, pattern.suffix)).sort();
+  const itemsPath = join4(changeDir, "items.yaml");
+  let existing = [];
+  if (await pathExists(itemsPath)) {
+    let raw;
+    try {
+      raw = await readYaml(itemsPath);
+    } catch {
+      throw new Error("items.yaml is invalid");
+    }
+    const parsed = itemsSchema.safeParse(raw);
+    if (!parsed.success) throw new Error("items.yaml is invalid");
+    existing = parsed.data;
+  }
+  const others = existing.filter((item) => item.stage !== stage.id);
+  const mine = new Map(
+    existing.filter((item) => item.stage === stage.id).map((item) => [item.id, item])
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const next = [];
+  for (const name of names) {
+    const id = itemId(name);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const source = `${pattern.dir}/${name}`;
+    const prev = mine.get(id);
+    if (prev) next.push({ ...prev, source });
+    else next.push({ id, stage: stage.id, source, status: "open" });
+  }
+  const items = [...others, ...next].sort(
+    (a, b) => a.stage === b.stage ? a.id.localeCompare(b.id) : a.stage.localeCompare(b.stage)
+  );
+  await writeYaml(itemsPath, items);
+  return next.map((item) => item.id);
+}
+
+// src/change.ts
+async function existingChangeIds(projectRoot, config) {
+  const open = await listDirs(changesDir(projectRoot, config));
+  const archived = await listDirs(archiveDir(projectRoot, config));
+  return /* @__PURE__ */ new Set([...open, ...archived]);
+}
+async function createChange(input) {
+  const { projectRoot, config, title, workflowName } = input;
+  const workflow = await loadWorkflow(projectRoot, workflowName);
+  if (!workflow.stages.length) {
+    throw new Error(`Workflow ${workflowName} has no stages`);
+  }
+  const baseId = changeDirName(title);
+  const id = uniqueChangeDirName(baseId, await existingChangeIds(projectRoot, config));
+  const dir = changePath(projectRoot, config, id);
+  await ensureDir(dir);
+  let meta = ChangeMetaSchema.parse({
+    id,
+    title,
+    workflow: workflowName,
+    created: nowIso(),
+    updated: nowIso(),
+    status: "in_progress",
+    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: [],
+      gates: {},
+      extra_stages: []
+    },
+    skipped: [],
+    gates: {}
+  });
+  const startId = firstActiveStageId(workflow, meta) ?? workflow.stages[0].id;
+  meta = { ...meta, stage: startId };
+  const firstStage = getStage(workflow, meta, startId);
+  if (!firstStage) {
+    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-PSIOQEYH.js");
+    await refreshActiveAgentContext(projectRoot);
+  } catch {
+  }
+  return buildContext(projectRoot, config, id);
+}
+async function materializeStageArtifacts(projectRoot, config, changeId, workflow, meta, stage) {
+  const created = [];
+  const dir = changePath(projectRoot, config, changeId);
+  const tdir = templatesDir(projectRoot);
+  for (const artifact of stage.artifacts) {
+    const target = join5(dir, artifact.path);
+    if (await pathExists(target)) continue;
+    if (artifact.path.endsWith("/")) {
+      await ensureDir(target);
+      created.push(artifact.path);
+      continue;
+    }
+    let content = defaultArtifactContent(artifact.id, meta, stage, workflow);
+    if (artifact.template) {
+      const templatePath = join5(tdir, artifact.template.replace(/^templates\//, ""));
+      const candidates = [
+        join5(tdir, artifact.template),
+        templatePath,
+        join5(tdir, `${artifact.id}.md`)
+      ];
+      for (const c of candidates) {
+        if (await pathExists(c)) {
+          content = interpolate(await readText(c), meta, stage, workflow, {
+            idea: String(meta.flags?.idea ?? meta.title ?? "")
+          });
+          break;
+        }
+      }
+    } else {
+      const fallback = join5(tdir, `${artifact.id}.md`);
+      if (await pathExists(fallback)) {
+        content = interpolate(await readText(fallback), meta, stage, workflow, {
+          idea: String(meta.flags?.idea ?? meta.title ?? "")
+        });
+      }
+    }
+    await writeText(target, content);
+    created.push(artifact.path);
+  }
+  if (stage.items_from) {
+    await syncStageItems(dir, stage);
+    created.push("items.yaml");
+  }
+  return created;
+}
+function interpolate(template, meta, stage, workflow, extra) {
+  const idea = extra?.idea || String(meta.flags?.idea ?? "") || meta.title.replace(/^Greenfield:\s*/i, "");
+  return template.replaceAll("{{title}}", meta.title).replaceAll("{{id}}", meta.id).replaceAll("{{workflow}}", workflow.name).replaceAll("{{stage}}", stage.id).replaceAll("{{stage_title}}", stage.title ?? stage.id).replaceAll("{{date}}", meta.created.slice(0, 10)).replaceAll("{{idea}}", idea);
+}
+function defaultArtifactContent(artifactId, meta, stage, workflow) {
+  return `# ${artifactId}
+
+> Change: **${meta.title}** (\`${meta.id}\`)
+> Workflow: \`${workflow.name}\` \xB7 Stage: \`${stage.id}\`
+
+## Summary
+
+<!-- Write the intent / content for this artifact -->
+
+## Notes
+
+-
+`;
+}
+async function advanceStage(projectRoot, config, changeId, opts) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const warnings = [];
+  if (ctx.meta.status === "completed") {
+    throw new Error("Change is already completed.");
+  }
+  if (!opts?.force) {
+    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);
+      const artifactsCreated2 = await materializeStageArtifacts(
+        projectRoot,
+        config,
+        changeId,
+        ctx.workflow,
+        ctx.meta,
+        stage2
+      );
+      try {
+        const { refreshActiveAgentContext } = await import("./agents-PSIOQEYH.js");
+        await refreshActiveAgentContext(projectRoot);
+      } catch {
+      }
+      const updated2 = await buildContext(projectRoot, config, changeId);
+      return {
+        ctx: updated2,
+        from: from2,
+        to: fallback,
+        completed: false,
+        artifactsCreated: artifactsCreated2,
+        warnings: [
+          ...warnings,
+          `Fell back to incomplete stage "${fallback}" (required work not done). Finish it before advancing.`
+        ]
+      };
+    }
+  }
+  const check = await canLeaveStage(ctx, config, projectRoot);
+  warnings.push(...check.warnings);
+  if (!check.ok && !opts?.force) {
+    throw new Error(check.errors.join("\n"));
+  }
+  const from = ctx.meta.stage;
+  const next = nextStageId(ctx.workflow, ctx.meta);
+  if (!next) {
+    return {
+      ctx,
+      from,
+      to: null,
+      completed: false,
+      artifactsCreated: [],
+      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);
+  const artifactsCreated = await materializeStageArtifacts(
+    projectRoot,
+    config,
+    changeId,
+    ctx.workflow,
+    ctx.meta,
+    stage
+  );
+  try {
+    const { refreshActiveAgentContext } = await import("./agents-PSIOQEYH.js");
+    await refreshActiveAgentContext(projectRoot);
+  } catch {
+  }
+  const updated = await buildContext(projectRoot, config, changeId);
+  return {
+    ctx: updated,
+    from,
+    to: next,
+    completed: false,
+    artifactsCreated,
+    warnings
+  };
+}
+async function skipStage(projectRoot, config, changeId, stageId, reason) {
+  if (!config.per_change.allow_skip) {
+    throw new Error("Skipping stages is disabled in .sdd/config.yaml (per_change.allow_skip).");
+  }
+  if (config.per_change.require_reason_on_skip && !reason.trim()) {
+    throw new Error("A reason is required to skip a stage.");
+  }
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const stage = getStage(ctx.workflow, ctx.meta, stageId);
+  if (!stage) {
+    throw new Error(`Stage "${stageId}" not found in workflow ${ctx.meta.workflow}`);
+  }
+  if (!stage.skippable) {
+    throw new Error(`Stage "${stageId}" is not skippable.`);
+  }
+  const skip_stages = new Set(ctx.meta.overrides.skip_stages ?? []);
+  skip_stages.add(stageId);
+  ctx.meta.overrides.skip_stages = [...skip_stages];
+  ctx.meta.skipped = [...ctx.meta.skipped ?? [], { stage: stageId, reason, at: nowIso() }];
+  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) {
+        await materializeStageArtifacts(
+          projectRoot,
+          config,
+          changeId,
+          ctx.workflow,
+          ctx.meta,
+          nextStage
+        );
+      }
+    }
+  }
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  return buildContext(projectRoot, config, changeId);
+}
+async function switchWorkflow(projectRoot, config, changeId, workflowName, reason) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const workflow = await loadWorkflow(projectRoot, workflowName);
+  if (config.allowed_workflows?.length && !config.allowed_workflows.includes(workflowName)) {
+    throw new Error(
+      `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,
+      workflow_switch_reason: reason
+    };
+  }
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  const stage = getStage(workflow, ctx.meta, ctx.meta.stage);
+  if (stage) {
+    await materializeStageArtifacts(projectRoot, config, changeId, workflow, ctx.meta, stage);
+  }
+  return buildContext(projectRoot, config, changeId);
+}
+async function completeChange(projectRoot, config, changeId) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const next = nextStageId(ctx.workflow, ctx.meta);
+  if (next) {
+    const active = activeStages(ctx.workflow, ctx.meta);
+    const last = active[active.length - 1];
+    if (last && ctx.meta.stage !== last.id) {
+      throw new Error(
+        `Cannot complete: still on stage "${ctx.meta.stage}". Finish remaining stages or skip them. Next: ${next}`
+      );
+    }
+  }
+  const check = await canLeaveStage(ctx, config, projectRoot);
+  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-QFA5WVHE.js");
+      promoted = await promoteGreenfieldToMemory2(projectRoot, config, changeId);
+    } catch {
+    }
+  }
+  await clearActiveIf(projectRoot, config, changeId);
+  let archivedTo = null;
+  const shouldArchive = config.persistence.archive_on_complete && ctx.workflow.on_complete?.archive !== false;
+  if (shouldArchive) {
+    const dest = join5(archiveDir(projectRoot, config), changeId);
+    if (await pathExists(dest)) {
+      throw new Error(`Archive already exists for change: ${changeId}`);
+    }
+    await ensureDir(archiveDir(projectRoot, config));
+    await copyDir(ctx.path, dest);
+    await removePath(ctx.path);
+    archivedTo = dest;
+  }
+  if (archivedTo) {
+    const meta = ChangeMetaSchema.parse(await readYaml(join5(archivedTo, "meta.yaml")));
+    return {
+      archivedTo,
+      promoted,
+      ctx: {
+        id: changeId,
+        path: archivedTo,
+        displayPath: displayArchivePath(config, changeId),
+        meta,
+        workflow: ctx.workflow,
+        stages: ctx.stages,
+        active: ctx.active
+      }
+    };
+  }
+  return {
+    archivedTo,
+    promoted,
+    ctx: await buildContext(projectRoot, config, changeId)
+  };
+}
+
+// src/greenfield.ts
+var FEATURE_HEADER = /^##\s+(F-\d+)\s*:\s*(.+?)\s*$/i;
+async function startGreenfield(input) {
+  const idea = input.idea.trim();
+  if (!idea || idea.length < 3) {
+    throw new Error(
+      'Provide a one-line product idea, e.g. sdd greenfield "Team expense tracker for remote startups"'
+    );
+  }
+  const title = idea.length > 80 ? `Greenfield: ${idea.slice(0, 77)}\u2026` : `Greenfield: ${idea}`;
+  const ctx = await createChange({
+    projectRoot: input.projectRoot,
+    config: input.config,
+    title,
+    workflowName: "greenfield",
+    flags: { greenfield: true, idea }
+  });
+  const visionPath = join6(ctx.path, "vision.md");
+  if (await pathExists(visionPath)) {
+    let body = await readText(visionPath);
+    if (body.includes("{{idea}}")) {
+      body = body.replaceAll("{{idea}}", idea);
+      await writeText(visionPath, body);
+    } else if (!body.includes(idea)) {
+      body = body.replace(/## One-liner\n+(\s*[-–—]\s*\n)?/, `## One-liner
+
+${idea}
+
+`);
+      if (!body.includes(idea)) {
+        body = `${body.trim()}
+
+## One-liner
+
+${idea}
+`;
+      }
+      await writeText(visionPath, body);
+    }
+  }
+  return { ctx, idea, visionPath };
+}
+function parseFeaturesBacklog(markdown, sourcePath) {
+  const lines = markdown.split(/\r?\n/);
+  const features = [];
+  let current = null;
+  const flush = () => {
+    if (current) features.push(current);
+    current = null;
+  };
+  for (const line of lines) {
+    const h = line.match(FEATURE_HEADER);
+    if (h) {
+      flush();
+      current = {
+        id: h[1].toUpperCase(),
+        name: h[2].trim(),
+        status: "planned",
+        priority: "should",
+        workflow: "feature",
+        summary: "",
+        requirements: "",
+        notes: "",
+        sourcePath
+      };
+      continue;
+    }
+    if (!current) continue;
+    const field = line.match(
+      /^\s*[-*]\s*\*\*(Status|Priority|Workflow|Summary|Requirements|Notes):\*\*\s*(.*)$/i
+    );
+    if (field) {
+      const key = field[1].toLowerCase();
+      const val = field[2].trim();
+      if (key === "status") current.status = val || current.status;
+      else if (key === "priority") current.priority = val || current.priority;
+      else if (key === "workflow") current.workflow = val || current.workflow;
+      else if (key === "summary") current.summary = val;
+      else if (key === "requirements") current.requirements = val;
+      else if (key === "notes") current.notes = val;
+    }
+  }
+  flush();
+  return features;
+}
+async function findFeaturesBacklogPath(projectRoot, config) {
+  const mem = join6(memoryDir(projectRoot, config), "features.md");
+  if (await pathExists(mem)) return mem;
+  const { getActiveChangeId: getActiveChangeId2 } = await import("./change-context-EZJMSGSP.js");
+  const active = await getActiveChangeId2(projectRoot, config);
+  if (active) {
+    const p = join6(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 = join6(changePath(projectRoot, config, id), "features.md");
+      if (await pathExists(p)) {
+        const body = await readText(p);
+        if (parseFeaturesBacklog(body, p).length) return p;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function listBacklogFeatures(projectRoot, config) {
+  const path = await findFeaturesBacklogPath(projectRoot, config);
+  if (!path) {
+    throw new Error(
+      [
+        "No feature backlog found.",
+        "Options:",
+        '  1. sdd greenfield "your idea" \u2192 fill features.md \u2192 sdd next \u2026 \u2192 sdd complete',
+        "  2. Or add memory/features.md with ## F-001: Name blocks",
+        "  3. If a greenfield pack is mid-flight, finish the features stage first (features.md must exist and list F-NNN items)"
+      ].join("\n")
+    );
+  }
+  const features = parseFeaturesBacklog(await readText(path), path);
+  if (!features.length) {
+    throw new Error(`No F-NNN features parsed in ${path}. Use headings like: ## F-001: Short name`);
+  }
+  return { path, features };
+}
+async function startFeatureFromBacklog(input) {
+  const id = input.featureId.trim().toUpperCase();
+  if (!/^F-\d+$/i.test(id)) {
+    throw new Error(`Feature id must look like F-001 (got "${input.featureId}")`);
+  }
+  const { path, features } = await listBacklogFeatures(input.projectRoot, input.config);
+  const feature = features.find((f) => f.id === id);
+  if (!feature) {
+    const known = features.map((f) => f.id).join(", ");
+    throw new Error(`Feature ${id} not found in ${path}. Known: ${known}`);
+  }
+  const workflowName = input.workflowName?.trim() || feature.workflow?.trim() || "feature";
+  const title = feature.name ? `${feature.id}: ${feature.name}` : feature.id;
+  const ctx = await createChange({
+    projectRoot: input.projectRoot,
+    config: input.config,
+    title,
+    workflowName,
+    flags: {
+      from_backlog: feature.id,
+      greenfield_feature: true
+    }
+  });
+  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 = join6(ctx.path, art.path);
+    if (await pathExists(artPath)) {
+      let body = await readText(artPath);
+      if (!isSubstantiveArtifactContent(body)) {
+        body = [
+          `# ${feature.name || feature.id}`,
+          ``,
+          `> From backlog **${feature.id}** \xB7 priority: ${feature.priority}`,
+          ``,
+          `## Summary`,
+          ``,
+          feature.summary || feature.name || "(fill in)",
+          ``,
+          `## Requirements`,
+          ``,
+          feature.requirements || "-",
+          ``,
+          `## Notes`,
+          ``,
+          feature.notes || "-",
+          ``,
+          `## Success`,
+          ``,
+          `-`,
+          ``
+        ].join("\n");
+        await writeText(artPath, body);
+      }
+    }
+  }
+  await updateFeatureStatus(path, feature.id, "in_progress");
+  return { ctx, feature };
+}
+async function updateFeatureStatus(backlogPath, featureId, status) {
+  const id = featureId.toUpperCase();
+  let md = await readText(backlogPath);
+  const re = new RegExp(
+    `(##\\s+${id}\\s*:[\\s\\S]*?[-*]\\s*\\*\\*Status:\\*\\*\\s*)([^\\n]+)`,
+    "i"
+  );
+  if (!re.test(md)) return;
+  md = md.replace(re, `$1${status}`);
+  await writeText(backlogPath, md);
+}
+async function promoteGreenfieldToMemory(projectRoot, config, changeId) {
+  const dir = changePath(projectRoot, config, changeId);
+  const mem = memoryDir(projectRoot, config);
+  await ensureDir(mem);
+  const map = [
+    { from: "vision.md", to: "product.md" },
+    { from: "requirements.md", to: "requirements.md" },
+    { from: "features.md", to: "features.md" },
+    { from: "architecture.md", to: "architecture.md" }
+  ];
+  const written = [];
+  for (const { from, to } of map) {
+    const src = join6(dir, from);
+    if (!await pathExists(src)) continue;
+    const body = await readText(src);
+    if (!isSubstantiveArtifactContent(body)) continue;
+    const dest = join6(mem, to);
+    await writeText(
+      dest,
+      body.includes("Promoted from greenfield") ? body : `${body.trim()}
+
+---
+
+_Promoted from greenfield change \`${changeId}\`._
+`
+    );
+    written.push(join6(config.memory_path, to));
+  }
+  const indexPath = join6(mem, "index.md");
+  if (await pathExists(indexPath)) {
+    let index = await readText(indexPath);
+    if (!index.includes("features.md")) {
+      index = index.replace(
+        /\| Architecture \|/,
+        `| Feature backlog | [features.md](features.md) |
+| Architecture |`
+      );
+      await writeText(indexPath, index);
+    }
+  }
+  return written;
+}
+
+export {
+  PhaseMetricSchema,
+  TokenUsageMetricSchema,
+  DecisionMetricSchema,
+  ChangeMetricsSchema,
+  emptyChangeMetrics,
+  readChangeMetrics,
+  recordDecisionMetric,
+  startPhase,
+  transitionPhase,
+  assertSessionLogAllowed,
+  importSessionMetrics,
+  isSubstantiveArtifactContent,
+  recordSignoff,
+  recordDecisionRequest,
+  incompletePriorStageErrors,
+  canLeaveStage,
+  fallbackIncompleteStageId,
+  approveGate,
+  startGreenfield,
+  parseFeaturesBacklog,
+  findFeaturesBacklogPath,
+  listBacklogFeatures,
+  startFeatureFromBacklog,
+  updateFeatureStatus,
+  promoteGreenfieldToMemory,
+  createChange,
+  advanceStage,
+  skipStage,
+  switchWorkflow,
+  completeChange
+};