@structured-vibe-coding/core 0.20.0 → 0.22.0

package/dist/index.js

@@ -1,32 +1,11 @@
 import {
-  SDD_CORE_VERSION,
-  callMcpSourceTool,
   explainMatch,
   formatMcpContextForHandoff,
   gatherMcpContext,
   gatherMcpContextForChange,
   listMatchingSourceIds,
-  listMcpSourceTools,
-  matchMcpSources,
-  mcpTimeoutMs,
-  toProcessEnv,
-  withMcpSource
-} from "./chunk-EDXT3RTN.js";
-import {
-  McpConfigSchema,
-  McpInvokeSchema,
-  McpSourceSchema,
-  McpWhenSchema,
-  addMcpSource,
-  defaultMcpConfig,
-  ensureMcpConfig,
-  interpolate,
-  interpolateArgs,
-  loadMcpConfig,
-  mcpConfigPath,
-  removeMcpSource,
-  saveMcpConfig
-} from "./chunk-4BRO7BOJ.js";
+  matchMcpSources
+} from "./chunk-RXVTVLCJ.js";
 import {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
@@ -68,7 +47,7 @@ import {
   renderThinAgent,
   saveGeneratedManifest,
   writeAgentHandoff
-} from "./chunk-O4OQWVC7.js";
+} from "./chunk-WCYVBZC4.js";
 import {
   ChangeMetricsSchema,
   DecisionMetricSchema,
@@ -83,6 +62,8 @@ import {
   emptyChangeMetrics,
   fallbackIncompleteStageId,
   findFeaturesBacklogPath,
+  h2Title,
+  headingsFilled,
   importSessionMetrics,
   incompletePriorStageErrors,
   isSubstantiveArtifactContent,
@@ -100,7 +81,7 @@ import {
   switchWorkflow,
   transitionPhase,
   updateFeatureStatus
-} from "./chunk-NY5FFWXG.js";
+} from "./chunk-XHNO536D.js";
 import {
   EMBEDDINGS_UNAVAILABLE,
   EMBEDDING_MODEL,
@@ -164,6 +145,7 @@ import {
   memoryDir as memoryDir2,
   mergeConfigDefaults,
   mergeRankedHits,
+  openMcpSearchProvider,
   packHits,
   parseRoleDocument,
   pinRole,
@@ -188,9 +170,10 @@ import {
   searchProject,
   showRoles,
   showTeam,
+  splitFrontmatter,
   workKind,
   writePackedCache
-} from "./chunk-HUSXETPS.js";
+} from "./chunk-QE6RMJUS.js";
 import {
   ArtifactDefSchema,
   ChangeMetaSchema,
@@ -236,10 +219,31 @@ import {
   workflowUnavailableMessage
 } from "./chunk-TNWFMRIA.js";
 import {
+  SDD_CORE_VERSION,
   SddError,
+  callMcpSourceTool,
   errorMessage,
-  isSddError
-} from "./chunk-MHODNFIL.js";
+  isSddError,
+  listMcpSourceTools,
+  mcpTimeoutMs,
+  toProcessEnv,
+  withMcpSource
+} from "./chunk-47GWMUCR.js";
+import {
+  McpConfigSchema,
+  McpInvokeSchema,
+  McpSourceSchema,
+  McpWhenSchema,
+  addMcpSource,
+  defaultMcpConfig,
+  ensureMcpConfig,
+  interpolate,
+  interpolateArgs,
+  loadMcpConfig,
+  mcpConfigPath,
+  removeMcpSource,
+  saveMcpConfig
+} from "./chunk-4BRO7BOJ.js";
 import {
   SDD_DIR,
   activePointerPath,
@@ -1395,7 +1399,7 @@ ${output}`);
     status = failed.length ? "fail" : "pass";
     reason = failed.length ? `failed: ${failed.join(", ")}` : void 0;
   }
-  const ok10 = status === "pass";
+  const ok12 = status === "pass";
   const checklist = stage.gate?.checklist ?? [];
   const lines = buildSummaryLines(
     ctx.meta.title,
@@ -1446,7 +1450,7 @@ ${output}`);
   ctx.meta.verify_results = {
     ...ctx.meta.verify_results,
     [stage.id]: {
-      ok: ok10,
+      ok: ok12,
       status,
       ...results.length && headSha2 ? { head_sha: headSha2 } : {},
       at: nowIso(),
@@ -1462,7 +1466,7 @@ ${output}`);
     checklist,
     evidencePath: evidenceDir,
     resultsPath: summaryPath,
-    ok: ok10
+    ok: ok12
   };
 }
 
@@ -1875,10 +1879,10 @@ function formatMarkdown(input) {
 `;
   return { markdown: packed ? frame + packed : frame, truncated: input.summary.truncated };
 }
-function formatJsonSummary(summary, gaps, slices, ok10) {
+function formatJsonSummary(summary, gaps, slices, ok12) {
   return JSON.stringify(
     {
-      ok: ok10,
+      ok: ok12,
       summary,
       gaps,
       slices: slices.map((s) => ({
@@ -3562,6 +3566,43 @@ function revisionPrompt(role, draft, gaps) {
     "changed must list every gap cite."
   ].join("\n");
 }
+function guideDraftPrompt(input) {
+  const rows = [`Job: ${input.role.job}`, `Description: ${input.role.description}`];
+  if (input.role.stages.length > 0) rows.push(`Stages: ${input.role.stages.join(", ")}`);
+  if (input.role.owns.length > 0) rows.push(`Owns: ${input.role.owns.join(", ")}`);
+  if (input.role.skills.length > 0) rows.push(`Skills: ${input.role.skills.join(", ")}`);
+  if (input.role.never.length > 0) rows.push(`Never: ${input.role.never.join(", ")}`);
+  if (input.role.askHumanWhen.length > 0) {
+    rows.push(`Ask when: ${input.role.askHumanWhen.join(", ")}`);
+  }
+  if (rows.length > 2) rows.push("Stay inside this role.");
+  rows.push(`Request: ${input.request}`);
+  if (input.answers.length > 0) {
+    rows.push("Answers:");
+    for (const item of input.answers) rows.push(`- ${item.question}: ${item.answer}`);
+  }
+  rows.push(`Stage: ${input.stageId}`);
+  if (input.summary.trim()) rows.push(`Summary: ${input.summary.trim()}`);
+  if (input.instructions.trim()) rows.push(`Instructions:
+${input.instructions.trim()}`);
+  rows.push(`Artifact: ${input.artifactPath}`);
+  if (input.headings.length > 0) {
+    rows.push("Headings:");
+    for (const heading of input.headings) rows.push(`- ${heading}`);
+  }
+  if (input.earlier.length > 0) {
+    rows.push("Earlier:");
+    for (const file of input.earlier) rows.push(`## ${file.path}`, file.body.trim());
+  }
+  rows.push('If one fact is missing, reply with JSON {"text":"Question: ..."}');
+  rows.push('Otherwise reply with JSON {"text":"...","parts":[{"heading":"...","text":"..."}]}');
+  rows.push("Use only the headings listed above.");
+  rows.push("Put this artifact's words under those headings.");
+  rows.push("Do not rename a heading.");
+  rows.push("Do not paste an earlier artifact.");
+  rows.push("Do not name a module, a path, or a command result that is not in this prompt.");
+  return rows.join("\n");
+}
 
 // src/team/tools.ts
 import { spawn as spawn4 } from "child_process";
@@ -3608,8 +3649,8 @@ function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return value;
 }
-function result(name, ok10, text2) {
-  return { ok: ok10, name, text: clip(text2) };
+function result(name, ok12, text2) {
+  return { ok: ok12, name, text: clip(text2) };
 }
 async function git(cwd, args) {
   return new Promise((resolve) => {
@@ -6139,6 +6180,176 @@ async function pickLead(root, all, services) {
   return { kind: "none" };
 }
 
+// src/role/connector.ts
+import { spawn as spawn5 } from "child_process";
+var X_LINE = "A connector cannot read or post on X.";
+var NOT_IN_SLICE = "That connector is not in this slice.";
+var DOES_NOT_RUN = "That connector action does not run in this slice.";
+var BAD_NUMBER = "A GitHub issue number is a positive integer.";
+var QA_LINE = "A routine cannot write a QA result.";
+var BAD_ROUTINES = "Routines on this role are invalid.";
+var NO_ROUTINE = "That routine is not on this role.";
+var READ_FIELDS = /* @__PURE__ */ new Set(["name", "read", "record"]);
+function ok9(stdout) {
+  return { exitCode: 0, stdout };
+}
+function fail9(stdout) {
+  return { exitCode: 1, stdout };
+}
+function positiveInteger(record) {
+  if (!/^[1-9][0-9]*$/.test(record)) return null;
+  const number = Number(record);
+  if (!Number.isSafeInteger(number)) return null;
+  return number;
+}
+function missingLine(number) {
+  return `GitHub issue ${number} was not found.`;
+}
+function unreadLine(number) {
+  return `GitHub issue ${number} could not be read.`;
+}
+function cleanLine(value) {
+  if (typeof value !== "string") return null;
+  const text2 = value.trim();
+  if (!text2 || text2.includes("\n") || text2.includes("\r")) return null;
+  return text2;
+}
+function ghIssueSource() {
+  return {
+    async read(number) {
+      const run = await spawnGh(number);
+      if (!run.ok) return { ok: false, missing: run.missing };
+      let parsed;
+      try {
+        parsed = JSON.parse(run.stdout);
+      } catch {
+        return { ok: false, missing: false };
+      }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, missing: false };
+      }
+      const rec = parsed;
+      const title = cleanLine(rec.title);
+      const state = cleanLine(rec.state);
+      const found = typeof rec.number === "number" ? rec.number : Number(rec.number);
+      if (found !== number || !title || !state) return { ok: false, missing: false };
+      return { ok: true, issue: { number, title, state } };
+    }
+  };
+}
+function spawnGh(number) {
+  return new Promise((resolve) => {
+    const child = spawn5("gh", ["issue", "view", String(number), "--json", "number,title,state"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const out = [];
+    const err = [];
+    child.stdout?.on("data", (chunk) => out.push(chunk));
+    child.stderr?.on("data", (chunk) => err.push(chunk));
+    child.on("error", () => resolve({ ok: false, missing: false }));
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(out).toString("utf8");
+      const stderr = Buffer.concat(err).toString("utf8");
+      if (code === 0) {
+        resolve({ ok: true, stdout });
+        return;
+      }
+      const text2 = `${stdout}
+${stderr}`.toLowerCase();
+      resolve({
+        ok: false,
+        missing: text2.includes("could not resolve") || text2.includes("not found")
+      });
+    });
+  });
+}
+function threeLines(issue) {
+  return `${issue.number}
+${issue.title}
+${issue.state}`;
+}
+async function readConnector(input) {
+  const verb = input.verb.trim();
+  const connector = input.connector.trim();
+  const record = input.record.trim();
+  if (connector === "x") return fail9(X_LINE);
+  if (verb !== "read") return fail9(DOES_NOT_RUN);
+  if (connector !== "github-issue") return fail9(NOT_IN_SLICE);
+  const number = positiveInteger(record);
+  if (number === null) return fail9(BAD_NUMBER);
+  const source = input.source ?? ghIssueSource();
+  let read;
+  try {
+    read = await source.read(number);
+  } catch {
+    return fail9(unreadLine(number));
+  }
+  if (!read.ok) return fail9(read.missing ? missingLine(number) : unreadLine(number));
+  if (read.issue.number !== number) return fail9(unreadLine(number));
+  const title = cleanLine(read.issue.title);
+  const state = cleanLine(read.issue.state);
+  if (!title || !state) return fail9(unreadLine(number));
+  return ok9(threeLines({ number, title, state }));
+}
+function classifyRoutines(value) {
+  if (!Array.isArray(value)) return { ok: false, reason: "invalid" };
+  for (const item of value) {
+    if (item && typeof item === "object" && !Array.isArray(item) && Object.hasOwn(item, "write")) {
+      return { ok: false, reason: "qa" };
+    }
+  }
+  const items = [];
+  const names = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      return { ok: false, reason: "invalid" };
+    }
+    const rec = item;
+    const keys = Object.keys(rec);
+    if (keys.length !== 3 || keys.some((key) => !READ_FIELDS.has(key))) {
+      return { ok: false, reason: "invalid" };
+    }
+    const name = rec.name;
+    const read = rec.read;
+    const record = rec.record;
+    if (typeof name !== "string" || typeof read !== "string" || typeof record !== "string") {
+      return { ok: false, reason: "invalid" };
+    }
+    const trimmed = { name: name.trim(), read: read.trim(), record: record.trim() };
+    if (!trimmed.name || !trimmed.read || !trimmed.record || names.has(trimmed.name)) {
+      return { ok: false, reason: "invalid" };
+    }
+    names.add(trimmed.name);
+    items.push(trimmed);
+  }
+  return { ok: true, items };
+}
+async function runRoutine(root, roleName, routineName, source) {
+  const name = canonicalRoleName(roleName);
+  if (!name) return fail9(ROLE_TEXT.notFound);
+  const path = roleFilePath(root, name);
+  if (!await pathExists(path)) return fail9(ROLE_TEXT.notFound);
+  let raw = "";
+  try {
+    raw = await readText(path);
+  } catch {
+    return fail9(ROLE_TEXT.notFound);
+  }
+  const split = splitFrontmatter(raw);
+  if (!split || !Object.hasOwn(split.data, "routines")) return fail9(NO_ROUTINE);
+  const classified = classifyRoutines(split.data.routines);
+  if (!classified.ok) return fail9(classified.reason === "qa" ? QA_LINE : BAD_ROUTINES);
+  const routine = classified.items.find((item) => item.name === routineName.trim());
+  if (!routine) return fail9(NO_ROUTINE);
+  if (routine.read === "x") return fail9(X_LINE);
+  return readConnector({
+    verb: "read",
+    connector: routine.read,
+    record: routine.record,
+    source
+  });
+}
+
 // src/role/guide.ts
 import { join as join18 } from "pathe";
 var PLANNING = /* @__PURE__ */ new Set([
@@ -6205,10 +6416,10 @@ var DUTIES = [
     description: "The builder builds the change. The person decides."
   }
 ];
-function ok9(stdout) {
+function ok10(stdout) {
   return { exitCode: 0, stdout };
 }
-function fail9(stdout) {
+function fail10(stdout) {
   return { exitCode: 1, stdout };
 }
 function statePath(root) {
@@ -6293,15 +6504,6 @@ function nextRoleQuestion(role, answers) {
   );
   return role.askHumanWhen.find((item) => !answered.has(item));
 }
-function taskFor(request, role, answers) {
-  const rows = [`Request: ${request}`];
-  const mine = answers.filter((item) => item.role === role);
-  if (mine.length > 0) {
-    rows.push("Answers:");
-    for (const item of mine) rows.push(`- ${item.question}: ${item.answer}`);
-  }
-  return rows.join("\n");
-}
 async function roleFiles(root) {
   const names = await listFiles(join18(root, ".sdd", "roles"));
   return names.filter((name) => name.endsWith(".md"));
@@ -6333,35 +6535,218 @@ async function prepareGuide(root, input = {}) {
       }
     }
     lines.push('Next: sdd go "what you want to build"');
-    return ok9(lines.join("\n"));
+    return ok10(lines.join("\n"));
   } catch (error) {
-    return fail9(error instanceof Error ? error.message : String(error));
+    return fail10(error instanceof Error ? error.message : String(error));
   }
 }
-async function writeDraft(ctxPath, stage, role, text2, request) {
-  const body = [
+function partText(text2) {
+  return text2.split(/\r?\n/).filter((line) => h2Title(line) === null).join("\n").trim();
+}
+function draftHeader(stage, role) {
+  return [
     `# ${stage.title ?? stage.id}`,
     "",
     `${role} drafted this stage. The person has not signed it.`,
-    "",
-    text2.trim(),
-    "",
-    `Request: ${request}`,
     ""
-  ].join("\n");
-  for (const artifact of stage.artifacts) {
-    if (!artifact.required) continue;
-    const abs = join18(ctxPath, artifact.path);
-    if (await pathExists(abs)) {
-      const current = await readText(abs);
-      if (isSubstantiveArtifactContent(current)) continue;
+  ];
+}
+function plainBody(stage, role, request, text2) {
+  return [...draftHeader(stage, role), text2.trim(), "", `Request: ${request}`, ""].join("\n");
+}
+function headedBody(stage, role, request, headings, parts) {
+  const matched = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    const heading = part.heading.trim();
+    const text2 = partText(part.text);
+    if (!headings.includes(heading) || !text2) continue;
+    const list = matched.get(heading) ?? [];
+    list.push(text2);
+    matched.set(heading, list);
+  }
+  const rows = draftHeader(stage, role);
+  for (const heading of headings) {
+    rows.push(`## ${heading}`, "", (matched.get(heading) ?? []).join("\n\n"), "");
+  }
+  rows.push(`Request: ${request}`, "");
+  return rows.join("\n");
+}
+var RESULTS_LINES = {
+  Results: "No command output is stored for this change.",
+  "Commands run": "This guide did not run a verify command.",
+  "Sign-off": "The person has not signed it."
+};
+function resultsBody(stage, role, request, headings) {
+  if (headings.length === 0) {
+    return plainBody(stage, role, request, Object.values(RESULTS_LINES).join(" "));
+  }
+  return headedBody(
+    stage,
+    role,
+    request,
+    headings,
+    headings.map((heading) => ({
+      heading,
+      text: RESULTS_LINES[heading] ?? RESULTS_LINES.Results
+    }))
+  );
+}
+function parseGuideReply(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const rec = value;
+  if (typeof rec.text !== "string") return null;
+  if (rec.parts === void 0) return { text: rec.text, parts: [] };
+  if (!Array.isArray(rec.parts)) return null;
+  const parts = [];
+  for (const part of rec.parts) {
+    if (!part || typeof part !== "object" || Array.isArray(part)) return null;
+    const item = part;
+    if (typeof item.heading !== "string" || typeof item.text !== "string") return null;
+    parts.push({ heading: item.heading, text: item.text });
+  }
+  return { text: rec.text, parts };
+}
+function missingHeading(content, headings) {
+  for (const heading of headings) {
+    if (!headingsFilled(content, [heading])) return heading;
+  }
+  return null;
+}
+function isResultsFile(path) {
+  const name = path.replace(/\\/g, "/");
+  return name === "local-test-results.md" || name.endsWith("/local-test-results.md");
+}
+async function templateHeadings(root, template) {
+  const name = template?.trim();
+  if (!name) return [];
+  const path = join18(templatesDir(root), name.replace(/^templates\//, ""));
+  if (!await pathExists(path)) return [];
+  const headings = [];
+  for (const line of (await readText(path)).split(/\r?\n/)) {
+    const title = h2Title(line);
+    if (title) headings.push(title);
+  }
+  return headings;
+}
+async function artifactReady(abs, headings) {
+  if (!await pathExists(abs)) return false;
+  const current = await readText(abs);
+  if (!isSubstantiveArtifactContent(current)) return false;
+  return headings.length === 0 || headingsFilled(current, headings);
+}
+async function readyArtifacts(changeDir, stages, currentPath) {
+  const files = [];
+  for (const stage of stages) {
+    for (const artifact of stage.artifacts) {
+      if (artifact.required === false || artifact.path === currentPath) continue;
+      const abs = join18(changeDir, artifact.path);
+      if (!await pathExists(abs)) continue;
+      const body = await readText(abs);
+      if (!isSubstantiveArtifactContent(body)) continue;
+      files.push({ path: artifact.path, body });
     }
-    await writeText(abs, body);
   }
+  return files;
+}
+async function writeOne(abs, body) {
+  await ensureDir(join18(abs, ".."));
+  await writeText(abs, body);
 }
 function optionalStage(stage) {
   return stage.optional || stage.kind === "clarify" || stage.kind === "brainstorm";
 }
+async function leaveStage(root, config, changeId, stageId, roleName, drafted, lines, state) {
+  const note = drafted ? `${roleName} drafted ${stageId}.` : `${roleName} left ${stageId}.`;
+  try {
+    const advanced = await advanceStage(root, config, changeId);
+    lines.push(note);
+    if (!advanced.to) {
+      await writeState(root, state);
+      return ok10(
+        [
+          "Done.",
+          ...lines,
+          "No further stages. Run `sdd complete` when ready.",
+          "The person has not signed this change."
+        ].join("\n")
+      );
+    }
+    return "next";
+  } catch (error) {
+    await writeState(root, state);
+    const message = error instanceof Error ? error.message : String(error);
+    return ok10(["Stopped.", note, message, ...lines].join("\n"));
+  }
+}
+async function draftStage(root, config, ctx, state, stage, role, required, input, lines) {
+  if (required.length === 0) {
+    return leaveStage(root, config, ctx.id, stage.id, role.name, false, lines, state);
+  }
+  const answers = state.answers.filter((item) => item.role === role.name);
+  for (const artifact of required) {
+    const headings = await templateHeadings(root, artifact.template);
+    const abs = join18(ctx.path, artifact.path);
+    if (await artifactReady(abs, headings)) continue;
+    if (isResultsFile(artifact.path)) {
+      await writeOne(abs, resultsBody(stage, role.name, state.request, headings));
+      continue;
+    }
+    if (!input.model) return fail10(ROLE_TEXT.noModel);
+    let raw = "";
+    try {
+      raw = await input.model.complete({
+        roleId: role.name,
+        prompt: guideDraftPrompt({
+          role,
+          request: state.request,
+          answers,
+          stageId: stage.id,
+          summary: stage.summary ?? "",
+          instructions: stage.agent_context?.instructions ?? "",
+          artifactPath: artifact.path,
+          headings,
+          earlier: await readyArtifacts(ctx.path, ctx.workflow.stages, artifact.path)
+        })
+      });
+    } catch {
+      return fail10("A draft is not valid.");
+    }
+    const parsed = parseGuideReply(raw);
+    if (!parsed) return fail10("A draft is not valid.");
+    const asked = parsed.text.trim();
+    if (asked.startsWith("Question:")) {
+      state.pending = {
+        role: role.name,
+        kind: "model",
+        question: asked.replace(/^Question:\s*/, "").trim() || asked
+      };
+      await writeState(root, state);
+      return ok10(
+        [
+          "Question:",
+          ...lines,
+          `${role.name} asks:`,
+          state.pending.question,
+          'Answer with: sdd go --answer "..."'
+        ].join("\n")
+      );
+    }
+    const body = headings.length > 0 ? headedBody(stage, role.name, state.request, headings, parsed.parts) : plainBody(stage, role.name, state.request, parsed.text);
+    const missing = headings.length > 0 ? missingHeading(body, headings) : null;
+    if (missing) {
+      await writeState(root, state);
+      return ok10(["Stopped.", `${missing} is still empty.`, ...lines].join("\n"));
+    }
+    await writeOne(abs, body);
+  }
+  return leaveStage(root, config, ctx.id, stage.id, role.name, true, lines, state);
+}
 async function runGuide(root, input = {}) {
   const prepared = await prepareGuide(root, {
     workflow: input.workflow,
@@ -6370,14 +6755,14 @@ async function runGuide(root, input = {}) {
   if (prepared.exitCode !== 0) return prepared;
   const title = input.title?.trim() ?? "";
   const answer = input.answer?.trim() ?? "";
-  if (input.answer !== void 0 && !answer) return fail9("An answer needs text.");
+  if (input.answer !== void 0 && !answer) return fail10("An answer needs text.");
   let loaded;
   try {
     loaded = await readState(root);
   } catch (error) {
-    return fail9(error instanceof Error ? error.message : String(error));
+    return fail10(error instanceof Error ? error.message : String(error));
   }
-  if (loaded === "invalid") return fail9("The guide file is invalid.");
+  if (loaded === "invalid") return fail10("The guide file is invalid.");
   const config = await loadConfig(root);
   let state = loaded;
   if (title) {
@@ -6391,7 +6776,7 @@ async function runGuide(root, input = {}) {
       state = { change: ctx.id, request: title, answers: [] };
       await writeState(root, state);
     } catch (error) {
-      return fail9(error instanceof Error ? error.message : String(error));
+      return fail10(error instanceof Error ? error.message : String(error));
     }
   } else if (!state) {
     const active = await getActiveChangeId(root, config);
@@ -6400,10 +6785,10 @@ async function runGuide(root, input = {}) {
       const ctx = await buildContext(root, config, active);
       state = { change: active, request: ctx.meta.title, answers: [] };
     } catch (error) {
-      return fail9(error instanceof Error ? error.message : String(error));
+      return fail10(error instanceof Error ? error.message : String(error));
     }
   }
-  if (answer && !state.pending) return fail9("No question is waiting.");
+  if (answer && !state.pending) return fail10("No question is waiting.");
   if (answer && state.pending) {
     state.answers.push({
       role: state.pending.role,
@@ -6413,7 +6798,7 @@ async function runGuide(root, input = {}) {
     state.pending = void 0;
     await writeState(root, state);
   } else if (state.pending) {
-    return ok9(questionText(state.pending.role, state.pending.question));
+    return ok10(questionText(state.pending.role, state.pending.question));
   }
   const lines = [];
   let lastRole = "";
@@ -6422,35 +6807,35 @@ async function runGuide(root, input = {}) {
     try {
       ctx = await buildContext(root, config, state.change);
     } catch (error) {
-      return fail9(error instanceof Error ? error.message : String(error));
+      return fail10(error instanceof Error ? error.message : String(error));
     }
     const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
-    if (!stage) return fail9("No active change.");
+    if (!stage) return fail10("No active change.");
     if (optionalStage(stage) && stage.skippable) {
       const before = ctx.meta.stage;
       try {
         await skipStage(root, config, ctx.id, stage.id, "No role runs this optional stage.");
       } catch (error) {
-        return fail9(error instanceof Error ? error.message : String(error));
+        return fail10(error instanceof Error ? error.message : String(error));
       }
       const after = await buildContext(root, config, state.change);
-      if (after.meta.stage === before) return fail9("This stage stayed put.");
+      if (after.meta.stage === before) return fail10("This stage stayed put.");
       lines.push(`Skipped ${stage.id}.`);
       continue;
     }
     const routed = await matchRoute(root, { stage: stage.id });
-    if (!routed.ok) return fail9(routed.message);
+    if (!routed.ok) return fail10(routed.message);
     if (routed.match.kind === "ask") {
-      return ok9(["Stopped.", "Ask the human.", routed.match.reason, ...lines].join("\n"));
+      return ok10(["Stopped.", "Ask the human.", routed.match.reason, ...lines].join("\n"));
     }
     const role = await readRole(root, routed.match.role);
-    if (!role) return fail9(ROLE_TEXT.notFound);
+    if (!role) return fail10(ROLE_TEXT.notFound);
     if (lastRole && lastRole !== role.name) lines.push(`Handoff: ${lastRole} to ${role.name}.`);
     const question = nextRoleQuestion(role, state.answers);
     if (question) {
       state.pending = { role: role.name, kind: "role", question };
       await writeState(root, state);
-      return ok9(
+      return ok10(
         [
           "Question:",
           ...lines,
@@ -6460,55 +6845,136 @@ async function runGuide(root, input = {}) {
         ].join("\n")
       );
     }
-    if (!input.model) return fail9(ROLE_TEXT.noModel);
-    const ran = await runRole(root, {
-      name: role.name,
-      task: taskFor(state.request, role.name, state.answers),
-      guide: { changeDir: ctx.displayPath },
-      model: input.model,
-      now: input.now
-    });
-    if (ran.exitCode !== 0) {
-      return fail9([ran.stdout, ...lines].filter((line) => line.length > 0).join("\n"));
+    const required = stage.artifacts.filter((artifact) => artifact.required !== false);
+    const moved = await draftStage(root, config, ctx, state, stage, role, required, input, lines);
+    if (moved !== "next") return moved;
+    lastRole = role.name;
+  }
+  return fail10("The guide stopped after 16 steps.");
+}
+
+// src/role/setup-tour.ts
+import { join as join19 } from "pathe";
+var SETUP_STEP_IDS = [
+  "folder",
+  "workflow",
+  "host",
+  "roles",
+  "model",
+  "check",
+  "start"
+];
+var SETUP_WHY = {
+  folder: "sdd reads .sdd/config.yaml first.",
+  workflow: "Stage lists on new role files come from this workflow.",
+  host: "A host is optional. Drafts use a role model, not the host.",
+  roles: "These files say who drafts each stage. Existing files stay.",
+  model: "A draft needs SDD_ROLE_MODEL. Setup does not write that command into the repo.",
+  check: "This is what is already in place.",
+  start: "The first change is optional. sdd go asks the role for that stage."
+};
+function ok11(stdout) {
+  return { exitCode: 0, stdout };
+}
+function fail11(stdout) {
+  return { exitCode: 1, stdout };
+}
+function parseSetupStep(raw) {
+  const id = raw.trim();
+  return SETUP_STEP_IDS.includes(id) ? id : null;
+}
+function formatSetupStatus(status) {
+  const folder = status.folder ? "Folder: ready." : "Folder: not set up.";
+  const host = status.host ? `Host: ${status.host}.` : "Host: none.";
+  const roles = status.roles.length > 0 ? `Roles: ${status.roles.join(", ")}.` : "Roles: none.";
+  const model = status.model === "configured" ? "Model: configured." : status.model === "missing" ? "Model: No role model is configured." : `Model: ${status.model.error}`;
+  return [folder, host, roles, model].join("\n");
+}
+async function roleNames(root) {
+  const names = await listFiles(join19(root, ".sdd", "roles"));
+  return names.filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -".md".length)).sort((left, right) => left.localeCompare(right));
+}
+async function modelState(root, env) {
+  if (modelFromEnv(env)) return "configured";
+  const loaded = await loadModels(root);
+  if (loaded === null) return "missing";
+  if ("error" in loaded) return { error: loaded.error };
+  return "configured";
+}
+async function readSetupStatus(root, env = process.env) {
+  const installed = await loadInstalledAgent(root);
+  return {
+    folder: await isInitialized(root),
+    host: installed?.ai ?? null,
+    roles: await roleNames(root),
+    model: await modelState(root, env)
+  };
+}
+function withRoleHints(result2) {
+  if (result2.exitCode !== 0) return result2;
+  const hints = [
+    "Add stages with sdd role edit <name> --stages ...",
+    'Add context with sdd role context <name> --text "..."'
+  ];
+  const body = result2.stdout.trim();
+  return ok11(body.length > 0 ? `${body}
+${hints.join("\n")}` : hints.join("\n"));
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runSetupStep(root, input, env = process.env) {
+  const workflow = input.workflow?.trim() || "feature";
+  try {
+    if (input.step === "folder") {
+      if (!await isInitialized(root)) {
+        await initProject({ projectRoot: root, agents: false });
+      }
+      return ok11("Folder: ready.");
+    }
+    if (input.step === "workflow") {
+      const lines = [`Workflow: ${workflow}.`];
+      if ((await roleNames(root)).length > 0) lines.push("Roles are already here.");
+      return ok11(lines.join("\n"));
+    }
+    if (input.step === "host") {
+      const installed = await loadInstalledAgent(root);
+      if (installed) return ok11(`Host: ${installed.ai}.`);
+      if (!input.host) return ok11("Host: none.");
+      if (!await isInitialized(root)) {
+        await initProject({ projectRoot: root, agents: input.host });
+      } else {
+        await installAgentIntegration({ projectRoot: root, target: input.host });
+      }
+      const after = await loadInstalledAgent(root);
+      return ok11(`Host: ${after?.ai ?? input.host}.`);
+    }
+    if (input.step === "roles") {
+      const choice = input.roles ?? "duties";
+      if (choice === "keep") {
+        const names = await roleNames(root);
+        const line = names.length > 0 ? "Roles are already here." : "Roles: none.";
+        return withRoleHints(ok11(line));
+      }
+      if (choice === "software") {
+        return withRoleHints(await initTeam(root, "software", gitUserName(root)));
+      }
+      return withRoleHints(await prepareGuide(root, { workflow, agents: false }));
     }
-    const text2 = ran.stdout.trim();
-    if (text2.startsWith("Question:")) {
-      const asked = text2.replace(/^Question:\s*/, "").trim();
-      state.pending = { role: role.name, kind: "model", question: asked || text2 };
-      await writeState(root, state);
-      return ok9(
-        [
-          "Question:",
-          ...lines,
-          `${role.name} asks:`,
-          state.pending.question,
-          'Answer with: sdd go --answer "..."'
-        ].join("\n")
-      );
+    if (input.step === "model") {
+      const state = await modelState(root, env);
+      if (state === "configured") return ok11("Model: configured.");
+      if (typeof state === "object") return fail11(state.error);
+      if (input.requireModel) return fail11("No role model is configured.");
+      return ok11("No role model is configured.");
     }
-    await writeDraft(ctx.path, stage, role.name, text2, state.request);
-    try {
-      const advanced = await advanceStage(root, config, ctx.id);
-      lines.push(`${role.name} drafted ${stage.id}.`);
-      lastRole = role.name;
-      if (!advanced.to) {
-        await writeState(root, state);
-        return ok9(
-          [
-            "Done.",
-            ...lines,
-            "No further stages. Run `sdd complete` when ready.",
-            "The person has not signed this change."
-          ].join("\n")
-        );
-      }
-    } catch (error) {
-      await writeState(root, state);
-      const message = error instanceof Error ? error.message : String(error);
-      return ok9(["Stopped.", `${role.name} drafted ${stage.id}.`, message, ...lines].join("\n"));
+    if (input.step === "check") {
+      return ok11(formatSetupStatus(await readSetupStatus(root, env)));
     }
+    return ok11('Next: sdd go "what you want to build"');
+  } catch (error) {
+    return fail11(messageOf(error));
   }
-  return fail9("The guide stopped after 16 steps.");
 }
 
 // src/role/models/show.ts
@@ -6549,7 +7015,7 @@ function explainModel(config, workType, ctx) {
 }
 
 // src/stories.ts
-import { join as join19 } from "pathe";
+import { join as join20 } from "pathe";
 var STORY_ID = /^S-\d+$/i;
 var EPIC_KEY = /^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/;
 function validBranchName(name) {
@@ -6591,7 +7057,7 @@ function parseStoryDraft(input) {
 async function metasIn(dir) {
   const out = [];
   for (const id of await listDirs(dir)) {
-    const path = join19(dir, id, "meta.yaml");
+    const path = join20(dir, id, "meta.yaml");
     if (!await pathExists(path)) continue;
     try {
       out.push(ChangeMetaSchema.parse(await readYaml(path)));
@@ -6739,6 +7205,8 @@ export {
   SDD_AGENT_ROLES,
   SDD_CORE_VERSION,
   SDD_DIR,
+  SETUP_STEP_IDS,
+  SETUP_WHY,
   SUMMARY_TOKEN_CAP,
   SddError,
   SearchConfigError,
@@ -6834,6 +7302,7 @@ export {
   formatJsonSummary,
   formatMcpContextForHandoff,
   formatModels,
+  formatSetupStatus,
   formatStatus,
   formatTeam,
   formatTokenInventory,
@@ -6849,6 +7318,7 @@ export {
   getHeadSha,
   getIntegration,
   getStage,
+  ghIssueSource,
   gitUserName,
   guidancePaths,
   handoffRole,
@@ -6913,11 +7383,13 @@ export {
   modelFromEnv,
   nextStageId,
   nowIso,
+  openMcpSearchProvider,
   optionForTarget,
   packHits,
   parseAgentTargets,
   parseFeaturesBacklog,
   parseIntegration,
+  parseSetupStep,
   parseStoryDraft,
   pathExists,
   phaseTiming,
@@ -6931,7 +7403,9 @@ export {
   queueRole,
   rankScope,
   readChangeMetrics,
+  readConnector,
   readHandoffCodePoints,
+  readSetupStatus,
   readTeamConfig,
   readText,
   readYaml,
@@ -6975,6 +7449,8 @@ export {
   runLoop,
   runNetwork,
   runRole,
+  runRoutine,
+  runSetupStep,
   saveChangeMeta,
   saveConfig,
   saveGeneratedManifest,