@structured-vibe-coding/core 0.2.2 → 0.3.1

package/dist/chunk-ANNG5SIL.js

@@ -0,0 +1,1282 @@
+// 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-AIH2DNH3.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-AIH2DNH3.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"];
+var SDD_AGENT_ROLES = [
+  {
+    id: "sdd",
+    description: "Default SDD agent. Use for any Spec-Driven Development work on the active change pack.",
+    roleLine: "Router: inspect stage in active-context; plan or implement accordingly.",
+    roleRules: [
+      "If stage is intent/feature/design/tasks/stories/research: act as planner (artifacts, little or no product code).",
+      "If stage is implement: act as implementer (scoped code only).",
+      "If stage is local_verify: act as reviewer (gaps vs acceptance; fixes only)."
+    ]
+  },
+  {
+    id: "sdd-planner",
+    description: "SDD planner. Use when filling intent, design, research, stories, or tasks \u2014 not large code changes.",
+    roleLine: "Planner: produce/update stage markdown only.",
+    roleRules: [
+      "Do not make large product code changes unless the user explicitly overrides.",
+      "Keep artifacts short and actionable."
+    ]
+  },
+  {
+    id: "sdd-implementer",
+    description: "SDD implementer. Use when coding the active change (implement stage).",
+    roleLine: "Implementer: code only for the active change pack.",
+    roleRules: [
+      "Follow tasks.md / acceptance; honor arb-decision and design constraints.",
+      "Do not expand scope beyond the change title/intent."
+    ]
+  },
+  {
+    id: "sdd-reviewer",
+    description: "SDD reviewer. Use before verify/complete or to check work against the change pack.",
+    roleLine: "Reviewer: compare work to acceptance and stage artifacts.",
+    roleRules: [
+      "List gaps; suggest minimal fixes only.",
+      "Remind user to run sdd verify before sdd complete."
+    ]
+  }
+];
+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 write(join4(".sdd", "protocol.md"), PROTOCOL_MD);
+  await refreshActiveAgentContext(root);
+  if (targets.includes("copilot") || targets.includes("claude-code")) {
+    for (const role of SDD_AGENT_ROLES) {
+      const body = renderThinAgent(role);
+      if (targets.includes("claude-code")) {
+        await write(`.claude/agents/${role.id}.md`, body);
+      }
+      if (targets.includes("copilot")) {
+        await write(`.github/agents/${role.id}.agent.md`, body);
+      }
+    }
+  }
+  if (targets.includes("intellij")) {
+    await write(".idea/sdd-agent-notes.md", INTELLIJ_NOTES);
+  }
+  if (targets.includes("copilot") || targets.includes("claude-code") || targets.includes("intellij")) {
+    await write("AGENTS.md", AGENTS_MD_THIN);
+  }
+  await write(
+    join4(".sdd", "agents.json"),
+    JSON.stringify(
+      {
+        version: 2,
+        mode: "agents-only",
+        protocol: ".sdd/protocol.md",
+        activeContext: ".sdd/active-context.md",
+        roles: SDD_AGENT_ROLES.map((r) => r.id),
+        installed: targets,
+        updated: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    ) + "\n"
+  );
+  return { created, skipped, targets };
+}
+function renderThinAgent(role) {
+  const rules = role.roleRules.map((r) => `- ${r}`).join("\n");
+  return `---
+name: ${role.id}
+description: ${role.description}
+---
+
+# ${role.id}
+
+${role.roleLine}
+
+## Required reads (in order)
+
+1. \`.sdd/active-context.md\` \u2014 current change and stage
+2. \`.sdd/protocol.md\` \u2014 SDD rules for this repo (single playbook)
+3. Active change files under \`changes/<id>/\` as listed in active-context
+
+## Role rules
+
+${rules}
+
+## Done
+
+Remind the human: \`sdd verify\` then \`sdd next\` / \`sdd complete\` as appropriate.
+Do not claim the change is complete without local verification when the workflow requires it.
+`;
+}
+async function refreshActiveAgentContext(projectRoot) {
+  const markerDir = sddRoot(projectRoot);
+  if (!await pathExists(join4(markerDir, "config.yaml"))) {
+    return null;
+  }
+  const protocolPath = join4(markerDir, "protocol.md");
+  if (!await pathExists(protocolPath)) {
+    await writeText(protocolPath, PROTOCOL_MD);
+  }
+  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.
+
+Protocol: \`.sdd/protocol.md\`
+`;
+    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 coding agents.  
+> Change: **${ctx.meta.title}** \xB7 \`${ctx.id}\` \xB7 stage **${ctx.meta.stage}**  
+> Protocol: \`.sdd/protocol.md\`
+
+## Status
+
+\`\`\`
+${status}
+\`\`\`
+
+${handoff}
+`;
+  await writeText(outPath, body);
+  return outPath;
+}
+var PROTOCOL_MD = `# SDD protocol
+
+This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this file plus \`.sdd/active-context.md\`. Do not invent a parallel process.
+
+## Source of truth
+
+| What | Where |
+|------|--------|
+| Process state | \`changes/<id>/meta.yaml\` (workflow, stage, gates) |
+| Current task snapshot | \`.sdd/active-context.md\` |
+| Stable product/tech rules | \`memory/*.md\` |
+| Stage artifacts | files in \`changes/<id>/\` for the active change |
+
+## Required read order
+
+1. \`.sdd/active-context.md\`
+2. This file (\`.sdd/protocol.md\`)
+3. \`meta.yaml\` + artifacts for the **current stage** (and prior stages if needed)
+4. \`memory/\` when architecture or conventions matter
+
+## Stage behavior
+
+| Stage kind | Agent focus |
+|------------|-------------|
+| intent / feature / stories | Clarify scope; write short artifacts |
+| design / lld / db / research / hl_arb | Specs and decisions; minimal product code |
+| tasks | Break work into implementable checklist |
+| implement | Code only for this change; follow tasks/acceptance |
+| local_verify | Check acceptance; fix only; prepare for complete |
+
+## Hard rules
+
+1. **Do not skip hard gates.** If blocked, tell the human to run \`sdd gate approve\` (or fix the gate).
+2. **Stay in scope** of the active change title/intent. No drive-by refactors or new features.
+3. **Honor constraints** in \`arb-decision.md\`, design, and memory non-negotiables.
+4. **Local verify** is part of done when the workflow has a verify stage: \`sdd verify\`.
+5. Prefer small, reviewable diffs.
+
+## Commands (human / shell)
+
+\`\`\`bash
+sdd status
+sdd next
+sdd agent              # print handoff
+sdd agents refresh     # refresh active-context.md
+sdd verify
+sdd complete
+\`\`\`
+
+## Out of scope for agents
+
+- Replacing CI/CD or team process tools
+- Deleting \`.sdd\` / archive history
+- Claiming complete without verify when required
+`;
+var AGENTS_MD_THIN = `# Agents
+
+This repo uses **SDD agents only** (no skills).
+
+| Read first | |
+|------------|--|
+| Live task | \`.sdd/active-context.md\` |
+| Playbook | \`.sdd/protocol.md\` |
+
+| Host | Agents |
+|------|--------|
+| Claude Code | \`.claude/agents/\` (\`sdd\`, \`sdd-planner\`, \`sdd-implementer\`, \`sdd-reviewer\`) |
+| GitHub Copilot | \`.github/agents/*.agent.md\` (same roles) |
+
+Refresh context: \`sdd agents refresh\`.
+`;
+var INTELLIJ_NOTES = `# SDD + IntelliJ
+
+Agents only. Playbook: \`.sdd/protocol.md\`. Live: \`.sdd/active-context.md\`.
+
+1. Install \`sdd\` on PATH: \`npm i -g @structured-vibe-coding/cli\`
+2. Tools \u2192 SDD \u2192 Initialize / Install Agent Integrations
+3. GitHub Copilot uses \`.github/agents/*\` + active-context (same as VS Code)
+4. After stage changes: **Refresh Agent Context**
+`;
+
+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,
+  SDD_AGENT_ROLES,
+  installAgentIntegrations,
+  renderThinAgent,
+  refreshActiveAgentContext,
+  PROTOCOL_MD,
+  createChange,
+  loadChangeMeta,
+  saveChangeMeta,
+  buildContext,
+  listChanges,
+  getActiveChangeId,
+  clearActiveIf,
+  setActiveChange,
+  resolveChangeId,
+  canLeaveStage,
+  advanceStage,
+  skipStage,
+  switchWorkflow,
+  approveGate,
+  completeChange,
+  formatStatus,
+  buildAgentPrompt
+};