@structured-vibe-coding/core 0.2.2 → 0.3.1

package/dist/index.js

@@ -1,966 +1,95 @@
-// 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");
-}
+import {
+  ALL_AGENT_TARGETS,
+  ArtifactDefSchema,
+  ChangeMetaSchema,
+  ConfigSchema,
+  GateSchema,
+  PROTOCOL_MD,
+  SDD_AGENT_ROLES,
+  SDD_DIR,
+  StageSchema,
+  VerifyCommandSchema,
+  WorkflowSchema,
+  activePointerPath,
+  activeStages,
+  advanceStage,
+  approveGate,
+  archiveDir,
+  buildAgentPrompt,
+  buildContext,
+  canLeaveStage,
+  changeDirName,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  clearActiveIf,
+  completeChange,
+  configPath,
+  copyDir,
+  createChange,
+  defaultConfig,
+  domainsDir,
+  ensureDir,
+  firstActiveStageId,
+  formatStatus,
+  getActiveChangeId,
+  getStage,
+  inferComplexity,
+  installAgentIntegrations,
+  isInitialized,
+  isStageSkipped,
+  listChanges,
+  listDirs,
+  listFiles,
+  listWorkflowNames,
+  loadChangeMeta,
+  loadConfig,
+  loadWorkflow,
+  memoryDir,
+  nextStageId,
+  nowIso,
+  pathExists,
+  previousStageId,
+  projectPaths,
+  readText,
+  readYaml,
+  recommendWorkflow,
+  refreshActiveAgentContext,
+  removePath,
+  renderThinAgent,
+  resolveChangeId,
+  resolveStages,
+  saveChangeMeta,
+  saveConfig,
+  sddRoot,
+  setActiveChange,
+  shouldAutoSkip,
+  skipStage,
+  slugify,
+  switchWorkflow,
+  templatesDir,
+  todayIsoDate,
+  uniqueChangeDirName,
+  workflowsDir,
+  writeText,
+  writeYaml
+} from "./chunk-ANNG5SIL.js";
 
 // src/init.ts
-import { join as join5 } from "pathe";
+import { join as join2 } from "pathe";
 
 // src/defaults.ts
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname as dirname2, join as join4 } from "pathe";
+import { dirname, join } from "pathe";
 function defaultsRoot() {
-  const here = dirname2(fileURLToPath(import.meta.url));
+  const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    join4(here, "..", "defaults"),
+    join(here, "..", "defaults"),
     // npm package: dist/../defaults
-    join4(here, "defaults"),
+    join(here, "defaults"),
     // extension bundle: dist/defaults
-    join4(here, "..", "..", "defaults")
+    join(here, "..", "..", "defaults")
     // src/ during some test runners
   ];
   for (const c of candidates) {
@@ -969,13 +98,13 @@ function defaultsRoot() {
   return candidates[0];
 }
 function defaultWorkflowsDir() {
-  return join4(defaultsRoot(), "workflows");
+  return join(defaultsRoot(), "workflows");
 }
 function defaultTemplatesDir() {
-  return join4(defaultsRoot(), "templates");
+  return join(defaultsRoot(), "templates");
 }
 function defaultMemoryDir() {
-  return join4(defaultsRoot(), "memory");
+  return join(defaultsRoot(), "memory");
 }
 
 // src/init.ts
@@ -983,15 +112,15 @@ async function initProject(opts) {
   const { projectRoot, force = false } = opts;
   const created = [];
   const root = sddRoot(projectRoot);
-  if (await pathExists(join5(root, "config.yaml")) && !force) {
+  if (await pathExists(join2(root, "config.yaml")) && !force) {
     throw new Error(
-      `Already initialized (${join5(root, "config.yaml")}). Use --force to re-copy defaults.`
+      `Already initialized (${join2(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"));
+  created.push(join2(root, "config.yaml"));
   const wfDest = workflowsDir(projectRoot);
   await ensureDir(wfDest);
   const wfSrc = defaultWorkflowsDir();
@@ -1013,15 +142,15 @@ async function initProject(opts) {
     await copyDir(mSrc, mDest);
   } else {
     await writeText(
-      join5(mDest, "product.md"),
+      join2(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
     );
     await writeText(
-      join5(mDest, "architecture.md"),
+      join2(mDest, "architecture.md"),
       "# Architecture\n\n<!-- High-level system shape -->\n"
     );
     await writeText(
-      join5(mDest, "conventions.md"),
+      join2(mDest, "conventions.md"),
       "# Conventions\n\n<!-- Coding and process conventions -->\n"
     );
   }
@@ -1032,10 +161,10 @@ async function initProject(opts) {
   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");
+  await writeText(join2(changesDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join2(archiveDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join2(domainsDir(projectRoot, config), ".gitkeep"), "");
+  const sddReadme = join2(root, "README.md");
   if (!await pathExists(sddReadme) || force) {
     await writeText(
       sddReadme,
@@ -1062,12 +191,23 @@ sdd complete
     );
     created.push(sddReadme);
   }
-  return { created, config };
+  let agentsResult;
+  if (opts.agents !== false) {
+    const targets = Array.isArray(opts.agents) && opts.agents.length ? opts.agents : void 0;
+    const ag = await installAgentIntegrations({
+      projectRoot,
+      targets,
+      force
+    });
+    created.push(...ag.created);
+    agentsResult = { created: ag.created, skipped: ag.skipped };
+  }
+  return { created, config, agents: agentsResult };
 }
 
 // src/verify.ts
 import { spawn } from "child_process";
-import { join as join6 } from "pathe";
+import { join as join3 } from "pathe";
 function runCommand(command, cwd) {
   return new Promise((resolve) => {
     const child = spawn(command, {
@@ -1096,7 +236,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
   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");
+  const evidenceDir = stage.verify?.evidence_dir != null ? join3(ctx.path, stage.verify.evidence_dir) : join3(ctx.path, "evidence", "local");
   await ensureDir(evidenceDir);
   const results = [];
   const runCommands = opts?.runCommands !== false;
@@ -1110,7 +250,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
         exitCode,
         output: output.slice(0, 5e4)
       });
-      const logPath = join6(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+      const logPath = join3(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
       await writeText(
         logPath,
         `# ${cmd.name}
@@ -1136,7 +276,7 @@ ${output}`
     ok = results.every((r) => r.exitCode === 0);
   }
   const checklist = stage.gate?.checklist ?? [];
-  const summaryPath = join6(ctx.path, "local-test-results.md");
+  const summaryPath = join3(ctx.path, "local-test-results.md");
   const lines = [
     `# Local verify results`,
     ``,
@@ -1172,7 +312,7 @@ ${output}`
   if (await pathExists(summaryPath)) {
     const stamp = nowIso();
     await writeText(
-      join6(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
+      join3(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
       lines.join("\n")
     );
   } else {
@@ -1196,10 +336,13 @@ ${output}`
   };
 }
 export {
+  ALL_AGENT_TARGETS,
   ArtifactDefSchema,
   ChangeMetaSchema,
   ConfigSchema,
   GateSchema,
+  PROTOCOL_MD,
+  SDD_AGENT_ROLES,
   SDD_DIR,
   StageSchema,
   VerifyCommandSchema,
@@ -1234,6 +377,7 @@ export {
   getStage,
   inferComplexity,
   initProject,
+  installAgentIntegrations,
   isInitialized,
   isStageSkipped,
   listChanges,
@@ -1252,7 +396,9 @@ export {
   readText,
   readYaml,
   recommendWorkflow,
+  refreshActiveAgentContext,
   removePath,
+  renderThinAgent,
   resolveChangeId,
   resolveStages,
   runLocalVerify,