@structured-vibe-coding/core 0.19.0 → 0.20.0

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   mcpTimeoutMs,
   toProcessEnv,
   withMcpSource
-} from "./chunk-H55RFAEI.js";
+} from "./chunk-EDXT3RTN.js";
 import {
   McpConfigSchema,
   McpInvokeSchema,
@@ -68,7 +68,7 @@ import {
   renderThinAgent,
   saveGeneratedManifest,
   writeAgentHandoff
-} from "./chunk-26YG6A4M.js";
+} from "./chunk-O4OQWVC7.js";
 import {
   ChangeMetricsSchema,
   DecisionMetricSchema,
@@ -100,7 +100,7 @@ import {
   switchWorkflow,
   transitionPhase,
   updateFeatureStatus
-} from "./chunk-2FJBFYVJ.js";
+} from "./chunk-NY5FFWXG.js";
 import {
   EMBEDDINGS_UNAVAILABLE,
   EMBEDDING_MODEL,
@@ -178,7 +178,9 @@ import {
   resolveBot,
   resolveEmbedder,
   resolveSearchProvider,
+  roleContextDir,
   roleFilePath,
+  rolesListingStage,
   rrf,
   saveConfig,
   scopeForPath,
@@ -188,7 +190,7 @@ import {
   showTeam,
   workKind,
   writePackedCache
-} from "./chunk-TGRV6WGS.js";
+} from "./chunk-HUSXETPS.js";
 import {
   ArtifactDefSchema,
   ChangeMetaSchema,
@@ -232,7 +234,7 @@ import {
   todayIsoDate,
   uniqueChangeDirName,
   workflowUnavailableMessage
-} from "./chunk-HG7TPW5V.js";
+} from "./chunk-TNWFMRIA.js";
 import {
   SddError,
   errorMessage,
@@ -1393,7 +1395,7 @@ ${output}`);
     status = failed.length ? "fail" : "pass";
     reason = failed.length ? `failed: ${failed.join(", ")}` : void 0;
   }
-  const ok8 = status === "pass";
+  const ok10 = status === "pass";
   const checklist = stage.gate?.checklist ?? [];
   const lines = buildSummaryLines(
     ctx.meta.title,
@@ -1444,7 +1446,7 @@ ${output}`);
   ctx.meta.verify_results = {
     ...ctx.meta.verify_results,
     [stage.id]: {
-      ok: ok8,
+      ok: ok10,
       status,
       ...results.length && headSha2 ? { head_sha: headSha2 } : {},
       at: nowIso(),
@@ -1460,7 +1462,7 @@ ${output}`);
     checklist,
     evidencePath: evidenceDir,
     resultsPath: summaryPath,
-    ok: ok8
+    ok: ok10
   };
 }
 
@@ -1873,10 +1875,10 @@ function formatMarkdown(input) {
 `;
   return { markdown: packed ? frame + packed : frame, truncated: input.summary.truncated };
 }
-function formatJsonSummary(summary, gaps, slices, ok8) {
+function formatJsonSummary(summary, gaps, slices, ok10) {
   return JSON.stringify(
     {
-      ok: ok8,
+      ok: ok10,
       summary,
       gaps,
       slices: slices.map((s) => ({
@@ -2641,11 +2643,11 @@ Run: \`sdd refine${plan.focusStageId ? ` ${plan.focusStageId}` : ""}\`
 }
 
 // src/role/handoff.ts
-import { join as join16 } from "pathe";
+import { join as join17 } from "pathe";
 import { parse as parseYaml3, stringify as stringifyYaml } from "yaml";
 
 // src/role/routing.ts
-import { join as join15 } from "pathe";
+import { join as join16 } from "pathe";
 import { parse as parseYaml2 } from "yaml";
 import { z as z6 } from "zod";
 
@@ -3064,19 +3066,143 @@ async function decide(input) {
 
 // src/role/run.ts
 import { appendFile as appendFile5 } from "fs/promises";
-import { isAbsolute as isAbsolute4, join as join14 } from "pathe";
+import { isAbsolute as isAbsolute4, join as join15 } from "pathe";
 
-// src/team/facts.ts
-import { appendFile } from "fs/promises";
+// src/role/context.ts
 import { join as join9 } from "pathe";
+var NO_SLICE = "No repo slice matched this role.";
 function ok(stdout = "") {
   return { exitCode: 0, stdout };
 }
 function fail(stdout) {
   return { exitCode: 1, stdout };
 }
+function contextPath(root, name) {
+  return join9(roleContextDir(root, name), "context.md");
+}
+function knowledgePath(root, name) {
+  return join9(roleContextDir(root, name), "knowledge.md");
+}
+async function readStoredContext(root, name) {
+  const path = contextPath(root, name);
+  if (!await pathExists(path)) return null;
+  const raw = await readText(path);
+  const match = /^---\r?\nsource: (provided|generated)\r?\n---\r?\n?/.exec(raw);
+  if (!match) return { source: "provided", body: raw.replace(/\s*$/, "") };
+  const source = match[1] === "generated" ? "generated" : "provided";
+  return { source, body: raw.slice(match[0].length).replace(/\s*$/, "") };
+}
+async function roleContextBody(root, name) {
+  const stored = await readStoredContext(root, name);
+  return stored?.body.trim() ?? "";
+}
+async function readKnowledge(root, name) {
+  const path = knowledgePath(root, name);
+  if (!await pathExists(path)) return "";
+  return (await readText(path)).trim();
+}
+async function writeKnowledge(root, name, text2) {
+  await ensureDir(roleContextDir(root, name));
+  const body = text2.trim();
+  if (!body) {
+    await removePath(knowledgePath(root, name));
+    return;
+  }
+  await writeText(knowledgePath(root, name), `${body}
+`);
+}
+function renderStored(source, body) {
+  return `---
+source: ${source}
+---
+${body.trim()}
+`;
+}
+function buildGeneratedContext(input) {
+  const rows = [`Role: ${input.name}`, `Job: ${input.job}`];
+  if (input.knowledge.trim()) rows.push("", "Knowledge:", input.knowledge.trim());
+  rows.push("", "Repo:", input.repo.trim() || NO_SLICE);
+  return rows.join("\n");
+}
+async function repoSlice(root, name, job, knowledge) {
+  const query = [name, job, knowledge].filter((part) => part.trim()).join("\n");
+  let seeds = [];
+  try {
+    const focused = await resolveFocus({ projectRoot: root, query });
+    seeds = focused.plan.seedPaths.filter((rel) => !isSecretPath(rel)).slice(0, 12);
+  } catch {
+    seeds = [];
+  }
+  try {
+    const found = await generateCodeContext({
+      projectRoot: root,
+      query,
+      paths: seeds.length > 0 ? seeds : void 0,
+      caps: { maxSlices: 8, maxTokensApprox: 2e3, maxLinesPerSlice: 40, maxFiles: 12 }
+    });
+    if (found.ok && found.slices.length > 0 && found.markdown.trim()) return found.markdown.trim();
+  } catch {
+  }
+  const blocks = [];
+  for (const rel of seeds) {
+    const abs = join9(root, rel);
+    if (!await pathExists(abs)) continue;
+    let text2 = "";
+    try {
+      text2 = await readText(abs);
+    } catch {
+      continue;
+    }
+    const body = text2.split(/\r?\n/).slice(0, 40).join("\n").trim();
+    if (!body) continue;
+    blocks.push(`${rel}
+${body}`);
+    if (blocks.length >= 8) break;
+  }
+  return blocks.join("\n\n") || NO_SLICE;
+}
+async function setRoleContext(root, input) {
+  const name = canonicalRoleName(input.name);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const role = await readRole(root, name);
+  if (!role) return fail(ROLE_TEXT.notFound);
+  if (input.knowledge !== void 0) await writeKnowledge(root, name, input.knowledge);
+  let knowledge = await readKnowledge(root, name);
+  const extra = input.generate && input.text !== void 0 ? input.text.trim() : "";
+  if (extra && input.knowledge === void 0) {
+    await writeKnowledge(root, name, extra);
+    knowledge = extra;
+  } else if (extra) {
+    knowledge = [knowledge, extra].filter((part) => part.length > 0).join("\n");
+  }
+  if (input.text !== void 0 && !input.generate) {
+    const text2 = input.text.trim();
+    if (!text2) return fail("A context needs text.");
+    await ensureDir(roleContextDir(root, name));
+    await writeText(contextPath(root, name), renderStored("provided", text2));
+    return ok(text2);
+  }
+  const saved = await readStoredContext(root, name);
+  if (!input.generate && input.knowledge !== void 0) return ok(saved?.body || knowledge);
+  if (!input.generate && saved) return ok(saved.body);
+  const repo = await repoSlice(root, name, role.job, knowledge);
+  const body = buildGeneratedContext({ name: role.name, job: role.job, knowledge, repo });
+  await ensureDir(roleContextDir(root, name));
+  await writeText(contextPath(root, name), renderStored("generated", body));
+  return ok(body);
+}
+
+// src/team/facts.ts
+import { appendFile } from "fs/promises";
+import { join as join10 } from "pathe";
+function ok2(stdout = "") {
+  return { exitCode: 0, stdout };
+}
+function fail2(stdout) {
+  return { exitCode: 1, stdout };
+}
 function factsPath(root) {
-  return join9(root, ".sdd", "facts.jsonl");
+  return join10(root, ".sdd", "facts.jsonl");
 }
 function sharesWords(left, right) {
   const bag = wordsOf(left);
@@ -3135,13 +3261,13 @@ async function setFact(root, input) {
   const rawValue = input.value ?? "";
   const rawSource = input.source ?? "";
   if (rawKey.includes("\n") || rawKey.includes("\r") || rawValue.includes("\n") || rawValue.includes("\r") || rawSource.includes("\n") || rawSource.includes("\r")) {
-    return fail("A fact is one line.");
+    return fail2("A fact is one line.");
   }
   const key = rawKey.trim();
   const value = rawValue.trim();
-  if (!key || !value) return fail("A fact needs a key and a value.");
+  if (!key || !value) return fail2("A fact needs a key and a value.");
   if (key.includes("/") || key.includes("\\") || key.includes("\0")) {
-    return fail("A fact key is not valid.");
+    return fail2("A fact key is not valid.");
   }
   if (await contradicts(root, value)) return escalate(root, key);
   const fact = {
@@ -3152,33 +3278,33 @@ async function setFact(root, input) {
     source: rawSource.trim() || "person"
   };
   const file = factsPath(root);
-  await ensureDir(join9(file, ".."));
+  await ensureDir(join10(file, ".."));
   await appendFile(file, `${JSON.stringify(fact)}
 `, "utf8");
-  return ok("Fact set.");
+  return ok2("Fact set.");
 }
 async function showFact(root, key) {
   const name = (key ?? "").trim();
-  if (!name) return fail("A fact needs a key and a value.");
+  if (!name) return fail2("A fact needs a key and a value.");
   const facts = await getFacts(root, { keys: [name] });
   const hit = facts[0];
-  if (!hit) return fail("Fact not set.");
-  return ok(hit.value);
+  if (!hit) return fail2("Fact not set.");
+  return ok2(hit.value);
 }
 async function listFacts(root, query) {
   const facts = await getFacts(root, query ? { query } : void 0);
-  if (facts.length === 0) return ok("No facts.");
-  return ok(facts.map((fact) => `${fact.key}: ${fact.value}`).join("\n"));
+  if (facts.length === 0) return ok2("No facts.");
+  return ok2(facts.map((fact) => `${fact.key}: ${fact.value}`).join("\n"));
 }
 async function contradicts(root, value) {
   if (!/\b(ignore|skip|override)\b/i.test(value)) return false;
   let text2 = "";
   try {
     const config = await loadConfig(root);
-    const file = join9(root, guidancePaths(config).constitution);
+    const file = join10(root, guidancePaths(config).constitution);
     if (await pathExists(file)) text2 = await readText(file);
   } catch {
-    const file = join9(root, "memory", "constitution.md");
+    const file = join10(root, "memory", "constitution.md");
     if (await pathExists(file)) text2 = await readText(file);
   }
   for (const line of text2.split(/\r?\n/)) {
@@ -3197,33 +3323,33 @@ async function escalate(root, key) {
   } catch {
     changeId = null;
   }
-  if (!changeId) return fail("A fact contradicts the constitution.");
+  if (!changeId) return fail2("A fact contradicts the constitution.");
   return recordDecisionRequest(root, { note, change: changeId });
 }
 
 // src/team/memory.ts
 import { appendFile as appendFile2 } from "fs/promises";
-import { join as join10 } from "pathe";
+import { join as join11 } from "pathe";
 var BRAIN_FILES = ["memory.md", "lessons.jsonl"];
-function ok2(stdout = "") {
+function ok3(stdout = "") {
   return { exitCode: 0, stdout };
 }
-function fail2(stdout) {
+function fail3(stdout) {
   return { exitCode: 1, stdout };
 }
 async function knownBot(root, name) {
   const team = await readTeamConfig(root);
-  if ("error" in team) return fail2(team.error);
-  if (!team.team.bots.some((bot) => bot.name === name)) return fail2("Bot not found.");
+  if ("error" in team) return fail3(team.error);
+  if (!team.team.bots.some((bot) => bot.name === name)) return fail3("Bot not found.");
   return null;
 }
 async function readMemory(root, bot) {
-  const file = join10(memoryDir2(root, bot, true), "memory.md");
+  const file = join11(memoryDir2(root, bot, true), "memory.md");
   if (!await pathExists(file)) return "";
   return readText(file);
 }
 async function readLessons(root, bot) {
-  const file = join10(memoryDir2(root, bot, true), "lessons.jsonl");
+  const file = join11(memoryDir2(root, bot, true), "lessons.jsonl");
   if (!await pathExists(file)) return [];
   const lessons = [];
   for (const line of (await readText(file)).split(/\r?\n/)) {
@@ -3247,35 +3373,35 @@ async function readLessons(root, bot) {
   return lessons;
 }
 async function appendLesson(root, bot, lesson) {
-  const file = join10(memoryDir2(root, bot, true), "lessons.jsonl");
-  await ensureDir(join10(file, ".."));
+  const file = join11(memoryDir2(root, bot, true), "lessons.jsonl");
+  await ensureDir(join11(file, ".."));
   await appendFile2(file, `${JSON.stringify(lesson)}
 `, "utf8");
 }
 async function showMemory(root, bot) {
   const name = canonicalRoleName(bot);
-  if (!name) return fail2(ROLE_TEXT.badName);
+  if (!name) return fail3(ROLE_TEXT.badName);
   const missing = await knownBot(root, name);
   if (missing) return missing;
   const text2 = await readMemory(root, name);
-  if (!text2) return ok2("No memory.");
-  return ok2(text2.endsWith("\n") ? text2.slice(0, -1) : text2);
+  if (!text2) return ok3("No memory.");
+  return ok3(text2.endsWith("\n") ? text2.slice(0, -1) : text2);
 }
 async function addLesson(root, bot, text2) {
   const name = canonicalRoleName(bot);
-  if (!name) return fail2(ROLE_TEXT.badName);
+  if (!name) return fail3(ROLE_TEXT.badName);
   const missing = await knownBot(root, name);
   if (missing) return missing;
-  if (text2.includes("\n") || text2.includes("\r")) return fail2("A lesson is one line.");
+  if (text2.includes("\n") || text2.includes("\r")) return fail3("A lesson is one line.");
   const words = text2.trim();
-  if (!words) return fail2("A lesson needs text.");
+  if (!words) return fail3("A lesson needs text.");
   await appendLesson(root, name, {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
     by: gitUserName(root) ?? "unknown",
     text: words,
     source: "person"
   });
-  return ok2("Lesson added.");
+  return ok3("Lesson added.");
 }
 async function addReviewerLesson(root, bot, lesson) {
   const text2 = lesson.text.trim();
@@ -3291,30 +3417,30 @@ async function addReviewerLesson(root, bot, lesson) {
 }
 async function migrateTeamMemory(root) {
   const team = await readTeamConfig(root);
-  if ("error" in team) return fail2(team.error);
-  const base = join10(root, ".sdd", "role-runs", "memory");
+  if ("error" in team) return fail3(team.error);
+  const base = join11(root, ".sdd", "role-runs", "memory");
   const lines = [];
   for (const name of (await listDirs(base)).sort()) {
     if (!canonicalRoleName(name)) continue;
     for (const file of BRAIN_FILES) {
-      const from = join10(base, name, file);
+      const from = join11(base, name, file);
       if (!await pathExists(from)) continue;
       const fromRel = `.sdd/role-runs/memory/${name}/${file}`;
       const toRel = `.sdd/agents/${name}/${file}`;
-      const to = join10(memoryDir2(root, name, true), file);
+      const to = join11(memoryDir2(root, name, true), file);
       if (await pathExists(to)) {
         lines.push(`left ${fromRel}`);
         continue;
       }
-      await ensureDir(join10(to, ".."));
+      await ensureDir(join11(to, ".."));
       await writeText(to, await readText(from));
       await removePath(from);
       lines.push(`moved ${fromRel} -> ${toRel}`);
     }
-    if ((await listFiles(join10(base, name))).length === 0) await removePath(join10(base, name));
+    if ((await listFiles(join11(base, name))).length === 0) await removePath(join11(base, name));
   }
-  if (lines.length === 0) return ok2("Nothing to migrate.");
-  return ok2(lines.join("\n"));
+  if (lines.length === 0) return ok3("Nothing to migrate.");
+  return ok3(lines.join("\n"));
 }
 
 // src/team/brain.ts
@@ -3327,11 +3453,13 @@ async function loadBrain(root, cfg, bot, item, budgetTokens) {
   const file = roleFilePath(root, spec.role);
   if (!await pathExists(file)) return { error: ROLE_TEXT.notFound };
   const roleText = await readText(file);
+  const context = await roleContextBody(root, spec.role);
   const memoryAll = await readMemory(root, spec.name);
   const lessonsNewest = (await readLessons(root, spec.name)).slice().reverse();
   const factsNewest = (await getFacts(root, { query: item.text })).slice().reverse();
   const packed = pack({
     roleText,
+    context,
     memoryAll,
     lessons: lessonsNewest,
     facts: factsNewest,
@@ -3353,12 +3481,15 @@ function pack(input) {
   let memory = input.memoryAll;
   let lessons = input.lessons.slice();
   let facts = input.facts.slice();
+  let context = input.context;
   let warning = "";
   const itemBlock = `Item:
 ${input.item}`;
   const render = () => {
     const parts = [input.roleText.trimEnd()];
     if (warning) parts.push(warning);
+    if (context.trim()) parts.push(`Context:
+${context.trimEnd()}`);
     if (memory.trim()) parts.push(`Memory:
 ${memory.trimEnd()}`);
     if (lessons.length > 0) {
@@ -3377,9 +3508,11 @@ ${facts.map((fact) => `${fact.key}: ${fact.value}`).join("\n")}`);
     memory = "";
     lessons = [];
     facts = [];
+    context = "";
     warning = input.memoryAll.trim() ? WARNING : "";
     return { memory, lessons, facts, prompt: render(), warning };
   }
+  if (countTokens(render()) > input.budget && context.trim()) context = "";
   while (countTokens(render()) > input.budget && facts.length > 0) facts.pop();
   while (countTokens(render()) > input.budget && lessons.length > 0) lessons.pop();
   if (countTokens(render()) > input.budget && memory.trim()) {
@@ -3400,12 +3533,12 @@ ${facts.map((fact) => `${fact.key}: ${fact.value}`).join("\n")}`);
 
 // src/team/loop.ts
 import { appendFile as appendFile4 } from "fs/promises";
-import { basename, join as join13 } from "pathe";
+import { basename, join as join14 } from "pathe";
 import { z as z5 } from "zod";
 
 // src/team/room.ts
 import { appendFile as appendFile3 } from "fs/promises";
-import { join as join12 } from "pathe";
+import { join as join13 } from "pathe";
 import { z as z4 } from "zod";
 
 // src/role/prompts.ts
@@ -3434,7 +3567,7 @@ function revisionPrompt(role, draft, gaps) {
 import { spawn as spawn4 } from "child_process";
 import { mkdtemp, rm } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute3, join as join11 } from "pathe";
+import { isAbsolute as isAbsolute3, join as join12 } from "pathe";
 import { z as z3 } from "zod";
 var OUTPUT_CAP = 4e3;
 var SCOPES = /* @__PURE__ */ new Set(["code", "specs", "memory"]);
@@ -3475,8 +3608,8 @@ function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return value;
 }
-function result(name, ok8, text2) {
-  return { ok: ok8, name, text: clip(text2) };
+function result(name, ok10, text2) {
+  return { ok: ok10, name, text: clip(text2) };
 }
 async function git(cwd, args) {
   return new Promise((resolve) => {
@@ -3525,7 +3658,7 @@ function evidenceRel(changesPath, changeId, sha) {
 }
 async function evidenceFile(root, changeId, sha) {
   const config = await loadConfig(root);
-  return join11(changePath(root, config, changeId), "evidence", `${sha}.json`);
+  return join12(changePath(root, config, changeId), "evidence", `${sha}.json`);
 }
 async function evidenceSupports(root, changeId, cite) {
   const sha = await headOf(root);
@@ -3533,7 +3666,7 @@ async function evidenceSupports(root, changeId, cite) {
   const config = await loadConfig(root);
   const expected = evidenceRel(config.changes_path, changeId, sha);
   if (cite.trim().replace(/\\/g, "/").replace(/^\.\//, "") !== expected) return false;
-  const file = join11(root, ...expected.split("/"));
+  const file = join12(root, ...expected.split("/"));
   if (!await pathExists(file)) return false;
   let parsed;
   try {
@@ -3564,7 +3697,7 @@ async function allowList(root) {
     const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
     for (const command of stage?.verify?.commands ?? []) stageRuns.push(command.run);
   }
-  const file = join11(root, ".sdd", "tools.yaml");
+  const file = join12(root, ".sdd", "tools.yaml");
   if (!await pathExists(file)) return stageRuns;
   let raw;
   try {
@@ -3584,7 +3717,7 @@ async function readFileTool(root, args) {
   const rel = typeof args.path === "string" ? args.path : "";
   if (!safePath(rel)) return result("read_file", false, "That path is outside the project.");
   if (isSecretPath(rel)) return result("read_file", false, "That path is not readable.");
-  const file = join11(root, ...rel.split(/[/\\]/));
+  const file = join12(root, ...rel.split(/[/\\]/));
   if (!await pathExists(file)) return result("read_file", false, "That path is not readable.");
   try {
     const text2 = await readText(file);
@@ -3641,7 +3774,7 @@ async function appendRun(root, changeId, sha, command, exitCode, output) {
     }
   }
   body.runs.push({ command, exitCode, output: clip(output) });
-  await ensureDir(join11(file, ".."));
+  await ensureDir(join12(file, ".."));
   await writeText(file, `${JSON.stringify(body, null, 2)}
 `);
   const config = await loadConfig(root);
@@ -3661,7 +3794,7 @@ async function runCheck(root, args) {
   if (!change) return result("run_check", false, "No active change.");
   const sha = await headOf(root);
   if (!sha) return result("run_check", false, "Git HEAD is unavailable.");
-  const dir = await mkdtemp(join11(tmpdir(), "sdd-check-"));
+  const dir = await mkdtemp(join12(tmpdir(), "sdd-check-"));
   const added = await git(root, ["worktree", "add", "--detach", dir, sha]);
   if (added.code !== 0) {
     await rm(dir, { recursive: true, force: true });
@@ -3688,7 +3821,7 @@ async function writeFileTool(root, args) {
   if (!safePath(rel) || typeof contents !== "string" || isSecretPath(rel)) {
     return result("write_file", false, "That file cannot be written.");
   }
-  await writeText(join11(root, ...rel.split(/[/\\]/)), contents);
+  await writeText(join12(root, ...rel.split(/[/\\]/)), contents);
   return result("write_file", true, `Wrote ${rel}.`);
 }
 function branchName(team, bot, changeId) {
@@ -3764,10 +3897,10 @@ var RoomEntrySchema = z4.object({
   sha: z4.string().optional(),
   evidence: z4.array(z4.string()).optional()
 }).strict();
-function ok3(stdout = "") {
+function ok4(stdout = "") {
   return { exitCode: 0, stdout };
 }
-function fail3(stdout) {
+function fail4(stdout) {
   return { exitCode: 1, stdout };
 }
 function safeId(value) {
@@ -3775,13 +3908,13 @@ function safeId(value) {
 }
 function oneLine(value, empty, broken) {
   const raw = value ?? "";
-  if (raw.includes("\n") || raw.includes("\r")) return fail3(broken);
+  if (raw.includes("\n") || raw.includes("\r")) return fail4(broken);
   const words = raw.trim();
-  if (!words) return fail3(empty);
+  if (!words) return fail4(empty);
   return words;
 }
 function roomPath(root, change, stage) {
-  return join12(root, ".sdd", "rooms", change, `${stage}.jsonl`);
+  return join13(root, ".sdd", "rooms", change, `${stage}.jsonl`);
 }
 function roomRounds(team) {
   return team.limits?.room_rounds ?? 2;
@@ -3820,21 +3953,28 @@ async function openChange(root, change) {
   try {
     config = await loadConfig(root);
   } catch (error) {
-    return fail3(error instanceof Error ? error.message : "Config is invalid.");
+    return fail4(error instanceof Error ? error.message : "Config is invalid.");
   }
   const id = (change?.trim() || await getActiveChangeId(root, config) || "").trim();
-  if (!id) return fail3("No active change.");
-  if (!safeId(id)) return fail3("A change id is not valid.");
+  if (!id) return fail4("No active change.");
+  if (!safeId(id)) return fail4("A change id is not valid.");
   try {
     const ctx = await buildContext(root, config, id);
     return { id, path: ctx.path, stage: ctx.meta.stage, workflow: ctx.workflow, meta: ctx.meta };
   } catch (error) {
-    return fail3(error instanceof Error ? error.message : "Change not found.");
+    return fail4(error instanceof Error ? error.message : "Change not found.");
   }
 }
 function isFailure(value) {
   return "exitCode" in value;
 }
+function stageMemberNames(stage, listed) {
+  const named = [stage.owner, ...stage.collaborates ?? []].filter(
+    (name) => !!name
+  );
+  if (named.length > 0) return named;
+  return listed;
+}
 function memberBots(team, names) {
   const bots = [];
   const seen = /* @__PURE__ */ new Set();
@@ -3852,7 +3992,7 @@ function memberBots(team, names) {
 async function draftOf(changePath2, stage) {
   const rel = stage?.artifacts[0]?.path;
   if (!rel || rel.includes("..")) return "";
-  const file = join12(changePath2, rel);
+  const file = join13(changePath2, rel);
   if (!await pathExists(file)) return "";
   return readText(file);
 }
@@ -3861,7 +4001,7 @@ function formatEntry(entry) {
   return `${entry.round} ${entry.from} ${entry.type}${cite} ${entry.text}`;
 }
 async function appendEntry(file, entry) {
-  await ensureDir(join12(file, ".."));
+  await ensureDir(join13(file, ".."));
   await appendFile3(file, `${JSON.stringify(entry)}
 `, "utf8");
 }
@@ -3870,36 +4010,36 @@ async function consensusLine(changePath2, stage, sha, entries) {
   const agreed = found.agreed.join(",") || "none";
   const open = found.open.map((entry) => entry.cite || entry.text).join(",") || "none";
   await appendFile3(
-    join12(changePath2, "decisions.md"),
+    join13(changePath2, "decisions.md"),
     `${nowIso()} room ${stage} ${sha ?? "none"} agreed ${agreed} open ${open}
 `
   );
 }
 async function showRoom(root, input) {
   const team = await readTeamConfig(root);
-  if ("error" in team) return fail3(team.error);
+  if ("error" in team) return fail4(team.error);
   const opened = await openChange(root, input.change);
   if (isFailure(opened)) return opened;
   const stage = (input.stage?.trim() || opened.stage).trim();
-  if (!safeId(stage)) return fail3("A stage id is not valid.");
+  if (!safeId(stage)) return fail4("A stage id is not valid.");
   const entries = await readEntries(roomPath(root, opened.id, stage));
-  if (entries.length === 0) return ok3("No room.");
-  return ok3(entries.map(formatEntry).join("\n"));
+  if (entries.length === 0) return ok4("No room.");
+  return ok4(entries.map(formatEntry).join("\n"));
 }
 async function postRoom(root, input) {
   const team = await readTeamConfig(root);
-  if ("error" in team) return fail3(team.error);
+  if ("error" in team) return fail4(team.error);
   const opened = await openChange(root, input.change);
   if (isFailure(opened)) return opened;
   const stage = (input.stage?.trim() || opened.stage).trim();
-  if (!safeId(stage)) return fail3("A stage id is not valid.");
+  if (!safeId(stage)) return fail4("A stage id is not valid.");
   const text2 = oneLine(input.text, "A room entry needs text.", "A room entry is one line.");
   if (typeof text2 !== "string") return text2;
   const type = input.type?.trim() || "post";
-  if (!ROOM_TYPES.includes(type)) return fail3("A room entry is not valid.");
+  if (!ROOM_TYPES.includes(type)) return fail4("A room entry is not valid.");
   const cite = input.cite?.trim() ?? "";
-  if (cite && (cite.includes("\n") || cite.includes("\r"))) return fail3("A cite is one line.");
-  if (type === "objection" && !cite) return fail3("An objection needs a cite.");
+  if (cite && (cite.includes("\n") || cite.includes("\r"))) return fail4("A cite is one line.");
+  if (type === "objection" && !cite) return fail4("An objection needs a cite.");
   const stageDef = getStage(opened.workflow, opened.meta, stage);
   const needed = await reviewNeedsEvidence(
     root,
@@ -3909,7 +4049,7 @@ async function postRoom(root, input) {
     text2,
     cite
   );
-  if (needed) return fail3(needed);
+  if (needed) return fail4(needed);
   const evidence = [];
   for (const item of input.evidence ?? []) {
     const line = oneLine(item, "Evidence needs text.", "Evidence is one line.");
@@ -3931,12 +4071,12 @@ async function postRoom(root, input) {
   if (sha) entry.sha = sha;
   if (evidence.length > 0) entry.evidence = evidence;
   await appendEntry(file, entry);
-  return ok3("Posted.");
+  return ok4("Posted.");
 }
 async function classifyReply(root, text2, env, runCommand2) {
   const loaded = await loadModels(root);
   if (loaded === null) return "post";
-  if ("error" in loaded) return fail3(loaded.error);
+  if ("error" in loaded) return fail4(loaded.error);
   const decision = await decide({
     models: loaded.config,
     ctx: { workType: "classify" },
@@ -3950,31 +4090,38 @@ async function classifyReply(root, text2, env, runCommand2) {
   return decision.pick;
 }
 async function reviewRoom(root, input) {
-  if (!input.model) return fail3(ROLE_TEXT.noModel);
+  if (!input.model) return fail4(ROLE_TEXT.noModel);
   const loaded = await readTeamConfig(root);
-  if ("error" in loaded) return fail3(loaded.error);
+  if ("error" in loaded) return fail4(loaded.error);
   const opened = await openChange(root, input.change);
   if (isFailure(opened)) return opened;
   const stageId = (input.stage?.trim() || opened.stage).trim();
-  if (!safeId(stageId)) return fail3("A stage id is not valid.");
+  if (!safeId(stageId)) return fail4("A stage id is not valid.");
   const stage = getStage(opened.workflow, opened.meta, stageId);
-  if (!stage) return fail3("Stage not found.");
-  const names = input.roles && input.roles.length > 0 ? input.roles : [stage.owner, ...stage.collaborates ?? []].filter((name) => !!name);
+  if (!stage) return fail4("Stage not found.");
+  const baked = stageMemberNames(stage, []);
+  let listed = [];
+  if ((!input.roles || input.roles.length === 0) && baked.length === 0) {
+    const found = await rolesListingStage(root, stageId);
+    if ("error" in found) return fail4(found.error);
+    listed = found;
+  }
+  const names = input.roles && input.roles.length > 0 ? input.roles : stageMemberNames(stage, listed);
   const bots = memberBots(loaded.team, names);
-  if ("error" in bots) return fail3(bots.error);
+  if ("error" in bots) return fail4(bots.error);
   const file = roomPath(root, opened.id, stageId);
   const prior = await readEntries(file);
   const highest = prior.reduce((max, entry) => Math.max(max, entry.round), 0);
   const round = highest + 1;
   const cap = roomRounds(loaded.team);
-  if (round > cap) return ok3("Round limit reached.");
+  if (round > cap) return ok4("Round limit reached.");
   const draft = await draftOf(opened.path, stage);
   const before = consensus(prior.filter((entry) => entry.round === highest));
   const sha = await headSha(root);
   const written = [];
   for (const bot of bots) {
     const role = await readRole(root, bot.role);
-    if (!role) return fail3(ROLE_TEXT.notFound);
+    if (!role) return fail4(ROLE_TEXT.notFound);
     const section = {
       id: stageId,
       decision: "room",
@@ -3984,7 +4131,8 @@ async function reviewRoom(root, input) {
     if (section.checks.length === 0) section.checks = ["room"];
     const rows = [critiquePrompt(role, section, draft || "(none)"), "Room:"];
     for (const entry2 of prior) rows.push(formatEntry(entry2));
-    const owner = stage.owner === bot.role || stage.owner === bot.name;
+    const listedOwner = stage.owner ?? (listed.length === 1 ? listed[0] : void 0);
+    const owner = listedOwner === bot.role || listedOwner === bot.name;
     if (owner && before.open.length > 0) {
       rows.push(
         revisionPrompt(
@@ -4000,7 +4148,7 @@ async function reviewRoom(root, input) {
     try {
       raw = await input.model.complete({ roleId: role.name, prompt: rows.join("\n") });
     } catch {
-      return fail3("A room entry is not valid.");
+      return fail4("A room entry is not valid.");
     }
     const stored = await entryFromReply(root, raw, input.env, input.runCommand);
     if (isFailure(stored)) return stored;
@@ -4012,7 +4160,7 @@ async function reviewRoom(root, input) {
       stored.text,
       stored.cite ?? ""
     );
-    if (needed) return fail3(needed);
+    if (needed) return fail4(needed);
     const entry = {
       ts: nowIso(),
       from: bot.name,
@@ -4033,9 +4181,9 @@ async function reviewRoom(root, input) {
       note: `Room ${stageId} still open after ${round} rounds.`
     });
     if (asked.exitCode !== 0) return asked;
-    return ok3("Decision needed.");
+    return ok4("Decision needed.");
   }
-  return ok3(`Round ${round}.`);
+  return ok4(`Round ${round}.`);
 }
 async function entryFromReply(root, raw, env = process.env, runCommand2) {
   let value;
@@ -4052,18 +4200,18 @@ async function entryFromReply(root, raw, env = process.env, runCommand2) {
   }
   const text2 = raw.trim();
   if (!text2 || text2.includes("\n") || text2.includes("\r"))
-    return fail3("A room entry is not valid.");
+    return fail4("A room entry is not valid.");
   const typed = await classifyReply(root, text2, env, runCommand2);
   if (typeof typed !== "string") return typed;
   return checked(typed, text2, "");
 }
 function checked(type, text2, cite) {
-  if (!ROOM_TYPES.includes(type)) return fail3("A room entry is not valid.");
+  if (!ROOM_TYPES.includes(type)) return fail4("A room entry is not valid.");
   const words = oneLine(text2, "A room entry needs text.", "A room entry is one line.");
   if (typeof words !== "string") return words;
   const citeWords = cite.trim();
-  if (citeWords && (cite.includes("\n") || cite.includes("\r"))) return fail3("A cite is one line.");
-  if (type === "objection" && !citeWords) return fail3("An objection needs a cite.");
+  if (citeWords && (cite.includes("\n") || cite.includes("\r"))) return fail4("A cite is one line.");
+  if (type === "objection" && !citeWords) return fail4("An objection needs a cite.");
   return citeWords ? { type, text: words, cite: citeWords } : { type, text: words };
 }
 async function activeRoom(root) {
@@ -4143,14 +4291,14 @@ var LoopStepSchema = z5.discriminatedUnion("step", [
   askStep,
   doneStep
 ]);
-function ok4(stdout = "") {
+function ok5(stdout = "") {
   return { exitCode: 0, stdout };
 }
-function fail4(stdout) {
+function fail5(stdout) {
   return { exitCode: 1, stdout };
 }
 async function appendLine(file, value) {
-  await ensureDir(join13(file, ".."));
+  await ensureDir(join14(file, ".."));
   await appendFile4(file, `${JSON.stringify(value)}
 `, "utf8");
 }
@@ -4184,13 +4332,13 @@ ${piece}`.trim().slice(-8e3);
       raw = await input.model.complete({ roleId: input.roleName, prompt: promptFor() });
     } catch {
       await appendLine(input.file, { type: "bad_call", roleId: input.roleName });
-      return fail4("A loop step is not valid.");
+      return fail5("A loop step is not valid.");
     }
     taken += 1;
     const step = parseStep(raw);
     if (!step) {
       await appendLine(input.file, { type: "bad_call", roleId: input.roleName });
-      return fail4("A loop step is not valid.");
+      return fail5("A loop step is not valid.");
     }
     if (step.kind === "understand") {
       await appendLine(input.file, { type: "step", step: "understand" });
@@ -4242,7 +4390,7 @@ ${piece}`.trim().slice(-8e3);
       await appendLine(input.file, { type: "step", step: "done", summary: body.summary });
       await copyReviewer();
       await postLoopDone(input.root, input.brain.bot.name, body.summary, cites[0]);
-      return ok4(body.summary);
+      return ok5(body.summary);
     }
   }
   return ask(input.root, input.file, `Stopped after ${max} steps.`, ["continue", "stop"]);
@@ -4253,7 +4401,7 @@ async function ask(root, file, question, options) {
   if (note && !note.includes("\n") && !note.includes("\r")) {
     await recordDecisionRequest(root, { note });
   }
-  return ok4(question);
+  return ok5(question);
 }
 function parseStep(raw) {
   let value;
@@ -4292,7 +4440,7 @@ async function priorLesson(root, logName, file, roleName) {
   const names = (await listFiles(dir)).filter((item) => item.endsWith(".jsonl")).sort();
   const index = names.indexOf(basename(file));
   if (index <= 0) return null;
-  const prior = join13(dir, names[index - 1]);
+  const prior = join14(dir, names[index - 1]);
   if (!await pathExists(prior)) return null;
   let fromChange = null;
   let fromOther = null;
@@ -4330,10 +4478,10 @@ var FORBIDDEN = /* @__PURE__ */ new Set([
 ]);
 var UNAVAILABLE = /* @__PURE__ */ new Set(["commit", "push", "tag", "pull_request", "merge", "deploy"]);
 var CLOSED = /* @__PURE__ */ new Set(["applied", "denied", "rejected", "unavailable", "stopped", "expired"]);
-function ok5(stdout = "", runId) {
+function ok6(stdout = "", runId) {
   return runId ? { exitCode: 0, stdout, runId } : { exitCode: 0, stdout };
 }
-function fail5(stdout, runId) {
+function fail6(stdout, runId) {
   return runId ? { exitCode: 1, stdout, runId } : { exitCode: 1, stdout };
 }
 function linesOf(...parts) {
@@ -4470,7 +4618,7 @@ function parseReply(raw) {
   return { text: rec.text, gaps, changed, action };
 }
 async function appendJson(file, value) {
-  await ensureDir(join14(file, ".."));
+  await ensureDir(join15(file, ".."));
   await appendFile5(file, `${JSON.stringify(value)}
 `, "utf8");
 }
@@ -4487,7 +4635,7 @@ async function readJsonLines(file) {
   return lines;
 }
 async function timeoutMinutes(root) {
-  const path = join14(root, ".sdd", "role.yaml");
+  const path = join15(root, ".sdd", "role.yaml");
   if (!await pathExists(path)) return 10;
   let data;
   try {
@@ -4506,13 +4654,21 @@ async function timeoutMinutes(root) {
 function citeOk(cite, section) {
   return section.checks.includes(cite) || cite === `${section.id}:${section.decision}`;
 }
-function authorPrompt(role, task, kind, section) {
-  const rows = [
-    `Job: ${role.job}`,
-    `Description: ${role.description}`,
-    `Task: ${task}`,
-    `Kind: ${kind}`
-  ];
+function purviewLines(role) {
+  const rows = [];
+  if (role.stages.length > 0) rows.push(`Stages: ${role.stages.join(", ")}`);
+  if (role.owns.length > 0) rows.push(`Owns: ${role.owns.join(", ")}`);
+  if (role.skills.length > 0) rows.push(`Skills: ${role.skills.join(", ")}`);
+  if (role.never.length > 0) rows.push(`Never: ${role.never.join(", ")}`);
+  if (role.askHumanWhen.length > 0) rows.push(`Ask when: ${role.askHumanWhen.join(", ")}`);
+  if (rows.length > 0) rows.push("Stay inside this role.");
+  return rows;
+}
+function authorPrompt(role, task, kind, section, context = "", guide = false) {
+  const rows = [`Job: ${role.job}`, `Description: ${role.description}`, ...purviewLines(role)];
+  if (context.trim()) rows.push(`Context:
+${context.trim()}`);
+  rows.push(`Task: ${task}`, `Kind: ${kind}`);
   if (section) {
     rows.push(
       `Section: ${section.id}`,
@@ -4522,12 +4678,32 @@ function authorPrompt(role, task, kind, section) {
     );
     rows.push("Section text:", section.body);
   }
+  if (guide) {
+    rows.push('If one fact is missing, reply with one line that starts with "Question: ".');
+    rows.push("Otherwise write the draft for this stage.");
+  }
   return rows.join("\n");
 }
+function neverBlocks(role, action) {
+  const words = action.words.trim().toLowerCase();
+  const name = action.name.trim().toLowerCase();
+  return role.never.some((item) => {
+    const line = item.trim().toLowerCase();
+    return line.length > 0 && (line === words || line === name);
+  });
+}
+function lockedToChange(role) {
+  return role.never.some((item) => item.trim().toLowerCase() === "write product code");
+}
+function outsideChange(changeDir, rel) {
+  const path = rel.replace(/\\/g, "/").replace(/^\.\//, "");
+  const dir = changeDir.replace(/\\/g, "/").replace(/\/$/, "");
+  return path !== dir && !path.startsWith(`${dir}/`);
+}
 async function acceptedFile(root, changeId) {
-  if (!await pathExists(configPath(root))) return join14(root, "changes", changeId, "accepted.md");
+  if (!await pathExists(configPath(root))) return join15(root, "changes", changeId, "accepted.md");
   const config = await loadConfig(root);
-  return join14(changesDir(root, config), changeId, "accepted.md");
+  return join15(changesDir(root, config), changeId, "accepted.md");
 }
 async function callModel(model, file, roleId, prompt, pass) {
   let raw;
@@ -4582,24 +4758,51 @@ async function applyAction(root, file, roleName, action, mode) {
     await appendJson(file, { type: "rejected" });
     return { exitCode: 1, stdout: ROLE_TEXT.cannot, applied: false };
   }
-  await writeText(join14(root, ...path.split(/[/\\]/)), contents);
+  await writeText(join15(root, ...path.split(/[/\\]/)), contents);
   if (mode === "always")
     await saveRule(root, roleName, { name: action.name, inputs: action.inputs });
   await appendJson(file, { type: "applied", name: "write_file" });
   return { exitCode: 0, stdout: "", applied: true };
 }
-async function finishRun(root, file, role, final, minutes, now, runId) {
+async function finishGuideRun(root, file, role, final, runId, changeDir) {
+  if (final.text.trim().startsWith("Question:")) return ok6(final.text, runId);
+  const action = final.action;
+  if (!action) return ok6(final.text, runId);
+  if (FORBIDDEN.has(action.name) || UNAVAILABLE.has(action.name) || neverBlocks(role, action)) {
+    await appendJson(file, { type: "rejected" });
+    return fail6("This role does not do that.", runId);
+  }
+  if (action.name !== "write_file") {
+    await appendJson(file, { type: "rejected" });
+    return fail6(ROLE_TEXT.cannot, runId);
+  }
+  const path = action.inputs.path;
+  const contents = action.inputs.contents;
+  if (typeof path !== "string" || typeof contents !== "string" || !isSafeProductPath(path)) {
+    await appendJson(file, { type: "rejected" });
+    return fail6(ROLE_TEXT.cannot, runId);
+  }
+  if (isSecretPath(path) || lockedToChange(role) && outsideChange(changeDir, path)) {
+    await appendJson(file, { type: "rejected" });
+    return fail6("That file is outside this role.", runId);
+  }
+  const applied = await applyAction(root, file, role.name, action, "once");
+  if (applied.exitCode !== 0) return fail6(applied.stdout || ROLE_TEXT.cannot, runId);
+  return ok6(final.text, runId);
+}
+async function finishRun(root, file, role, final, minutes, now, runId, guide) {
+  if (guide) return finishGuideRun(root, file, role, final, runId, guide.changeDir);
   const action = final.action;
-  if (!action) return ok5(final.text, runId);
+  if (!action) return ok6(final.text, runId);
   if (FORBIDDEN.has(action.name) || !UNAVAILABLE.has(action.name) && action.name !== "write_file") {
     await appendJson(file, { type: "rejected" });
-    return fail5(linesOf(final.text, ROLE_TEXT.cannot), runId);
+    return fail6(linesOf(final.text, ROLE_TEXT.cannot), runId);
   }
   const rule = await readRule(root, role.name);
   if (!role.askFirst && rule && rule.name === action.name && sameInputs(rule.inputs, action.inputs)) {
     const applied = await applyAction(root, file, role.name, action, "always");
     const stdout = applied.applied ? final.text : linesOf(final.text, applied.stdout);
-    return applied.exitCode === 0 ? ok5(stdout, runId) : fail5(stdout, runId);
+    return applied.exitCode === 0 ? ok6(stdout, runId) : fail6(stdout, runId);
   }
   const expiresAt = new Date(now.getTime() + minutes * 6e4).toISOString();
   await appendJson(file, {
@@ -4607,12 +4810,12 @@ async function finishRun(root, file, role, final, minutes, now, runId) {
     action: { name: action.name, words: action.words, inputs: action.inputs },
     expiresAt
   });
-  if (role.askFirst) return ok5(linesOf(action.words, ROLE_TEXT.askFirst), runId);
-  return ok5(linesOf(action.words, ROLE_TEXT.choice), runId);
+  if (role.askFirst) return ok6(linesOf(action.words, ROLE_TEXT.askFirst), runId);
+  return ok6(linesOf(action.words, ROLE_TEXT.choice), runId);
 }
 async function settleRoleReply(root, file, role, reply, now, runId) {
   const minutes = await timeoutMinutes(root);
-  if (minutes === "invalid") return fail5(ROLE_TEXT.badYaml, runId);
+  if (minutes === "invalid") return fail6(ROLE_TEXT.badYaml, runId);
   return finishRun(
     root,
     file,
@@ -4627,27 +4830,27 @@ async function latestRunFile(root, name) {
   const dir = conversationDir(root, name);
   const files = (await listFiles(dir)).filter((file) => file.endsWith(".jsonl")).sort();
   const last = files[files.length - 1];
-  return last ? join14(dir, last) : null;
+  return last ? join15(dir, last) : null;
 }
 async function runRole(root, input) {
   const name = canonicalRoleName(input.name);
-  if (!name) return fail5(ROLE_TEXT.badName);
+  if (!name) return fail6(ROLE_TEXT.badName);
   if (input.stop) {
-    if (!await readRole(root, name)) return fail5(ROLE_TEXT.notFound);
+    if (!await readRole(root, name)) return fail6(ROLE_TEXT.notFound);
     const latest = await latestRunFile(root, name);
-    if (!latest) return fail5(ROLE_TEXT.runNotFound);
+    if (!latest) return fail6(ROLE_TEXT.runNotFound);
     await appendJson(latest, { type: "stopped" });
-    return ok5();
+    return ok6();
   }
   let roleName = name;
   let team = null;
   let botName = "";
-  if (await pathExists(join14(root, ".sdd", "team.yaml"))) {
+  if (await pathExists(join15(root, ".sdd", "team.yaml"))) {
     const loaded = await readTeamConfig(root);
-    if ("error" in loaded) return fail5(loaded.error);
+    if ("error" in loaded) return fail6(loaded.error);
     const resolved = resolveBot(loaded.team, name);
     if ("error" in resolved) {
-      if (resolved.error === "Name the bot.") return fail5(resolved.error);
+      if (resolved.error === "Name the bot.") return fail6(resolved.error);
     } else {
       team = loaded.team;
       botName = resolved.name;
@@ -4655,41 +4858,41 @@ async function runRole(root, input) {
     }
   }
   const role = await readRole(root, roleName);
-  if (!role) return fail5(ROLE_TEXT.notFound);
-  if (!role.job.trim()) return fail5(ROLE_TEXT.needsJob);
+  if (!role) return fail6(ROLE_TEXT.notFound);
+  if (!role.job.trim()) return fail6(ROLE_TEXT.needsJob);
   const task = input.task ?? "";
   let withName = "";
   if (input.withRole !== void 0 && input.withRole.trim() !== "") {
     const canonical = canonicalRoleName(input.withRole);
-    if (!canonical) return fail5(ROLE_TEXT.badName);
-    if (canonical === name) return fail5(ROLE_TEXT.self);
+    if (!canonical) return fail6(ROLE_TEXT.badName);
+    if (canonical === name) return fail6(ROLE_TEXT.self);
     withName = canonical;
   }
-  if (mentionsX(task)) return fail5(ROLE_TEXT.x);
+  if (mentionsX(task)) return fail6(ROLE_TEXT.x);
   const kind = input.kind?.trim() || "reading";
   let section;
   if (kind !== "reading") {
-    if (!DRAFT_KINDS.has(kind)) return fail5(ROLE_TEXT.needsSection);
+    if (!DRAFT_KINDS.has(kind)) return fail6(ROLE_TEXT.needsSection);
     const changeId = input.change?.trim() ?? "";
     const sectionId = input.section?.trim() ?? "";
-    if (!safeChangeId(changeId) || !sectionId) return fail5(ROLE_TEXT.needsSection);
+    if (!safeChangeId(changeId) || !sectionId) return fail6(ROLE_TEXT.needsSection);
     const acceptedPath = await acceptedFile(root, changeId);
-    if (!await pathExists(acceptedPath)) return fail5(ROLE_TEXT.needsSection);
+    if (!await pathExists(acceptedPath)) return fail6(ROLE_TEXT.needsSection);
     const parsed = parseSection(await readText(acceptedPath), sectionId);
-    if (!parsed) return fail5(ROLE_TEXT.needsSection);
+    if (!parsed) return fail6(ROLE_TEXT.needsSection);
     section = parsed;
   }
   let critic = null;
   if (withName && section) {
     critic = await readRole(root, withName);
-    if (!critic) return fail5(ROLE_TEXT.notFound);
+    if (!critic) return fail6(ROLE_TEXT.notFound);
   }
   const minutes = await timeoutMinutes(root);
-  if (minutes === "invalid") return fail5(ROLE_TEXT.badYaml);
-  if (!input.model) return fail5(ROLE_TEXT.noModel);
+  if (minutes === "invalid") return fail6(ROLE_TEXT.badYaml);
+  if (!input.model) return fail6(ROLE_TEXT.noModel);
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const runId = runIdFrom(now);
-  const file = join14(conversationDir(root, name), `${runId}.jsonl`);
+  const file = join15(conversationDir(root, name), `${runId}.jsonl`);
   if (section) {
     await appendJson(file, {
       type: "checks",
@@ -4698,17 +4901,17 @@ async function runRole(root, input) {
       decision: section.decision
     });
   }
-  if (team && botName) {
+  if (team && botName && !input.guide) {
     let budget = 12e3;
     try {
       const search = await loadSearchConfig(root);
       budget = budgetForStage(search, void 0);
     } catch (error) {
-      if (error instanceof SearchConfigError) return fail5("search.yaml is invalid", runId);
+      if (error instanceof SearchConfigError) return fail6("search.yaml is invalid", runId);
       throw error;
     }
     const brain = await loadBrain(root, team, botName, { text: task }, budget);
-    if ("error" in brain) return fail5(brain.error, runId);
+    if ("error" in brain) return fail6(brain.error, runId);
     return runLoop({
       root,
       cfg: team,
@@ -4723,10 +4926,17 @@ async function runRole(root, input) {
     input.model,
     file,
     role.name,
-    authorPrompt(role, task, kind, section),
+    authorPrompt(
+      role,
+      task,
+      kind,
+      section,
+      await roleContextBody(root, role.name),
+      input.guide !== void 0
+    ),
     1
   );
-  if (!draft) return fail5("", runId);
+  if (!draft) return fail6("", runId);
   let final = draft;
   if (critic && section) {
     const accepted = section;
@@ -4737,10 +4947,10 @@ async function runRole(root, input) {
       critiquePrompt(critic, accepted, draft.text),
       2
     );
-    if (!critique) return fail5(draft.text, runId);
+    if (!critique) return fail6(draft.text, runId);
     if (critique.gaps.some((gap) => !citeOk(gap.cite, accepted))) {
       await appendJson(file, { type: "bad_call", roleId: critic.name });
-      return fail5(draft.text, runId);
+      return fail6(draft.text, runId);
     }
     if (critique.gaps.length > 0) {
       const revision = await callModel(
@@ -4750,16 +4960,16 @@ async function runRole(root, input) {
         revisionPrompt(role, draft.text, critique.gaps),
         3
       );
-      if (!revision) return fail5(draft.text, runId);
+      if (!revision) return fail6(draft.text, runId);
       const cites = critique.gaps.map((gap) => gap.cite);
       if (revision.changed === null || !sameCiteSet(revision.changed, cites)) {
         await appendJson(file, { type: "bad_call", roleId: role.name });
-        return fail5(draft.text, runId);
+        return fail6(draft.text, runId);
       }
       final = revision;
     }
   }
-  return finishRun(root, file, role, final, minutes, now, runId);
+  return finishRun(root, file, role, final, minutes, now, runId, input.guide);
 }
 function openPending(lines) {
   let pending = null;
@@ -4793,7 +5003,7 @@ async function findRun(root, runId) {
   if (!safeRunId(runId)) return null;
   const hits = [];
   for (const roleName of await listConversationRoles(root)) {
-    const file = join14(conversationDir(root, roleName), `${runId}.jsonl`);
+    const file = join15(conversationDir(root, roleName), `${runId}.jsonl`);
     if (await pathExists(file)) hits.push({ file, roleName });
   }
   if (hits.length === 1) return hits[0];
@@ -4805,24 +5015,24 @@ async function findRun(root, runId) {
 }
 async function allowRole(root, input) {
   const found = await findRun(root, input.runId);
-  if (!found) return fail5(ROLE_TEXT.runNotFound);
+  if (!found) return fail6(ROLE_TEXT.runNotFound);
   const pending = openPending(await readJsonLines(found.file));
-  if (!pending) return fail5(ROLE_TEXT.runNotFound);
+  if (!pending) return fail6(ROLE_TEXT.runNotFound);
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const expires = Date.parse(pending.expiresAt);
   if (!Number.isFinite(expires) || now.getTime() >= expires) {
     await appendJson(found.file, { type: "expired" });
-    return fail5(ROLE_TEXT.expired);
+    return fail6(ROLE_TEXT.expired);
   }
   if (input.mode === "deny") {
     await appendJson(found.file, { type: "denied" });
-    return ok5("", input.runId);
+    return ok6("", input.runId);
   }
   const role = await readRole(root, found.roleName);
-  if (!role) return fail5(ROLE_TEXT.notFound);
-  if (role.askFirst) return ok5(ROLE_TEXT.askFirst, input.runId);
+  if (!role) return fail6(ROLE_TEXT.notFound);
+  if (role.askFirst) return ok6(ROLE_TEXT.askFirst, input.runId);
   const applied = await applyAction(root, found.file, found.roleName, pending, input.mode);
-  return applied.exitCode === 0 ? ok5(applied.stdout, input.runId) : fail5(applied.stdout, input.runId);
+  return applied.exitCode === 0 ? ok6(applied.stdout, input.runId) : fail6(applied.stdout, input.runId);
 }
 
 // src/role/routing.ts
@@ -4857,10 +5067,10 @@ var RoutingSchema = z6.object({
     seen.add(rule.id);
   }
 });
-function ok6(stdout = "") {
+function ok7(stdout = "") {
   return { exitCode: 0, stdout };
 }
-function fail6(stdout) {
+function fail7(stdout) {
   return { exitCode: 1, stdout };
 }
 function formatRoutingError(error) {
@@ -4889,7 +5099,7 @@ function cleanItem(input) {
 function inboxFile(root, name) {
   const canonical = canonicalRoleName(name);
   if (!canonical) return null;
-  return join15(root, ".sdd", "agents", canonical, "inbox.jsonl");
+  return join16(root, ".sdd", "agents", canonical, "inbox.jsonl");
 }
 async function writeHandoffInboxes(root, record) {
   const seen = /* @__PURE__ */ new Set();
@@ -4902,7 +5112,7 @@ async function writeHandoffInboxes(root, record) {
   }
 }
 async function readRouting(root) {
-  const path = join15(root, ".sdd", "routing.yaml");
+  const path = join16(root, ".sdd", "routing.yaml");
   if (!await pathExists(path)) return { rules: [] };
   let raw;
   try {
@@ -4915,14 +5125,14 @@ async function readRouting(root) {
   return parsed.data;
 }
 async function loadRoles(root) {
-  const dir = join15(root, ".sdd", "roles");
+  const dir = join16(root, ".sdd", "roles");
   const files = (await listFiles(dir)).filter((file) => file.endsWith(".md")).sort();
   const roles = [];
   for (const file of files) {
     const name = file.slice(0, -".md".length);
     let parsed;
     try {
-      parsed = parseRoleDocument(name, await readText(join15(dir, file)));
+      parsed = parseRoleDocument(name, await readText(join16(dir, file)));
     } catch {
       return { error: `Role file is invalid: ${name}.` };
     }
@@ -5005,6 +5215,24 @@ async function matchRoute(root, input) {
       }
     };
   }
+  if (item.stage) {
+    const named = roles.filter((role) => role.stages.includes(item.stage ?? ""));
+    if (named.length > 1) {
+      return { ok: true, match: { kind: "ask", reason: "Two roles list this stage." } };
+    }
+    if (named.length === 1) {
+      const role = named[0]?.name ?? "";
+      return {
+        ok: true,
+        match: {
+          kind: "role",
+          role,
+          reason: `Role ${role} lists stage ${item.stage}.`,
+          rule: "role-stage"
+        }
+      };
+    }
+  }
   if (item.stage) {
     const owner = await stageOwner(root, item.stage);
     if (owner && typeof owner === "object") return { ok: false, message: owner.error };
@@ -5080,17 +5308,17 @@ async function routeMetrics(root) {
 }
 async function routeRole(root, input, deps) {
   const item = await prepareItem(root, input);
-  if ("error" in item) return fail6(item.error);
+  if ("error" in item) return fail7(item.error);
   const matched = await matchRoute(root, item);
-  if (!matched.ok) return fail6(matched.message);
+  if (!matched.ok) return fail7(matched.message);
   if (matched.match.kind !== "ask" || matched.match.reason !== "No rule matched.") {
-    return ok6(formatHit(matched.match));
+    return ok7(formatHit(matched.match));
   }
   const loaded = await loadModels(root);
-  if (loaded === null) return ok6(formatHit(matched.match));
-  if ("error" in loaded) return fail6(loaded.error);
+  if (loaded === null) return ok7(formatHit(matched.match));
+  if ("error" in loaded) return fail7(loaded.error);
   const roles = await loadRoles(root);
-  if ("error" in roles) return fail6(roles.error);
+  if ("error" in roles) return fail7(roles.error);
   const names = roles.map((role) => role.name).sort((left, right) => left.localeCompare(right));
   const options = names.includes("human") ? names : [...names, "human"];
   const decision = await decide({
@@ -5107,10 +5335,10 @@ async function routeRole(root, input, deps) {
   });
   if (decision.pick !== "human" && names.includes(decision.pick)) {
     const id = decision.choice?.id ?? "model";
-    return ok6(`role ${decision.pick}
+    return ok7(`role ${decision.pick}
 reason Model ${id} picked ${decision.pick}.`);
   }
-  return ok6("Ask the human.\nNo rule matched.");
+  return ok7("Ask the human.\nNo rule matched.");
 }
 async function readInbox(root, name) {
   const file = inboxFile(root, name);
@@ -5186,20 +5414,20 @@ async function queueNames(root, bot) {
   }
   const team = await readTeamConfig(root);
   if ("team" in team) return team.team.bots.map((item) => item.name);
-  const dirs = (await listDirs(join15(root, ".sdd", "agents"))).sort();
+  const dirs = (await listDirs(join16(root, ".sdd", "agents"))).sort();
   if (dirs.length === 0) return { error: team.error };
   return dirs;
 }
 async function queueRole(root, bot) {
   const names = await queueNames(root, bot?.trim());
-  if ("error" in names) return fail6(names.error);
+  if ("error" in names) return fail7(names.error);
   const blocks = [];
   for (const name of names) {
     const entries = await readInbox(root, name);
-    if ("error" in entries) return fail6(entries.error);
+    if ("error" in entries) return fail7(entries.error);
     blocks.push(formatInbox(name, entries));
   }
-  return ok6(blocks.join("\n\n"));
+  return ok7(blocks.join("\n\n"));
 }
 function itemId(item) {
   if (item.id) return item.id;
@@ -5212,26 +5440,26 @@ function itemId(item) {
 }
 async function takeRole(root, input) {
   const item = await prepareItem(root, input);
-  if ("error" in item) return fail6(item.error);
+  if ("error" in item) return fail7(item.error);
   const matched = await matchRoute(root, item);
-  if (!matched.ok) return fail6(matched.message);
+  if (!matched.ok) return fail7(matched.message);
   const match = matched.match;
-  if (match.kind === "ask") return fail6(formatHit(match));
+  if (match.kind === "ask") return fail7(formatHit(match));
   const team = await readTeamConfig(root);
-  if ("error" in team) return fail6(team.error);
+  if ("error" in team) return fail7(team.error);
   const bots = team.team.bots.filter((bot) => bot.role === match.role);
-  if (bots.length === 0) return fail6(`No bot has role ${match.role}.`);
+  if (bots.length === 0) return fail7(`No bot has role ${match.role}.`);
   const requested = input.bot?.trim();
-  if (requested && !canonicalRoleName(requested)) return fail6(ROLE_TEXT.badName);
+  if (requested && !canonicalRoleName(requested)) return fail7(ROLE_TEXT.badName);
   if (requested && !bots.some((bot) => bot.name === requested)) {
     const known = team.team.bots.some((bot) => bot.name === requested);
-    if (!known) return fail6("Bot not found.");
-    return fail6(`${requested} is not a ${match.role}.`);
+    if (!known) return fail7("Bot not found.");
+    return fail7(`${requested} is not a ${match.role}.`);
   }
   const counts = /* @__PURE__ */ new Map();
   for (const bot of team.team.bots) {
     const entries = await readInbox(root, bot.name);
-    if ("error" in entries) return fail6(entries.error);
+    if ("error" in entries) return fail7(entries.error);
     counts.set(
       bot.name,
       entries.filter((entry) => entry.type === "item" && entry.status === "active").length
@@ -5240,19 +5468,19 @@ async function takeRole(root, input) {
   const roleCount = bots.reduce((sum, bot) => sum + (counts.get(bot.name) ?? 0), 0);
   const roleCap = team.team.role_wip?.[match.role];
   if (roleCap !== void 0 && roleCount >= roleCap) {
-    return fail6(`${match.role} is at the limit.`);
+    return fail7(`${match.role} is at the limit.`);
   }
   const chosen = requested ? bots.find((bot) => bot.name === requested) : bots.find((bot) => (counts.get(bot.name) ?? 0) < bot.wip);
   if (!chosen || (counts.get(chosen.name) ?? 0) >= chosen.wip) {
-    return fail6(`${requested || bots[0]?.name || match.role} is at the limit.`);
+    return fail7(`${requested || bots[0]?.name || match.role} is at the limit.`);
   }
   const id = itemId(item);
-  if (!id) return fail6("An item needs an id.");
+  if (!id) return fail7("An item needs an id.");
   for (const bot of team.team.bots) {
     const entries = await readInbox(root, bot.name);
-    if ("error" in entries) return fail6(entries.error);
+    if ("error" in entries) return fail7(entries.error);
     if (entries.some((entry) => entry.type === "item" && entry.status === "active" && entry.id === id)) {
-      return fail6(`${id} is already active.`);
+      return fail7(`${id} is already active.`);
     }
   }
   const record = {
@@ -5267,9 +5495,9 @@ async function takeRole(root, input) {
   if (item.artifact) record.artifact = item.artifact;
   if (item.skill) record.skill = item.skill;
   const file = inboxFile(root, chosen.name);
-  if (!file) return fail6(ROLE_TEXT.badName);
+  if (!file) return fail7(ROLE_TEXT.badName);
   await appendJson(file, record);
-  return ok6(`${chosen.name} took ${id}
+  return ok7(`${chosen.name} took ${id}
 role ${match.role}
 rule ${match.rule}`);
 }
@@ -5277,10 +5505,10 @@ rule ${match.rule}`);
 // src/role/handoff.ts
 var ID = /^[a-z][a-z0-9-]{0,39}$/;
 var ROLE_YAML = ["role.yaml"];
-function ok7(stdout = "", runId) {
+function ok8(stdout = "", runId) {
   return runId ? { exitCode: 0, stdout, runId } : { exitCode: 0, stdout };
 }
-function fail7(stdout, runId) {
+function fail8(stdout, runId) {
   return runId ? { exitCode: 1, stdout, runId } : { exitCode: 1, stdout };
 }
 function mentionsX2(task) {
@@ -5291,10 +5519,10 @@ function safeChangeId2(id) {
   return !id.includes("/") && !id.includes("\\") && !id.includes("\0");
 }
 function yamlPath(root) {
-  return join16(root, ".sdd", ...ROLE_YAML);
+  return join17(root, ".sdd", ...ROLE_YAML);
 }
 function planPath(root, changeId, sectionId) {
-  return join16(root, ".sdd", "role-runs", "plans", changeId, `${sectionId}.json`);
+  return join17(root, ".sdd", "role-runs", "plans", changeId, `${sectionId}.json`);
 }
 async function loadYaml(root) {
   const path = yamlPath(root);
@@ -5325,11 +5553,11 @@ async function messagingOn(root) {
 }
 async function setRoleMessaging(root, enabled) {
   const loaded = await loadYaml(root);
-  if (loaded === "invalid") return fail7(ROLE_TEXT.badYaml);
+  if (loaded === "invalid") return fail8(ROLE_TEXT.badYaml);
   const raw = loaded === "missing" ? {} : loaded;
   raw.role_messaging = enabled;
   await writeText(yamlPath(root), stringifyYaml(raw));
-  return ok7(enabled ? "Messaging between roles is on." : "Messaging between roles is off.");
+  return ok8(enabled ? "Messaging between roles is on." : "Messaging between roles is off.");
 }
 function field(body, prefix) {
   const found = [];
@@ -5428,26 +5656,26 @@ function receiverPrompt(role, task, section) {
 async function handoffRole(root, input) {
   const from = canonicalRoleName(input.from);
   const to = canonicalRoleName(input.to);
-  if (!from || !to) return fail7(ROLE_TEXT.badName);
-  if (from === to) return fail7("A role cannot hand off to itself.");
+  if (!from || !to) return fail8(ROLE_TEXT.badName);
+  if (from === to) return fail8("A role cannot hand off to itself.");
   const sender = await readRole(root, from);
   const receiver = await readRole(root, to);
-  if (!sender || !receiver) return fail7(ROLE_TEXT.notFound);
+  if (!sender || !receiver) return fail8(ROLE_TEXT.notFound);
   const task = input.task ?? "";
-  if (mentionsX2(task)) return fail7(ROLE_TEXT.x);
+  if (mentionsX2(task)) return fail8(ROLE_TEXT.x);
   const loaded = await acceptedFacts(root, input.change?.trim() ?? "", input.section?.trim() ?? "");
-  if (!loaded) return fail7(ROLE_TEXT.needsSection);
+  if (!loaded) return fail8(ROLE_TEXT.needsSection);
   if (loaded.current.owners.length > 0 && !loaded.current.owners.includes(to)) {
-    return fail7("One owner handles this section.");
+    return fail8("One owner handles this section.");
   }
   const messaging = await messagingOn(root);
-  if (messaging === false) return ok7("Messaging between roles is off.");
-  if (!input.model) return fail7(ROLE_TEXT.noModel);
-  if (messaging === "invalid") return fail7(ROLE_TEXT.badYaml);
+  if (messaging === false) return ok8("Messaging between roles is off.");
+  if (!input.model) return fail8(ROLE_TEXT.noModel);
+  if (messaging === "invalid") return fail8(ROLE_TEXT.badYaml);
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const runId = runIdFrom(now);
-  const senderFile = join16(conversationDir(root, from), `${runId}.jsonl`);
-  const receiverFile = join16(conversationDir(root, to), `${runId}.jsonl`);
+  const senderFile = join17(conversationDir(root, from), `${runId}.jsonl`);
+  const receiverFile = join17(conversationDir(root, to), `${runId}.jsonl`);
   const record = handoffRecord(from, to, input.change?.trim() ?? "", loaded.current);
   await appendJson(senderFile, record);
   await appendJson(receiverFile, record);
@@ -5460,12 +5688,12 @@ async function handoffRole(root, input) {
     });
   } catch {
     await appendJson(receiverFile, { type: "bad_call", roleId: to });
-    return fail7("", runId);
+    return fail8("", runId);
   }
   const parsed = parseReply(raw);
   if (!parsed) {
     await appendJson(receiverFile, { type: "bad_call", roleId: to });
-    return fail7("", runId);
+    return fail8("", runId);
   }
   await appendJson(receiverFile, { type: "model", pass: 1, roleId: to, text: parsed.text });
   const settled = await settleRoleReply(root, receiverFile, receiver, parsed, now, runId);
@@ -5482,7 +5710,7 @@ async function handoffRole(root, input) {
 }
 async function showRoleGroup(root, changeId) {
   const path = safeChangeId2(changeId) ? await acceptedFile(root, changeId) : "";
-  if (!path || !await pathExists(path)) return ok7("No roles in this group.");
+  if (!path || !await pathExists(path)) return ok8("No roles in this group.");
   const seen = /* @__PURE__ */ new Set();
   const owners = [];
   for (const section of factsFrom(await readText(path))) {
@@ -5492,7 +5720,7 @@ async function showRoleGroup(root, changeId) {
       owners.push(owner);
     }
   }
-  return ok7(owners.length > 0 ? owners.join("\n") : "No roles in this group.");
+  return ok8(owners.length > 0 ? owners.join("\n") : "No roles in this group.");
 }
 function distinctServices(all) {
   const services = /* @__PURE__ */ new Map();
@@ -5620,20 +5848,20 @@ function leadPrompt(task, services) {
 }
 async function connectionResult(root, changeId, section, now) {
   const messaging = await messagingOn(root);
-  if (messaging === "invalid") return fail7(ROLE_TEXT.badYaml);
-  if (!messaging) return ok7("Messaging between roles is off.");
+  if (messaging === "invalid") return fail8(ROLE_TEXT.badYaml);
+  if (!messaging) return ok8("Messaging between roles is off.");
   const owners = unique(section.owners);
   const runId = runIdFrom(now);
   for (let i = 0; i < owners.length - 1; i++) {
     const from = owners[i] ?? "";
     const to = owners[i + 1] ?? "";
     const record = handoffRecord(from, to, changeId, section);
-    await appendJson(join16(conversationDir(root, from), `${runId}.jsonl`), record);
-    await appendJson(join16(conversationDir(root, to), `${runId}.jsonl`), record);
+    await appendJson(join17(conversationDir(root, from), `${runId}.jsonl`), record);
+    await appendJson(join17(conversationDir(root, to), `${runId}.jsonl`), record);
     await writeHandoffInboxes(root, record);
   }
   const lines = ["Connection hands off. Lead is absent.", ...owners];
-  return ok7(lines.join("\n"));
+  return ok8(lines.join("\n"));
 }
 function freshPlan(task, nodes) {
   return { status: "pending", rebuilds: 0, stalled: false, task, nodes, results: [] };
@@ -5642,7 +5870,7 @@ async function planNetwork(root, input) {
   const changeId = input.change?.trim() ?? "";
   const sectionId = input.section?.trim() ?? "";
   const loaded = await acceptedFacts(root, changeId, sectionId);
-  if (!loaded) return fail7(ROLE_TEXT.needsSection);
+  if (!loaded) return fail8(ROLE_TEXT.needsSection);
   const task = input.task ?? "";
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const connection = loaded.all.find(
@@ -5650,23 +5878,23 @@ async function planNetwork(root, input) {
   );
   if (connection?.connection) return connectionResult(root, changeId, connection, now);
   const services = distinctServices(loaded.all);
-  if (services.size === 0) return ok7("One scope. No lead.");
+  if (services.size === 0) return ok8("One scope. No lead.");
   if (services.size === 1) {
     const entry = [...services.entries()][0];
-    if (!entry) return ok7("One scope. No lead.");
+    if (!entry) return ok8("One scope. No lead.");
     const [name, section] = entry;
     const owner = section.owners[0];
-    if (!owner) return fail7("This service needs an owner.");
-    if (!await readRole(root, owner)) return fail7(ROLE_TEXT.notFound);
-    return ok7(`Service ${name} runs ${owner}.`);
+    if (!owner) return fail8("This service needs an owner.");
+    if (!await readRole(root, owner)) return fail8(ROLE_TEXT.notFound);
+    return ok8(`Service ${name} runs ${owner}.`);
   }
   const picked = await pickLead(root, loaded.all, services);
-  if (picked.kind === "none") return ok7("One scope. No lead.");
-  if (picked.kind === "missing") return fail7(picked.sentence);
+  if (picked.kind === "none") return ok8("One scope. No lead.");
+  if (picked.kind === "missing") return fail8(picked.sentence);
   const lead = await readRole(root, picked.name);
-  if (!lead) return fail7(ROLE_TEXT.notFound);
-  if (await messagingOn(root) === "invalid") return fail7(ROLE_TEXT.badYaml);
-  if (!input.model) return fail7(ROLE_TEXT.noModel);
+  if (!lead) return fail8(ROLE_TEXT.notFound);
+  if (await messagingOn(root) === "invalid") return fail8(ROLE_TEXT.badYaml);
+  if (!input.model) return fail8(ROLE_TEXT.noModel);
   return storeLeadPlan(
     root,
     changeId,
@@ -5684,17 +5912,17 @@ async function storeLeadPlan(root, changeId, sectionId, task, lead, services, al
   try {
     raw = await model.complete({ roleId: lead.name, prompt: leadPrompt(task, services) });
   } catch {
-    return fail7("");
+    return fail8("");
   }
   const parsed = await parsePlan(root, raw, contextOf(all));
-  if (previous && (parsed === "invalid" || parsed === "deep")) return fail7(planFailure(parsed));
-  if (parsed === "invalid") return fail7("The plan is not valid.");
-  if (parsed === "deep") return fail7("A plan is deeper than 2.");
+  if (previous && (parsed === "invalid" || parsed === "deep")) return fail8(planFailure(parsed));
+  if (parsed === "invalid") return fail8("The plan is not valid.");
+  if (parsed === "deep") return fail8("A plan is deeper than 2.");
   if (previous && sameArtifacts(previous.nodes, parsed)) {
     previous.stalled = true;
     previous.rebuilds += 1;
     await writePlan(root, changeId, sectionId, previous);
-    return ok7("Stopped. The plan made no progress.");
+    return ok8("Stopped. The plan made no progress.");
   }
   const next = previous ? {
     ...previous,
@@ -5705,7 +5933,7 @@ async function storeLeadPlan(root, changeId, sectionId, task, lead, services, al
     results: []
   } : freshPlan(task, parsed);
   await writePlan(root, changeId, sectionId, next);
-  return ok7(["Accept this plan before anyone writes.", ...planLines(parsed)].join("\n"));
+  return ok8(["Accept this plan before anyone writes.", ...planLines(parsed)].join("\n"));
 }
 function planFailure(parsed) {
   return parsed === "deep" ? "A plan is deeper than 2." : "The plan is not valid.";
@@ -5718,13 +5946,13 @@ function sameArtifacts(left, right) {
 async function acceptNetwork(root, input) {
   const changeId = input.change?.trim() ?? "";
   const sectionId = input.section?.trim() ?? "";
-  if (!safeChangeId2(changeId) || !sectionId) return fail7("No plan is stored.");
+  if (!safeChangeId2(changeId) || !sectionId) return fail8("No plan is stored.");
   const plan = await readPlan(root, changeId, sectionId);
-  if (!plan) return fail7("No plan is stored.");
-  if (plan.status !== "pending") return fail7("The plan is not waiting for acceptance.");
+  if (!plan) return fail8("No plan is stored.");
+  if (plan.status !== "pending") return fail8("The plan is not waiting for acceptance.");
   plan.status = "accepted";
   await writePlan(root, changeId, sectionId, plan);
-  return ok7("Plan accepted.");
+  return ok8("Plan accepted.");
 }
 function walk(nodes) {
   const flat = [];
@@ -5745,16 +5973,16 @@ function ready(node, results) {
 async function runNetwork(root, input) {
   const changeId = input.change?.trim() ?? "";
   const sectionId = input.section?.trim() ?? "";
-  if (!safeChangeId2(changeId) || !sectionId) return fail7("No plan is stored.");
+  if (!safeChangeId2(changeId) || !sectionId) return fail8("No plan is stored.");
   const plan = await readPlan(root, changeId, sectionId);
-  if (!plan) return fail7("No plan is stored.");
-  if (plan.status === "pending") return ok7("Accept this plan before anyone writes.");
-  if (plan.status === "done") return ok7("The parent is done.");
-  if (plan.status !== "accepted" && plan.status !== "open") return fail7("No plan is stored.");
-  if (await messagingOn(root) === "invalid") return fail7(ROLE_TEXT.badYaml);
+  if (!plan) return fail8("No plan is stored.");
+  if (plan.status === "pending") return ok8("Accept this plan before anyone writes.");
+  if (plan.status === "done") return ok8("The parent is done.");
+  if (plan.status !== "accepted" && plan.status !== "open") return fail8("No plan is stored.");
+  if (await messagingOn(root) === "invalid") return fail8(ROLE_TEXT.badYaml);
   const minutes = await timeoutMinutes(root);
-  if (minutes === "invalid") return fail7(ROLE_TEXT.badYaml);
-  if (!input.model) return fail7(ROLE_TEXT.noModel);
+  if (minutes === "invalid") return fail8(ROLE_TEXT.badYaml);
+  if (!input.model) return fail8(ROLE_TEXT.noModel);
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   const summaries = [];
   const called = /* @__PURE__ */ new Set();
@@ -5774,7 +6002,7 @@ async function runNetwork(root, input) {
       const when = new Date(now.getTime() + index * 1e3);
       index += 1;
       const runId = runIdFrom(when);
-      const file = join16(conversationDir(root, owner.name), `${runId}.jsonl`);
+      const file = join17(conversationDir(root, owner.name), `${runId}.jsonl`);
       let raw;
       try {
         raw = await input.model.complete({
@@ -5818,7 +6046,7 @@ async function runNetwork(root, input) {
   const waiting = all.some((node) => !plan.results.some((item) => item.decision === node.decision));
   plan.status = waiting ? "open" : "done";
   await writePlan(root, changeId, sectionId, plan);
-  if (missingOwner) return fail7(ROLE_TEXT.notFound);
+  if (missingOwner) return fail8(ROLE_TEXT.notFound);
   const lines = [...summaries];
   if (waiting) {
     lines.push("A branch is waiting for its prerequisites.");
@@ -5826,25 +6054,25 @@ async function runNetwork(root, input) {
   } else {
     lines.push("The parent is done.");
   }
-  return ok7(lines.join("\n"));
+  return ok8(lines.join("\n"));
 }
 async function rebuildNetwork(root, input) {
   const changeId = input.change?.trim() ?? "";
   const sectionId = input.section?.trim() ?? "";
-  if (!safeChangeId2(changeId) || !sectionId) return fail7("No plan is stored.");
+  if (!safeChangeId2(changeId) || !sectionId) return fail8("No plan is stored.");
   const plan = await readPlan(root, changeId, sectionId);
-  if (!plan) return fail7("No plan is stored.");
+  if (!plan) return fail8("No plan is stored.");
   const allowed = plan.rebuilds === 0 || plan.rebuilds === 1 && !plan.stalled && plan.status === "accepted";
-  if (!allowed) return fail7("A second rebuild does not start.");
+  if (!allowed) return fail8("A second rebuild does not start.");
   const loaded = await acceptedFacts(root, changeId, sectionId);
-  if (!loaded) return fail7(ROLE_TEXT.needsSection);
-  if (!input.model) return fail7(ROLE_TEXT.noModel);
+  if (!loaded) return fail8(ROLE_TEXT.needsSection);
+  if (!input.model) return fail8(ROLE_TEXT.noModel);
   const services = distinctServices(loaded.all);
   const picked = await pickLead(root, loaded.all, services);
-  if (picked.kind === "missing") return fail7(picked.sentence);
-  if (picked.kind !== "lead") return fail7("This module needs a lead.");
+  if (picked.kind === "missing") return fail8(picked.sentence);
+  if (picked.kind !== "lead") return fail8("This module needs a lead.");
   const lead = await readRole(root, picked.name);
-  if (!lead) return fail7(ROLE_TEXT.notFound);
+  if (!lead) return fail8(ROLE_TEXT.notFound);
   const before = JSON.stringify(plan);
   const result2 = await storeLeadPlan(
     root,
@@ -5911,6 +6139,378 @@ async function pickLead(root, all, services) {
   return { kind: "none" };
 }
 
+// src/role/guide.ts
+import { join as join18 } from "pathe";
+var PLANNING = /* @__PURE__ */ new Set([
+  "intent",
+  "vision",
+  "requirements",
+  "feature",
+  "stories",
+  "clarify_intent",
+  "brainstorm",
+  "hl_arb",
+  "research",
+  "outcome",
+  "plan"
+]);
+var ARCHITECTURE = /* @__PURE__ */ new Set([
+  "design",
+  "architecture",
+  "clarify_design",
+  "lld",
+  "db_design",
+  "code_research"
+]);
+var CONSTRUCTION = /* @__PURE__ */ new Set([
+  "tasks",
+  "clarify_tasks",
+  "implement",
+  "local_verify",
+  "acceptance",
+  "pr_review"
+]);
+var DUTIES = [
+  {
+    name: "planner",
+    label: "Planner",
+    job: "Plan the change",
+    bucket: "planning",
+    owns: ["the request", "the plan"],
+    skills: ["plan the change"],
+    never: ["accept a spec", "write product code"],
+    askHumanWhen: ["Who is this for?", "How will you know it worked?"],
+    description: "The planner proposes. The person decides."
+  },
+  {
+    name: "architect",
+    label: "Architect",
+    job: "Name the modules",
+    bucket: "architecture",
+    owns: ["the design"],
+    skills: ["name the modules"],
+    never: ["accept a spec", "write product code"],
+    askHumanWhen: ["Which module owns this change?"],
+    description: "The architect names the modules. The person decides."
+  },
+  {
+    name: "builder",
+    label: "Builder",
+    job: "Build the change",
+    bucket: "construction",
+    owns: ["the change pack"],
+    skills: ["build the change"],
+    never: ["accept a spec", "generate a release"],
+    askHumanWhen: [],
+    description: "The builder builds the change. The person decides."
+  }
+];
+function ok9(stdout) {
+  return { exitCode: 0, stdout };
+}
+function fail9(stdout) {
+  return { exitCode: 1, stdout };
+}
+function statePath(root) {
+  return join18(root, ".sdd", "role-runs", "guide.yaml");
+}
+function dutyForStage(id, allIds) {
+  if (PLANNING.has(id)) return "planning";
+  if (ARCHITECTURE.has(id)) return "architecture";
+  if (CONSTRUCTION.has(id)) return "construction";
+  const index = allIds.indexOf(id);
+  const archAt = allIds.findIndex((item) => ARCHITECTURE.has(item));
+  const buildAt = allIds.findIndex((item) => CONSTRUCTION.has(item));
+  if (archAt >= 0 && index >= 0 && index < archAt) return "planning";
+  if (buildAt >= 0 && index >= buildAt) return "construction";
+  if (archAt >= 0 && (buildAt < 0 || index < buildAt)) return "architecture";
+  const third = Math.max(1, Math.ceil(allIds.length / 3));
+  if (index < third) return "planning";
+  if (index < third * 2) return "architecture";
+  return "construction";
+}
+function asText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function parseState(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const rec = value;
+  const change = asText(rec.change);
+  const request = asText(rec.request);
+  if (!change || !request || !Array.isArray(rec.answers)) return null;
+  const answers = [];
+  for (const item of rec.answers) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const row = item;
+    const role = asText(row.role);
+    const question = asText(row.question);
+    const answer = asText(row.answer);
+    if (!role || !question || !answer) return null;
+    answers.push({ role, question, answer });
+  }
+  let pending;
+  if (rec.pending !== void 0) {
+    if (!rec.pending || typeof rec.pending !== "object" || Array.isArray(rec.pending)) return null;
+    const row = rec.pending;
+    const role = asText(row.role);
+    const question = asText(row.question);
+    const kind = row.kind === "model" ? "model" : row.kind === "role" ? "role" : "";
+    if (!role || !question || !kind) return null;
+    pending = { role, kind, question };
+  }
+  const state = { change, request, answers };
+  if (pending) state.pending = pending;
+  return state;
+}
+async function readState(root) {
+  const path = statePath(root);
+  if (!await pathExists(path)) return null;
+  try {
+    const parsed = parseState(await readYaml(path));
+    return parsed ?? "invalid";
+  } catch {
+    return "invalid";
+  }
+}
+async function writeState(root, state) {
+  await ensureDir(join18(root, ".sdd", "role-runs"));
+  const body = {
+    change: state.change,
+    request: state.request,
+    answers: state.answers
+  };
+  if (state.pending) body.pending = state.pending;
+  await writeYaml(statePath(root), body);
+}
+function questionText(role, question) {
+  return [`Question:`, `${role} asks:`, question, `Answer with: sdd go --answer "..."`.trim()].join(
+    "\n"
+  );
+}
+function nextRoleQuestion(role, answers) {
+  const answered = new Set(
+    answers.filter((item) => item.role === role.name).map((item) => item.question)
+  );
+  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"));
+}
+async function prepareGuide(root, input = {}) {
+  const workflowName = input.workflow?.trim() || "feature";
+  try {
+    if (!await isInitialized(root)) {
+      await initProject({ projectRoot: root, agents: input.agents ?? false });
+    }
+    const workflow = await loadWorkflow(root, workflowName);
+    const ids = workflow.stages.map((stage) => stage.id);
+    const existing = await roleFiles(root);
+    if (existing.length === 0) {
+      for (const duty of DUTIES) {
+        const { bucket, ...role } = duty;
+        const stages = ids.filter((id) => dutyForStage(id, ids) === bucket);
+        const created = await createRole(root, { ...role, stages });
+        if (created.exitCode !== 0) return created;
+      }
+    }
+    const lines = ["Ready.", `Workflow: ${workflowName}.`];
+    if (existing.length > 0) {
+      lines.push("Roles are already here.");
+    } else {
+      for (const duty of DUTIES) {
+        const stages = ids.filter((id) => dutyForStage(id, ids) === duty.bucket);
+        lines.push(`${duty.name}: ${stages.join(", ") || "no stage on this workflow"}`);
+      }
+    }
+    lines.push('Next: sdd go "what you want to build"');
+    return ok9(lines.join("\n"));
+  } catch (error) {
+    return fail9(error instanceof Error ? error.message : String(error));
+  }
+}
+async function writeDraft(ctxPath, stage, role, text2, request) {
+  const body = [
+    `# ${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;
+    }
+    await writeText(abs, body);
+  }
+}
+function optionalStage(stage) {
+  return stage.optional || stage.kind === "clarify" || stage.kind === "brainstorm";
+}
+async function runGuide(root, input = {}) {
+  const prepared = await prepareGuide(root, {
+    workflow: input.workflow,
+    agents: input.agents
+  });
+  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.");
+  let loaded;
+  try {
+    loaded = await readState(root);
+  } catch (error) {
+    return fail9(error instanceof Error ? error.message : String(error));
+  }
+  if (loaded === "invalid") return fail9("The guide file is invalid.");
+  const config = await loadConfig(root);
+  let state = loaded;
+  if (title) {
+    try {
+      const ctx = await createChange({
+        projectRoot: root,
+        config,
+        title,
+        workflowName: input.workflow?.trim() || "feature"
+      });
+      state = { change: ctx.id, request: title, answers: [] };
+      await writeState(root, state);
+    } catch (error) {
+      return fail9(error instanceof Error ? error.message : String(error));
+    }
+  } else if (!state) {
+    const active = await getActiveChangeId(root, config);
+    if (!active) return prepared;
+    try {
+      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));
+    }
+  }
+  if (answer && !state.pending) return fail9("No question is waiting.");
+  if (answer && state.pending) {
+    state.answers.push({
+      role: state.pending.role,
+      question: state.pending.question,
+      answer
+    });
+    state.pending = void 0;
+    await writeState(root, state);
+  } else if (state.pending) {
+    return ok9(questionText(state.pending.role, state.pending.question));
+  }
+  const lines = [];
+  let lastRole = "";
+  for (let step = 0; step < 16; step++) {
+    let ctx;
+    try {
+      ctx = await buildContext(root, config, state.change);
+    } catch (error) {
+      return fail9(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 (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));
+      }
+      const after = await buildContext(root, config, state.change);
+      if (after.meta.stage === before) return fail9("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.match.kind === "ask") {
+      return ok9(["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 (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(
+        [
+          "Question:",
+          ...lines,
+          `${role.name} asks:`,
+          question,
+          'Answer with: sdd go --answer "..."'
+        ].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 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")
+      );
+    }
+    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"));
+    }
+  }
+  return fail9("The guide stopped after 16 steps.");
+}
+
 // src/role/models/show.ts
 function formatModelChoice(workType, choice) {
   return `${workType}  ${choice.id}  ${choice.kind}  ${choice.provider}  ${choice.why}`;
@@ -5949,7 +6549,7 @@ function explainModel(config, workType, ctx) {
 }
 
 // src/stories.ts
-import { join as join17 } from "pathe";
+import { join as join19 } from "pathe";
 var STORY_ID = /^S-\d+$/i;
 var EPIC_KEY = /^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/;
 function validBranchName(name) {
@@ -5991,7 +6591,7 @@ function parseStoryDraft(input) {
 async function metasIn(dir) {
   const out = [];
   for (const id of await listDirs(dir)) {
-    const path = join17(dir, id, "meta.yaml");
+    const path = join19(dir, id, "meta.yaml");
     if (!await pathExists(path)) continue;
     try {
       out.push(ChangeMetaSchema.parse(await readYaml(path)));
@@ -6212,6 +6812,7 @@ export {
   displayChangePath,
   domainsDir,
   duplicateRole,
+  dutyForStage,
   editRole,
   embedSearchQuery,
   emptyChangeMetrics,
@@ -6324,6 +6925,7 @@ export {
   planAgentIntegration,
   planNetwork,
   postRoom,
+  prepareGuide,
   productTeamHome,
   promoteGreenfieldToMemory,
   queueRole,
@@ -6365,8 +6967,10 @@ export {
   resolveSearchProvider,
   resolveStages,
   reviewRoom,
+  roleContextBody,
   routeRole,
   rrf,
+  runGuide,
   runLocalVerify,
   runLoop,
   runNetwork,
@@ -6382,6 +6986,7 @@ export {
   selectModel,
   setActiveChange,
   setFact,
+  setRoleContext,
   setRoleMessaging,
   shouldAutoSkip,
   showFact,