@structured-vibe-coding/core 0.2.2 → 0.3.0

package/dist/chunk-PT2BZ23N.js

@@ -0,0 +1,1314 @@
+// src/agents.ts
+import { join as join4 } from "pathe";
+
+// 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/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/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/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/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
+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);
+  try {
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-7PTSPJFQ.js");
+    await refreshActiveAgentContext2(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 = 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
+  );
+  try {
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-7PTSPJFQ.js");
+    await refreshActiveAgentContext2(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) {
+      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/agents.ts
+var ALL_AGENT_TARGETS = ["copilot", "claude-code", "intellij"];
+async function installAgentIntegrations(opts) {
+  const targets = opts.targets?.length ? opts.targets : ALL_AGENT_TARGETS;
+  const created = [];
+  const skipped = [];
+  const root = opts.projectRoot;
+  const force = opts.force ?? false;
+  const write = async (rel, content) => {
+    const full = join4(root, rel);
+    if (await pathExists(full) && !force) {
+      skipped.push(rel);
+      return;
+    }
+    await writeText(full, content);
+    created.push(rel);
+  };
+  await refreshActiveAgentContext(root);
+  if (targets.includes("copilot")) {
+    await write(
+      ".github/copilot-instructions.md",
+      COPILOT_INSTRUCTIONS
+    );
+    await write(
+      ".github/agents/sdd.agent.md",
+      COPILOT_SDD_AGENT
+    );
+    await write(
+      ".github/instructions/sdd.instructions.md",
+      COPILOT_PATH_INSTRUCTIONS
+    );
+  }
+  if (targets.includes("claude-code")) {
+    await write(".claude/skills/sdd/SKILL.md", CLAUDE_SDD_SKILL);
+    await write(".claude/CLAUDE.md", CLAUDE_PROJECT_MD);
+  }
+  if (targets.includes("intellij")) {
+    await write(".idea/sdd-agent-notes.md", INTELLIJ_NOTES);
+    await write("AGENTS.md", AGENTS_MD);
+  } else if (targets.includes("copilot") || targets.includes("claude-code")) {
+    await write("AGENTS.md", AGENTS_MD);
+  }
+  await write(
+    join4(".sdd", "agents.json"),
+    JSON.stringify(
+      {
+        version: 1,
+        installed: targets,
+        updated: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    ) + "\n"
+  );
+  return { created, skipped, targets };
+}
+async function refreshActiveAgentContext(projectRoot) {
+  const markerDir = sddRoot(projectRoot);
+  if (!await pathExists(join4(markerDir, "config.yaml"))) {
+    return null;
+  }
+  const config = await loadConfig(projectRoot);
+  const activeId = await getActiveChangeId(projectRoot, config);
+  const outPath = join4(markerDir, "active-context.md");
+  if (!activeId) {
+    const empty = `# SDD active context
+
+_No active change._ Run \`sdd new "\u2026"\` or **SDD: New Change** in the IDE.
+
+Then re-run \`sdd agents refresh\` (or advance a stage) to update this file.
+`;
+    await writeText(outPath, empty);
+    return outPath;
+  }
+  const ctx = await buildContext(projectRoot, config, activeId);
+  const handoff = await buildAgentPrompt(ctx, config, projectRoot);
+  const status = formatStatus(ctx);
+  const body = `# SDD active context
+
+> Auto-generated for GitHub Copilot, Claude Code, and IDE agents.  
+> Change: **${ctx.meta.title}** \xB7 \`${ctx.id}\` \xB7 stage **${ctx.meta.stage}**
+
+## Status
+
+\`\`\`
+${status}
+\`\`\`
+
+${handoff}
+`;
+  await writeText(outPath, body);
+  return outPath;
+}
+var AGENTS_MD = `# Agent instructions \u2014 Structured Vibe Coding (SDD)
+
+This repository uses **Spec-Driven Development** via the \`sdd\` tool (CLI / VS Code / IntelliJ).
+
+## Always
+
+1. Prefer the **active change pack** under \`changes/<id>/\` as the source of truth for the current task.
+2. Read \`.sdd/active-context.md\` at the start of a coding session (refresh with \`sdd agents refresh\`).
+3. Read \`memory/\` for product and architecture constraints.
+4. Do **not** invent large features outside the current change intent.
+5. Respect **ARB / gate decisions** (e.g. \`arb-decision.md\`) and workflow constraints.
+6. When implementation is done, remind the human to run **local verify** (\`sdd verify\`) before \`sdd complete\`.
+
+## Workflows
+
+Process is defined in \`.sdd/workflows/*.yaml\`. Stages produce markdown artifacts in the change folder. Do not skip hard gates.
+
+## Tools
+
+| Surface | How |
+|---------|-----|
+| CLI | \`sdd status\`, \`sdd next\`, \`sdd agent\`, \`sdd verify\` |
+| VS Code / Cursor | Command Palette \u2192 **SDD:*** |
+| IntelliJ | Tools \u2192 **SDD** actions (runs CLI) |
+| GitHub Copilot | \`.github/copilot-instructions.md\` + agent \`sdd\` |
+| Claude Code | \`.claude/skills/sdd/SKILL.md\` |
+
+## Local only
+
+Verification is **local development**. Do not assume CI replaced \`sdd verify\`.
+`;
+var COPILOT_INSTRUCTIONS = `<!-- Structured Vibe Coding (SDD) \u2014 GitHub Copilot instructions -->
+
+# Project coding agent rules
+
+This repo uses **Spec-Driven Development (SDD)** with the \`sdd\` CLI / IDE plugins.
+
+## Before writing code
+
+1. Open and follow \`.sdd/active-context.md\` if present.
+2. Open the active change under \`changes/\` (see \`changes/.active\` or the latest in-progress folder).
+3. Prefer artifacts for the **current stage** (intent/feature/design/tasks) over guessing.
+4. Honor \`memory/product.md\`, \`memory/architecture.md\`, \`memory/conventions.md\`.
+
+## While coding
+
+- Stay within the change scope (title + intent/feature).
+- Match patterns described in \`research.md\` / design when present.
+- Do not violate constraints in \`arb-decision.md\` or gate notes.
+- Prefer small, reviewable diffs.
+
+## When finishing
+
+- Suggest \`sdd verify\` (local) and only then \`sdd complete\`.
+- Do not claim the change is complete without local verification when the workflow has a verify stage.
+
+## Commands the human may run
+
+\`\`\`bash
+sdd status
+sdd next
+sdd agent          # print handoff
+sdd agents refresh # refresh .sdd/active-context.md
+sdd verify
+sdd complete
+\`\`\`
+`;
+var COPILOT_SDD_AGENT = `---
+name: sdd
+description: Spec-Driven Development agent for this repo. Use when implementing the active sdd change, advancing stages, or following .sdd workflows.
+---
+
+# SDD agent (GitHub Copilot)
+
+You are the **SDD implementer** for this workspace.
+
+## Mission
+
+Implement only what the **active change pack** specifies. Specs and gates win over improvisation.
+
+## Required reads (in order)
+
+1. \`.sdd/active-context.md\`
+2. \`changes/<active-id>/meta.yaml\` (workflow + stage)
+3. Artifacts for the current stage and prior stages in that folder
+4. \`memory/*.md\`
+
+## Behavior
+
+- If there is no active change, tell the user to run \`sdd new "\u2026"\` or **SDD: New Change**.
+- If \`meta.yaml\` stage is not \`implement\`, help fill the current stage artifact instead of large code rewrites\u2014unless the user explicitly wants implementation early.
+- On implement stage: execute tasks from \`tasks.md\` / acceptance criteria; keep diffs scoped.
+- After code changes: remind them to run **local** \`sdd verify\`.
+
+## Out of scope
+
+- Redesigning the whole product
+- Skipping hard gates
+- Inventing requirements not in the change pack
+`;
+var COPILOT_PATH_INSTRUCTIONS = `---
+applyTo: "changes/**,memory/**,.sdd/**"
+---
+
+# SDD paths
+
+Files under \`changes/\`, \`memory/\`, and \`.sdd/\` drive Spec-Driven Development.
+
+- Treat \`changes/**/meta.yaml\` as process state (do not invent fields).
+- Prefer editing stage artifacts over deleting workflow history.
+- When modifying code for an active change, keep alignment with that change's intent/design/tasks.
+`;
+var CLAUDE_SDD_SKILL = `---
+name: sdd
+description: Use Spec-Driven Development (sdd) for this repository \u2014 read active change, follow stages, implement within scope, local verify.
+---
+
+# Skill: Structured Vibe Coding (SDD)
+
+## When to use
+
+- User asks to implement a feature/fix in this repo
+- User mentions sdd, change packs, stages, ARB, or local verify
+- You need the source of truth for the current task
+
+## Instructions
+
+1. Read \`.sdd/active-context.md\` (if missing, run \`sdd agents refresh\` via bash or ask the user).
+2. Read \`changes/<id>/meta.yaml\` for \`workflow\` and \`stage\`.
+3. Read relevant artifacts in that change folder (intent/feature/design/tasks/acceptance).
+4. Read \`memory/\` for global constraints.
+5. Implement **only** in-scope work for the current change.
+6. Prefer project conventions in \`memory/conventions.md\`.
+7. When done coding, instruct the user to run:
+
+\`\`\`bash
+sdd verify
+sdd gate approve   # if hard gate
+sdd next           # or sdd complete on last stage
+\`\`\`
+
+## Bash helpers (if tools allow)
+
+\`\`\`bash
+sdd status
+sdd agent
+sdd agents refresh
+\`\`\`
+
+## Do not
+
+- Skip hard gates
+- Expand scope beyond the change title/intent
+- Delete \`.sdd\` or archive history casually
+`;
+var CLAUDE_PROJECT_MD = `# Claude Code \u2014 this repo uses SDD
+
+Load the **sdd** skill under \`.claude/skills/sdd/\` for implementation work.
+
+Always check \`.sdd/active-context.md\` and the active folder under \`changes/\` before large edits.
+
+CLI: \`sdd\` (npm: \`@structured-vibe-coding/cli\`).
+`;
+var INTELLIJ_NOTES = `# SDD + IntelliJ / GitHub Copilot
+
+This project uses Structured Vibe Coding (\`sdd\`).
+
+## IntelliJ plugin
+
+Install the **Structured Vibe Coding (SDD)** plugin (or run the Gradle plugin from \`packages/intellij\`).  
+Actions under **Tools \u2192 SDD** shell out to the \`sdd\` CLI \u2014 install the CLI on PATH:
+
+\`\`\`bash
+npm i -g @structured-vibe-coding/cli
+\`\`\`
+
+## GitHub Copilot in IntelliJ
+
+Copilot respects repository instructions:
+
+- \`.github/copilot-instructions.md\`
+- \`AGENTS.md\`
+- \`.sdd/active-context.md\` (refresh often)
+
+Use the SDD plugin action **Refresh agent context** after \`sdd new\` / stage changes.
+`;
+
+export {
+  GateSchema,
+  ArtifactDefSchema,
+  VerifyCommandSchema,
+  StageSchema,
+  WorkflowSchema,
+  ConfigSchema,
+  ChangeMetaSchema,
+  SDD_DIR,
+  sddRoot,
+  configPath,
+  workflowsDir,
+  templatesDir,
+  memoryDir,
+  changesDir,
+  archiveDir,
+  domainsDir,
+  changePath,
+  changeMetaPath,
+  activePointerPath,
+  pathExists,
+  ensureDir,
+  readText,
+  writeText,
+  readYaml,
+  writeYaml,
+  listDirs,
+  listFiles,
+  copyDir,
+  removePath,
+  isInitialized,
+  loadConfig,
+  saveConfig,
+  defaultConfig,
+  projectPaths,
+  listWorkflowNames,
+  loadWorkflow,
+  resolveStages,
+  isStageSkipped,
+  shouldAutoSkip,
+  activeStages,
+  getStage,
+  nextStageId,
+  previousStageId,
+  firstActiveStageId,
+  inferComplexity,
+  recommendWorkflow,
+  slugify,
+  todayIsoDate,
+  nowIso,
+  changeDirName,
+  uniqueChangeDirName,
+  ALL_AGENT_TARGETS,
+  installAgentIntegrations,
+  refreshActiveAgentContext,
+  createChange,
+  loadChangeMeta,
+  saveChangeMeta,
+  buildContext,
+  listChanges,
+  getActiveChangeId,
+  clearActiveIf,
+  setActiveChange,
+  resolveChangeId,
+  canLeaveStage,
+  advanceStage,
+  skipStage,
+  switchWorkflow,
+  approveGate,
+  completeChange,
+  formatStatus,
+  buildAgentPrompt
+};