@structured-vibe-coding/core 0.17.1 → 0.18.0

package/dist/chunk-4PIRWYRA.js

@@ -0,0 +1,1125 @@
+import {
+  buildAgentPrompt,
+  defaultConfig,
+  formatStatus,
+  loadConfig
+} from "./chunk-44LQ5BKZ.js";
+import {
+  buildContext,
+  getActiveChangeId
+} from "./chunk-QHV5KZKX.js";
+import {
+  SddError
+} from "./chunk-MHODNFIL.js";
+import {
+  configPath,
+  guidancePaths,
+  listDirs,
+  listFiles,
+  memoryDir,
+  pathExists,
+  readText,
+  sddRoot,
+  writeText
+} from "./chunk-O5SP6X5R.js";
+
+// src/agents.ts
+import { constants } from "fs";
+import { access, lstat as lstat2, readdir, rmdir, unlink } from "fs/promises";
+import { dirname as dirname2, join as join4 } from "pathe";
+
+// src/generated.ts
+import { createHash } from "crypto";
+import { lstat } from "fs/promises";
+import { join } from "pathe";
+import { z } from "zod";
+var MARKER_RE = /^<!-- sdd:generated sha256=([0-9a-f]{64})\b[^\n]*-->[ \t]*\r?\n/m;
+function contentHash(body) {
+  return createHash("sha256").update(body.replace(/\r\n/g, "\n"), "utf8").digest("hex");
+}
+function markerLine(hash) {
+  return `<!-- sdd:generated sha256=${hash} (sdd regenerates this file only while it is unchanged; edit freely) -->
+`;
+}
+function markGenerated(body) {
+  const line = markerLine(contentHash(body));
+  if (body.startsWith("---\n")) {
+    const close = body.indexOf("\n---\n", 3);
+    if (close !== -1) {
+      const at = close + "\n---\n".length;
+      return body.slice(0, at) + line + body.slice(at);
+    }
+  }
+  return line + body;
+}
+function generatedState(content) {
+  const m = MARKER_RE.exec(content);
+  if (!m) return "not-generated";
+  const body = content.slice(0, m.index) + content.slice(m.index + m[0].length);
+  return contentHash(body) === m[1] ? "unmodified" : "edited";
+}
+var GeneratedManifestSchema = z.object({
+  version: z.literal(1),
+  files: z.record(z.string().regex(/^[0-9a-f]{64}$/))
+}).strict();
+async function loadGeneratedManifest(path) {
+  let st;
+  try {
+    st = await lstat(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return { version: 1, files: {} };
+    throw err;
+  }
+  if (st.isSymbolicLink() || !st.isFile()) {
+    throw new Error(`Cannot trust generated file manifest at ${path}; no files were changed.`);
+  }
+  try {
+    return GeneratedManifestSchema.parse(JSON.parse(await readText(path)));
+  } catch (err) {
+    throw new Error(
+      `Invalid generated file manifest at ${path}: ${err instanceof Error ? err.message : String(err)}. No files were changed.`
+    );
+  }
+}
+async function saveGeneratedManifest(path, manifest) {
+  const validated = GeneratedManifestSchema.parse(manifest);
+  const files = Object.fromEntries(
+    Object.entries(validated.files).sort(([a], [b]) => a.localeCompare(b))
+  );
+  await writeText(path, `${JSON.stringify({ version: 1, files }, null, 2)}
+`);
+}
+async function defaultFiles(sourceDir, relativeDir = "") {
+  const files = (await listFiles(join(sourceDir, relativeDir))).map(
+    (file) => [relativeDir, file].filter(Boolean).join("/")
+  );
+  const nested = await Promise.all(
+    (await listDirs(join(sourceDir, relativeDir))).map(
+      (dir) => defaultFiles(sourceDir, [relativeDir, dir].filter(Boolean).join("/"))
+    )
+  );
+  return [...files, ...nested.flat()].sort();
+}
+async function symlinkInPath(projectRoot, relativePath) {
+  let current = projectRoot;
+  const parts = relativePath.split("/");
+  const traversed = [];
+  for (const part of parts) {
+    current = join(current, part);
+    traversed.push(part);
+    try {
+      if ((await lstat(current)).isSymbolicLink()) return traversed.join("/");
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT" || code === "ENOTDIR") return null;
+      throw err;
+    }
+  }
+  return null;
+}
+async function reconcileGeneratedTree(projectRoot, sourceDir, destinationDir, destinationRelative, manifest, force) {
+  const created = [];
+  const refreshed = [];
+  const kept = [];
+  let changed = false;
+  for (const relativeFile of await defaultFiles(sourceDir)) {
+    const projectRelative = `${destinationRelative}/${relativeFile}`;
+    const sourcePath = join(sourceDir, relativeFile);
+    const destPath = join(destinationDir, relativeFile);
+    const symlinkPath = await symlinkInPath(projectRoot, projectRelative);
+    if (symlinkPath) {
+      kept.push({ path: symlinkPath, reason: "symlink" });
+      continue;
+    }
+    const generated = await readText(sourcePath);
+    const generatedHash = contentHash(generated);
+    if (!await pathExists(destPath)) {
+      await writeText(destPath, generated);
+      manifest.files[projectRelative] = generatedHash;
+      created.push(projectRelative);
+      changed = true;
+      continue;
+    }
+    let current;
+    try {
+      const st = await lstat(destPath);
+      if (!st.isFile()) {
+        kept.push({ path: projectRelative, reason: "unreadable" });
+        continue;
+      }
+      current = await readText(destPath);
+    } catch {
+      kept.push({ path: projectRelative, reason: "unreadable" });
+      continue;
+    }
+    const previousHash = manifest.files[projectRelative];
+    if (!previousHash) {
+      kept.push({ path: projectRelative, reason: "not-generated" });
+      continue;
+    }
+    if (contentHash(current) !== previousHash) {
+      kept.push({ path: projectRelative, reason: "edited" });
+      continue;
+    }
+    if (force && current !== generated) {
+      await writeText(destPath, generated);
+      manifest.files[projectRelative] = generatedHash;
+      refreshed.push(projectRelative);
+      changed = true;
+    }
+  }
+  return { created, refreshed, kept, changed };
+}
+function describeKept(k) {
+  switch (k.reason) {
+    case "edited":
+      return `${k.path} (generated by sdd, then edited \u2014 kept)`;
+    case "symlink":
+      return `${k.path} (symbolic link \u2014 not followed, left untouched)`;
+    case "unreadable":
+      return `${k.path} (could not be read \u2014 left untouched)`;
+    default:
+      return `${k.path} (not generated by sdd \u2014 left untouched)`;
+  }
+}
+
+// src/guidance.ts
+import { join as join3 } from "pathe";
+
+// src/defaults.ts
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join2 } from "pathe";
+function defaultsRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "..", "defaults"),
+    // npm package: dist/../defaults
+    join2(here, "defaults"),
+    // same-dir defaults if present
+    join2(here, "..", "..", "defaults")
+    // src/ during some test runners
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return candidates[0];
+}
+function defaultWorkflowsDir() {
+  return join2(defaultsRoot(), "workflows");
+}
+function defaultTemplatesDir() {
+  return join2(defaultsRoot(), "templates");
+}
+function defaultMemoryDir() {
+  return join2(defaultsRoot(), "memory");
+}
+function defaultMcpYamlPath() {
+  return join2(defaultsRoot(), "mcp.yaml");
+}
+function defaultPricesYamlPath() {
+  return join2(defaultsRoot(), "prices.yaml");
+}
+function defaultSearchYamlPath() {
+  return join2(defaultsRoot(), "search.yaml");
+}
+
+// src/guidance.ts
+function renderSddReadme(config) {
+  const paths = guidancePaths(config);
+  return `# Structured Vibe Coding (SDD)
+
+This directory configures local Spec-Driven Development for this repo.
+
+- \`config.yaml\` \u2014 project settings and per-change policy
+- \`workflows/\` \u2014 YAML workflow packs (customize freely)
+- \`templates/\` \u2014 markdown templates for stage artifacts
+- \`protocol.md\` / \`active-context.md\` \u2014 agent playbook + live task (after agent install)
+
+Work lives in \`../${paths.changes}/<id>/\`. Completed packs stay there with \`status: completed\`.
+Promote lasting decisions into \`../${paths.memory}/\`. (Archive-on-complete is opt-in.)
+
+**Documentation map (stable):** \`../${paths.memoryIndex}\`  
+**Change-scoped docs:** \`../${paths.changes}/<id>/\`
+
+## Quick commands
+
+\`\`\`bash
+sdd new "My feature"
+sdd status
+sdd next
+sdd verify
+sdd complete
+\`\`\`
+`;
+}
+function renderMemoryIndex(config) {
+  const paths = guidancePaths(config);
+  return `# Documentation map
+
+Parent page for **stable** project docs. Humans and coding agents: start here, then open only what you need.
+
+| Kind | Where | Lifetime |
+|------|--------|----------|
+| **This map + memory** | \`${paths.memory}/*.md\` | Long-lived |
+| **Active change** | \`${paths.changes}/<id>/\` (see \`.sdd/active-context.md\`) | Until complete |
+| **Finished work** | \`${paths.changes}/<id>/\` with \`status: completed\` | History (pack stays in place; archive is opt-in) |
+| **Optional domains** | \`domains/\` | Long-lived by area |
+
+## Stable docs
+
+| Topic | File |
+|-------|------|
+| Product / vision | [product.md](product.md) |
+| Requirements | [requirements.md](requirements.md) (after greenfield) |
+| Feature backlog | [features.md](features.md) (after greenfield; \`sdd backlog start F-001\`) |
+| Constitution (non-negotiables) | [constitution.md](constitution.md) |
+| Architecture | [architecture.md](architecture.md) |
+| Coding & process conventions | [conventions.md](conventions.md) |
+
+**Greenfield:** \`sdd greenfield "one-line idea"\` then promote into \`${paths.memory}/\` on complete.  
+Add rows here when you introduce new durable docs (e.g. \`security.md\`, \`ops.md\`).
+
+## Active work
+
+1. Run \`sdd status\` (or open \`.sdd/active-context.md\`).
+2. Read stage artifacts under the active change folder only.
+3. Prefer small updates to change packs; **promote** lasting decisions into \`${paths.memory}/\` after \`sdd complete\`.
+
+## Ownership (suggested)
+
+| Area | Owner |
+|------|--------|
+| \`${paths.memory}/*\` | Tech lead / architect |
+| Current \`${paths.changes}/<id>/\` | Author of the change (PR owner) |
+| \`domains/<name>/\` | Domain owner (if used) |
+
+Keep this map short. Link out; do not paste large designs here.
+`;
+}
+async function refreshConfiguredGuidance(projectRoot, config) {
+  await writeConfiguredMemoryIndex(memoryDir(projectRoot, config), config);
+  await writeConfiguredReadme(projectRoot, config);
+}
+async function writeConfiguredMemoryIndex(memoryRoot, config) {
+  const indexPath = join3(memoryRoot, "index.md");
+  const paths = guidancePaths(config);
+  if (paths.memory === "memory" && paths.changes === "changes") return;
+  if (!await pathExists(indexPath)) return;
+  const existing = await readText(indexPath);
+  const state = generatedState(existing);
+  if (state === "edited") return;
+  const shippedPath = join3(defaultMemoryDir(), "index.md");
+  const shipped = await pathExists(shippedPath) ? await readText(shippedPath) : "";
+  if (state !== "unmodified" && existing.replace(/\r\n/g, "\n").trim() !== shipped.trim()) return;
+  const body = renderMemoryIndex(config);
+  if (existing.includes(`\`${paths.memory}/`) && existing.includes(`\`${paths.changes}/`)) return;
+  await writeText(indexPath, markGenerated(body));
+}
+async function writeConfiguredReadme(projectRoot, config) {
+  const readmePath = join3(sddRoot(projectRoot), "README.md");
+  if (!await pathExists(readmePath)) return;
+  const existing = await readText(readmePath);
+  if (generatedState(existing) !== "unmodified") return;
+  const body = renderSddReadme(config);
+  const marked = markGenerated(body);
+  if (existing === marked) return;
+  await writeText(readmePath, marked);
+}
+
+// src/agents.ts
+var AGENT_INTEGRATIONS = [
+  {
+    id: "copilot",
+    key: "copilot",
+    aliases: ["github-copilot", "gh-copilot"],
+    label: "GitHub Copilot",
+    hint: ".github/agents/*.agent.md (VS Code, Cursor, JetBrains, \u2026)",
+    requiresCli: false,
+    installUrl: "https://github.com/features/copilot",
+    rolePath: (roleId) => `.github/agents/${roleId}.agent.md`,
+    agentsMdRow: "| GitHub Copilot | `.github/agents/*.agent.md` (same roles; any IDE that supports Copilot agents) |"
+  },
+  {
+    id: "claude-code",
+    key: "claude",
+    aliases: ["claude-code", "claudecode"],
+    label: "Claude Code",
+    hint: ".claude/agents/*.md (terminal agent)",
+    requiresCli: true,
+    cliBinary: "claude",
+    installUrl: "https://docs.anthropic.com/en/docs/claude-code",
+    rolePath: (roleId) => `.claude/agents/${roleId}.md`,
+    agentsMdRow: "| Claude Code | `.claude/agents/` (`sdd`, `sdd-planner`, `sdd-implementer`, `sdd-reviewer`) |"
+  },
+  {
+    id: "grok",
+    key: "grok",
+    aliases: ["grok-build", "grokbuild", "xai", "xai-grok"],
+    label: "Grok Build",
+    hint: ".grok/rules/sdd.md + AGENTS.md (terminal TUI from xAI)",
+    requiresCli: false,
+    cliBinary: "grok",
+    installUrl: "https://docs.x.ai",
+    // Single rules file: Grok auto-loads all .grok/rules/*.md
+    rolePath: () => `.grok/rules/sdd.md`,
+    rolesToInstall: ["sdd"],
+    agentsMdRow: "| Grok Build | `.grok/rules/sdd.md` + `AGENTS.md` (reads protocol + active-context; run `sdd` in shell) |"
+  },
+  {
+    id: "ollama",
+    key: "ollama",
+    aliases: ["local", "llama", "ollama-local"],
+    label: "Ollama (local)",
+    hint: "Local models via `ollama` CLI + AGENTS.md / .ollama/sdd.md (set SDD_OLLAMA_MODEL)",
+    requiresCli: true,
+    cliBinary: "ollama",
+    installUrl: "https://ollama.com",
+    // Single project brief — Ollama does not auto-load multi-role agent trees
+    rolePath: () => `.ollama/sdd.md`,
+    rolesToInstall: ["sdd"],
+    agentsMdRow: "| Ollama (local) | `.ollama/sdd.md` + `AGENTS.md` + handoff; launch: `ollama run $SDD_OLLAMA_MODEL` |"
+  },
+  {
+    id: "kilo",
+    key: "kilo",
+    aliases: ["kilocode", "kilo-code", "kilo-ai"],
+    label: "Kilo Code",
+    hint: ".kilo/sdd.md + AGENTS.md (terminal CLI from kilo.ai)",
+    requiresCli: true,
+    cliBinary: "kilo",
+    installUrl: "https://kilo.ai/docs/code-with-ai/platforms/cli",
+    // Single project brief — Kilo loads AGENTS.md and supports instruction files
+    rolePath: () => `.kilo/sdd.md`,
+    rolesToInstall: ["sdd"],
+    agentsMdRow: "| Kilo Code | `.kilo/sdd.md` + `AGENTS.md` (reads protocol + active-context; run `kilo` or `sdd` in shell) |"
+  }
+];
+var ALL_AGENT_TARGETS = AGENT_INTEGRATIONS.map((i) => i.id);
+var DEFAULT_INIT_INTEGRATION = "copilot";
+var AGENT_TARGET_OPTIONS = AGENT_INTEGRATIONS.map(
+  ({ id, key, label, hint, requiresCli, installUrl }) => ({
+    id,
+    key,
+    label,
+    hint,
+    requiresCli,
+    installUrl
+  })
+);
+var IDE_NAMES = /* @__PURE__ */ new Set(["intellij", "idea", "jetbrains", "vscode", "vs-code", "cursor"]);
+function getIntegration(target) {
+  const found = AGENT_INTEGRATIONS.find((i) => i.id === target);
+  if (!found) throw new Error(`Unknown agent integration: ${target}`);
+  return found;
+}
+function integrationKeyFor(target) {
+  return getIntegration(target).key;
+}
+function optionForTarget(target) {
+  return getIntegration(target);
+}
+function agentHostPaths(target) {
+  switch (target) {
+    case "copilot":
+      return [".github/agents"];
+    case "claude-code":
+      return [".claude/agents"];
+    case "grok":
+      return [".grok/rules"];
+    case "ollama":
+      return [".ollama"];
+    case "kilo":
+      return [".kilo"];
+    default:
+      return [];
+  }
+}
+var LEGACY_AGENT_PATHS = [".idea/sdd-agent-notes.md"];
+var PRUNABLE_PARENTS = [".claude", ".idea", ".grok", ".ollama", ".kilo"];
+async function pathKind(full) {
+  try {
+    const st = await lstat2(full);
+    if (st.isSymbolicLink()) return "symlink";
+    if (st.isDirectory()) return "dir";
+    if (st.isFile()) return "file";
+    return "other";
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return "missing";
+    throw err;
+  }
+}
+async function symlinkOnPath(projectRoot, rel) {
+  let cur = "";
+  for (const part of rel.split("/")) {
+    cur = cur ? `${cur}/${part}` : part;
+    const kind = await pathKind(join4(projectRoot, cur));
+    if (kind === "symlink") return cur;
+    if (kind === "missing") return null;
+  }
+  return null;
+}
+async function canAccess(full, mode) {
+  try {
+    await access(full, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function fsCode(err) {
+  return err?.code;
+}
+function describeFsError(err, action, rel) {
+  const code = fsCode(err);
+  const why = code === "EACCES" || code === "EPERM" ? "permission denied" : code === "EISDIR" ? "it is a directory, not a file" : code === "ENOTDIR" ? "a parent path is a file, not a directory" : code === "ELOOP" ? "too many levels of symbolic links" : code === "ENOENT" ? "it does not exist (dangling symbolic link?)" : err?.message ?? String(err);
+  return `Cannot ${action} ${rel}: ${why}${code ? ` (${code})` : ""}.`;
+}
+var AgentInstallPreflightError = class extends SddError {
+  problems;
+  constructor(problems) {
+    super(
+      [
+        "sdd cannot set up the AI agent files. Nothing was written.",
+        ...problems.map((pr) => `  - ${pr}`),
+        "Fix the paths above, then re-run."
+      ].join("\n"),
+      { code: "AGENT_PREFLIGHT" }
+    );
+    this.name = "AgentInstallPreflightError";
+    this.problems = problems;
+  }
+};
+async function planOtherHostRemoval(projectRoot, keep) {
+  const remove = [];
+  const kept = [];
+  const candidates = [];
+  for (const integ of AGENT_INTEGRATIONS) {
+    if (integ.id === keep) continue;
+    candidates.push(...agentHostPaths(integ.id));
+  }
+  candidates.push(...LEGACY_AGENT_PATHS);
+  const visit = async (rel) => {
+    const full = join4(projectRoot, rel);
+    const kind = await pathKind(full);
+    if (kind === "missing") return;
+    if (kind === "symlink") {
+      kept.push({ path: rel, reason: "symlink" });
+      return;
+    }
+    if (kind === "dir") {
+      let names;
+      try {
+        names = (await readdir(full)).sort();
+      } catch {
+        kept.push({ path: rel, reason: "unreadable" });
+        return;
+      }
+      for (const name of names) await visit(`${rel}/${name}`);
+      return;
+    }
+    if (kind !== "file") {
+      kept.push({ path: rel, reason: "not-generated" });
+      return;
+    }
+    let state;
+    try {
+      state = generatedState(await readText(full));
+    } catch {
+      kept.push({ path: rel, reason: "unreadable" });
+      return;
+    }
+    if (state === "unmodified") remove.push(rel);
+    else kept.push({ path: rel, reason: state });
+  };
+  for (const rel of candidates) {
+    const link = await symlinkOnPath(projectRoot, rel);
+    if (link) {
+      if (!kept.some((k) => k.path === link)) kept.push({ path: link, reason: "symlink" });
+      continue;
+    }
+    await visit(rel);
+  }
+  return { remove, kept };
+}
+async function removalProblems(projectRoot, plan) {
+  const problems = [];
+  for (const rel of plan.remove) {
+    const dir = dirname2(rel);
+    if (!await canAccess(join4(projectRoot, dir), constants.W_OK)) {
+      problems.push(
+        `Cannot remove ${rel} (another host's sdd file): ${dir}/ is not writable (permission denied). Make it writable or delete the file yourself.`
+      );
+    }
+  }
+  return problems;
+}
+async function executeRemoval(projectRoot, plan) {
+  const removed = [];
+  const ancestors = /* @__PURE__ */ new Set();
+  for (const rel of plan.remove) {
+    try {
+      await unlink(join4(projectRoot, rel));
+    } catch (err) {
+      throw new SddError(describeFsError(err, "remove", rel), { cause: err });
+    }
+    removed.push(rel);
+    let dir = dirname2(rel);
+    while (dir !== "." && dir !== "") {
+      const top = !dir.includes("/");
+      if (top && !PRUNABLE_PARENTS.includes(dir)) break;
+      ancestors.add(dir);
+      dir = dirname2(dir);
+    }
+  }
+  const dirs = [...ancestors].sort((a, b) => b.split("/").length - a.split("/").length);
+  for (const rel of dirs) {
+    const full = join4(projectRoot, rel);
+    if (await pathKind(full) !== "dir") continue;
+    if ((await readdir(full)).length !== 0) continue;
+    try {
+      await rmdir(full);
+      removed.push(rel);
+    } catch {
+    }
+  }
+  return removed;
+}
+async function removeOtherAgentHostsDetailed(projectRoot, keep) {
+  const plan = await planOtherHostRemoval(projectRoot, keep);
+  const problems = await removalProblems(projectRoot, plan);
+  if (problems.length) throw new AgentInstallPreflightError(problems);
+  const removed = await executeRemoval(projectRoot, plan);
+  return { removed, kept: plan.kept };
+}
+async function removeOtherAgentHosts(projectRoot, keep) {
+  return (await removeOtherAgentHostsDetailed(projectRoot, keep)).removed;
+}
+function parseIntegration(raw) {
+  const p = raw.trim().toLowerCase();
+  if (!p) {
+    throw new Error(
+      `Expected one AI coding agent. Choose from: ${AGENT_INTEGRATIONS.map((i) => i.key).join(", ")}`
+    );
+  }
+  if (IDE_NAMES.has(p)) {
+    throw new Error(
+      `"${p}" is an IDE, not an AI coding agent. Choose: ${AGENT_INTEGRATIONS.map((i) => i.key).join(", ")}.`
+    );
+  }
+  for (const integ of AGENT_INTEGRATIONS) {
+    if (integ.id === p || integ.key === p || integ.aliases.includes(p)) {
+      return integ.id;
+    }
+  }
+  throw new Error(
+    `Unknown AI coding agent "${raw}". Choose from: ${AGENT_INTEGRATIONS.map((i) => i.key).join(", ")}`
+  );
+}
+function parseAgentTargets(raw) {
+  const parts = (Array.isArray(raw) ? raw : [raw]).flatMap((s) => String(s).split(",")).map((s) => s.trim()).filter(Boolean);
+  if (!parts.length) {
+    throw new Error("No AI coding agent specified");
+  }
+  const out = [];
+  for (const p of parts) {
+    const id = parseIntegration(p);
+    if (!out.includes(id)) out.push(id);
+  }
+  return out;
+}
+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).",
+      "If kickoff/brief says refine or analyze: follow <changes_path>/<id>/refine-brief.md \u2014 stage-scoped refine; never edit constitution; do not sdd next."
+    ]
+  },
+  {
+    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."
+    ]
+  }
+];
+function agentFiles(integ, config) {
+  const roles = integ.rolesToInstall?.length ? SDD_AGENT_ROLES.filter((r) => integ.rolesToInstall.includes(r.id)) : SDD_AGENT_ROLES;
+  return [
+    { rel: join4(".sdd", "protocol.md"), content: renderProtocolMd(config) },
+    ...roles.map((role) => ({
+      rel: integ.rolePath(role.id),
+      content: renderThinAgent(role, config)
+    })),
+    { rel: "AGENTS.md", content: renderAgentsMd(integ, config) }
+  ];
+}
+async function planAgentIntegration(opts) {
+  const root = opts.projectRoot;
+  const force = opts.force ?? false;
+  const integ = getIntegration(opts.target);
+  const problems = [];
+  const writes = [];
+  const config = await pathExists(configPath(root)) ? await loadConfig(root) : defaultConfig();
+  for (const { rel, content } of agentFiles(integ, config)) {
+    const full = join4(root, rel);
+    if (!rel.startsWith(".sdd/")) {
+      const link = await symlinkOnPath(root, rel);
+      if (link) {
+        writes.push({ rel, content, action: "keep", keptReason: "symlink", keptPath: link });
+        continue;
+      }
+    }
+    const kind = await pathKind(full);
+    if (kind === "missing") {
+      let anc = dirname2(rel);
+      while (anc !== "." && await pathKind(join4(root, anc)) === "missing") anc = dirname2(anc);
+      const ancFull = anc === "." ? root : join4(root, anc);
+      const ancKind = await pathKind(ancFull);
+      if (ancKind !== "dir" && ancKind !== "symlink") {
+        problems.push(`Cannot create ${rel}: ${anc} is a file, not a directory.`);
+      } else if (!await canAccess(ancFull, constants.W_OK)) {
+        problems.push(
+          `Cannot create ${rel}: ${anc === "." ? "the project folder" : `${anc}/`} is not writable (permission denied).`
+        );
+      }
+      writes.push({ rel, content, action: "create" });
+      continue;
+    }
+    if (kind === "dir") {
+      problems.push(
+        `Cannot write ${rel}: it is a directory, not a file (EISDIR). Rename or move it.`
+      );
+      writes.push({ rel, content, action: "keep", keptReason: "not-generated" });
+      continue;
+    }
+    if (kind !== "file") {
+      writes.push({ rel, content, action: "keep", keptReason: "not-generated" });
+      continue;
+    }
+    let state;
+    try {
+      state = generatedState(await readText(full));
+    } catch (err) {
+      problems.push(
+        `${describeFsError(err, "read", rel)} sdd must read it to tell whether it generated the file; fix its permissions or move it.`
+      );
+      writes.push({ rel, content, action: "keep", keptReason: "unreadable" });
+      continue;
+    }
+    if (state !== "unmodified") {
+      writes.push({ rel, content, action: "keep", keptReason: state });
+    } else if (!force) {
+      writes.push({ rel, content, action: "skip" });
+    } else {
+      if (!await canAccess(full, constants.W_OK)) {
+        problems.push(
+          `Cannot regenerate ${rel} (--force): the file is read-only (permission denied). Make it writable or delete it.`
+        );
+      }
+      writes.push({ rel, content, action: "overwrite" });
+    }
+  }
+  const removal = await planOtherHostRemoval(root, opts.target);
+  problems.push(...await removalProblems(root, removal));
+  return { writes, removal, problems };
+}
+async function assertAgentInstallable(opts) {
+  const plan = await planAgentIntegration(opts);
+  if (plan.problems.length) throw new AgentInstallPreflightError(plan.problems);
+}
+async function installAgentIntegration(opts) {
+  const integ = getIntegration(opts.target);
+  const created = [];
+  const skipped = [];
+  const root = opts.projectRoot;
+  const force = opts.force ?? false;
+  const plan = await planAgentIntegration({ projectRoot: root, target: opts.target, force });
+  if (plan.problems.length) throw new AgentInstallPreflightError(plan.problems);
+  const removed = await executeRemoval(root, plan.removal);
+  const kept = [...plan.removal.kept];
+  const byRel = new Map(plan.writes.map((w) => [w.rel, w]));
+  const write = async (rel) => {
+    const w = byRel.get(rel);
+    if (w.action === "keep") {
+      kept.push({ path: w.keptPath ?? rel, reason: w.keptReason });
+      return;
+    }
+    if (w.action === "skip") {
+      skipped.push(rel);
+      return;
+    }
+    try {
+      await writeText(join4(root, rel), markGenerated(w.content));
+    } catch (err) {
+      throw new SddError(describeFsError(err, "write", rel), { cause: err });
+    }
+    created.push(rel);
+  };
+  await write(join4(".sdd", "protocol.md"));
+  await refreshActiveAgentContext(root);
+  for (const w of plan.writes) {
+    if (w.rel !== join4(".sdd", "protocol.md") && w.rel !== "AGENTS.md") await write(w.rel);
+  }
+  await write("AGENTS.md");
+  const snapshotRel = join4(".sdd", "agents.json");
+  if (await pathExists(join4(root, snapshotRel)) && !force) {
+    skipped.push(snapshotRel);
+  } else {
+    await writeText(
+      join4(root, snapshotRel),
+      JSON.stringify(
+        {
+          version: 3,
+          mode: "agents-only",
+          protocol: ".sdd/protocol.md",
+          activeContext: ".sdd/active-context.md",
+          roles: SDD_AGENT_ROLES.map((r) => r.id),
+          /** Speckit-style public key */
+          ai: integ.key,
+          integration: integ.key,
+          installed: [integ.id],
+          updated: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    created.push(snapshotRel);
+  }
+  return { created, skipped, kept, removed, target: opts.target };
+}
+async function installAgentIntegrations(opts) {
+  if (!opts.targets?.length) {
+    throw new Error(
+      `Specify one AI coding agent: ${AGENT_INTEGRATIONS.map((i) => i.key).join(", ")}`
+    );
+  }
+  const created = [];
+  const skipped = [];
+  for (const target of opts.targets) {
+    const r = await installAgentIntegration({
+      projectRoot: opts.projectRoot,
+      target,
+      force: opts.force
+    });
+    created.push(...r.created);
+    skipped.push(...r.skipped);
+  }
+  return { created, skipped, targets: opts.targets };
+}
+function renderThinAgent(role, config) {
+  const paths = guidancePaths(config ?? { memory_path: "memory", changes_path: "changes" });
+  const rules = role.roleRules.map((r) => `- ${r.replaceAll("<changes_path>", paths.changes)}`).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. \`${paths.constitution}\` if present \u2014 non-negotiables
+4. Active change files under \`${paths.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 loadInstalledAgent(projectRoot) {
+  const path = join4(sddRoot(projectRoot), "agents.json");
+  if (!await pathExists(path)) return null;
+  try {
+    const raw = JSON.parse(await readText(path));
+    const key = raw.ai ?? raw.integration ?? raw.installed?.[0];
+    if (!key || typeof key !== "string") return null;
+    const target = parseIntegration(key);
+    return { ai: integrationKeyFor(target), target, integration: getIntegration(target) };
+  } catch {
+    return null;
+  }
+}
+async function writeAgentHandoff(projectRoot, config, changeId, budget, runtime) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const body = await buildAgentPrompt(ctx, config, projectRoot, budget, runtime);
+  const outPath = join4(sddRoot(projectRoot), "handoff.md");
+  const header = `# SDD handoff (auto)
+
+> Generated for the AI coding agent configured at init.  
+> Change: **${ctx.meta.title}** \xB7 \`${ctx.id}\`
+
+Also read: \`.sdd/active-context.md\`, \`.sdd/protocol.md\`, \`${guidancePaths(config).constitution}\` if present.
+
+---
+
+`;
+  await writeText(outPath, header + body + "\n");
+  return outPath;
+}
+function agentKickoffMessage(opts) {
+  const event = opts.event ?? "context updated";
+  const paths = guidancePaths({
+    memory_path: opts.memoryPath ?? "memory",
+    changes_path: opts.changesPath ?? "changes"
+  });
+  if (opts.instructions?.trim()) {
+    return [
+      `SDD: ${event}.`,
+      `Title: ${opts.title}`,
+      `Change: ${opts.changeId}`,
+      `Stage: ${opts.stage}`,
+      opts.instructions.trim()
+    ].join(" ");
+  }
+  return [
+    `SDD: ${event}.`,
+    `Title: ${opts.title}`,
+    `Change: ${opts.changeId}`,
+    `Stage: ${opts.stage}`,
+    `Read in order: .sdd/active-context.md, .sdd/handoff.md, .sdd/protocol.md, ${paths.constitution} (if present).`,
+    `Do the work for the current stage only under ${paths.changes}/${opts.changeId}/. Do not expand scope.`,
+    `When the stage is done, tell the human to run: sdd next (or sdd verify / sdd complete as appropriate).`
+  ].join(" ");
+}
+async function refreshGeneratedAgentFiles(projectRoot, config) {
+  const installed = await loadInstalledAgent(projectRoot);
+  const files = installed ? agentFiles(installed.integration, config) : [{ rel: join4(".sdd", "protocol.md"), content: renderProtocolMd(config) }];
+  for (const { rel, content } of files) {
+    const full = join4(projectRoot, rel);
+    if (!await pathExists(full)) {
+      if (rel === join4(".sdd", "protocol.md")) {
+        await writeText(full, markGenerated(content));
+      }
+      continue;
+    }
+    const existing = await readText(full);
+    if (generatedState(existing) !== "unmodified") continue;
+    if (existing === markGenerated(content)) continue;
+    await writeText(full, markGenerated(content));
+  }
+}
+async function refreshActiveAgentContext(projectRoot) {
+  const markerDir = sddRoot(projectRoot);
+  if (!await pathExists(join4(markerDir, "config.yaml"))) {
+    return null;
+  }
+  const config = await loadConfig(projectRoot);
+  await refreshConfiguredGuidance(projectRoot, config);
+  await refreshGeneratedAgentFiles(projectRoot, config);
+  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 = renderProtocolMd({ memory_path: "memory", changes_path: "changes" });
+function renderProtocolMd(config) {
+  const paths = guidancePaths(config);
+  const fence = "```";
+  return [
+    "# 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 | \`${paths.changes}/<id>/meta.yaml\` (workflow, stage, gates) |`,
+    "| Current task snapshot | `.sdd/active-context.md` |",
+    `| Non-negotiables | \`${paths.constitution}\` if present |`,
+    `| Stable product/tech rules | \`${paths.memory}/*.md\` (start at \`${paths.memoryIndex}\` if present) |`,
+    `| Stage artifacts | files in \`${paths.changes}/<id>/\` for the active change |`,
+    "",
+    "## Required read order",
+    "",
+    "1. `.sdd/active-context.md`",
+    "2. This file (`.sdd/protocol.md`)",
+    `3. \`${paths.constitution}\` if present (non-negotiables agents must not violate)`,
+    "4. `meta.yaml` + artifacts for the **current stage** (and prior stages if needed)",
+    `5. \`${paths.memoryIndex}\` (documentation map) if present, then linked memory pages 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 |",
+    "| brainstorm (optional) | Multiple approaches; parallel exploration; no final design yet |",
+    "| clarify_* (optional) | Ask clarifying questions; write Q&A; or tell human to skip |",
+    "",
+    "## Optional stages",
+    "",
+    "- Stages marked **optional** / kind `brainstorm` or `clarify` may be skipped:  ",
+    '  `sdd skip <stage_id> -r "not needed"`',
+    "- Do **not** invent a skip by jumping stages. `sdd next` blocks on empty required stubs (e.g. design.md).",
+    "- If the tool falls back to an earlier stage, **complete that stage** before advancing again.",
+    "",
+    "## 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.",
+    "6. **Required stage artifacts must be substantive** \u2014 not empty templates. Design cannot be skipped via empty design.md.",
+    "",
+    "## Commands (human / shell)",
+    "",
+    `${fence}bash`,
+    "sdd status",
+    "sdd next",
+    "sdd agent              # print handoff",
+    "sdd agents refresh     # refresh active-context.md",
+    "sdd verify",
+    "sdd complete",
+    fence,
+    "",
+    "## Out of scope for agents",
+    "",
+    "- Replacing CI/CD or team process tools",
+    "- Deleting `.sdd` / completed change history",
+    "- Claiming complete without verify when required",
+    ""
+  ].join("\n");
+}
+function renderAgentsMd(integ, config) {
+  const paths = guidancePaths(config ?? { memory_path: "memory", changes_path: "changes" });
+  return [
+    "# Agents",
+    "",
+    "This repo uses **SDD agents only** (no skills).",
+    "",
+    "AI coding agents are **not** the same as IDEs: VS Code, Cursor, and IntelliJ host tools like Copilot or Claude Code.",
+    "",
+    "| Read first | |",
+    "|------------|--|",
+    "| Live task | `.sdd/active-context.md` |",
+    "| Playbook | `.sdd/protocol.md` |",
+    `| Constitution | \`${paths.constitution}\` if present |`,
+    `| Doc map (stable) | \`${paths.memoryIndex}\` if present |`,
+    `| Active change | \`${paths.changes}/<id>/\` |`,
+    "",
+    "| AI agent | Files |",
+    "|----------|--------|",
+    integ.agentsMdRow,
+    "",
+    "Refresh context: `sdd agents refresh`.",
+    ""
+  ].join("\n");
+}
+
+export {
+  contentHash,
+  markGenerated,
+  generatedState,
+  loadGeneratedManifest,
+  saveGeneratedManifest,
+  reconcileGeneratedTree,
+  describeKept,
+  defaultsRoot,
+  defaultWorkflowsDir,
+  defaultTemplatesDir,
+  defaultMemoryDir,
+  defaultMcpYamlPath,
+  defaultPricesYamlPath,
+  defaultSearchYamlPath,
+  renderSddReadme,
+  renderMemoryIndex,
+  refreshConfiguredGuidance,
+  AGENT_INTEGRATIONS,
+  ALL_AGENT_TARGETS,
+  DEFAULT_INIT_INTEGRATION,
+  AGENT_TARGET_OPTIONS,
+  getIntegration,
+  integrationKeyFor,
+  optionForTarget,
+  agentHostPaths,
+  describeFsError,
+  AgentInstallPreflightError,
+  removeOtherAgentHostsDetailed,
+  removeOtherAgentHosts,
+  parseIntegration,
+  parseAgentTargets,
+  SDD_AGENT_ROLES,
+  planAgentIntegration,
+  assertAgentInstallable,
+  installAgentIntegration,
+  installAgentIntegrations,
+  renderThinAgent,
+  loadInstalledAgent,
+  writeAgentHandoff,
+  agentKickoffMessage,
+  refreshActiveAgentContext,
+  PROTOCOL_MD,
+  renderProtocolMd,
+  renderAgentsMd
+};