@structured-vibe-coding/core 0.2.2

package/dist/index.js

@@ -0,0 +1,1273 @@
+// src/schemas.ts
+import { z } from "zod";
+var GateSchema = z.object({
+  type: z.enum(["none", "soft", "hard"]).default("soft"),
+  mode: z.enum(["none", "human_approval", "checklist"]).default("checklist"),
+  checklist: z.array(z.string()).default([]),
+  overridable: z.boolean().default(true)
+});
+var ArtifactDefSchema = z.object({
+  id: z.string(),
+  path: z.string(),
+  template: z.string().optional(),
+  required: z.boolean().default(true)
+});
+var VerifyCommandSchema = z.object({
+  name: z.string(),
+  run: z.string(),
+  required: z.boolean().default(false)
+});
+var StageSchema = z.object({
+  id: z.string(),
+  title: z.string().optional(),
+  summary: z.string().optional(),
+  artifacts: z.array(ArtifactDefSchema).default([]),
+  gate: GateSchema.default({}),
+  skippable: z.boolean().default(true),
+  skip_when: z.object({
+    flags: z.array(z.string()).optional()
+  }).optional(),
+  verify: z.object({
+    commands: z.array(VerifyCommandSchema).default([]),
+    evidence_dir: z.string().optional()
+  }).optional(),
+  agent_context: z.object({
+    include: z.array(z.string()).default([]),
+    instructions: z.string().optional()
+  }).optional()
+});
+var WorkflowSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  version: z.number().default(1),
+  stages: z.array(StageSchema).min(1),
+  recommendation: z.object({
+    when: z.object({
+      labels: z.array(z.string()).optional(),
+      keywords: z.array(z.string()).optional(),
+      max_complexity: z.enum(["low", "medium", "high"]).optional(),
+      min_complexity: z.enum(["low", "medium", "high"]).optional()
+    }).optional(),
+    priority: z.number().default(0)
+  }).optional(),
+  on_complete: z.object({
+    archive: z.boolean().default(true),
+    domain_sync: z.enum(["never", "recommend", "require"]).default("never")
+  }).optional()
+});
+var ConfigSchema = z.object({
+  version: z.number().default(1),
+  memory_path: z.string().default("memory"),
+  changes_path: z.string().default("changes"),
+  archive_path: z.string().default("archive"),
+  domains_path: z.string().default("domains"),
+  default_workflow: z.string().default("recommend"),
+  allowed_workflows: z.array(z.string()).optional(),
+  per_change: z.object({
+    allow_skip: z.boolean().default(true),
+    allow_gate_override: z.enum(["true", "false", "soft_only"]).default("soft_only"),
+    allow_custom_stages: z.boolean().default(true),
+    require_reason_on_skip: z.boolean().default(true)
+  }).default({}),
+  persistence: z.object({
+    default: z.enum(["change_only", "domain_sync"]).default("change_only"),
+    archive_on_complete: z.boolean().default(true),
+    domain_sync: z.object({
+      mode: z.enum(["never", "recommend", "require"]).default("never"),
+      anchored_domains: z.array(z.string()).default([])
+    }).default({})
+  }).default({}),
+  policy: z.object({
+    gates: z.enum(["soft", "hard"]).default("soft")
+  }).default({})
+});
+var ChangeMetaSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  workflow: z.string(),
+  created: z.string(),
+  updated: z.string().optional(),
+  status: z.enum(["in_progress", "blocked", "completed", "abandoned"]).default("in_progress"),
+  stage: z.string(),
+  branch: z.string().optional(),
+  domain: z.string().optional(),
+  flags: z.record(z.union([z.boolean(), z.string(), z.number()])).default({}),
+  overrides: z.object({
+    skip_stages: z.array(z.string()).default([]),
+    gates: z.record(z.enum(["none", "soft", "hard"])).default({}),
+    extra_stages: z.array(StageSchema).default([])
+  }).default({}),
+  skipped: z.array(
+    z.object({
+      stage: z.string(),
+      reason: z.string(),
+      at: z.string()
+    })
+  ).default([]),
+  gates: z.record(
+    z.object({
+      status: z.enum(["pending", "approved", "failed", "waived"]),
+      note: z.string().optional(),
+      at: z.string().optional()
+    })
+  ).default({}),
+  /** Results from `sdd verify` keyed by stage id */
+  verify_results: z.record(
+    z.object({
+      ok: z.boolean(),
+      at: z.string(),
+      results: z.array(
+        z.object({
+          name: z.string(),
+          exitCode: z.number().nullable()
+        })
+      ).default([])
+    })
+  ).default({}),
+  pr: z.object({
+    number: z.number().optional(),
+    url: z.string().optional()
+  }).optional(),
+  completed_at: z.string().optional()
+});
+
+// src/paths.ts
+import { join } from "pathe";
+var SDD_DIR = ".sdd";
+function sddRoot(projectRoot) {
+  return join(projectRoot, SDD_DIR);
+}
+function configPath(projectRoot) {
+  return join(sddRoot(projectRoot), "config.yaml");
+}
+function workflowsDir(projectRoot) {
+  return join(sddRoot(projectRoot), "workflows");
+}
+function templatesDir(projectRoot) {
+  return join(sddRoot(projectRoot), "templates");
+}
+function memoryDir(projectRoot, config) {
+  return join(projectRoot, config.memory_path);
+}
+function changesDir(projectRoot, config) {
+  return join(projectRoot, config.changes_path);
+}
+function archiveDir(projectRoot, config) {
+  return join(projectRoot, config.archive_path);
+}
+function domainsDir(projectRoot, config) {
+  return join(projectRoot, config.domains_path);
+}
+function changePath(projectRoot, config, changeId) {
+  return join(changesDir(projectRoot, config), changeId);
+}
+function changeMetaPath(projectRoot, config, changeId) {
+  return join(changePath(projectRoot, config, changeId), "meta.yaml");
+}
+function activePointerPath(projectRoot, config) {
+  return join(changesDir(projectRoot, config), ".active");
+}
+
+// src/fs.ts
+import { promises as fs } from "fs";
+import { dirname } from "pathe";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+async function pathExists(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDir(path) {
+  await fs.mkdir(path, { recursive: true });
+}
+async function readText(path) {
+  return fs.readFile(path, "utf8");
+}
+async function writeText(path, content) {
+  await ensureDir(dirname(path));
+  await fs.writeFile(path, content, "utf8");
+}
+async function readYaml(path) {
+  const raw = await readText(path);
+  return parseYaml(raw);
+}
+async function writeYaml(path, data) {
+  const content = stringifyYaml(data, {
+    lineWidth: 100,
+    defaultStringType: "PLAIN",
+    defaultKeyType: "PLAIN"
+  });
+  await writeText(path, content.endsWith("\n") ? content : `${content}
+`);
+}
+async function listDirs(path) {
+  if (!await pathExists(path)) return [];
+  const entries = await fs.readdir(path, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+async function listFiles(path) {
+  if (!await pathExists(path)) return [];
+  const entries = await fs.readdir(path, { withFileTypes: true });
+  return entries.filter((e) => e.isFile()).map((e) => e.name);
+}
+async function copyDir(src, dest) {
+  await ensureDir(dest);
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const from = `${src}/${entry.name}`;
+    const to = `${dest}/${entry.name}`;
+    if (entry.isDirectory()) {
+      await copyDir(from, to);
+    } else {
+      await ensureDir(dirname(to));
+      await fs.copyFile(from, to);
+    }
+  }
+}
+async function removePath(path) {
+  await fs.rm(path, { recursive: true, force: true });
+}
+
+// src/config.ts
+async function isInitialized(projectRoot) {
+  return pathExists(configPath(projectRoot));
+}
+async function loadConfig(projectRoot) {
+  const path = configPath(projectRoot);
+  if (!await pathExists(path)) {
+    throw new Error(
+      `SDD is not initialized in ${projectRoot}. Run \`sdd init\` first.`
+    );
+  }
+  const raw = await readYaml(path);
+  return ConfigSchema.parse(raw);
+}
+async function saveConfig(projectRoot, config) {
+  await ensureDir(sddRoot(projectRoot));
+  await writeYaml(configPath(projectRoot), ConfigSchema.parse(config));
+}
+function defaultConfig() {
+  return ConfigSchema.parse({});
+}
+function projectPaths(projectRoot, config) {
+  return {
+    sdd: sddRoot(projectRoot),
+    config: configPath(projectRoot),
+    workflows: workflowsDir(projectRoot),
+    templates: templatesDir(projectRoot),
+    memory: memoryDir(projectRoot, config)
+  };
+}
+
+// src/workflow.ts
+import { join as join2 } from "pathe";
+async function listWorkflowNames(projectRoot) {
+  const dir = workflowsDir(projectRoot);
+  const files = await listFiles(dir);
+  return files.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).map((f) => f.replace(/\.ya?ml$/, "")).sort();
+}
+async function loadWorkflow(projectRoot, name) {
+  const dir = workflowsDir(projectRoot);
+  const candidates = [`${name}.yaml`, `${name}.yml`];
+  for (const file of candidates) {
+    const path = join2(dir, file);
+    if (await pathExists(path)) {
+      const raw = await readYaml(path);
+      const workflow = WorkflowSchema.parse(raw);
+      if (workflow.name !== name) {
+      }
+      return workflow;
+    }
+  }
+  throw new Error(
+    `Workflow "${name}" not found in ${dir}. Available: ${(await listWorkflowNames(projectRoot)).join(", ") || "(none)"}`
+  );
+}
+function resolveStages(workflow, meta) {
+  const base = [...workflow.stages];
+  const extra = meta.overrides?.extra_stages ?? [];
+  const stages = [...base, ...extra];
+  return stages.map((stage) => {
+    const gateOverride = meta.overrides?.gates?.[stage.id];
+    if (!gateOverride) return stage;
+    return {
+      ...stage,
+      gate: {
+        ...stage.gate,
+        type: gateOverride
+      }
+    };
+  });
+}
+function isStageSkipped(meta, stageId) {
+  if (meta.overrides?.skip_stages?.includes(stageId)) return true;
+  if (meta.skipped?.some((s) => s.stage === stageId)) return true;
+  return false;
+}
+function shouldAutoSkip(stage, meta) {
+  const flags = stage.skip_when?.flags ?? [];
+  for (const flag of flags) {
+    if (meta.flags?.[flag] === true || meta.flags?.[flag] === "true") {
+      return true;
+    }
+  }
+  return false;
+}
+function activeStages(workflow, meta) {
+  return resolveStages(workflow, meta).filter((s) => {
+    if (isStageSkipped(meta, s.id)) return false;
+    if (shouldAutoSkip(s, meta)) return false;
+    return true;
+  });
+}
+function getStage(workflow, meta, stageId) {
+  return resolveStages(workflow, meta).find((s) => s.id === stageId);
+}
+function nextStageId(workflow, meta) {
+  const all = resolveStages(workflow, meta);
+  const activeIds = new Set(activeStages(workflow, meta).map((s) => s.id));
+  let start = all.findIndex((s) => s.id === meta.stage);
+  if (start === -1) start = -1;
+  for (let i = start + 1; i < all.length; i++) {
+    const id = all[i].id;
+    if (activeIds.has(id)) return id;
+  }
+  return null;
+}
+function previousStageId(workflow, meta) {
+  const all = resolveStages(workflow, meta);
+  const activeIds = new Set(activeStages(workflow, meta).map((s) => s.id));
+  const start = all.findIndex((s) => s.id === meta.stage);
+  if (start <= 0) return null;
+  for (let i = start - 1; i >= 0; i--) {
+    const id = all[i].id;
+    if (activeIds.has(id)) return id;
+  }
+  return null;
+}
+function firstActiveStageId(workflow, meta) {
+  return activeStages(workflow, meta)[0]?.id ?? null;
+}
+function inferComplexity(title, hints) {
+  const text = `${title} ${(hints?.keywords ?? []).join(" ")}`.toLowerCase();
+  const hotfixHints = ["typo", "hotfix", "nit", "rename", "bump", "chore", "readme", "docs"];
+  const highHints = [
+    "architecture",
+    "migration",
+    "auth",
+    "payment",
+    "billing",
+    "redesign",
+    "platform",
+    "arb",
+    "epic"
+  ];
+  if (hotfixHints.some((h) => text.includes(h))) return "low";
+  if (highHints.some((h) => text.includes(h))) return "high";
+  if (text.length > 80) return "medium";
+  return "medium";
+}
+async function recommendWorkflow(projectRoot, title, config, opts) {
+  const available = await listWorkflowNames(projectRoot);
+  const allowed = config.allowed_workflows?.length ? available.filter((n) => config.allowed_workflows.includes(n)) : available;
+  if (opts?.preferred) {
+    if (!available.includes(opts.preferred)) {
+      throw new Error(
+        `Workflow "${opts.preferred}" is not available. Available: ${available.join(", ") || "(none)"}`
+      );
+    }
+    if (config.allowed_workflows?.length && !config.allowed_workflows.includes(opts.preferred)) {
+      throw new Error(
+        `Workflow "${opts.preferred}" is not in allowed_workflows: ${config.allowed_workflows.join(", ")}`
+      );
+    }
+    return {
+      name: opts.preferred,
+      reason: "Explicitly selected",
+      alternatives: allowed.filter((n) => n !== opts.preferred)
+    };
+  }
+  if (config.default_workflow !== "recommend" && allowed.includes(config.default_workflow)) {
+    return {
+      name: config.default_workflow,
+      reason: `Repo default_workflow=${config.default_workflow}`,
+      alternatives: allowed.filter((n) => n !== config.default_workflow)
+    };
+  }
+  const complexity = opts?.complexity ?? inferComplexity(title);
+  const scored = [];
+  for (const name of allowed) {
+    try {
+      const wf = await loadWorkflow(projectRoot, name);
+      let score = wf.recommendation?.priority ?? 0;
+      let reason = `workflow priority ${score}`;
+      const when = wf.recommendation?.when;
+      if (complexity === "low" && name === "hotfix") {
+        score += 50;
+        reason = "Low complexity \u2192 hotfix";
+      } else if (complexity === "low" && name === "patch") {
+        score += 40;
+        reason = "Low complexity \u2192 patch";
+      } else if (complexity === "medium" && name === "feature") {
+        score += 45;
+        reason = "Medium complexity \u2192 feature";
+      } else if (complexity === "medium" && name === "patch") {
+        score += 30;
+        reason = "Medium complexity \u2192 patch";
+      } else if (complexity === "high" && name === "enterprise-feature") {
+        score += 50;
+        reason = "High complexity \u2192 enterprise-feature";
+      } else if (complexity === "high" && name === "feature") {
+        score += 35;
+        reason = "High complexity \u2192 feature";
+      }
+      const keywords = when?.keywords ?? [];
+      const titleLower = title.toLowerCase();
+      if (keywords.some((k) => titleLower.includes(k.toLowerCase()))) {
+        score += 20;
+        reason = `Keyword match for ${name}`;
+      }
+      scored.push({ name, score, reason });
+    } catch {
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  if (!best) {
+    throw new Error("No workflows available. Run `sdd init` or add files under .sdd/workflows/");
+  }
+  return {
+    name: best.name,
+    reason: best.reason,
+    alternatives: scored.slice(1).map((s) => s.name)
+  };
+}
+
+// src/change.ts
+import { join as join3 } from "pathe";
+
+// src/slug.ts
+function slugify(input) {
+  return input.toLowerCase().trim().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+}
+function todayIsoDate(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString().slice(0, 10);
+}
+function nowIso(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString();
+}
+function changeDirName(title, d = /* @__PURE__ */ new Date()) {
+  const slug = slugify(title) || "change";
+  return `${todayIsoDate(d)}-${slug}`;
+}
+function uniqueChangeDirName(base, taken) {
+  if (!taken.has(base)) return base;
+  let n = 2;
+  while (taken.has(`${base}-${n}`)) n += 1;
+  return `${base}-${n}`;
+}
+
+// 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,
+    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 materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
+  await setActiveChange(projectRoot, config, id);
+  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 = join3(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 = join3(tdir, artifact.template.replace(/^templates\//, ""));
+      const candidates = [
+        join3(tdir, artifact.template),
+        templatePath,
+        join3(tdir, `${artifact.id}.md`)
+      ];
+      for (const c of candidates) {
+        if (await pathExists(c)) {
+          const raw = await readText(c);
+          content = interpolate(raw, meta, stage, workflow);
+          break;
+        }
+      }
+    } else {
+      const fallback = join3(tdir, `${artifact.id}.md`);
+      if (await pathExists(fallback)) {
+        content = interpolate(await readText(fallback), meta, stage, workflow);
+      }
+    }
+    await writeText(target, content);
+    created.push(artifact.path);
+  }
+  return created;
+}
+function interpolate(template, meta, stage, workflow) {
+  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));
+}
+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 loadChangeMeta(projectRoot, config, changeId) {
+  const path = changeMetaPath(projectRoot, config, changeId);
+  if (!await pathExists(path)) {
+    throw new Error(`Change not found: ${changeId}`);
+  }
+  return ChangeMetaSchema.parse(await readYaml(path));
+}
+async function saveChangeMeta(projectRoot, config, meta) {
+  meta.updated = nowIso();
+  await writeYaml(changeMetaPath(projectRoot, config, meta.id), ChangeMetaSchema.parse(meta));
+}
+async function buildContext(projectRoot, config, changeId) {
+  const meta = await loadChangeMeta(projectRoot, config, changeId);
+  const workflow = await loadWorkflow(projectRoot, meta.workflow);
+  return {
+    id: changeId,
+    path: changePath(projectRoot, config, changeId),
+    meta,
+    workflow,
+    stages: resolveStages(workflow, meta),
+    active: activeStages(workflow, meta)
+  };
+}
+async function listChanges(projectRoot, config) {
+  return listDirs(changesDir(projectRoot, config));
+}
+async function getActiveChangeId(projectRoot, config) {
+  const pointer = activePointerPath(projectRoot, config);
+  if (await pathExists(pointer)) {
+    const id = (await readText(pointer)).trim();
+    if (id && await pathExists(changePath(projectRoot, config, id))) {
+      return id;
+    }
+    if (id) {
+      await writeText(pointer, "");
+    }
+  }
+  const all = await listChanges(projectRoot, config);
+  const inProgress = [];
+  for (const id of all) {
+    try {
+      const meta = await loadChangeMeta(projectRoot, config, id);
+      if (meta.status === "in_progress" || meta.status === "blocked") {
+        inProgress.push({ id, updated: meta.updated ?? meta.created });
+      }
+    } catch {
+    }
+  }
+  if (!inProgress.length) return null;
+  inProgress.sort((a, b) => b.updated.localeCompare(a.updated));
+  return inProgress[0].id;
+}
+async function clearActiveIf(projectRoot, config, changeId) {
+  const pointer = activePointerPath(projectRoot, config);
+  if (!await pathExists(pointer)) return;
+  const id = (await readText(pointer)).trim();
+  if (id === changeId) {
+    await writeText(pointer, "");
+  }
+}
+async function setActiveChange(projectRoot, config, changeId) {
+  await ensureDir(changesDir(projectRoot, config));
+  await writeText(activePointerPath(projectRoot, config), `${changeId}
+`);
+}
+async function resolveChangeId(projectRoot, config, changeId) {
+  if (changeId) return changeId;
+  const active = await getActiveChangeId(projectRoot, config);
+  if (!active) {
+    throw new Error("No active change. Pass --change <id> or run `sdd new`.");
+  }
+  return active;
+}
+async function canLeaveStage(ctx, config) {
+  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 };
+  }
+  for (const artifact of stage.artifacts) {
+    if (!artifact.required) continue;
+    const target = join3(ctx.path, artifact.path);
+    if (!await pathExists(target)) {
+      errors.push(`Missing required artifact: ${artifact.path}`);
+      continue;
+    }
+  }
+  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];
+  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 verifyOk = ctx.meta.verify_results?.[stage.id]?.ok === true;
+    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.`
+      );
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+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.");
+  }
+  const check = await canLeaveStage(ctx, config);
+  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."]
+    };
+  }
+  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
+  );
+  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) {
+      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(", ")}`
+    );
+  }
+  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 (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 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);
+}
+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);
+  if (!check.ok) {
+    throw new Error(check.errors.join("\n"));
+  }
+  ctx.meta.status = "completed";
+  ctx.meta.completed_at = nowIso();
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  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 = join3(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(join3(archivedTo, "meta.yaml")));
+    return {
+      archivedTo,
+      ctx: {
+        id: changeId,
+        path: archivedTo,
+        meta,
+        workflow: ctx.workflow,
+        stages: ctx.stages,
+        active: ctx.active
+      }
+    };
+  }
+  return { archivedTo, ctx: await buildContext(projectRoot, config, changeId) };
+}
+function formatStatus(ctx) {
+  const lines = [];
+  lines.push(`Change: ${ctx.meta.title}`);
+  lines.push(`ID:     ${ctx.id}`);
+  lines.push(`Status: ${ctx.meta.status}`);
+  lines.push(`Workflow: ${ctx.meta.workflow}`);
+  lines.push(`Path: ${ctx.path}`);
+  lines.push("");
+  lines.push("Stages:");
+  for (const stage of ctx.stages) {
+    const skipped = isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta);
+    let mark = " ";
+    if (skipped) mark = "\xB7";
+    else if (stage.id === ctx.meta.stage) mark = "\u25CF";
+    else {
+      const order = ctx.active.map((s) => s.id);
+      const cur = order.indexOf(ctx.meta.stage);
+      const idx = order.indexOf(stage.id);
+      if (idx >= 0 && cur >= 0 && idx < cur) mark = "\u2713";
+    }
+    const gate = ctx.meta.gates?.[stage.id];
+    const gateInfo = gate ? ` [${gate.status}]` : "";
+    const skipInfo = skipped ? " (skipped)" : "";
+    lines.push(`  [${mark}] ${stage.id}${stage.title ? ` \u2014 ${stage.title}` : ""}${gateInfo}${skipInfo}`);
+  }
+  if (ctx.meta.overrides?.skip_stages?.length) {
+    lines.push("");
+    lines.push(`Overrides: skip=${ctx.meta.overrides.skip_stages.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+async function buildAgentPrompt(ctx, config, projectRoot) {
+  const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
+  const parts = [];
+  parts.push(`# SDD Agent Handoff`);
+  parts.push("");
+  parts.push(`You are implementing a change under Structured Vibe Coding (local SDD).`);
+  parts.push("");
+  parts.push(`## Change`);
+  parts.push(`- Title: ${ctx.meta.title}`);
+  parts.push(`- ID: ${ctx.id}`);
+  parts.push(`- Workflow: ${ctx.meta.workflow}`);
+  parts.push(`- Current stage: ${ctx.meta.stage}${stage?.title ? ` (${stage.title})` : ""}`);
+  parts.push(`- Change path: ${ctx.path}`);
+  parts.push("");
+  if (stage?.summary) {
+    parts.push(`## Stage goal`);
+    parts.push(stage.summary);
+    parts.push("");
+  }
+  if (stage?.agent_context?.instructions) {
+    parts.push(`## Instructions`);
+    parts.push(stage.agent_context.instructions);
+    parts.push("");
+  }
+  parts.push(`## Constraints`);
+  parts.push(`- Follow artifacts in the change directory as source of truth.`);
+  parts.push(`- Do not skip ARB/decision constraints if present.`);
+  parts.push(`- Local development only \u2014 verify on this machine.`);
+  parts.push(`- Prefer small, reviewable commits.`);
+  parts.push("");
+  parts.push(`## Artifacts to read`);
+  const memoryHint = join3(projectRoot, config.memory_path);
+  parts.push(`- Memory: ${memoryHint}/`);
+  for (const s of ctx.stages) {
+    for (const a of s.artifacts) {
+      parts.push(`- ${join3(ctx.path, a.path)}`);
+    }
+  }
+  parts.push("");
+  parts.push(`## Current stage artifacts`);
+  if (stage) {
+    for (const a of stage.artifacts) {
+      parts.push(`- ${a.path}${a.required ? " (required)" : ""}`);
+    }
+  }
+  parts.push("");
+  parts.push(`When done with this stage, the human will run \`sdd next\` or \`sdd verify\` / \`sdd complete\`.`);
+  return parts.join("\n");
+}
+
+// src/init.ts
+import { join as join5 } from "pathe";
+
+// src/defaults.ts
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, join as join4 } from "pathe";
+function defaultsRoot() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const candidates = [
+    join4(here, "..", "defaults"),
+    // npm package: dist/../defaults
+    join4(here, "defaults"),
+    // extension bundle: dist/defaults
+    join4(here, "..", "..", "defaults")
+    // src/ during some test runners
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return candidates[0];
+}
+function defaultWorkflowsDir() {
+  return join4(defaultsRoot(), "workflows");
+}
+function defaultTemplatesDir() {
+  return join4(defaultsRoot(), "templates");
+}
+function defaultMemoryDir() {
+  return join4(defaultsRoot(), "memory");
+}
+
+// src/init.ts
+async function initProject(opts) {
+  const { projectRoot, force = false } = opts;
+  const created = [];
+  const root = sddRoot(projectRoot);
+  if (await pathExists(join5(root, "config.yaml")) && !force) {
+    throw new Error(
+      `Already initialized (${join5(root, "config.yaml")}). Use --force to re-copy defaults.`
+    );
+  }
+  const config = defaultConfig();
+  await ensureDir(root);
+  await saveConfig(projectRoot, config);
+  created.push(join5(root, "config.yaml"));
+  const wfDest = workflowsDir(projectRoot);
+  await ensureDir(wfDest);
+  const wfSrc = defaultWorkflowsDir();
+  if (await pathExists(wfSrc)) {
+    await copyDir(wfSrc, wfDest);
+    created.push(wfDest);
+  }
+  const tDest = templatesDir(projectRoot);
+  await ensureDir(tDest);
+  const tSrc = defaultTemplatesDir();
+  if (await pathExists(tSrc)) {
+    await copyDir(tSrc, tDest);
+    created.push(tDest);
+  }
+  const mDest = memoryDir(projectRoot, config);
+  await ensureDir(mDest);
+  const mSrc = defaultMemoryDir();
+  if (await pathExists(mSrc)) {
+    await copyDir(mSrc, mDest);
+  } else {
+    await writeText(
+      join5(mDest, "product.md"),
+      "# Product\n\n<!-- What are you building? -->\n"
+    );
+    await writeText(
+      join5(mDest, "architecture.md"),
+      "# Architecture\n\n<!-- High-level system shape -->\n"
+    );
+    await writeText(
+      join5(mDest, "conventions.md"),
+      "# Conventions\n\n<!-- Coding and process conventions -->\n"
+    );
+  }
+  created.push(mDest);
+  await ensureDir(changesDir(projectRoot, config));
+  await ensureDir(archiveDir(projectRoot, config));
+  await ensureDir(domainsDir(projectRoot, config));
+  created.push(changesDir(projectRoot, config));
+  created.push(archiveDir(projectRoot, config));
+  created.push(domainsDir(projectRoot, config));
+  await writeText(join5(changesDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join5(archiveDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join5(domainsDir(projectRoot, config), ".gitkeep"), "");
+  const sddReadme = join5(root, "README.md");
+  if (!await pathExists(sddReadme) || force) {
+    await writeText(
+      sddReadme,
+      `# Structured Vibe Coding (SDD)
+
+This directory configures local Spec-Driven Development for this repo.
+
+- \`config.yaml\` \u2014 project settings and per-change policy
+- \`workflows/\` \u2014 YAML workflow packs (customize freely)
+- \`templates/\` \u2014 markdown templates for stage artifacts
+
+Work lives in \`../changes/\` and completed work in \`../archive/\`.
+
+## Quick commands
+
+\`\`\`bash
+sdd new "My feature"
+sdd status
+sdd next
+sdd verify
+sdd complete
+\`\`\`
+`
+    );
+    created.push(sddReadme);
+  }
+  return { created, config };
+}
+
+// src/verify.ts
+import { spawn } from "child_process";
+import { join as join6 } from "pathe";
+function runCommand(command, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      env: process.env
+    });
+    let output = "";
+    child.stdout?.on("data", (d) => {
+      output += d.toString();
+    });
+    child.stderr?.on("data", (d) => {
+      output += d.toString();
+    });
+    child.on("close", (code) => {
+      resolve({ exitCode: code, output });
+    });
+    child.on("error", (err) => {
+      resolve({ exitCode: 1, output: String(err) });
+    });
+  });
+}
+async function runLocalVerify(projectRoot, config, changeId, opts) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
+  if (!stage) {
+    throw new Error(`Unknown stage: ${ctx.meta.stage}`);
+  }
+  const evidenceDir = stage.verify?.evidence_dir != null ? join6(ctx.path, stage.verify.evidence_dir) : join6(ctx.path, "evidence", "local");
+  await ensureDir(evidenceDir);
+  const results = [];
+  const runCommands = opts?.runCommands !== false;
+  const commands = stage.verify?.commands ?? [];
+  if (runCommands && commands.length) {
+    for (const cmd of commands) {
+      const { exitCode, output } = await runCommand(cmd.run, projectRoot);
+      results.push({
+        name: cmd.name,
+        command: cmd.run,
+        exitCode,
+        output: output.slice(0, 5e4)
+      });
+      const logPath = join6(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+      await writeText(
+        logPath,
+        `# ${cmd.name}
+$ ${cmd.run}
+exit: ${exitCode}
+
+${output}`
+      );
+    }
+  }
+  const required = commands.filter((c) => c.required);
+  let ok = true;
+  if (required.length) {
+    if (!runCommands) {
+      ok = false;
+    } else {
+      for (const cmd of required) {
+        const r = results.find((x) => x.name === cmd.name);
+        if (!r || r.exitCode !== 0) ok = false;
+      }
+    }
+  } else if (commands.length && runCommands) {
+    ok = results.every((r) => r.exitCode === 0);
+  }
+  const checklist = stage.gate?.checklist ?? [];
+  const summaryPath = join6(ctx.path, "local-test-results.md");
+  const lines = [
+    `# Local verify results`,
+    ``,
+    `> Change: ${ctx.meta.title}`,
+    `> Stage: ${stage.id}`,
+    `> At: ${nowIso()}`,
+    `> Overall: ${ok ? "PASS" : "FAIL"}`,
+    ``,
+    `## Commands`,
+    ``
+  ];
+  if (results.length === 0) {
+    lines.push(`_No commands configured for this stage. Complete the checklist manually._`);
+    lines.push("");
+  } else {
+    for (const r of results) {
+      lines.push(`### ${r.name}`);
+      lines.push(`- Command: \`${r.command}\``);
+      lines.push(`- Exit: ${r.exitCode}`);
+      lines.push("");
+    }
+  }
+  lines.push(`## Checklist`);
+  lines.push("");
+  for (const item of checklist) {
+    lines.push(`- [ ] ${item}`);
+  }
+  lines.push("");
+  lines.push(`## Notes`);
+  lines.push("");
+  lines.push(`-`);
+  lines.push("");
+  if (await pathExists(summaryPath)) {
+    const stamp = nowIso();
+    await writeText(
+      join6(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
+      lines.join("\n")
+    );
+  } else {
+    await writeText(summaryPath, lines.join("\n"));
+  }
+  ctx.meta.verify_results = {
+    ...ctx.meta.verify_results,
+    [stage.id]: {
+      ok,
+      at: nowIso(),
+      results: results.map((r) => ({ name: r.name, exitCode: r.exitCode }))
+    }
+  };
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  return {
+    stageId: stage.id,
+    results,
+    checklist,
+    evidencePath: evidenceDir,
+    ok
+  };
+}
+export {
+  ArtifactDefSchema,
+  ChangeMetaSchema,
+  ConfigSchema,
+  GateSchema,
+  SDD_DIR,
+  StageSchema,
+  VerifyCommandSchema,
+  WorkflowSchema,
+  activePointerPath,
+  activeStages,
+  advanceStage,
+  approveGate,
+  archiveDir,
+  buildAgentPrompt,
+  buildContext,
+  canLeaveStage,
+  changeDirName,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  clearActiveIf,
+  completeChange,
+  configPath,
+  copyDir,
+  createChange,
+  defaultConfig,
+  defaultMemoryDir,
+  defaultTemplatesDir,
+  defaultWorkflowsDir,
+  defaultsRoot,
+  domainsDir,
+  ensureDir,
+  firstActiveStageId,
+  formatStatus,
+  getActiveChangeId,
+  getStage,
+  inferComplexity,
+  initProject,
+  isInitialized,
+  isStageSkipped,
+  listChanges,
+  listDirs,
+  listFiles,
+  listWorkflowNames,
+  loadChangeMeta,
+  loadConfig,
+  loadWorkflow,
+  memoryDir,
+  nextStageId,
+  nowIso,
+  pathExists,
+  previousStageId,
+  projectPaths,
+  readText,
+  readYaml,
+  recommendWorkflow,
+  removePath,
+  resolveChangeId,
+  resolveStages,
+  runLocalVerify,
+  saveChangeMeta,
+  saveConfig,
+  sddRoot,
+  setActiveChange,
+  shouldAutoSkip,
+  skipStage,
+  slugify,
+  switchWorkflow,
+  templatesDir,
+  todayIsoDate,
+  uniqueChangeDirName,
+  workflowsDir,
+  writeText,
+  writeYaml
+};