@structured-vibe-coding/core 0.5.2 → 0.5.4

package/dist/{chunk-IO6AS6JI.js → chunk-I45MAHM6.js}

@@ -256,9 +256,6 @@ function defaultConfig() {
   return ConfigSchema.parse({});
 }
 
-// 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, "");
@@ -453,113 +450,7 @@ async function recommendWorkflow(projectRoot, title, config, opts) {
   };
 }
 
-// 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-MIMBQVHE.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
-
--
-`;
-}
+// src/change-context.ts
 async function loadChangeMeta(projectRoot, config, changeId) {
   const path = changeMetaPath(projectRoot, config, changeId);
   if (!await pathExists(path)) {
@@ -633,231 +524,9 @@ async function resolveChangeId(projectRoot, config, changeId) {
   }
   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-MIMBQVHE.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) };
-}
+
+// src/agent-handoff.ts
+import { join as join3 } from "pathe";
 function formatStatus(ctx) {
   const lines = [];
   lines.push(`Change: ${ctx.meta.title}`);
@@ -881,7 +550,9 @@ function formatStatus(ctx) {
     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}`);
+    lines.push(
+      `  [${mark}] ${stage.id}${stage.title ? ` \u2014 ${stage.title}` : ""}${gateInfo}${skipInfo}`
+    );
   }
   if (ctx.meta.overrides?.skip_stages?.length) {
     lines.push("");
@@ -900,7 +571,9 @@ async function buildAgentPrompt(ctx, config, projectRoot) {
   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(
+    `- Current stage: ${ctx.meta.stage}${stage?.title ? ` (${stage.title})` : ""}`
+  );
   parts.push(`- Change path: ${ctx.path}`);
   parts.push("");
   if (stage?.summary) {
@@ -921,6 +594,7 @@ async function buildAgentPrompt(ctx, config, projectRoot) {
   parts.push("");
   parts.push(`## Artifacts to read`);
   const memoryHint = join3(projectRoot, config.memory_path);
+  parts.push(`- Documentation map (if present): ${memoryHint}/index.md`);
   parts.push(`- Memory: ${memoryHint}/`);
   for (const s of ctx.stages) {
     for (const a of s.artifacts) {
@@ -935,64 +609,102 @@ async function buildAgentPrompt(ctx, config, projectRoot) {
     }
   }
   parts.push("");
-  parts.push(`When done with this stage, the human will run \`sdd next\` or \`sdd verify\` / \`sdd complete\`.`);
+  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"];
-var DEFAULT_INIT_INTEGRATION = "copilot";
-var AGENT_TARGET_OPTIONS = [
+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"
+    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,
-    installUrl: "https://docs.anthropic.com/en/docs/claude-code"
+    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`) |"
   }
 ];
+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 AGENT_TARGET_OPTIONS.find((o) => o.id === target)?.key ?? target;
+  return getIntegration(target).key;
 }
 function optionForTarget(target) {
-  return AGENT_TARGET_OPTIONS.find((o) => o.id === target);
+  return getIntegration(target);
+}
+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: copilot or claude (Claude Code).`
+    );
+  }
+  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().toLowerCase()).filter(Boolean);
+  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) {
-    if (p === "intellij" || p === "idea" || p === "jetbrains" || p === "vscode" || p === "vs-code" || p === "cursor") {
-      throw new Error(
-        `"${p}" is an IDE, not an AI coding agent. Choose: copilot or claude (Claude Code).`
-      );
-    }
-    const id = p === "claude" || p === "claude-code" || p === "claudecode" ? "claude-code" : p === "github-copilot" || p === "gh-copilot" || p === "copilot" ? "copilot" : p;
-    if (!ALL_AGENT_TARGETS.includes(id)) {
-      const keys = AGENT_TARGET_OPTIONS.map((o) => o.key).join(", ");
-      throw new Error(`Unknown AI coding agent "${p}". Choose from: ${keys}`);
-    }
+    const id = parseIntegration(p);
     if (!out.includes(id)) out.push(id);
   }
   return out;
 }
-function parseIntegration(raw) {
-  const list = parseAgentTargets(raw);
-  if (list.length !== 1) {
-    throw new Error(
-      `Expected one AI coding agent (like Speckit --integration), got: ${raw}`
-    );
-  }
-  return list[0];
-}
 var SDD_AGENT_ROLES = [
   {
     id: "sdd",
@@ -1032,13 +744,8 @@ var SDD_AGENT_ROLES = [
     ]
   }
 ];
-async function installAgentIntegrations(opts) {
-  if (!opts.targets?.length) {
-    throw new Error(
-      `Specify at least one AI coding agent: ${ALL_AGENT_TARGETS.join(", ")} (not an IDE; do not install all by default)`
-    );
-  }
-  const targets = opts.targets;
+async function installAgentIntegration(opts) {
+  const integ = getIntegration(opts.target);
   const created = [];
   const skipped = [];
   const root = opts.projectRoot;
@@ -1055,47 +762,48 @@ async function installAgentIntegrations(opts) {
   await write(join4(".sdd", "protocol.md"), PROTOCOL_MD);
   await refreshActiveAgentContext(root);
   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);
-    }
+    await write(integ.rolePath(role.id), renderThinAgent(role));
   }
-  await write("AGENTS.md", renderAgentsMd(targets));
+  await write("AGENTS.md", renderAgentsMd(integ));
   await write(
     join4(".sdd", "agents.json"),
     JSON.stringify(
       {
-        version: 2,
+        version: 3,
         mode: "agents-only",
         protocol: ".sdd/protocol.md",
         activeContext: ".sdd/active-context.md",
         roles: SDD_AGENT_ROLES.map((r) => r.id),
-        installed: targets,
-        /** Speckit-style primary integration key (first target). */
-        integration: targets[0] ? integrationKeyFor(targets[0]) : null,
+        /** Speckit-style public key */
+        ai: integ.key,
+        integration: integ.key,
+        installed: [integ.id],
         updated: (/* @__PURE__ */ new Date()).toISOString()
       },
       null,
       2
     ) + "\n"
   );
-  await write(
-    join4(".sdd", "init-options.json"),
-    JSON.stringify(
-      {
-        ai: targets[0] ? integrationKeyFor(targets[0]) : null,
-        integration: targets[0] ? integrationKeyFor(targets[0]) : null,
-        installed: targets.map(integrationKeyFor),
-        updated: (/* @__PURE__ */ new Date()).toISOString()
-      },
-      null,
-      2
-    ) + "\n"
-  );
-  return { created, skipped, targets };
+  return { created, skipped, 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) {
   const rules = role.roleRules.map((r) => `- ${r}`).join("\n");
@@ -1178,7 +886,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 |------|--------|
 | Process state | \`changes/<id>/meta.yaml\` (workflow, stage, gates) |
 | Current task snapshot | \`.sdd/active-context.md\` |
-| Stable product/tech rules | \`memory/*.md\` |
+| Stable product/tech rules | \`memory/*.md\` (start at \`memory/index.md\` if present) |
 | Stage artifacts | files in \`changes/<id>/\` for the active change |
 
 ## Required read order
@@ -1186,7 +894,7 @@ This repo uses **Structured Vibe Coding** (\`sdd\`). Agents must follow this fil
 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
+4. \`memory/index.md\` (documentation map) if present, then linked memory pages when architecture or conventions matter
 
 ## Stage behavior
 
@@ -1223,18 +931,7 @@ sdd complete
 - Deleting \`.sdd\` / archive history
 - Claiming complete without verify when required
 `;
-function renderAgentsMd(targets) {
-  const rows = [];
-  if (targets.includes("claude-code")) {
-    rows.push(
-      "| Claude Code | `.claude/agents/` (`sdd`, `sdd-planner`, `sdd-implementer`, `sdd-reviewer`) |"
-    );
-  }
-  if (targets.includes("copilot")) {
-    rows.push(
-      "| GitHub Copilot | `.github/agents/*.agent.md` (same roles; any IDE that supports Copilot agents) |"
-    );
-  }
+function renderAgentsMd(integ) {
   return `# Agents
 
 This repo uses **SDD agents only** (no skills).
@@ -1245,10 +942,11 @@ AI coding agents are **not** the same as IDEs: VS Code, Cursor, and IntelliJ hos
 |------------|--|
 | Live task | \`.sdd/active-context.md\` |
 | Playbook | \`.sdd/protocol.md\` |
+| Doc map (stable) | \`memory/index.md\` if present |
 
 | AI agent | Files |
 |----------|--------|
-${rows.join("\n")}
+${integ.agentsMdRow}
 
 Refresh context: \`sdd agents refresh\`.
 `;
@@ -1304,33 +1002,29 @@ export {
   nowIso,
   changeDirName,
   uniqueChangeDirName,
+  loadChangeMeta,
+  saveChangeMeta,
+  buildContext,
+  listChanges,
+  getActiveChangeId,
+  clearActiveIf,
+  setActiveChange,
+  resolveChangeId,
+  formatStatus,
+  buildAgentPrompt,
+  AGENT_INTEGRATIONS,
   ALL_AGENT_TARGETS,
   DEFAULT_INIT_INTEGRATION,
   AGENT_TARGET_OPTIONS,
+  getIntegration,
   integrationKeyFor,
   optionForTarget,
-  parseAgentTargets,
   parseIntegration,
+  parseAgentTargets,
   SDD_AGENT_ROLES,
+  installAgentIntegration,
   installAgentIntegrations,
   renderThinAgent,
   refreshActiveAgentContext,
-  PROTOCOL_MD,
-  createChange,
-  loadChangeMeta,
-  saveChangeMeta,
-  buildContext,
-  listChanges,
-  getActiveChangeId,
-  clearActiveIf,
-  setActiveChange,
-  resolveChangeId,
-  canLeaveStage,
-  advanceStage,
-  skipStage,
-  switchWorkflow,
-  approveGate,
-  completeChange,
-  formatStatus,
-  buildAgentPrompt
+  PROTOCOL_MD
 };