@structured-vibe-coding/core 0.17.2 → 0.18.0

package/dist/index.js

@@ -1,22 +1,3 @@
-import {
-  advanceStage,
-  approveGate,
-  canLeaveStage,
-  completeChange,
-  createChange,
-  fallbackIncompleteStageId,
-  findFeaturesBacklogPath,
-  incompletePriorStageErrors,
-  isSubstantiveArtifactContent,
-  listBacklogFeatures,
-  parseFeaturesBacklog,
-  promoteGreenfieldToMemory,
-  skipStage,
-  startFeatureFromBacklog,
-  startGreenfield,
-  switchWorkflow,
-  updateFeatureStatus
-} from "./chunk-7JLDL2OK.js";
 import {
   SDD_CORE_VERSION,
   callMcpSourceTool,
@@ -30,7 +11,7 @@ import {
   mcpTimeoutMs,
   toProcessEnv,
   withMcpSource
-} from "./chunk-74OGSVJZ.js";
+} from "./chunk-QGP43XCN.js";
 import {
   McpConfigSchema,
   McpInvokeSchema,
@@ -45,40 +26,142 @@ import {
   mcpConfigPath,
   removeMcpSource,
   saveMcpConfig
-} from "./chunk-KYWETNFU.js";
+} from "./chunk-4BRO7BOJ.js";
 import {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
+  AgentInstallPreflightError,
   DEFAULT_INIT_INTEGRATION,
   PROTOCOL_MD,
   SDD_AGENT_ROLES,
   agentHostPaths,
   agentKickoffMessage,
+  assertAgentInstallable,
+  contentHash,
+  defaultMcpYamlPath,
+  defaultMemoryDir,
+  defaultPricesYamlPath,
+  defaultSearchYamlPath,
+  defaultTemplatesDir,
+  defaultWorkflowsDir,
+  defaultsRoot,
+  describeFsError,
+  describeKept,
+  generatedState,
   getIntegration,
   installAgentIntegration,
   installAgentIntegrations,
   integrationKeyFor,
+  loadGeneratedManifest,
   loadInstalledAgent,
+  markGenerated,
   optionForTarget,
   parseAgentTargets,
   parseIntegration,
+  planAgentIntegration,
+  reconcileGeneratedTree,
   refreshActiveAgentContext,
+  refreshConfiguredGuidance,
   removeOtherAgentHosts,
+  removeOtherAgentHostsDetailed,
+  renderAgentsMd,
+  renderMemoryIndex,
+  renderProtocolMd,
+  renderSddReadme,
   renderThinAgent,
+  saveGeneratedManifest,
   writeAgentHandoff
-} from "./chunk-P3N67UEZ.js";
+} from "./chunk-4PIRWYRA.js";
 import {
-  buildAgentPrompt,
-  formatStatus
-} from "./chunk-R5WQN4HA.js";
+  ChangeMetricsSchema,
+  PhaseMetricSchema,
+  TokenUsageMetricSchema,
+  advanceStage,
+  approveGate,
+  assertSessionLogAllowed,
+  canLeaveStage,
+  completeChange,
+  createChange,
+  emptyChangeMetrics,
+  fallbackIncompleteStageId,
+  findFeaturesBacklogPath,
+  importSessionMetrics,
+  incompletePriorStageErrors,
+  isSubstantiveArtifactContent,
+  listBacklogFeatures,
+  parseFeaturesBacklog,
+  promoteGreenfieldToMemory,
+  readChangeMetrics,
+  skipStage,
+  startFeatureFromBacklog,
+  startGreenfield,
+  startPhase,
+  switchWorkflow,
+  transitionPhase,
+  updateFeatureStatus
+} from "./chunk-LHSR7JG2.js";
 import {
+  EMBEDDINGS_UNAVAILABLE,
+  EMBEDDING_MODEL,
+  RRF_K,
+  SUMMARY_TOKEN_CAP,
+  SearchConfigError,
+  budgetForStage,
+  buildAgentPrompt,
+  buildRetrievedInner,
+  chunkCode,
+  chunkMarkdown,
+  classifyPath,
+  clearRegisteredSearchProviders,
+  countTokens,
+  createBuiltinProvider,
+  createFastembedEmbedder,
   defaultConfig,
+  embedSearchQuery,
+  executeSearch,
+  extractiveSummary,
+  fallbackWarning,
+  fastembedImportCount,
+  formatStatus,
+  ftsTokens,
+  fuseByRank,
+  fuseHits,
+  getHeadSha,
+  isHardDenied,
+  isIgnoredPath,
   isInitialized,
+  isPrunedDir,
+  isSecretPath,
+  keywordHits,
+  listScopeHits,
   loadConfig,
-  saveConfig
-} from "./chunk-WHDG6OTG.js";
+  loadExcluder,
+  loadSearchConfig,
+  mergeConfigDefaults,
+  mergeRankedHits,
+  packHits,
+  rankScope,
+  readPackedCache,
+  registerSearchProvider,
+  renderBlock,
+  resolveActiveDirectory,
+  resolveEmbedder,
+  resolveSearchProvider,
+  rrf,
+  saveConfig,
+  scopeForPath,
+  searchPreamble,
+  writePackedCache
+} from "./chunk-44LQ5BKZ.js";
 import {
+  ArtifactDefSchema,
+  ChangeMetaSchema,
+  ConfigSchema,
+  GateSchema,
+  StageSchema,
+  VerifyCommandSchema,
+  WorkflowSchema,
   activeStages,
   buildContext,
   changeDirName,
@@ -103,16 +186,7 @@ import {
   slugify,
   todayIsoDate,
   uniqueChangeDirName
-} from "./chunk-A752UVPF.js";
-import {
-  ArtifactDefSchema,
-  ChangeMetaSchema,
-  ConfigSchema,
-  GateSchema,
-  StageSchema,
-  VerifyCommandSchema,
-  WorkflowSchema
-} from "./chunk-67AUAGNV.js";
+} from "./chunk-QHV5KZKX.js";
 import {
   SddError,
   errorMessage,
@@ -125,105 +199,557 @@ import {
   changeMetaPath,
   changePath,
   changesDir,
+  changesPathRel,
   configPath,
-  domainsDir,
-  memoryDir,
-  sddRoot,
-  templatesDir,
-  workflowsDir
-} from "./chunk-7MJYPJMR.js";
-import {
   copyDir,
   copyDirSkipExisting,
+  displayArchivePath,
+  displayChangePath,
+  domainsDir,
   ensureDir,
+  guidancePaths,
+  indexDbPath,
   listDirs,
   listFiles,
+  memoryDir,
+  memoryPathRel,
   pathExists,
   readText,
   readYaml,
   removePath,
+  sddRoot,
+  searchConfigPath,
+  templatesDir,
+  workflowsDir,
   writeText,
   writeTextIfMissing,
   writeYaml
-} from "./chunk-EPFURATC.js";
-
-// src/init.ts
-import { join as join2 } from "pathe";
+} from "./chunk-O5SP6X5R.js";
 
-// src/defaults.ts
-import { existsSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "pathe";
-function defaultsRoot() {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    join(here, "..", "defaults"),
-    // npm package: dist/../defaults
-    join(here, "defaults"),
-    // same-dir defaults if present
-    join(here, "..", "..", "defaults")
-    // src/ during some test runners
+// src/report.ts
+import { join } from "pathe";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+var RATE_SCALE = 1000000000n;
+var USD_DENOM = 1000000n * RATE_SCALE;
+var PriceCardSchema = z.object({
+  input_per_million_usd: z.number().finite().nonnegative(),
+  cache_read_per_million_usd: z.number().finite().nonnegative(),
+  cache_write_per_million_usd: z.number().finite().nonnegative(),
+  output_per_million_usd: z.number().finite().nonnegative()
+});
+var PricesSchema = z.object({
+  usd_to_inr: z.number().finite().nonnegative().default(84),
+  models: z.object({
+    default: PriceCardSchema
+  }).catchall(PriceCardSchema)
+});
+var TOKEN_HEADER = "source  phase  provider  model  requests  input  cache_read  cache_write  output  usd  inr";
+function finiteMs(startIso, endMs) {
+  const start = Date.parse(startIso);
+  if (!Number.isFinite(start) || !Number.isFinite(endMs)) return 0;
+  return Math.max(0, endMs - start);
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return "0h 0m 0s";
+  const totalSeconds = Math.floor(ms / 1e3);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor(totalSeconds % 3600 / 60);
+  const seconds = totalSeconds % 60;
+  return `${hours}h ${minutes}m ${seconds}s`;
+}
+function phaseTiming(phases, now) {
+  const nowMs = now.getTime();
+  let activeMs = 0;
+  const rows = phases.map((phase) => {
+    const endedAt = phase.endedAt;
+    const open = endedAt === void 0;
+    const active = finiteMs(phase.startedAt, open ? nowMs : Date.parse(endedAt));
+    activeMs += active;
+    return {
+      phase: phase.phase,
+      startedAt: phase.startedAt,
+      endedAt: phase.endedAt,
+      activeMs: active,
+      open
+    };
+  });
+  let waitMs = 0;
+  for (let i = 0; i < phases.length - 1; i++) {
+    const phase = phases[i];
+    const next = phases[i + 1];
+    if (!phase?.endedAt || !next) continue;
+    const gap = Date.parse(next.startedAt) - Date.parse(phase.endedAt);
+    if (Number.isFinite(gap)) waitMs += Math.max(0, gap);
+  }
+  return { activeMs, waitMs, totalMs: activeMs + waitMs, phases: rows };
+}
+function stripLeadingZeros(digits) {
+  let i = 0;
+  while (i < digits.length - 1 && digits.charCodeAt(i) === 48) i += 1;
+  return digits.slice(i);
+}
+function rateUnits(rate) {
+  if (!Number.isFinite(rate) || rate < 0) throw new Error("prices.yaml is invalid");
+  let text;
+  try {
+    text = rate.toFixed(9);
+  } catch {
+    throw new Error("prices.yaml is invalid");
+  }
+  const negative = text.startsWith("-");
+  const unsigned = negative ? text.slice(1) : text;
+  const dot = unsigned.indexOf(".");
+  const whole = dot === -1 ? unsigned : unsigned.slice(0, dot);
+  const frac = dot === -1 ? "" : unsigned.slice(dot + 1, dot + 10);
+  const units = BigInt(stripLeadingZeros(`${whole}${frac.padEnd(9, "0")}`));
+  return negative ? -units : units;
+}
+function formatRatio(numerator, denominator, decimals) {
+  const negative = numerator < 0n;
+  const scale = 10n ** BigInt(decimals);
+  const num = (negative ? -numerator : numerator) * scale;
+  const quot = num / denominator;
+  const rem = num % denominator;
+  const rounded = rem * 2n >= denominator ? quot + 1n : quot;
+  const digits = rounded.toString().padStart(decimals + 1, "0");
+  const cut = digits.length - decimals;
+  return `${negative ? "-" : ""}${digits.slice(0, cut)}.${digits.slice(cut)}`;
+}
+function costFor(counts, card, usdToInr) {
+  const parts = [
+    [counts.input, card.input_per_million_usd],
+    [counts.cacheRead, card.cache_read_per_million_usd],
+    [counts.cacheWrite, card.cache_write_per_million_usd],
+    [counts.output, card.output_per_million_usd]
+  ];
+  let numerator = 0n;
+  let any = false;
+  for (const [tokens, rate] of parts) {
+    if (tokens === null) continue;
+    any = true;
+    numerator += BigInt(tokens) * rateUnits(rate);
+  }
+  if (!any) return { usd: "n/a", inr: "n/a" };
+  const inrNumerator = numerator * rateUnits(usdToInr);
+  return {
+    usd: formatRatio(numerator, USD_DENOM, 4),
+    inr: formatRatio(inrNumerator, USD_DENOM * RATE_SCALE, 2)
+  };
+}
+async function loadPrices(projectRoot) {
+  const path = join(sddRoot(projectRoot), "prices.yaml");
+  if (!await pathExists(path)) return null;
+  try {
+    return PricesSchema.parse(parseYaml(await readText(path)));
+  } catch {
+    throw new Error("prices.yaml is invalid");
+  }
+}
+function cardFor(prices, provider, model) {
+  if (model && prices.models[model]) return prices.models[model];
+  return prices.models[provider] ?? prices.models.default;
+}
+function modelCell(model) {
+  return model ? model : "n/a";
+}
+function emptyTotals() {
+  return { requests: 0, input: null, cacheRead: null, cacheWrite: null, output: null };
+}
+function addCount(current, value) {
+  if (typeof value !== "number") return current;
+  return (current ?? 0) + value;
+}
+function addRequest(totals, request) {
+  totals.requests += 1;
+  totals.input = addCount(totals.input, request.inputTokens);
+  totals.cacheRead = addCount(totals.cacheRead, request.cacheReadTokens);
+  totals.cacheWrite = addCount(totals.cacheWrite, request.cacheWriteTokens);
+  totals.output = addCount(totals.output, request.outputTokens);
+}
+function cell(value) {
+  return value === null ? "n/a" : String(value);
+}
+function tokenLine(source, phase, provider, model, totals, prices, card) {
+  const cost = prices && card ? costFor(totals, card, prices.usd_to_inr) : { usd: "n/a", inr: "n/a" };
+  return [
+    source,
+    phase,
+    provider,
+    model,
+    String(totals.requests),
+    cell(totals.input),
+    cell(totals.cacheRead),
+    cell(totals.cacheWrite),
+    cell(totals.output),
+    cost.usd,
+    cost.inr
+  ].join("  ");
+}
+function groupRequests(metrics) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const request of metrics.requests) {
+    const model = request.model ?? null;
+    const key = `${request.phase}\0${request.provider}\0${model ?? ""}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { phase: request.phase, provider: request.provider, model, totals: emptyTotals() };
+      groups.set(key, group);
+    }
+    addRequest(group.totals, request);
+  }
+  const phaseOrder = [];
+  for (const phase of metrics.phases) {
+    if (!phaseOrder.includes(phase.phase)) phaseOrder.push(phase.phase);
+  }
+  for (const request of metrics.requests) {
+    if (!phaseOrder.includes(request.phase)) phaseOrder.push(request.phase);
+  }
+  return [...groups.values()].sort((left, right) => {
+    const phaseDelta = phaseOrder.indexOf(left.phase) - phaseOrder.indexOf(right.phase);
+    if (phaseDelta !== 0) return phaseDelta;
+    const providerDelta = left.provider.localeCompare(right.provider);
+    if (providerDelta !== 0) return providerDelta;
+    return (left.model ?? "").localeCompare(right.model ?? "");
+  });
+}
+function renderChangeReport(input) {
+  const timing = phaseTiming(input.metrics.phases, input.now);
+  const lines = [
+    `Change: ${input.changeId}`,
+    `Active: ${formatDuration(timing.activeMs)}`,
+    `Human wait: ${formatDuration(timing.waitMs)}`,
+    `Total: ${formatDuration(timing.totalMs)}`,
+    "Phases:"
+  ];
+  if (timing.phases.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const phase of timing.phases) {
+      const start = new Date(phase.startedAt).toLocaleString();
+      const end = phase.open ? "in progress" : new Date(phase.endedAt ?? "").toLocaleString();
+      lines.push(`  ${phase.phase}  ${start} \u2192 ${end}  active ${formatDuration(phase.activeMs)}`);
+    }
+  }
+  lines.push("Tokens:");
+  lines.push(`  ${TOKEN_HEADER}`);
+  if (input.metrics.requests.length === 0) {
+    if (input.handoffCodePoints === null) {
+      lines.push("  (none)");
+      lines.push("No estimate: .sdd/handoff.md is missing.");
+    } else {
+      const estimated = Math.floor(input.handoffCodePoints / 4);
+      lines.push(
+        `  ${tokenLine(
+          "estimated (handoff code points / 4)",
+          "n/a",
+          "default",
+          "n/a",
+          {
+            requests: 1,
+            input: estimated,
+            cacheRead: null,
+            cacheWrite: null,
+            output: null
+          },
+          input.prices,
+          input.prices?.models.default ?? null
+        )}`
+      );
+    }
+  } else {
+    for (const group of groupRequests(input.metrics)) {
+      const card = input.prices ? cardFor(input.prices, group.provider, group.model) : null;
+      lines.push(
+        `  ${tokenLine(
+          "measured",
+          group.phase,
+          group.provider,
+          modelCell(group.model),
+          group.totals,
+          input.prices,
+          card
+        )}`
+      );
+    }
+    const total = emptyTotals();
+    for (const request of input.metrics.requests) addRequest(total, request);
+    lines.push(`  ${totalLine(total, input.metrics, input.prices)}`);
+  }
+  if (input.prices === null) lines.push("prices.yaml is missing");
+  return lines.join("\n");
+}
+function requestUsdNumerator(request, card) {
+  const parts = [
+    [request.inputTokens, card.input_per_million_usd],
+    [request.cacheReadTokens, card.cache_read_per_million_usd],
+    [request.cacheWriteTokens, card.cache_write_per_million_usd],
+    [request.outputTokens, card.output_per_million_usd]
   ];
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
+  let numerator = 0n;
+  for (const [tokens, rate] of parts) {
+    if (tokens === null) continue;
+    numerator += BigInt(tokens) * rateUnits(rate);
+  }
+  return numerator;
+}
+function requestHasNumericToken(request) {
+  return request.inputTokens !== null || request.cacheReadTokens !== null || request.cacheWriteTokens !== null || request.outputTokens !== null;
+}
+function totalLine(totals, metrics, prices) {
+  if (!prices) return tokenLine("measured", "total", "all", "all", totals, null, null);
+  let numerator = 0n;
+  let any = false;
+  for (const request of metrics.requests) {
+    if (!requestHasNumericToken(request)) continue;
+    any = true;
+    numerator += requestUsdNumerator(request, cardFor(prices, request.provider, request.model));
+  }
+  const cost = !any ? { usd: "n/a", inr: "n/a" } : {
+    usd: formatRatio(numerator, USD_DENOM, 4),
+    inr: formatRatio(numerator * rateUnits(prices.usd_to_inr), USD_DENOM * RATE_SCALE, 2)
+  };
+  return [
+    "measured",
+    "total",
+    "all",
+    "all",
+    String(totals.requests),
+    cell(totals.input),
+    cell(totals.cacheRead),
+    cell(totals.cacheWrite),
+    cell(totals.output),
+    cost.usd,
+    cost.inr
+  ].join("  ");
+}
+function compareChangesByFirstPhase(left, right) {
+  if (left.invalid !== right.invalid) return left.invalid ? 1 : -1;
+  const leftStart = left.invalid ? null : left.firstStartedAt;
+  const rightStart = right.invalid ? null : right.firstStartedAt;
+  if (leftStart === null !== (rightStart === null)) return leftStart === null ? 1 : -1;
+  if (leftStart !== null && rightStart !== null && leftStart !== rightStart) {
+    return leftStart < rightStart ? -1 : 1;
+  }
+  return left.id.localeCompare(right.id);
+}
+async function readHandoffCodePoints(projectRoot) {
+  try {
+    const text = await readText(join(sddRoot(projectRoot), "handoff.md"));
+    return Array.from(text).length;
+  } catch (err) {
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+    if (code === "ENOENT") return null;
+    throw new Error("Could not read .sdd/handoff.md.");
   }
-  return candidates[0];
 }
-function defaultWorkflowsDir() {
-  return join(defaultsRoot(), "workflows");
+async function readReportMetrics(path) {
+  if (!await pathExists(path)) return { status: "missing" };
+  try {
+    return { status: "ok", metrics: ChangeMetricsSchema.parse(JSON.parse(await readText(path))) };
+  } catch {
+    return { status: "invalid" };
+  }
 }
-function defaultTemplatesDir() {
-  return join(defaultsRoot(), "templates");
+async function reportChange(input) {
+  const found = await readReportMetrics(
+    join(changePath(input.projectRoot, input.config, input.changeId), "metrics.json")
+  );
+  if (found.status === "invalid") throw new Error("metrics.json is invalid");
+  const metrics = found.status === "ok" ? found.metrics : emptyChangeMetrics();
+  const handoffCodePoints = metrics.requests.length === 0 ? await readHandoffCodePoints(input.projectRoot) : null;
+  return renderChangeReport({
+    changeId: input.changeId,
+    metrics,
+    prices: input.prices,
+    handoffCodePoints,
+    now: input.now
+  });
 }
-function defaultMemoryDir() {
-  return join(defaultsRoot(), "memory");
+async function reportAllChanges(projectRoot, config, prices, now) {
+  const ids = await listDirs(changesDir(projectRoot, config));
+  const blocks = [];
+  let handoff;
+  for (const id of ids) {
+    const found = await readReportMetrics(
+      join(changePath(projectRoot, config, id), "metrics.json")
+    );
+    if (found.status === "missing") continue;
+    if (found.status === "invalid") {
+      blocks.push({
+        id,
+        invalid: true,
+        firstStartedAt: null,
+        text: `Change: ${id}
+metrics.json is invalid`
+      });
+      continue;
+    }
+    let handoffCodePoints = null;
+    if (found.metrics.requests.length === 0) {
+      if (handoff === void 0) handoff = await readHandoffCodePoints(projectRoot);
+      handoffCodePoints = handoff;
+    }
+    blocks.push({
+      id,
+      invalid: false,
+      firstStartedAt: found.metrics.phases[0]?.startedAt ?? null,
+      text: renderChangeReport({
+        changeId: id,
+        metrics: found.metrics,
+        prices,
+        handoffCodePoints,
+        now
+      })
+    });
+  }
+  if (!blocks.length) return "No change metrics found.";
+  blocks.sort(compareChangesByFirstPhase);
+  return blocks.map((block) => block.text).join("\n\n");
 }
-function defaultMcpYamlPath() {
-  return join(defaultsRoot(), "mcp.yaml");
+
+// src/sync.ts
+import { join as join2 } from "pathe";
+var VERIFY_MARKER = /<!-- sdd:verify stage="([^"]+)" head_sha="(?:none|[0-9a-f]{40}|[0-9a-f]{64})" result_count="(\d+)" -->/gi;
+async function syncChangeHead(projectRoot, config, changeId, opts) {
+  const headSha = opts?.headSha !== void 0 ? opts.headSha : await getHeadSha(projectRoot);
+  if (!headSha) throw new Error("Cannot sync: Git HEAD is unavailable in this project.");
+  const ctx = await buildContext(projectRoot, config, changeId);
+  let updatedResults = 0;
+  for (const result of Object.values(ctx.meta.verify_results ?? {})) {
+    if (!result.results.length || result.head_sha === headSha) continue;
+    result.head_sha = headSha;
+    updatedResults += 1;
+  }
+  if (updatedResults) await saveChangeMeta(projectRoot, config, ctx.meta);
+  const reportPath = join2(ctx.path, "local-test-results.md");
+  let reportUpdated = false;
+  let reportPreserved = false;
+  if (await pathExists(reportPath)) {
+    const report = await readText(reportPath);
+    const markers = [...report.matchAll(VERIFY_MARKER)];
+    if (markers.length) {
+      const updated = report.replace(
+        VERIFY_MARKER,
+        (_marker, stage, resultCount) => `<!-- sdd:verify stage="${stage}" head_sha="${headSha}" result_count="${resultCount}" -->`
+      );
+      if (updated !== report) {
+        await writeText(reportPath, updated);
+        reportUpdated = true;
+      }
+    } else {
+      reportPreserved = true;
+    }
+  }
+  return { changeId, headSha, updatedResults, reportUpdated, reportPreserved };
 }
 
 // src/init.ts
+import { spawn } from "child_process";
+import { lstat } from "fs/promises";
+import { join as join3 } from "pathe";
 async function initProject(opts) {
   const { projectRoot, force = false } = opts;
   const created = [];
+  const kept = [];
+  const warnings = [];
   const root = sddRoot(projectRoot);
-  if (await pathExists(join2(root, "config.yaml")) && !force) {
-    throw new Error(
-      `Already initialized (${join2(root, "config.yaml")}). Use --force to re-copy defaults.`
-    );
+  const configFile = join3(root, "config.yaml");
+  if (await pathExists(configFile) && !force) {
+    await repairRequiredIgnores(projectRoot);
+    return { created, config: await loadConfig(projectRoot), kept, warnings };
+  }
+  try {
+    const st = await lstat(root);
+    if (!st.isDirectory() && !st.isSymbolicLink()) {
+      throw new SddError(`Cannot initialize: ${root} exists and is not a directory. Move it away.`);
+    }
+  } catch (err) {
+    if (err instanceof SddError) throw err;
+  }
+  const config = await pathExists(configFile) ? mergeConfigDefaults(await readYaml(configFile)) : defaultConfig();
+  if (opts.layoutRoot !== void 0) {
+    const layoutRoot = validateLayoutRoot(opts.layoutRoot);
+    config.memory_path = join3(layoutRoot, "memory");
+    config.changes_path = join3(layoutRoot, "changes");
+    config.domains_path = join3(layoutRoot, "domains");
+    config.archive_path = join3(layoutRoot, "archive");
+  }
+  const manifestPath = join3(root, ".generated.json");
+  const manifestExisted = await pathExists(manifestPath);
+  const manifest = await loadGeneratedManifest(manifestPath);
+  if (opts.agents) {
+    await assertAgentInstallable({ projectRoot, target: opts.agents, force });
   }
-  const config = defaultConfig();
   await ensureDir(root);
   await saveConfig(projectRoot, config);
-  created.push(join2(root, "config.yaml"));
+  created.push(join3(root, "config.yaml"));
   const wfDest = workflowsDir(projectRoot);
-  await ensureDir(wfDest);
   const wfSrc = defaultWorkflowsDir();
   if (await pathExists(wfSrc)) {
-    await copyDir(wfSrc, wfDest);
+    const result = await reconcileGeneratedTree(
+      projectRoot,
+      wfSrc,
+      wfDest,
+      ".sdd/workflows",
+      manifest,
+      force
+    );
+    kept.push(...result.kept);
     created.push(wfDest);
+  } else {
+    await ensureDir(wfDest);
   }
   const tDest = templatesDir(projectRoot);
-  await ensureDir(tDest);
   const tSrc = defaultTemplatesDir();
   if (await pathExists(tSrc)) {
-    await copyDir(tSrc, tDest);
+    const result = await reconcileGeneratedTree(
+      projectRoot,
+      tSrc,
+      tDest,
+      ".sdd/templates",
+      manifest,
+      force
+    );
+    kept.push(...result.kept);
     created.push(tDest);
+  } else {
+    await ensureDir(tDest);
   }
+  await saveGeneratedManifest(manifestPath, manifest);
+  if (!manifestExisted) created.push(manifestPath);
   const mcpSrc = defaultMcpYamlPath();
   const mcpDest = mcpConfigPath(projectRoot);
   if (await pathExists(mcpSrc)) {
     const wrote = await writeTextIfMissing(mcpDest, await readText(mcpSrc));
     if (wrote) created.push(mcpDest);
   }
+  const pricesSrc = defaultPricesYamlPath();
+  const pricesDest = join3(root, "prices.yaml");
+  if (await pathExists(pricesSrc)) {
+    const wrote = await writeTextIfMissing(pricesDest, await readText(pricesSrc));
+    if (wrote) created.push(pricesDest);
+  }
+  const searchSrc = defaultSearchYamlPath();
+  const searchDest = join3(root, "search.yaml");
+  if (await pathExists(searchSrc)) {
+    const wrote = await writeTextIfMissing(searchDest, await readText(searchSrc));
+    if (wrote) created.push(searchDest);
+  }
   const mDest = memoryDir(projectRoot, config);
+  const existingMemoryFiles = await listRelativeFiles(mDest);
+  if (existingMemoryFiles.length && config.memory_path === "memory") {
+    warnings.push(
+      `Existing ${config.memory_path}/ content will be preserved. Use --root .sdd to keep SDD memory alongside the project without merging folders.`
+    );
+  }
   await ensureDir(mDest);
   const mSrc = defaultMemoryDir();
   if (await pathExists(mSrc)) {
     await copyDirSkipExisting(mSrc, mDest);
   } else {
     await writeTextIfMissing(
-      join2(mDest, "index.md"),
+      join3(mDest, "index.md"),
       `# Documentation map
 
 Parent page for **stable** project docs. Start here, then open only what you need.
@@ -235,15 +761,15 @@ Parent page for **stable** project docs. Start here, then open only what you nee
 | Architecture | [architecture.md](architecture.md) |
 | Conventions | [conventions.md](conventions.md) |
 
-Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
+Active work: \`.sdd/active-context.md\` and the configured changes folder.
 `
     );
     await writeTextIfMissing(
-      join2(mDest, "product.md"),
+      join3(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
     );
     await writeTextIfMissing(
-      join2(mDest, "constitution.md"),
+      join3(mDest, "constitution.md"),
       `# Constitution
 
 <!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
@@ -270,21 +796,21 @@ Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
 `
     );
     await writeTextIfMissing(
-      join2(mDest, "architecture.md"),
+      join3(mDest, "architecture.md"),
       "# Architecture\n\n<!-- High-level system shape -->\n"
     );
     await writeTextIfMissing(
-      join2(mDest, "conventions.md"),
+      join3(mDest, "conventions.md"),
       "# Conventions\n\n<!-- Coding and process conventions -->\n"
     );
   }
-  if (!await pathExists(join2(mDest, "constitution.md"))) {
-    const fromDefault = join2(mSrc, "constitution.md");
+  if (!await pathExists(join3(mDest, "constitution.md"))) {
+    const fromDefault = join3(mSrc, "constitution.md");
     if (await pathExists(fromDefault)) {
       await copyDirSkipExisting(mSrc, mDest);
     } else {
       await writeTextIfMissing(
-        join2(mDest, "constitution.md"),
+        join3(mDest, "constitution.md"),
         `# Constitution
 
 <!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
@@ -317,38 +843,36 @@ Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
   await ensureDir(domainsDir(projectRoot, config));
   created.push(changesDir(projectRoot, config));
   created.push(domainsDir(projectRoot, config));
-  await writeText(join2(changesDir(projectRoot, config), ".gitkeep"), "");
-  await writeText(join2(domainsDir(projectRoot, config), ".gitkeep"), "");
-  const sddReadme = join2(root, "README.md");
-  if (!await pathExists(sddReadme) || force) {
-    await writeText(
-      sddReadme,
-      `# Structured Vibe Coding (SDD)
-
-This directory configures local Spec-Driven Development for this repo.
-
-- \`config.yaml\` \u2014 project settings and per-change policy
-- \`workflows/\` \u2014 YAML workflow packs (customize freely)
-- \`templates/\` \u2014 markdown templates for stage artifacts
-- \`protocol.md\` / \`active-context.md\` \u2014 agent playbook + live task (after agent install)
-
-Work lives in \`../changes/<id>/\`. Completed packs stay there with \`status: completed\`.
-Promote lasting decisions into \`../memory/\`. (Archive-on-complete is opt-in.)
-
-**Documentation map (stable):** \`../memory/index.md\`  
-**Change-scoped docs:** \`../changes/<id>/\`
-
-## Quick commands
-
-\`\`\`bash
-sdd new "My feature"
-sdd status
-sdd next
-sdd verify
-sdd complete
-\`\`\`
-`
-    );
+  await writeTextIfMissing(join3(changesDir(projectRoot, config), ".gitkeep"), "");
+  await writeTextIfMissing(join3(domainsDir(projectRoot, config), ".gitkeep"), "");
+  const sddIgnore = join3(root, ".gitignore");
+  const changesIgnore = join3(changesDir(projectRoot, config), ".gitignore");
+  if ((await ensureIgnoreEntries(sddIgnore, SDD_IGNORE_LINES)).created) {
+    created.push(sddIgnore);
+  }
+  if ((await ensureIgnoreEntries(changesIgnore, [".active"])).created) {
+    created.push(changesIgnore);
+  }
+  const perMachine = [
+    ".sdd/active-context.md",
+    ".sdd/handoff.md",
+    ".sdd/index.db",
+    `${changesPathRel(config)}/.active`
+  ];
+  const tracked = await (opts.indexLookup ?? gitTrackedPaths)(projectRoot, perMachine);
+  if (tracked) {
+    for (const rel of tracked) {
+      warnings.push(
+        `Already tracked (gitignore will not hide edits): ${rel}. sdd does not run git rm.`
+      );
+    }
+  }
+  const sddReadme = join3(root, "README.md");
+  const readmeState = await pathExists(sddReadme) ? generatedState(await readText(sddReadme)) : null;
+  if (readmeState === "edited" || readmeState === "not-generated") {
+    kept.push({ path: ".sdd/README.md", reason: readmeState });
+  } else if (readmeState === null || force) {
+    await writeText(sddReadme, markGenerated(renderSddReadme(config)));
     created.push(sddReadme);
   }
   let agentsResult;
@@ -359,17 +883,92 @@ sdd complete
       force
     });
     created.push(...ag.created);
-    agentsResult = { created: ag.created, skipped: ag.skipped };
+    kept.push(...ag.kept);
+    agentsResult = { created: ag.created, skipped: ag.skipped, kept: ag.kept, removed: ag.removed };
+  }
+  return { created, config, kept, warnings, agents: agentsResult };
+}
+var SDD_IGNORE_LINES = [
+  "handoff.md",
+  "active-context.md",
+  "index.db",
+  "index.db-journal",
+  "index.db-wal",
+  "index.db-shm",
+  "models/",
+  "role-runs/"
+];
+async function repairRequiredIgnores(projectRoot) {
+  const config = await loadConfig(projectRoot);
+  const root = sddRoot(projectRoot);
+  const sdd = await ensureIgnoreEntries(join3(root, ".gitignore"), SDD_IGNORE_LINES);
+  const changes = await ensureIgnoreEntries(join3(changesDir(projectRoot, config), ".gitignore"), [
+    ".active"
+  ]);
+  return sdd.added || changes.added;
+}
+async function ensureIgnoreEntries(filePath, required) {
+  const existed = await pathExists(filePath);
+  const original = existed ? await readText(filePath) : "";
+  const present = new Set(
+    original.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"))
+  );
+  const missing = required.filter((line) => !present.has(line));
+  if (existed && missing.length === 0) return { created: false, added: false };
+  let next = original;
+  if (next.length > 0 && !next.endsWith("\n")) next += "\n";
+  next += missing.map((line) => `${line}
+`).join("");
+  await writeText(filePath, next);
+  return { created: !existed, added: missing.length > 0 };
+}
+function gitTrackedPaths(projectRoot, relativePaths) {
+  return new Promise((resolve) => {
+    const child = spawn("git", ["ls-files", "--", ...relativePaths], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => {
+      if (code !== 0) resolve(null);
+      else
+        resolve(
+          stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+        );
+    });
+  });
+}
+function validateLayoutRoot(value) {
+  const root = value.trim();
+  const segments = root.split(/[\\/]+/);
+  if (!root || root !== value || root.startsWith("/") || root.startsWith("\\") || /^[A-Za-z]:/.test(root) || segments.some((segment) => segment === ".." || segment === "")) {
+    throw new Error("--root must be a non-empty, project-relative path without '..' segments.");
   }
-  return { created, config, agents: agentsResult };
+  return segments.join("/");
+}
+async function listRelativeFiles(directory, prefix = "") {
+  if (!await pathExists(directory)) return [];
+  const files = (await listFiles(directory)).map(
+    (name) => [prefix, name].filter(Boolean).join("/")
+  );
+  const nested = await Promise.all(
+    (await listDirs(directory)).map(
+      (name) => listRelativeFiles(join3(directory, name), [prefix, name].filter(Boolean).join("/"))
+    )
+  );
+  return [...files, ...nested.flat()];
 }
 
 // src/verify.ts
-import { spawn } from "child_process";
-import { join as join3 } from "pathe";
+import { spawn as spawn2 } from "child_process";
+import { join as join4 } from "pathe";
 function runCommand(command, cwd) {
   return new Promise((resolve) => {
-    const child = spawn(command, {
+    const child = spawn2(command, {
       cwd,
       shell: true,
       env: process.env
@@ -392,30 +991,51 @@ function runCommand(command, cwd) {
 function isToolGeneratedResults(content) {
   const trimmed = content.trim();
   if (!trimmed) return true;
-  if (trimmed.includes("{{") || trimmed.includes("TODO")) return true;
-  if (trimmed.startsWith("# Local verify results")) return true;
+  if (trimmed.includes("{{")) return true;
+  if (trimmed.startsWith("# Local verify results")) {
+    return false;
+  }
+  if (trimmed.startsWith("<!-- sdd:verify-report:start -->")) {
+    return trimmed.includes("<!-- sdd:verify-report:end -->") && /<!-- sdd:verify stage="[^"]+" head_sha="(?:none|[0-9a-f]{40}|[0-9a-f]{64})" result_count="\d+" -->/i.test(
+      trimmed
+    );
+  }
+  if (trimmed.startsWith("# Local test results")) {
+    const body = trimmed.replace(/^# Local test results\s*/, "");
+    const filled = !body.includes("{{") && !body.includes("| 1 | PASS / FAIL |") && !/\bTODO\b/.test(body) && body.length > 80;
+    return !filled;
+  }
+  if (/\bTODO\b/.test(trimmed)) return true;
   return false;
 }
-function buildSummaryLines(title, stageId, ok, results, checklist) {
+var STATUS_LABEL = {
+  pass: "PASS",
+  fail: "FAIL",
+  not_run: "NOT RUN"
+};
+function buildSummaryLines(title, stageId, headSha, status, reason, results, checklist) {
   const lines = [
+    `<!-- sdd:verify-report:start -->`,
+    ``,
     `# Local verify results`,
     ``,
     `> Change: ${title}`,
     `> Stage: ${stageId}`,
+    `<!-- sdd:verify stage="${stageId}" head_sha="${headSha ?? "none"}" result_count="${results.length}" -->`,
     `> At: ${nowIso()}`,
-    `> Overall: ${ok ? "PASS" : "FAIL"}`,
+    `> Overall: ${STATUS_LABEL[status]}${reason ? ` \u2014 ${reason}` : ""}`,
     ``,
     `## Commands`,
     ``
   ];
   if (results.length === 0) {
-    lines.push(`_No commands configured for this stage. Complete the checklist manually._`);
+    lines.push(`_No commands ran. Complete the checklist manually._`);
     lines.push("");
   } else {
     for (const r of results) {
       lines.push(`### ${r.name}`);
       lines.push(`- Command: \`${r.command}\``);
-      lines.push(`- Exit: ${r.exitCode}`);
+      lines.push(`- Exit: ${r.exitCode}${r.exitCode === 0 ? "" : " (FAILED)"}`);
       lines.push("");
     }
   }
@@ -429,6 +1049,8 @@ function buildSummaryLines(title, stageId, ok, results, checklist) {
   lines.push("");
   lines.push(`-`);
   lines.push("");
+  lines.push(`<!-- sdd:verify-report:end -->`);
+  lines.push("");
   return lines;
 }
 async function runLocalVerify(projectRoot, config, changeId, opts) {
@@ -437,8 +1059,73 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
   if (!stage) {
     throw new Error(`Unknown stage: ${ctx.meta.stage}`);
   }
+  if (!stage.verify) {
+    const verifyStage = ctx.workflow.stages.find((st) => st.verify);
+    return {
+      stageId: stage.id,
+      status: "not_run",
+      reason: verifyStage ? `stage "${stage.id}" has no verify step; run sdd verify on "${verifyStage.id}"` : `workflow "${ctx.workflow.name}" has no verify step`,
+      results: [],
+      checklist: [],
+      evidencePath: null,
+      resultsPath: null,
+      ok: false
+    };
+  }
+  const headSha = opts?.headSha !== void 0 ? opts.headSha : await getHeadSha(projectRoot);
+  const anyRecordedSha = Object.entries(ctx.meta.verify_results ?? {}).find(
+    ([, recorded]) => recorded.head_sha
+  );
+  if (anyRecordedSha && !headSha) {
+    throw new Error(
+      `Cannot validate recorded SHA in ${join4(ctx.path, "meta.yaml")} at verify_results.${anyRecordedSha[0]}.head_sha because Git HEAD is unavailable.`
+    );
+  }
+  for (const [resultStage, recorded] of Object.entries(ctx.meta.verify_results ?? {})) {
+    if (recorded.head_sha && headSha && recorded.head_sha !== headSha) {
+      throw new Error(
+        `Stale SHA in ${join4(ctx.path, "meta.yaml")} at verify_results.${resultStage}.head_sha: recorded ${recorded.head_sha}, current HEAD ${headSha}. Run sdd sync ${changeId}.`
+      );
+    }
+  }
+  const summaryPath = join4(ctx.path, "local-test-results.md");
+  if (await pathExists(summaryPath)) {
+    const existing = await readText(summaryPath);
+    const markerPattern = /<!-- sdd:verify stage="([^"]+)" head_sha="(none|[0-9a-f]{40}|[0-9a-f]{64})" result_count="(\d+)" -->/gi;
+    for (const marker of existing.matchAll(markerPattern)) {
+      const line = existing.slice(0, marker.index).split("\n").length;
+      const reportStage = marker[1];
+      const reportSha = marker[2].toLowerCase();
+      const reportResult = ctx.meta.verify_results?.[reportStage];
+      if (!reportResult) {
+        throw new Error(
+          `Missing verification metadata in ${join4(ctx.path, "meta.yaml")} for ${summaryPath}:${line} (${reportStage}).`
+        );
+      }
+      if (reportSha !== "none" && !headSha) {
+        throw new Error(
+          `Cannot validate SHA in ${summaryPath}:${line} because Git HEAD is unavailable.`
+        );
+      }
+      if (headSha && reportSha !== "none" && reportSha !== headSha) {
+        throw new Error(
+          `Stale SHA in ${summaryPath}:${line}: recorded ${reportSha}, current HEAD ${headSha}. Run sdd sync ${changeId}.`
+        );
+      }
+      if (reportResult && Number(marker[3]) !== reportResult.results.length) {
+        throw new Error(
+          `Recorded result count mismatch in ${summaryPath}:${line}: report has ${marker[3]}, metadata has ${reportResult.results.length}.`
+        );
+      }
+      if (reportResult?.head_sha && reportSha !== reportResult.head_sha) {
+        throw new Error(
+          `SHA mismatch between ${join4(ctx.path, "meta.yaml")} and ${summaryPath}:${line}.`
+        );
+      }
+    }
+  }
   const evidenceDirRaw = stage.verify?.evidence_dir?.trim();
-  const evidenceDir = evidenceDirRaw && evidenceDirRaw.length > 0 ? join3(ctx.path, evidenceDirRaw) : null;
+  const evidenceDir = evidenceDirRaw && evidenceDirRaw.length > 0 ? join4(ctx.path, evidenceDirRaw) : null;
   if (evidenceDir) {
     await ensureDir(evidenceDir);
   }
@@ -455,7 +1142,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
         output: output.slice(0, 5e4)
       });
       if (evidenceDir) {
-        const logPath = join3(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+        const logPath = join4(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
         await writeText(logPath, `# ${cmd.name}
 $ ${cmd.run}
 exit: ${exitCode}
@@ -464,28 +1151,36 @@ ${output}`);
       }
     }
   }
-  const required = commands.filter((c) => c.required);
-  let ok = true;
-  if (required.length) {
-    if (!runCommands) {
-      ok = false;
-    } else {
-      for (const cmd of required) {
-        const r = results.find((x) => x.name === cmd.name);
-        if (!r || r.exitCode !== 0) ok = false;
-      }
-    }
-  } else if (commands.length && runCommands) {
-    ok = results.every((r) => r.exitCode === 0);
+  let status;
+  let reason;
+  if (!commands.length) {
+    status = "not_run";
+    reason = `no verify commands configured for stage "${stage.id}"`;
+  } else if (!runCommands) {
+    status = "not_run";
+    reason = "commands not run (--no-run)";
+  } else {
+    const failed = results.filter((r) => r.exitCode !== 0).map((r) => r.name);
+    status = failed.length ? "fail" : "pass";
+    reason = failed.length ? `failed: ${failed.join(", ")}` : void 0;
   }
+  const ok4 = status === "pass";
   const checklist = stage.gate?.checklist ?? [];
-  const summaryPath = join3(ctx.path, "local-test-results.md");
-  const lines = buildSummaryLines(ctx.meta.title, stage.id, ok, results, checklist);
+  const lines = buildSummaryLines(
+    ctx.meta.title,
+    stage.id,
+    results.length ? headSha : null,
+    status,
+    reason,
+    results,
+    checklist
+  );
   const summaryBody = lines.join("\n");
   if (await pathExists(summaryPath)) {
     const existing = await readText(summaryPath);
     if (isToolGeneratedResults(existing)) {
       await writeText(summaryPath, summaryBody);
+    } else if (results.length === 0) {
     } else {
       const stamp = nowIso();
       const append = [
@@ -494,12 +1189,13 @@ ${output}`);
         ``,
         `## Latest run (${stamp})`,
         ``,
-        `> Overall: ${ok ? "PASS" : "FAIL"}`,
+        `> Overall: ${STATUS_LABEL[status]}${reason ? ` \u2014 ${reason}` : ""}`,
         `> Stage: ${stage.id}`,
+        `<!-- sdd:verify stage="${stage.id}" head_sha="${results.length ? headSha ?? "none" : "none"}" result_count="${results.length}" -->`,
         ``
       ];
       if (results.length === 0) {
-        append.push(`_No commands configured for this stage._`);
+        append.push(`_No commands ran._`);
         append.push("");
       } else {
         for (const r of results) {
@@ -511,7 +1207,7 @@ ${output}`);
     }
     if (evidenceDir) {
       const stamp = nowIso();
-      await writeText(join3(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`), summaryBody);
+      await writeText(join4(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`), summaryBody);
     }
   } else {
     await writeText(summaryPath, summaryBody);
@@ -519,7 +1215,9 @@ ${output}`);
   ctx.meta.verify_results = {
     ...ctx.meta.verify_results,
     [stage.id]: {
-      ok,
+      ok: ok4,
+      status,
+      ...results.length && headSha ? { head_sha: headSha } : {},
       at: nowIso(),
       results: results.map((r) => ({ name: r.name, exitCode: r.exitCode }))
     }
@@ -527,304 +1225,23 @@ ${output}`);
   await saveChangeMeta(projectRoot, config, ctx.meta);
   return {
     stageId: stage.id,
+    status,
+    reason,
     results,
     checklist,
     evidencePath: evidenceDir,
-    ok
+    resultsPath: summaryPath,
+    ok: ok4
   };
 }
 
 // src/code-context/index.ts
-import { extname as extname4, join as join6, normalize as normalize5 } from "pathe";
-
-// src/code-context/adapters/registry.ts
-import { extname as extname2 } from "pathe";
-
-// src/code-context/adapters/typescript.ts
-import { extname } from "pathe";
-import ts from "typescript";
-var TS_JS_EXTENSIONS = [
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".mts",
-  ".cts",
-  ".mjs",
-  ".cjs"
-];
-function scriptKindForPath(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  switch (ext) {
-    case ".tsx":
-      return ts.ScriptKind.TSX;
-    case ".jsx":
-      return ts.ScriptKind.JSX;
-    case ".js":
-    case ".mjs":
-    case ".cjs":
-      return ts.ScriptKind.JS;
-    case ".cts":
-    case ".mts":
-    case ".ts":
-    default:
-      return ts.ScriptKind.TS;
-  }
-}
-function lineOf(sf, pos) {
-  return sf.getLineAndCharacterOfPosition(pos).line + 1;
-}
-function hasExportModifier(node) {
-  const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0;
-  return Boolean(mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
-}
-function isTopLevel(node, sf) {
-  let p = node.parent;
-  while (p && p !== sf) {
-    if (ts.isFunctionDeclaration(p) || ts.isFunctionExpression(p) || ts.isArrowFunction(p) || ts.isMethodDeclaration(p) || ts.isConstructorDeclaration(p) || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p)) {
-      return false;
-    }
-    if (ts.isClassDeclaration(p) || ts.isClassExpression(p)) {
-      return false;
-    }
-    p = p.parent;
-  }
-  return true;
-}
-function extractFromSource(filePath, source, repoRelativePath) {
-  const sf = ts.createSourceFile(
-    filePath,
-    source,
-    ts.ScriptTarget.Latest,
-    /*setParentNodes*/
-    true,
-    scriptKindForPath(filePath)
-  );
-  const symbols = [];
-  const imports = [];
-  const exports = [];
-  const references = [];
-  const pushSymbol = (name, node, kind, exported) => {
-    if (!name) return;
-    symbols.push({
-      name,
-      kind,
-      filePath: repoRelativePath,
-      startLine: lineOf(sf, node.getStart(sf, false)),
-      endLine: lineOf(sf, node.getEnd()),
-      exported
-    });
-    if (exported) {
-      exports.push({ name, kind });
-    }
-  };
-  const visit = (node) => {
-    if (ts.isImportDeclaration(node)) {
-      const spec = node.moduleSpecifier;
-      if (ts.isStringLiteral(spec)) {
-        const names = [];
-        const clause = node.importClause;
-        if (clause?.name) names.push(clause.name.text);
-        if (clause?.namedBindings) {
-          if (ts.isNamespaceImport(clause.namedBindings)) {
-            names.push(clause.namedBindings.name.text);
-          } else if (ts.isNamedImports(clause.namedBindings)) {
-            for (const el of clause.namedBindings.elements) {
-              names.push(el.name.text);
-            }
-          }
-        }
-        imports.push({ from: spec.text, names: names.length ? names : void 0 });
-      }
-    }
-    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
-      imports.push({ from: node.moduleSpecifier.text, names: ["*"] });
-    }
-    if (ts.isFunctionDeclaration(node) && node.name && isTopLevel(node, sf)) {
-      pushSymbol(node.name.text, node, "function", hasExportModifier(node));
-    }
-    if (ts.isClassDeclaration(node) && node.name && isTopLevel(node, sf)) {
-      pushSymbol(node.name.text, node, "class", hasExportModifier(node));
-    }
-    if (ts.isInterfaceDeclaration(node) && isTopLevel(node, sf)) {
-      pushSymbol(node.name.text, node, "interface", hasExportModifier(node));
-    }
-    if (ts.isTypeAliasDeclaration(node) && isTopLevel(node, sf)) {
-      pushSymbol(node.name.text, node, "type", hasExportModifier(node));
-    }
-    if (ts.isEnumDeclaration(node) && isTopLevel(node, sf)) {
-      pushSymbol(node.name.text, node, "type", hasExportModifier(node));
-    }
-    if (ts.isVariableStatement(node) && isTopLevel(node, sf)) {
-      const exported = hasExportModifier(node);
-      for (const decl of node.declarationList.declarations) {
-        if (!ts.isIdentifier(decl.name)) continue;
-        const name = decl.name.text;
-        const init = decl.initializer;
-        const isFn = init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init));
-        if (exported || isFn) {
-          pushSymbol(name, decl, isFn ? "function" : "const", exported);
-        }
-      }
-    }
-    if (ts.isExportAssignment(node) && !node.isExportEquals) {
-      exports.push({ name: "default", kind: "export" });
-    }
-    if (ts.isIdentifier(node) && node.parent && !ts.isImportSpecifier(node.parent)) {
-      const parent = node.parent;
-      if (ts.isCallExpression(parent) || ts.isPropertyAccessExpression(parent) || ts.isTypeReferenceNode(parent)) {
-        references.push({ name: node.text, line: lineOf(sf, node.getStart(sf)) });
-      }
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(sf);
-  return {
-    ok: true,
-    language: "typescript",
-    symbols,
-    imports,
-    exports,
-    references: references.slice(0, 200)
-    // bound noise
-  };
-}
-var typescriptAdapter = {
-  id: "typescript",
-  extensions: [...TS_JS_EXTENSIONS],
-  extract(input) {
-    try {
-      return extractFromSource(input.filePath, input.source, input.filePath);
-    } catch (err) {
-      return {
-        ok: false,
-        language: "typescript",
-        symbols: [],
-        imports: [],
-        exports: [],
-        errors: [err instanceof Error ? err.message : String(err)]
-      };
-    }
-  }
-};
-function isTypescriptAdapterAvailable() {
-  try {
-    return typeof ts.createSourceFile === "function";
-  } catch {
-    return false;
-  }
-}
-
-// src/code-context/adapters/registry.ts
-var AdapterRegistry = class {
-  byExt = /* @__PURE__ */ new Map();
-  constructor(adapters) {
-    const list = adapters ?? [typescriptAdapter];
-    for (const a of list) {
-      for (const ext of a.extensions) {
-        this.byExt.set(ext.toLowerCase(), a);
-      }
-    }
-  }
-  getByPath(filePath) {
-    const ext = extname2(filePath).toLowerCase();
-    return this.byExt.get(ext);
-  }
-  hasExtension(ext) {
-    return this.byExt.has(ext.toLowerCase());
-  }
-};
+import { stat } from "fs/promises";
+import { extname as extname3, isAbsolute as isAbsolute2, join as join6, relative as relative2 } from "pathe";
 
 // src/code-context/focus.ts
 import { promises as fs } from "fs";
-import { isAbsolute, join as join4, normalize as normalize3, relative } from "pathe";
-
-// src/code-context/ignore.ts
-import { basename as basename2, extname as extname3, normalize as normalize2 } from "pathe";
-
-// src/code-context/secrets.ts
-import { basename, normalize } from "pathe";
-var SECRET_BASENAME_PATTERNS = [
-  /^\.env$/i,
-  /^\.env\..+/i,
-  /\.pem$/i,
-  /\.key$/i,
-  /id_rsa/i,
-  /credentials/i,
-  /secret/i
-];
-function isSecretPath(filePath) {
-  const norm = normalize(filePath).replace(/\\/g, "/");
-  const parts = norm.split("/").filter(Boolean);
-  if (parts.includes(".git")) return true;
-  if (norm.includes("/.git/") || norm.startsWith(".git/") || norm === ".git") {
-    return true;
-  }
-  const base = basename(norm);
-  return SECRET_BASENAME_PATTERNS.some((re) => re.test(base));
-}
-
-// src/code-context/ignore.ts
-var IGNORED_DIR_SEGMENTS = /* @__PURE__ */ new Set([
-  "node_modules",
-  "dist",
-  "coverage",
-  ".turbo",
-  ".next",
-  "build",
-  ".cache"
-]);
-var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".ico",
-  ".svg",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".eot",
-  ".pdf",
-  ".zip",
-  ".tar",
-  ".gz",
-  ".tgz",
-  ".7z",
-  ".rar",
-  ".exe",
-  ".dll",
-  ".so",
-  ".dylib",
-  ".bin",
-  ".wasm",
-  ".mp3",
-  ".mp4",
-  ".mov",
-  ".lock"
-]);
-function isIgnoredPath(filePath) {
-  const norm = normalize2(filePath).replace(/\\/g, "/");
-  const parts = norm.split("/").filter(Boolean);
-  for (const p of parts) {
-    if (IGNORED_DIR_SEGMENTS.has(p)) return true;
-  }
-  const ext = extname3(basename2(norm)).toLowerCase();
-  if (BINARY_EXTENSIONS.has(ext)) return true;
-  const base = basename2(norm);
-  if (base === "package-lock.json" || base === "pnpm-lock.yaml" || base === "yarn.lock" || base === "bun.lockb") {
-    return true;
-  }
-  return false;
-}
-function classifyPath(filePath) {
-  if (isSecretPath(filePath)) return "secret";
-  if (isIgnoredPath(filePath)) return "ignored";
-  return "allowed";
-}
-
-// src/code-context/focus.ts
+import { isAbsolute, join as join5, normalize, relative } from "pathe";
 var KEYWORD_STOPWORDS = new Set(
   [
     "a",
@@ -915,12 +1332,12 @@ function extractPathLikeTokens(text) {
   return found;
 }
 function toRepoRelative(projectRoot, p) {
-  const abs = isAbsolute(p) ? p : join4(projectRoot, p);
+  const abs = isAbsolute(p) ? p : join5(projectRoot, p);
   const rel = relative(projectRoot, abs);
-  return normalize3(rel).replace(/\\/g, "/");
+  return normalize(rel).replace(/\\/g, "/");
 }
 function toAbsolute(projectRoot, p) {
-  return isAbsolute(p) ? p : join4(projectRoot, p);
+  return isAbsolute(p) ? p : join5(projectRoot, p);
 }
 async function walkFiles(absDir, projectRoot, maxFiles, out, gaps) {
   if (out.length >= maxFiles) return;
@@ -933,7 +1350,7 @@ async function walkFiles(absDir, projectRoot, maxFiles, out, gaps) {
   }
   for (const entry of entries) {
     if (out.length >= maxFiles) return;
-    const abs = join4(absDir, entry.name);
+    const abs = join5(absDir, entry.name);
     const rel = toRepoRelative(projectRoot, abs);
     const kind = classifyPath(rel);
     if (kind === "secret" || kind === "ignored") continue;
@@ -1027,7 +1444,7 @@ async function resolveChangeMeta(projectRoot, changeId, gaps) {
     return null;
   }
   const cpath = changePath(projectRoot, config, id);
-  const metaPath = join4(cpath, "meta.yaml");
+  const metaPath = join5(cpath, "meta.yaml");
   if (!await pathExists(metaPath)) {
     if (!await pathExists(cpath)) {
       gaps.push({
@@ -1060,7 +1477,7 @@ async function searchByKeywords(projectRoot, keywords, symbols, maxFiles) {
   const terms = [...keywords, ...symbols.map((s) => s.toLowerCase())];
   if (!terms.length) return out;
   for (const root of SOURCE_ROOTS) {
-    const abs = join4(projectRoot, root);
+    const abs = join5(projectRoot, root);
     if (!await pathExists(abs)) continue;
     const files = [];
     await walkFiles(abs, projectRoot, maxFiles * 4, files, []);
@@ -1074,7 +1491,7 @@ async function searchByKeywords(projectRoot, keywords, symbols, maxFiles) {
       }
       if (symbols.length) {
         try {
-          const text = await readText(join4(projectRoot, rel));
+          const text = await readText(join5(projectRoot, rel));
           if (symbols.some((s) => text.includes(s))) {
             out.push(rel);
           }
@@ -1110,7 +1527,7 @@ async function resolveFocus(request, options) {
     }
     notes.push(`Change signals from: ${change.id}`);
     for (const artifact of ["tasks.md", "feature.md", "stories.md", "lld.md"]) {
-      const body = await readBounded(join4(change.path, artifact), 8e3);
+      const body = await readBounded(join5(change.path, artifact), 8e3);
       if (!body) continue;
       if (!request.paths?.length) {
         for (const p of extractPathLikeTokens(body)) {
@@ -1183,17 +1600,6 @@ async function resolveFocus(request, options) {
 }
 
 // src/code-context/formatter.ts
-function fenceLang(filePath) {
-  const lower = filePath.toLowerCase();
-  if (lower.endsWith(".tsx") || lower.endsWith(".jsx")) return "tsx";
-  if (lower.endsWith(".ts") || lower.endsWith(".mts") || lower.endsWith(".cts")) {
-    return "ts";
-  }
-  if (lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs")) {
-    return "js";
-  }
-  return "";
-}
 function formatMarkdown(input) {
   const lines = [];
   lines.push("# Code context");
@@ -1233,50 +1639,15 @@ function formatMarkdown(input) {
   lines.push("");
   lines.push("## Slices");
   lines.push("");
-  let truncated = input.summary.truncated;
-  const maxLines = input.maxOutputLines ?? 8e3;
-  const maxTokens = input.maxTokensApprox ?? 12e3;
-  let approxTokens = 0;
-  for (const slice of input.slices) {
-    if (lines.length >= maxLines) {
-      truncated = true;
-      break;
-    }
-    const header = `### \`${slice.filePath}\`${slice.symbolName ? ` \xB7 \`${slice.symbolName}\`` : ""} (lines ${slice.startLine}\u2013${slice.endLine}) \xB7 ${slice.reason}`;
-    lines.push(header);
-    lines.push("```" + fenceLang(slice.filePath));
-    lines.push(slice.body);
-    lines.push("```");
-    lines.push("");
-    approxTokens += Math.ceil((header.length + slice.body.length) / 4);
-    if (approxTokens > maxTokens) {
-      truncated = true;
-      break;
-    }
-  }
-  if (!input.slices.length) {
-    lines.push("_No slices emitted._");
-    lines.push("");
-  }
-  lines.push("## Structural notes");
-  const topFiles = [...new Set(input.slices.map((s) => s.filePath))].slice(0, 15);
-  if (topFiles.length) {
-    lines.push(`- Ranked files (sample): ${topFiles.join(", ")}`);
-  } else {
-    lines.push("- No structural neighborhood (empty analysis set).");
-  }
-  lines.push("");
-  let markdown = lines.join("\n");
-  if (Math.ceil(markdown.length / 4) > maxTokens) {
-    truncated = true;
-    markdown = markdown.slice(0, maxTokens * 4) + "\n\n\u2026(truncated)\n";
-  }
-  return { markdown, truncated };
+  const packed = input.packedText ?? "";
+  const frame = `${lines.join("\n")}
+`;
+  return { markdown: packed ? frame + packed : frame, truncated: input.summary.truncated };
 }
-function formatJsonSummary(summary, gaps, slices, ok) {
+function formatJsonSummary(summary, gaps, slices, ok4) {
   return JSON.stringify(
     {
-      ok,
+      ok: ok4,
       summary,
       gaps,
       slices: slices.map((s) => ({
@@ -1293,288 +1664,6 @@ function formatJsonSummary(summary, gaps, slices, ok) {
   );
 }
 
-// src/code-context/graph.ts
-import { dirname as dirname2, join as join5, normalize as normalize4 } from "pathe";
-var GraphLite = class {
-  files = /* @__PURE__ */ new Map();
-  edges = [];
-  add(path, source, extract) {
-    const norm = normalize4(path).replace(/\\/g, "/");
-    this.files.set(norm, { path: norm, extract, source });
-    for (const imp of extract.imports) {
-      this.edges.push({
-        from: norm,
-        to: imp.from,
-        names: imp.names
-      });
-    }
-  }
-  allSymbols() {
-    const out = [];
-    for (const node of this.files.values()) {
-      out.push(...node.extract.symbols);
-    }
-    return out;
-  }
-  getSource(path) {
-    return this.files.get(normalize4(path).replace(/\\/g, "/"))?.source;
-  }
-  /**
-   * Resolve relative import specifier to a known graph file path, if present.
-   */
-  resolveImportTarget(fromFile, specifier) {
-    if (!specifier.startsWith(".")) return void 0;
-    const base = dirname2(fromFile);
-    const joined = normalize4(join5(base, specifier)).replace(/\\/g, "/");
-    const candidates = [
-      joined,
-      `${joined}.ts`,
-      `${joined}.tsx`,
-      `${joined}.js`,
-      `${joined}.jsx`,
-      `${joined}.mts`,
-      `${joined}.cts`,
-      `${joined}/index.ts`,
-      `${joined}/index.js`
-    ];
-    for (const c of candidates) {
-      if (this.files.has(c)) return c;
-    }
-    for (const [p] of this.files) {
-      if (p === joined || p.startsWith(joined + ".")) return p;
-    }
-    return void 0;
-  }
-  /** Import hop distance from any seed file (0 = seed, 1 = direct import, …). */
-  hopDistance(filePath, seedPaths, maxHops) {
-    const norm = normalize4(filePath).replace(/\\/g, "/");
-    const seeds = new Set(seedPaths.map((s) => normalize4(s).replace(/\\/g, "/")));
-    if (seeds.has(norm)) return 0;
-    let frontier = new Set(seeds);
-    const visited = new Set(seeds);
-    for (let hop = 1; hop <= maxHops; hop++) {
-      const next = /* @__PURE__ */ new Set();
-      for (const f of frontier) {
-        for (const e of this.edges) {
-          if (e.from !== f) continue;
-          const target = this.resolveImportTarget(e.from, e.to);
-          if (!target || visited.has(target)) continue;
-          visited.add(target);
-          next.add(target);
-          if (target === norm) return hop;
-        }
-      }
-      frontier = next;
-      if (!frontier.size) break;
-    }
-    return null;
-  }
-  importNeighbors(filePath) {
-    const norm = normalize4(filePath).replace(/\\/g, "/");
-    const out = [];
-    for (const e of this.edges) {
-      if (e.from !== norm) continue;
-      const t = this.resolveImportTarget(e.from, e.to);
-      if (t) out.push(t);
-    }
-    return out;
-  }
-};
-
-// src/code-context/ranker.ts
-import { basename as basename3 } from "pathe";
-function isTestPath(filePath) {
-  const p = filePath.replace(/\\/g, "/");
-  return p.includes("__tests__/") || p.includes("/__tests__/") || /\.test\.[cm]?[jt]sx?$/.test(p) || /\.spec\.[cm]?[jt]sx?$/.test(p);
-}
-function pathSegments(filePath) {
-  return filePath.replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean).flatMap((s) => s.replace(/\.[^.]+$/, "").split(/[-_.]/));
-}
-function scoreSymbol(symbol, plan, graph, caps) {
-  let score = 0;
-  const reasons = [];
-  const seeds = new Set(plan.seedPaths);
-  const seedSymbols = plan.seedSymbols;
-  if (seedSymbols.length) {
-    const exact = seedSymbols.find((s) => s === symbol.name);
-    if (exact) {
-      score += 100;
-      reasons.push("exact-symbol");
-    } else {
-      const ci = seedSymbols.find((s) => s.toLowerCase() === symbol.name.toLowerCase());
-      if (ci) {
-        score += 90;
-        reasons.push("symbol-ci");
-      }
-    }
-  }
-  if (seeds.has(symbol.filePath)) {
-    score += 40;
-    reasons.push("seed-path");
-  }
-  const hop = graph.hopDistance(symbol.filePath, plan.seedPaths, caps.maxImportHops);
-  if (hop === 0) {
-    score += 30;
-    reasons.push("hop-0");
-  } else if (hop === 1) {
-    score += 18;
-    reasons.push("hop-1");
-  }
-  const nameLower = symbol.name.toLowerCase();
-  let kwHits = 0;
-  for (const k of plan.keywords) {
-    if (nameLower.includes(k)) {
-      kwHits++;
-      if (kwHits >= 3) break;
-    }
-  }
-  if (kwHits) {
-    score += 15 * kwHits;
-    reasons.push(`keyword-name\xD7${kwHits}`);
-  }
-  const segs = pathSegments(symbol.filePath);
-  let pathHits = 0;
-  for (const k of plan.keywords) {
-    if (segs.some((s) => s.includes(k) || k.includes(s))) {
-      pathHits++;
-      if (pathHits >= 3) break;
-    }
-  }
-  if (pathHits) {
-    score += 8 * pathHits;
-    reasons.push(`keyword-path\xD7${pathHits}`);
-  }
-  if (symbol.exported) {
-    score += 5;
-    reasons.push("exported");
-  }
-  const base = basename3(symbol.filePath).toLowerCase();
-  let titleHits = 0;
-  for (const k of plan.keywords.slice(0, 10)) {
-    if (base.includes(k)) {
-      titleHits++;
-      if (titleHits >= 2) break;
-    }
-  }
-  if (titleHits) {
-    score += 6 * titleHits;
-    reasons.push(`title-path\xD7${titleHits}`);
-  }
-  const focusIsTest = plan.seedPaths.some(isTestPath) || plan.keywords.some((k) => k === "test" || k === "tests" || k === "vitest");
-  if (isTestPath(symbol.filePath) && !focusIsTest) {
-    score -= 12;
-    reasons.push("test-penalty");
-  }
-  const source = graph.getSource(symbol.filePath);
-  if (source) {
-    const lines = source.split(/\r?\n/).length;
-    if (lines > 400) {
-      const over = Math.floor((lines - 400) / 200);
-      const pen = Math.min(10, over);
-      if (pen > 0) {
-        score -= pen;
-        reasons.push("huge-file");
-      }
-    }
-  }
-  if (symbol.kind === "function" || symbol.kind === "class" || symbol.kind === "interface") {
-    score += 2;
-  }
-  return { symbol, score, reasons };
-}
-function rankSymbols(graph, plan, caps) {
-  const items = graph.allSymbols().map((s) => scoreSymbol(s, plan, graph, caps));
-  items.sort((a, b) => {
-    if (b.score !== a.score) return b.score - a.score;
-    const fa = a.symbol.filePath.localeCompare(b.symbol.filePath);
-    if (fa !== 0) return fa;
-    return a.symbol.startLine - b.symbol.startLine;
-  });
-  return items.slice(0, caps.maxSymbols);
-}
-
-// src/code-context/slicer.ts
-function sliceBody(source, startLine, endLine, maxLines) {
-  const lines = source.split(/\r?\n/);
-  const start = Math.max(1, startLine);
-  let end = Math.min(lines.length, endLine);
-  let truncated = false;
-  if (end - start + 1 > maxLines) {
-    end = start + maxLines - 1;
-    truncated = true;
-  }
-  const body = lines.slice(start - 1, end).join("\n");
-  return { body, end, truncated };
-}
-function emitSlices(ranked, graph, caps, options) {
-  const slices = [];
-  const gaps = [];
-  let truncated = false;
-  const seen = /* @__PURE__ */ new Set();
-  for (const item of ranked) {
-    if (slices.length >= caps.maxSlices) {
-      truncated = true;
-      break;
-    }
-    const sym = item.symbol;
-    if (isSecretPath(sym.filePath)) continue;
-    const source = graph.getSource(sym.filePath);
-    if (!source) continue;
-    const {
-      body,
-      end,
-      truncated: lineTrunc
-    } = sliceBody(source, sym.startLine, sym.endLine, caps.maxLinesPerSlice);
-    if (lineTrunc) truncated = true;
-    const id = `${sym.filePath}:${sym.startLine}-${end}:${sym.name}`;
-    if (seen.has(id)) continue;
-    seen.add(id);
-    const reasonParts = item.reasons.length ? item.reasons.slice(0, 4).join(", ") : "ranked";
-    slices.push({
-      id,
-      filePath: sym.filePath,
-      startLine: sym.startLine,
-      endLine: end,
-      symbolName: sym.name,
-      reason: reasonParts,
-      body
-    });
-    if (options?.includeNeighbors && slices.length < caps.maxSlices) {
-      const neighbors = graph.importNeighbors(sym.filePath);
-      for (const n of neighbors.slice(0, 1)) {
-        if (isSecretPath(n)) continue;
-        const nSource = graph.getSource(n);
-        const nNode = graph.files.get(n);
-        if (!nSource || !nNode) continue;
-        const nSym = nNode.extract.symbols.find((s) => s.exported) ?? nNode.extract.symbols[0];
-        if (!nSym) continue;
-        const nb = sliceBody(nSource, nSym.startLine, nSym.endLine, caps.maxLinesPerSlice);
-        const nid = `${nSym.filePath}:${nSym.startLine}-${nb.end}:${nSym.name}:neighbor`;
-        if (seen.has(nid)) continue;
-        seen.add(nid);
-        slices.push({
-          id: nid,
-          filePath: nSym.filePath,
-          startLine: nSym.startLine,
-          endLine: nb.end,
-          symbolName: nSym.name,
-          reason: `neighbor-of ${sym.name}`,
-          body: nb.body
-        });
-        if (nb.truncated) truncated = true;
-        break;
-      }
-    }
-  }
-  if (truncated) {
-    gaps.push({
-      code: "cap_truncated",
-      message: "Output truncated at configured caps (maxSlices/maxLinesPerSlice)."
-    });
-  }
-  return { slices, gaps, truncated };
-}
-
 // src/code-context/types.ts
 var DEFAULT_CODE_CONTEXT_CAPS = {
   maxFiles: 40,
@@ -1589,13 +1678,204 @@ function mergeCaps(partial) {
   return { ...DEFAULT_CODE_CONTEXT_CAPS, ...partial };
 }
 
-// src/code-context/adapters/fallback.ts
-var fallbackAdapter = {
-  id: "fallback",
-  extensions: [],
-  extract(input) {
-    const lines = input.source.split(/\r?\n/);
-    const headEnd = Math.min(lines.length, 20);
+// src/code-context/adapters/registry.ts
+import { extname as extname2 } from "pathe";
+
+// src/code-context/adapters/typescript.ts
+import { extname } from "pathe";
+import ts from "typescript";
+var TS_JS_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".cts",
+  ".mjs",
+  ".cjs"
+];
+function scriptKindForPath(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".tsx":
+      return ts.ScriptKind.TSX;
+    case ".jsx":
+      return ts.ScriptKind.JSX;
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return ts.ScriptKind.JS;
+    case ".cts":
+    case ".mts":
+    case ".ts":
+    default:
+      return ts.ScriptKind.TS;
+  }
+}
+function lineOf(sf, pos) {
+  return sf.getLineAndCharacterOfPosition(pos).line + 1;
+}
+function hasExportModifier(node) {
+  const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0;
+  return Boolean(mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+}
+function isTopLevel(node, sf) {
+  let p = node.parent;
+  while (p && p !== sf) {
+    if (ts.isFunctionDeclaration(p) || ts.isFunctionExpression(p) || ts.isArrowFunction(p) || ts.isMethodDeclaration(p) || ts.isConstructorDeclaration(p) || ts.isGetAccessorDeclaration(p) || ts.isSetAccessorDeclaration(p)) {
+      return false;
+    }
+    if (ts.isClassDeclaration(p) || ts.isClassExpression(p)) {
+      return false;
+    }
+    p = p.parent;
+  }
+  return true;
+}
+function extractFromSource(filePath, source, repoRelativePath) {
+  const sf = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+    /*setParentNodes*/
+    true,
+    scriptKindForPath(filePath)
+  );
+  const symbols = [];
+  const imports = [];
+  const exports = [];
+  const references = [];
+  const pushSymbol = (name, node, kind, exported) => {
+    if (!name) return;
+    symbols.push({
+      name,
+      kind,
+      filePath: repoRelativePath,
+      startLine: lineOf(sf, node.getStart(sf, false)),
+      endLine: lineOf(sf, node.getEnd()),
+      exported
+    });
+    if (exported) {
+      exports.push({ name, kind });
+    }
+  };
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node)) {
+      const spec = node.moduleSpecifier;
+      if (ts.isStringLiteral(spec)) {
+        const names = [];
+        const clause = node.importClause;
+        if (clause?.name) names.push(clause.name.text);
+        if (clause?.namedBindings) {
+          if (ts.isNamespaceImport(clause.namedBindings)) {
+            names.push(clause.namedBindings.name.text);
+          } else if (ts.isNamedImports(clause.namedBindings)) {
+            for (const el of clause.namedBindings.elements) {
+              names.push(el.name.text);
+            }
+          }
+        }
+        imports.push({ from: spec.text, names: names.length ? names : void 0 });
+      }
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.push({ from: node.moduleSpecifier.text, names: ["*"] });
+    }
+    if (ts.isFunctionDeclaration(node) && node.name && isTopLevel(node, sf)) {
+      pushSymbol(node.name.text, node, "function", hasExportModifier(node));
+    }
+    if (ts.isClassDeclaration(node) && node.name && isTopLevel(node, sf)) {
+      pushSymbol(node.name.text, node, "class", hasExportModifier(node));
+    }
+    if (ts.isInterfaceDeclaration(node) && isTopLevel(node, sf)) {
+      pushSymbol(node.name.text, node, "interface", hasExportModifier(node));
+    }
+    if (ts.isTypeAliasDeclaration(node) && isTopLevel(node, sf)) {
+      pushSymbol(node.name.text, node, "type", hasExportModifier(node));
+    }
+    if (ts.isEnumDeclaration(node) && isTopLevel(node, sf)) {
+      pushSymbol(node.name.text, node, "type", hasExportModifier(node));
+    }
+    if (ts.isVariableStatement(node) && isTopLevel(node, sf)) {
+      const exported = hasExportModifier(node);
+      for (const decl of node.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name)) continue;
+        const name = decl.name.text;
+        const init = decl.initializer;
+        const isFn = init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init));
+        if (exported || isFn) {
+          pushSymbol(name, decl, isFn ? "function" : "const", exported);
+        }
+      }
+    }
+    if (ts.isExportAssignment(node) && !node.isExportEquals) {
+      exports.push({ name: "default", kind: "export" });
+    }
+    if (ts.isIdentifier(node) && node.parent && !ts.isImportSpecifier(node.parent)) {
+      const parent = node.parent;
+      if (ts.isCallExpression(parent) || ts.isPropertyAccessExpression(parent) || ts.isTypeReferenceNode(parent)) {
+        references.push({ name: node.text, line: lineOf(sf, node.getStart(sf)) });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return {
+    ok: true,
+    language: "typescript",
+    symbols,
+    imports,
+    exports,
+    references: references.slice(0, 200)
+    // bound noise
+  };
+}
+var typescriptAdapter = {
+  id: "typescript",
+  extensions: [...TS_JS_EXTENSIONS],
+  extract(input) {
+    try {
+      return extractFromSource(input.filePath, input.source, input.filePath);
+    } catch (err) {
+      return {
+        ok: false,
+        language: "typescript",
+        symbols: [],
+        imports: [],
+        exports: [],
+        errors: [err instanceof Error ? err.message : String(err)]
+      };
+    }
+  }
+};
+
+// src/code-context/adapters/registry.ts
+var AdapterRegistry = class {
+  byExt = /* @__PURE__ */ new Map();
+  constructor(adapters) {
+    const list = adapters ?? [typescriptAdapter];
+    for (const a of list) {
+      for (const ext of a.extensions) {
+        this.byExt.set(ext.toLowerCase(), a);
+      }
+    }
+  }
+  getByPath(filePath) {
+    const ext = extname2(filePath).toLowerCase();
+    return this.byExt.get(ext);
+  }
+  hasExtension(ext) {
+    return this.byExt.has(ext.toLowerCase());
+  }
+};
+
+// src/code-context/adapters/fallback.ts
+var fallbackAdapter = {
+  id: "fallback",
+  extensions: [],
+  extract(input) {
+    const lines = input.source.split(/\r?\n/);
+    const headEnd = Math.min(lines.length, 20);
     return {
       ok: true,
       language: "text",
@@ -1657,75 +1937,125 @@ function hardFailure(gaps, message, summary) {
     gaps
   };
 }
+function toRepoPath(projectRoot, input) {
+  const abs = isAbsolute2(input) ? input : join6(projectRoot, input);
+  let rel = relative2(projectRoot, abs).replaceAll("\\", "/");
+  while (rel.startsWith("./")) rel = rel.slice(2);
+  return rel;
+}
+function pathKept(rel, fileArgs, dirArgs) {
+  if (fileArgs.includes(rel)) return true;
+  return dirArgs.some((dir) => rel.startsWith(`${dir}/`));
+}
+function symbolKept(symbol, names) {
+  return names.some((name) => symbol === name || symbol.endsWith(`.${name}`));
+}
 async function generateCodeContext(request, deps) {
-  const caps = mergeCaps(request.caps);
   const projectRoot = request.projectRoot;
   const gaps = [];
-  if (!deps?.adapters?.length && !isTypescriptAdapterAvailable()) {
-    return hardFailure(
-      [
-        {
-          code: "adapter_unavailable",
-          message: "TypeScript language adapter could not be loaded; ensure `typescript` is installed with @structured-vibe-coding/core."
-        }
-      ],
-      "Language adapter unavailable"
-    );
-  }
-  const registry = new AdapterRegistry(deps?.adapters);
   const { plan, gaps: focusGaps } = await resolveFocus(request);
   gaps.push(...focusGaps);
-  const hasFocus = plan.seedPaths.length > 0 || plan.candidatePaths.length > 0 || plan.seedSymbols.length > 0 || plan.keywords.length > 0 || Boolean(request.paths?.length) || Boolean(request.query) || Boolean(request.symbols?.length);
-  if (!plan.seedPaths.length && !plan.candidatePaths.length && !plan.seedSymbols.length && !request.paths?.length && !request.query && !request.symbols?.length) {
-    if (!plan.keywords.length) {
-      gaps.push({
-        code: "no_focus",
-        message: "No focus resolved. Pass --path, --symbol, and/or --query, or run with an active change."
-      });
-      return hardFailure(gaps, "No focus resolved", {
-        focusSymbols: plan.seedSymbols,
-        keywords: plan.keywords
-      });
-    }
-  }
-  if (!plan.candidatePaths.length && !plan.seedPaths.length) {
-    if (!hasFocus) {
-      gaps.push({
-        code: "no_focus",
-        message: "No focus resolved. Pass --path, --symbol, and/or --query, or run with an active change."
-      });
-      return hardFailure(gaps, "No focus resolved", {
-        focusSymbols: plan.seedSymbols,
-        keywords: plan.keywords
-      });
-    }
+  const hasExplicit = Boolean(request.paths?.length) || Boolean(request.query?.trim()) || Boolean(request.symbols?.length) || Boolean(request.changeId) || plan.seedPaths.length > 0 || plan.candidatePaths.length > 0 || plan.keywords.length > 0;
+  if (!hasExplicit) {
     gaps.push({
       code: "no_focus",
-      message: "Focus signals present but no candidate source files resolved. Pass --path to a file or directory."
+      message: "No focus resolved. Pass --path, --symbol, and/or --query, or run with an active change."
     });
-    return hardFailure(gaps, "No candidate files", {
+    return hardFailure(gaps, "No focus resolved", {
       focusSymbols: plan.seedSymbols,
-      keywords: plan.keywords,
-      focusPaths: plan.seedPaths
+      keywords: plan.keywords
     });
   }
-  let candidates = [...plan.candidatePaths];
-  if (!candidates.length) candidates = [...plan.seedPaths];
-  let truncated = false;
-  if (candidates.length > caps.maxFiles) {
-    candidates = candidates.slice(0, caps.maxFiles);
-    truncated = true;
-    gaps.push({
-      code: "cap_truncated",
-      message: `Candidate files capped at maxFiles=${caps.maxFiles}.`
+  let searchConfig;
+  try {
+    searchConfig = await loadSearchConfig(projectRoot);
+  } catch {
+    return hardFailure(
+      [{ code: "parse_error", message: "search.yaml is invalid" }],
+      "search.yaml is invalid"
+    );
+  }
+  const config = await loadConfig(projectRoot);
+  let changeTitle = plan.changeId;
+  let stage;
+  if (request.changeId) {
+    const mp = join6(changePath(projectRoot, config, request.changeId), "meta.yaml");
+    if (await pathExists(mp)) {
+      const meta = await readYaml(mp);
+      changeTitle = meta.title ?? request.changeId;
+      stage = meta.stage;
+    }
+  }
+  const runtime = {
+    embedder: deps?.embedder,
+    embedderFactory: deps?.embedderFactory
+  };
+  await createBuiltinProvider(projectRoot, config, runtime).index();
+  const budget = request.caps?.maxTokensApprox ?? budgetForStage(searchConfig, stage);
+  const k = request.caps?.maxSlices ?? searchConfig.k;
+  let query = request.query?.trim() ? request.query : "";
+  if (!query && request.symbols?.length) query = request.symbols.join(" ");
+  if (!query && changeTitle && request.changeId) query = changeTitle;
+  const activeChange = await resolveActiveDirectory(projectRoot, config);
+  const cacheRequest = {
+    projectRoot,
+    query: query.trim() ? query : "",
+    channel: "context",
+    scope: "code",
+    k,
+    budget,
+    embeddings: searchConfig.embeddings,
+    activeChange,
+    filterPaths: request.paths ?? [],
+    filterSymbols: request.symbols ?? [],
+    scopes: ["code"]
+  };
+  try {
+    const cached = readPackedCache(cacheRequest);
+    if (cached) return finishContext(cached.hits, cached.text, cached.warning);
+  } catch {
+  }
+  let hits;
+  let mode = "bm25";
+  let hybridScopes = "";
+  if (query.trim()) {
+    const embedder = await resolveEmbedder(projectRoot, searchConfig.embeddings, runtime);
+    const embedded = await embedSearchQuery(embedder, searchConfig.embeddings, query);
+    const ranked = await rankScope(projectRoot, query, "code", k, {
+      embeddings: searchConfig.embeddings,
+      queryVec: embedded.queryVec,
+      failure: embedded.failure
     });
+    hits = ranked.hits;
+    if (ranked.hybrid) hybridScopes = "code";
+    if (ranked.hits.some((hit) => hit.rankedBy === "rrf")) mode = "rrf";
+    if (ranked.warning) {
+      gaps.push({ code: "embeddings_unavailable", message: EMBEDDINGS_UNAVAILABLE });
+    }
+  } else {
+    hits = await listScopeHits(projectRoot, "code");
   }
-  const graph = new GraphLite();
-  let filesAnalyzed = 0;
-  let symbolsExtracted = 0;
-  for (const rel of candidates) {
-    const kind = classifyPath(rel);
-    if (kind === "secret") {
+  const fileArgs = [];
+  const dirArgs = [];
+  for (const input of request.paths ?? []) {
+    const rel = toRepoPath(projectRoot, input);
+    let info = null;
+    try {
+      info = await stat(join6(projectRoot, rel));
+    } catch {
+      info = null;
+    }
+    if (!info) {
+      gaps.push({ code: "path_missing", message: `Path not found: ${rel}`, path: rel });
+      continue;
+    }
+    if (info.isDirectory()) {
+      dirArgs.push(rel);
+      continue;
+    }
+    fileArgs.push(rel);
+    const ext = extname3(rel).toLowerCase();
+    if (isSecretPath(rel)) {
       gaps.push({
         code: "path_denied_secret",
         message: `Skipped potential secret path: ${rel}`,
@@ -1733,169 +2063,150 @@ async function generateCodeContext(request, deps) {
       });
       continue;
     }
-    if (kind === "ignored") {
-      gaps.push({
-        code: "path_ignored",
-        message: `Skipped ignored path: ${rel}`,
-        path: rel
-      });
+    if (isIgnoredPath(rel)) {
+      gaps.push({ code: "path_ignored", message: `Skipped ignored path: ${rel}`, path: rel });
       continue;
     }
-    const abs = join6(projectRoot, rel);
-    if (!await pathExists(abs)) {
+    if (ext === ".go") {
       gaps.push({
-        code: "path_missing",
-        message: `Path not found: ${rel}`,
+        code: "unsupported_language",
+        message: `No structure adapter for ${ext}; skipped.`,
         path: rel
       });
-      continue;
     }
-    const adapter = registry.getByPath(rel);
-    if (!adapter) {
-      gaps.push({
-        code: "unsupported_language",
-        message: `No structure adapter for ${extname4(rel) || rel}; skipped.`,
-        path: rel
-      });
-      continue;
-    }
-    let source;
-    try {
-      source = await readText(abs);
-    } catch (err) {
-      gaps.push({
-        code: "parse_error",
-        message: `Could not read ${rel}`,
-        path: rel,
-        detail: err instanceof Error ? err.message : String(err)
-      });
-      continue;
-    }
-    let extract;
-    try {
-      extract = await adapter.extract({
-        filePath: normalize5(rel).replace(/\\/g, "/"),
-        source,
-        projectRoot
-      });
-    } catch (err) {
-      gaps.push({
-        code: "parse_error",
-        message: `Parse failed for ${rel} (continuing with other files).`,
-        path: rel,
-        detail: err instanceof Error ? err.message : String(err)
-      });
-      continue;
-    }
-    if (!extract.ok) {
+  }
+  if (request.paths?.length) {
+    hits = hits.filter((hit) => pathKept(hit.path, fileArgs, dirArgs));
+  }
+  const names = request.symbols ?? [];
+  if (names.length) {
+    hits = hits.filter((hit) => symbolKept(hit.symbol, names));
+    hits.sort((a, b) => {
+      const aExact = names.some((name) => a.symbol === name) ? 0 : 1;
+      const bExact = names.some((name) => b.symbol === name) ? 0 : 1;
+      return aExact - bExact;
+    });
+  }
+  if (!query.trim()) hits = hits.slice(0, k);
+  const indexed = new Set((await listScopeHits(projectRoot, "code")).map((hit) => hit.path));
+  for (const rel of fileArgs) {
+    const ext = extname3(rel).toLowerCase();
+    if (ext === ".go") continue;
+    if (isSecretPath(rel) || isIgnoredPath(rel)) continue;
+    if (!indexed.has(rel) && ext) {
       gaps.push({
         code: "parse_error",
         message: `Parse failed for ${rel} (continuing with other files).`,
-        path: rel,
-        detail: extract.errors?.join("; ")
-      });
-      if (!extract.symbols.length) continue;
-    }
-    extract.symbols = extract.symbols.map((s) => ({
-      ...s,
-      filePath: normalize5(rel).replace(/\\/g, "/")
-    }));
-    if (!extract.symbols.length && extract.ok) {
-      gaps.push({
-        code: "empty_extract",
-        message: `No symbols extracted from ${rel}.`,
         path: rel
       });
     }
-    graph.add(normalize5(rel).replace(/\\/g, "/"), source, extract);
-    filesAnalyzed++;
-    symbolsExtracted += extract.symbols.length;
   }
-  const ranked = rankSymbols(graph, plan, caps);
-  const sliceResult = emitSlices(ranked, graph, caps, {
-    includeNeighbors: request.includeNeighbors
-  });
-  gaps.push(...sliceResult.gaps);
-  truncated = truncated || sliceResult.truncated;
+  const packed = packHits({ preamble: "", hits, budget });
+  try {
+    writePackedCache(cacheRequest, packed, hits, mode, hybridScopes);
+  } catch {
+  }
+  const truncated = hits.length > packed.hits.length || packed.hits.some((hit) => hit.form === "signature");
+  if (truncated) {
+    gaps.push({
+      code: "cap_truncated",
+      message: "Packed under the token budget. Lower hits are signatures."
+    });
+  }
+  const slices = packed.hits.map((hit) => ({
+    id: `${hit.path}:${hit.startLine}-${hit.endLine}:${hit.symbol}`,
+    filePath: hit.path,
+    startLine: hit.startLine,
+    endLine: hit.endLine,
+    symbolName: hit.symbol,
+    reason: hit.form === "full" ? "keyword full" : "keyword signature",
+    body: hit.form === "full" ? hit.body : hit.signature
+  }));
   const summary = {
     focusPaths: plan.seedPaths,
     focusSymbols: plan.seedSymbols,
     keywords: plan.keywords,
-    filesAnalyzed,
-    symbolsExtracted,
-    slicesEmitted: sliceResult.slices.length,
+    filesAnalyzed: new Set(hits.map((hit) => hit.path)).size,
+    symbolsExtracted: hits.length,
+    slicesEmitted: slices.length,
     truncated
   };
-  let changeTitle = plan.changeId;
-  if (plan.changeId) {
-    try {
-      const { readYaml: readYaml2 } = await import("./fs-J6DIV6CX.js");
-      const metaPath = join6(
-        projectRoot,
-        // best-effort: changes/<id>/meta.yaml via relative walk
-        // Prefer using change path from resolve — re-read lightly
-        "changes",
-        plan.changeId,
-        "meta.yaml"
-      );
-      const { loadConfig: loadConfig2 } = await import("./config-X5VDBVR4.js");
-      const { changePath: changePath2 } = await import("./paths-64GA32IZ.js");
-      const config = await loadConfig2(projectRoot);
-      const mp = join6(changePath2(projectRoot, config, plan.changeId), "meta.yaml");
-      if (await pathExists(mp)) {
-        const meta = await readYaml2(mp);
-        changeTitle = meta.title ?? plan.changeId;
-      } else if (await pathExists(metaPath)) {
-        const meta = await readYaml2(metaPath);
-        changeTitle = meta.title ?? plan.changeId;
-      }
-    } catch {
-    }
-  }
   const formatted = formatMarkdown({
     plan,
     summary,
-    slices: sliceResult.slices,
+    slices,
     gaps,
     changeTitle,
-    maxOutputLines: caps.maxOutputLines,
-    maxTokensApprox: caps.maxTokensApprox
-  });
-  if (formatted.truncated && !summary.truncated) {
-    summary.truncated = true;
-    if (!gaps.some((g) => g.code === "cap_truncated")) {
-      gaps.push({
-        code: "cap_truncated",
-        message: "Output truncated at configured caps (maxOutputLines/maxTokensApprox)."
-      });
-    }
-  }
-  const finalFormat = formatMarkdown({
-    plan,
-    summary,
-    slices: sliceResult.slices,
-    gaps,
-    changeTitle,
-    maxOutputLines: caps.maxOutputLines,
-    maxTokensApprox: caps.maxTokensApprox
+    packedText: packed.text
   });
   let artifactPath;
   if (request.writeArtifactTo) {
-    await writeText(request.writeArtifactTo, finalFormat.markdown);
+    await writeText(request.writeArtifactTo, formatted.markdown);
     artifactPath = request.writeArtifactTo;
   }
   return {
     ok: true,
-    markdown: finalFormat.markdown,
+    markdown: formatted.markdown,
     summary,
-    slices: sliceResult.slices,
+    slices,
     gaps,
     artifactPath
   };
+  async function finishContext(packedHits, packedText, warning) {
+    if (warning) {
+      gaps.push({ code: "embeddings_unavailable", message: EMBEDDINGS_UNAVAILABLE });
+    }
+    const truncated2 = packedHits.some((hit) => hit.form === "signature");
+    if (truncated2) {
+      gaps.push({
+        code: "cap_truncated",
+        message: "Packed under the token budget. Lower hits are signatures."
+      });
+    }
+    const slices2 = packedHits.map((hit) => ({
+      id: `${hit.path}:${hit.startLine}-${hit.endLine}:${hit.symbol}`,
+      filePath: hit.path,
+      startLine: hit.startLine,
+      endLine: hit.endLine,
+      symbolName: hit.symbol,
+      reason: hit.form === "full" ? "keyword full" : "keyword signature",
+      body: hit.form === "full" ? hit.body : hit.signature
+    }));
+    const summary2 = {
+      focusPaths: plan.seedPaths,
+      focusSymbols: plan.seedSymbols,
+      keywords: plan.keywords,
+      filesAnalyzed: new Set(packedHits.map((hit) => hit.path)).size,
+      symbolsExtracted: packedHits.length,
+      slicesEmitted: slices2.length,
+      truncated: truncated2
+    };
+    const formatted2 = formatMarkdown({
+      plan,
+      summary: summary2,
+      slices: slices2,
+      gaps,
+      changeTitle,
+      packedText
+    });
+    let artifactPath2;
+    if (request.writeArtifactTo) {
+      await writeText(request.writeArtifactTo, formatted2.markdown);
+      artifactPath2 = request.writeArtifactTo;
+    }
+    return {
+      ok: true,
+      markdown: formatted2.markdown,
+      summary: summary2,
+      slices: slices2,
+      gaps,
+      artifactPath: artifactPath2
+    };
+  }
 }
 
 // src/refine.ts
-import { join as join7 } from "pathe";
+import { join as join7, relative as relative3 } from "pathe";
 function stageArtifactRefs(ctx, stageId) {
   const stage = getStage(ctx.workflow, ctx.meta, stageId);
   if (!stage) return [];
@@ -1906,10 +2217,10 @@ function stageArtifactRefs(ctx, stageId) {
     absPath: join7(ctx.path, a.path)
   }));
 }
-function listMarkdown(refs) {
+function listMarkdown(refs, displayDir) {
   if (!refs.length) return "_None._";
   return refs.map(
-    (r) => `- \`${r.path}\` (stage \`${r.stageId}\`${r.required ? ", required" : ""}) \u2192 \`${r.absPath}\``
+    (r) => `- \`${r.path}\` (stage \`${r.stageId}\`${r.required ? ", required" : ""}) \u2192 \`${displayDir}/${r.path}\``
   ).join("\n");
 }
 async function buildRefinePlan(opts) {
@@ -1949,8 +2260,13 @@ async function buildRefinePlan(opts) {
   const briefPath = join7(ctx.path, "refine-brief.md");
   const reportPath = join7(ctx.path, "quality-report.md");
   const openItemsPath = join7(ctx.path, "open-items.md");
+  const paths = guidancePaths(opts.config);
+  const briefRel = `${ctx.displayPath}/refine-brief.md`;
+  const reportRel = `${ctx.displayPath}/quality-report.md`;
+  const openItemsRel = `${ctx.displayPath}/open-items.md`;
   const briefMarkdown = buildRefineBriefMarkdown({
     ctx,
+    config: opts.config,
     focusStageId,
     focusStageTitle: focusStage.title ?? focusStageId,
     mode,
@@ -1958,19 +2274,19 @@ async function buildRefinePlan(opts) {
     focusArtifacts,
     priorArtifacts,
     laterArtifacts,
-    constitutionPath,
+    constitutionPath: paths.constitution,
     constitutionExists,
-    reportPath,
-    openItemsPath
+    reportPath: reportRel,
+    openItemsPath: openItemsRel
   });
   const kickoff = [
     `SDD: ${mode} stage \`${focusStageId}\`.`,
     `Title: ${ctx.meta.title}`,
     `Change: ${ctx.id}`,
-    `Read first: ${briefPath}`,
+    `Read first: ${briefRel}`,
     `Also: .sdd/protocol.md, .sdd/active-context.md`,
-    constitutionExists ? `Constitution (READ-ONLY): ${constitutionPath}` : `No constitution.md found (optional).`,
-    mode === "analyze" ? `Mode ANALYZE: write findings to ${reportPath} only \u2014 do not edit pack artifacts.` : `Mode REFINE: improve focus-stage artifacts; impact-scan prior pack files (fix mechanical inconsistencies; highlight judgment calls). Never edit constitution. Do not run sdd next.`,
+    constitutionExists ? `Constitution (READ-ONLY): ${paths.constitution}` : `No constitution.md found (optional).`,
+    mode === "analyze" ? `Mode ANALYZE: write findings to ${reportRel} only \u2014 do not edit pack artifacts.` : `Mode REFINE: improve focus-stage artifacts; impact-scan prior pack files (fix mechanical inconsistencies; highlight judgment calls). Never edit constitution. Do not run sdd next.`,
     focusOnly ? `focusOnly=true: edit only focus-stage files (still read prior + constitution).` : `Prior artifacts may be auto-fixed for clear contradictions/term drift; scope changes \u2192 highlight + open-items (human accept).`
   ].join(" ");
   return {
@@ -1997,6 +2313,7 @@ async function buildRefinePlan(opts) {
 function buildRefineBriefMarkdown(opts) {
   const {
     ctx,
+    config,
     focusStageId,
     focusStageTitle,
     mode,
@@ -2009,6 +2326,7 @@ function buildRefineBriefMarkdown(opts) {
     reportPath,
     openItemsPath
   } = opts;
+  const paths = guidancePaths(config);
   return `# Refine brief (auto-generated)
 
 > Change: **${ctx.meta.title}** \xB7 \`${ctx.id}\`  
@@ -2021,9 +2339,10 @@ function buildRefineBriefMarkdown(opts) {
 You are the **SDD refine** agent (one agent, mode \`${mode}\`).
 
 1. Work by **stage**, not hard-coded filenames. Focus stage resolves to the files below.
-2. **Never edit** \`memory/constitution.md\` (or any constitution path). Read it as constraints only.
-3. **Do not** run \`sdd next\`, \`sdd complete\`, or change \`meta.yaml\` stage/status.
-4. Process is **never blocked** by findings \u2014 report and improve docs only.
+2. **Never edit** \`${paths.constitution}\` (or any constitution path). Read it as constraints only.
+3. Stage-scoped refine brief lives at \`${paths.changes}/<id>/refine-brief.md\`.
+4. **Do not** run \`sdd next\`, \`sdd complete\`, or change \`meta.yaml\` stage/status.
+5. Process is **never blocked** by findings \u2014 report and improve docs only.
 
 ## Constitution (READ-ONLY)
 
@@ -2031,11 +2350,11 @@ ${constitutionExists ? `- Path: \`${constitutionPath}\` \u2014 **read only**. Co
 
 ## Focus stage artifacts (primary ${mode === "analyze" ? "review" : "edit"} target)
 
-${listMarkdown(focusArtifacts)}
+${listMarkdown(focusArtifacts, ctx.displayPath)}
 
 ## Prior stage artifacts (pack trail \u2014 always read)
 
-${listMarkdown(priorArtifacts)}
+${listMarkdown(priorArtifacts, ctx.displayPath)}
 
 ${focusOnly ? `**focusOnly:** Do **not** edit prior files. Still read them for consistency. Highlight conflicts for the human.` : `**Auto prior impact (required):** After refining the focus stage, use search (\`rg\` / grep) across the change pack for terms, claims, and names you changed. For each hit on a **prior** artifact:
 - **Fix** mechanical inconsistencies (contradictions, renamed terms, outdated references that clearly disagree with the refined focus).
@@ -2044,7 +2363,7 @@ ${focusOnly ? `**focusOnly:** Do **not** edit prior files. Still read them for c
 
 ## Later stage artifacts (usually leave alone)
 
-${listMarkdown(laterArtifacts)}
+${listMarkdown(laterArtifacts, ctx.displayPath)}
 
 Do **not** invent content for later stages that were not materialized yet. If a later file exists and contradicts the refined focus, **highlight** only (unless the human asked to align the whole pack).
 
@@ -2078,11 +2397,12 @@ Do **not** invent content for later stages that were not materialized yet. If a
 async function writeRefineBrief(plan, projectRoot) {
   await writeText(plan.briefPath, plan.briefMarkdown);
   const pointer = join7(sddRoot(projectRoot), "refine-brief.md");
+  const briefRel = relative3(projectRoot, plan.briefPath);
   await writeText(
     pointer,
     `# Refine brief pointer
 
-Active refine brief: \`${plan.briefPath}\`
+Active refine brief: \`${briefRel}\`
 
 Run: \`sdd refine${plan.focusStageId ? ` ${plan.focusStageId}` : ""}\`
 
@@ -2090,79 +2410,1644 @@ Run: \`sdd refine${plan.focusStageId ? ` ${plan.focusStageId}` : ""}\`
   );
   return plan.briefPath;
 }
+
+// src/role/handoff.ts
+import { join as join10 } from "pathe";
+import { parse as parseYaml3, stringify as stringifyYaml2 } from "yaml";
+
+// src/role/profile.ts
+import { readFile, writeFile } from "fs/promises";
+import { join as join8 } from "pathe";
+import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
+
+// src/role/types.ts
+var ROLE_TEXT = {
+  needsJob: "A role needs a job.",
+  notFound: "Role not found.",
+  exists: "Role already exists.",
+  badName: "A role name is not valid.",
+  self: "A role cannot review itself.",
+  x: "X is not a role tool.",
+  needsSection: "This needs an accepted section before a draft.",
+  noModel: "No role model is configured.",
+  cannot: "A role cannot do that.",
+  askFirst: "Ask first. This stays stopped.",
+  choice: "Allow once, Always allow, or Deny.",
+  unavailable: "This action is not available in this slice.",
+  expired: "Expired. The action did not run.",
+  runNotFound: "Run not found.",
+  badYaml: "role.yaml is invalid"
+};
+
+// src/role/profile.ts
+var NAME_LIMIT = 80;
+function canonicalRoleName(input) {
+  const name = input.trim();
+  if (!name || name === "." || name === "..") return null;
+  if (name.length > NAME_LIMIT) return null;
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) return null;
+  return name;
+}
+function roleFilePath(root, name) {
+  return join8(root, ".sdd", "roles", `${name}.md`);
+}
+function conversationDir(root, name) {
+  return join8(root, ".sdd", "role-runs", "conversation", name);
+}
+function memoryDir2(root, name) {
+  return join8(root, ".sdd", "role-runs", "memory", name);
+}
+function allowFilePath(root) {
+  return join8(root, ".sdd", "role-runs", "allow.json");
+}
+function ok(stdout = "") {
+  return { exitCode: 0, stdout };
+}
+function fail(stdout) {
+  return { exitCode: 1, stdout };
+}
+function asText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function parseRoleDocument(name, raw) {
+  const text = raw.replace(/^\uFEFF/, "");
+  const nl = text.indexOf("\n");
+  if (nl < 0 || text.slice(0, nl).trim() !== "---") return null;
+  const rest = text.slice(nl + 1);
+  const close = /\r?\n---\s*(?:\r?\n|$)/.exec(rest);
+  if (!close) return null;
+  let data;
+  try {
+    data = parseYaml2(rest.slice(0, close.index));
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const rec = data;
+  const body = rest.slice(close.index + close[0].length).trim();
+  return {
+    name,
+    label: asText(rec.label),
+    job: asText(rec.job),
+    description: body,
+    askFirst: rec.ask_first === true,
+    pinned: rec.pinned === true,
+    hidden: rec.hidden === true
+  };
+}
+function renderRole(role) {
+  const front = stringifyYaml(
+    {
+      name: role.name,
+      label: role.label,
+      job: role.job,
+      ask_first: role.askFirst,
+      pinned: role.pinned,
+      hidden: role.hidden
+    },
+    { lineWidth: 100 }
+  ).trimEnd();
+  const description = role.description.trim();
+  if (!description) return `---
+${front}
+---
+`;
+  return `---
+${front}
+---
+${description}
+`;
+}
+async function readRole(root, name) {
+  const canonical = canonicalRoleName(name);
+  if (!canonical) return null;
+  const path = roleFilePath(root, canonical);
+  if (!await pathExists(path)) return null;
+  try {
+    return parseRoleDocument(canonical, await readText(path));
+  } catch {
+    return null;
+  }
+}
+async function writeRole(root, role) {
+  await writeText(roleFilePath(root, role.name), renderRole(role));
+}
+async function createRole(root, input) {
+  const name = canonicalRoleName(input.name);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const job = input.job.trim();
+  if (!job) return fail(ROLE_TEXT.needsJob);
+  if (await pathExists(roleFilePath(root, name))) return fail(ROLE_TEXT.exists);
+  await writeRole(root, {
+    name,
+    label: input.label.trim(),
+    job,
+    description: (input.description ?? "").trim(),
+    askFirst: input.askFirst === true,
+    pinned: false,
+    hidden: false
+  });
+  return ok();
+}
+async function editRole(root, nameInput, patch) {
+  const name = canonicalRoleName(nameInput);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const role = await readRole(root, name);
+  if (!role) return fail(ROLE_TEXT.notFound);
+  if (patch.job !== void 0 && !patch.job.trim()) return fail(ROLE_TEXT.needsJob);
+  if (patch.label !== void 0) role.label = patch.label.trim();
+  if (patch.job !== void 0) role.job = patch.job.trim();
+  if (patch.description !== void 0) role.description = patch.description.trim();
+  if (patch.askFirst !== void 0) role.askFirst = patch.askFirst;
+  await writeRole(root, role);
+  return ok();
+}
+async function setFlag(root, nameInput, flag) {
+  const name = canonicalRoleName(nameInput);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const role = await readRole(root, name);
+  if (!role) return fail(ROLE_TEXT.notFound);
+  role[flag] = true;
+  await writeRole(root, role);
+  return ok();
+}
+function pinRole(root, name) {
+  return setFlag(root, name, "pinned");
+}
+function hideRole(root, name) {
+  return setFlag(root, name, "hidden");
+}
+async function showRoles(root, opts = {}) {
+  if (opts.name !== void 0) {
+    const name = canonicalRoleName(opts.name);
+    if (!name) return fail(ROLE_TEXT.badName);
+    const path = roleFilePath(root, name);
+    if (!await pathExists(path) || !await readRole(root, name)) return fail(ROLE_TEXT.notFound);
+    return ok((await readText(path)).replace(/\s*$/, ""));
+  }
+  const dir = join8(root, ".sdd", "roles");
+  if (!await pathExists(dir)) return ok();
+  const roles = [];
+  for (const file of await listFiles(dir)) {
+    if (!file.endsWith(".md")) continue;
+    const role = await readRole(root, file.slice(0, -".md".length));
+    if (!role) continue;
+    if (role.hidden && !opts.all) continue;
+    roles.push(role);
+  }
+  roles.sort((a, b) => {
+    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
+    if (a.name < b.name) return -1;
+    if (a.name > b.name) return 1;
+    return 0;
+  });
+  return ok(roles.map((role) => `${role.name} ${role.label}`).join("\n"));
+}
+async function duplicateRole(root, nameInput) {
+  const name = canonicalRoleName(nameInput);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const source = await readRole(root, name);
+  if (!source) return fail(ROLE_TEXT.notFound);
+  const copyName = canonicalRoleName(`${name} copy`);
+  if (!copyName) return fail(ROLE_TEXT.badName);
+  if (await pathExists(roleFilePath(root, copyName))) return fail(ROLE_TEXT.exists);
+  await writeRole(root, { ...source, name: copyName });
+  return ok();
+}
+async function deleteRole(root, nameInput) {
+  const name = canonicalRoleName(nameInput);
+  if (!name) return fail(ROLE_TEXT.badName);
+  const path = roleFilePath(root, name);
+  if (!await pathExists(path)) return fail(ROLE_TEXT.notFound);
+  await removePath(path);
+  await removePath(conversationDir(root, name));
+  await removePath(memoryDir2(root, name));
+  await removeAllowKey(root, name);
+  return ok();
+}
+async function removeAllowKey(root, name) {
+  const path = allowFilePath(root);
+  if (!await pathExists(path)) return;
+  let data;
+  try {
+    data = JSON.parse(await readText(path));
+  } catch {
+    return;
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return;
+  const rec = data;
+  if (!(name in rec)) return;
+  delete rec[name];
+  await writeFile(path, `${JSON.stringify(rec, null, 2)}
+`, "utf8");
+}
+async function listConversationRoles(root) {
+  return listDirs(join8(root, ".sdd", "role-runs", "conversation"));
+}
+async function readAllowFile(root) {
+  const path = allowFilePath(root);
+  if (!await pathExists(path)) return null;
+  try {
+    const data = JSON.parse(await readFile(path, "utf8"));
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+// src/role/run.ts
+import { appendFile } from "fs/promises";
+import { isAbsolute as isAbsolute3, join as join9 } from "pathe";
+var DRAFT_KINDS = /* @__PURE__ */ new Set(["code", "scenario", "release"]);
+var FORBIDDEN = /* @__PURE__ */ new Set([
+  "accept_spec",
+  "replace_decision",
+  "write_qa",
+  "generate_release",
+  "sdd_next",
+  "sdd_complete",
+  "create_change"
+]);
+var UNAVAILABLE = /* @__PURE__ */ new Set(["commit", "push", "tag", "pull_request", "merge", "deploy"]);
+var CLOSED = /* @__PURE__ */ new Set(["applied", "denied", "rejected", "unavailable", "stopped", "expired"]);
+function ok2(stdout = "", runId) {
+  return runId ? { exitCode: 0, stdout, runId } : { exitCode: 0, stdout };
+}
+function fail2(stdout, runId) {
+  return runId ? { exitCode: 1, stdout, runId } : { exitCode: 1, stdout };
+}
+function linesOf(...parts) {
+  return parts.filter((part) => part.length > 0).join("\n");
+}
+function runIdFrom(date) {
+  const iso = date.toISOString();
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/.exec(iso);
+  if (!match) return "unknown";
+  return `${match[1]}${match[2]}${match[3]}T${match[4]}${match[5]}${match[6]}Z`;
+}
+function mentionsX(task) {
+  return /@X|x\.com|twitter\.com/.test(task);
+}
+function safeChangeId(id) {
+  if (!id || id.length > 200) return false;
+  if (id === "." || id === "..") return false;
+  return !id.includes("/") && !id.includes("\\") && !id.includes("\0");
+}
+function safeRunId(id) {
+  if (!id || id.length > 80) return false;
+  if (id === "." || id === "..") return false;
+  return !id.includes("/") && !id.includes("\\") && !id.includes("\0");
+}
+function isSafeProductPath(rel) {
+  if (typeof rel !== "string" || rel.length === 0 || rel.includes("\0")) return false;
+  if (isAbsolute3(rel) || rel.startsWith("\\")) return false;
+  if (/^[A-Za-z]:/.test(rel)) return false;
+  const parts = rel.split(/[/\\]/);
+  for (const part of parts) {
+    if (part === "" || part === "." || part === ".." || part === ".active" || part === ".sdd") {
+      return false;
+    }
+  }
+  return parts[parts.length - 1] !== "accepted.md";
+}
+function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const rec = value;
+    const out = {};
+    for (const key of Object.keys(rec).sort()) out[key] = sortKeys(rec[key]);
+    return out;
+  }
+  return value;
+}
+function sameInputs(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+function sameCiteSet(changed, cites) {
+  const left = [...new Set(changed)].sort();
+  const right = [...new Set(cites)].sort();
+  return left.length === right.length && left.every((cite, index) => cite === right[index]);
+}
+function parseSection(markdown, sectionId) {
+  const rows = markdown.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i] ?? "";
+    if (row.startsWith("## ") && row.slice(3).trim() === sectionId) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return null;
+  let end = rows.length;
+  for (let i = start + 1; i < rows.length; i++) {
+    if ((rows[i] ?? "").startsWith("## ")) {
+      end = i;
+      break;
+    }
+  }
+  const body = rows.slice(start + 1, end);
+  let decision = "";
+  let accepted = false;
+  const checks = [];
+  for (const row of body) {
+    const trimmed = row.trim();
+    if (!decision && trimmed.startsWith("decision: "))
+      decision = trimmed.slice("decision: ".length).trim();
+    if (trimmed === "accepted: yes") accepted = true;
+    if (trimmed.startsWith("- check: ")) {
+      const id = trimmed.slice("- check: ".length).trim();
+      if (id) checks.push(id);
+    }
+  }
+  if (!decision || !accepted) return null;
+  return { id: sectionId, decision, checks, body: body.join("\n") };
+}
+function parseReply(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const rec = value;
+  if (typeof rec.text !== "string") return null;
+  const gaps = [];
+  if (rec.gaps !== void 0) {
+    if (!Array.isArray(rec.gaps)) return null;
+    for (const gap of rec.gaps) {
+      if (!gap || typeof gap !== "object" || Array.isArray(gap)) return null;
+      const item = gap;
+      if (typeof item.cite !== "string" || typeof item.text !== "string") return null;
+      gaps.push({ cite: item.cite, text: item.text });
+    }
+  }
+  let changed = null;
+  if (rec.changed !== void 0) {
+    if (!Array.isArray(rec.changed) || rec.changed.some((cite) => typeof cite !== "string"))
+      return null;
+    changed = rec.changed;
+  }
+  let action = null;
+  if (rec.action !== void 0) {
+    if (!rec.action || typeof rec.action !== "object" || Array.isArray(rec.action)) return null;
+    const item = rec.action;
+    if (typeof item.name !== "string" || !item.name) return null;
+    if (item.words !== void 0 && typeof item.words !== "string") return null;
+    if (item.inputs !== void 0 && (!item.inputs || typeof item.inputs !== "object" || Array.isArray(item.inputs))) {
+      return null;
+    }
+    action = {
+      name: item.name,
+      words: typeof item.words === "string" ? item.words : "",
+      inputs: item.inputs && typeof item.inputs === "object" && !Array.isArray(item.inputs) ? item.inputs : {}
+    };
+  }
+  return { text: rec.text, gaps, changed, action };
+}
+async function appendJson(file, value) {
+  await ensureDir(join9(file, ".."));
+  await appendFile(file, `${JSON.stringify(value)}
+`, "utf8");
+}
+async function readJsonLines(file) {
+  const raw = await readText(file);
+  const lines = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      lines.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return lines;
+}
+async function timeoutMinutes(root) {
+  const path = join9(root, ".sdd", "role.yaml");
+  if (!await pathExists(path)) return 10;
+  let data;
+  try {
+    data = await readYaml(path);
+  } catch {
+    return "invalid";
+  }
+  if (data == null) return 10;
+  if (typeof data !== "object" || Array.isArray(data)) return "invalid";
+  const rec = data;
+  if (!("approval_timeout_minutes" in rec) || rec.approval_timeout_minutes == null) return 10;
+  const minutes = rec.approval_timeout_minutes;
+  if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes < 0) return "invalid";
+  return minutes;
+}
+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}`
+  ];
+  if (section) {
+    rows.push(
+      `Section: ${section.id}`,
+      `Decision: ${section.decision}`,
+      "Check ids:",
+      ...section.checks
+    );
+    rows.push("Section text:", section.body);
+  }
+  return rows.join("\n");
+}
+function critiquePrompt(role, section, draft) {
+  return [
+    `Job: ${role.job}`,
+    "Check ids:",
+    ...section.checks,
+    `Cite: ${section.id}:${section.decision}`,
+    "Draft:",
+    draft
+  ].join("\n");
+}
+function revisionPrompt(role, draft, gaps) {
+  return [
+    `Job: ${role.job}`,
+    "Draft:",
+    draft,
+    "Gaps:",
+    ...gaps.map((gap) => `${gap.cite}: ${gap.text}`),
+    "changed must list every gap cite."
+  ].join("\n");
+}
+async function acceptedFile(root, changeId) {
+  if (!await pathExists(configPath(root))) return join9(root, "changes", changeId, "accepted.md");
+  const config = await loadConfig(root);
+  return join9(changesDir(root, config), changeId, "accepted.md");
+}
+async function callModel(model, file, roleId, prompt, pass) {
+  let raw;
+  try {
+    raw = await model.complete({ roleId, prompt });
+  } catch {
+    await appendJson(file, { type: "bad_call", roleId });
+    return null;
+  }
+  const parsed = parseReply(raw);
+  if (!parsed) {
+    await appendJson(file, { type: "bad_call", roleId });
+    return null;
+  }
+  await appendJson(file, { type: "model", pass, roleId, text: parsed.text });
+  return parsed;
+}
+async function readRule(root, roleName) {
+  const data = await readAllowFile(root);
+  if (!data) return null;
+  const entry = data[roleName];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const rec = entry;
+  const name = typeof rec.tool === "string" ? rec.tool : typeof rec.name === "string" ? rec.name : "";
+  if (!name) return null;
+  if (!rec.inputs || typeof rec.inputs !== "object" || Array.isArray(rec.inputs)) return null;
+  return { name, inputs: rec.inputs };
+}
+async function saveRule(root, roleName, rule) {
+  const path = allowFilePath(root);
+  const existing = await readAllowFile(root) ?? {};
+  existing[roleName] = { tool: rule.name, inputs: rule.inputs };
+  await writeText(path, `${JSON.stringify(existing, null, 2)}
+`);
+}
+async function applyAction(root, file, roleName, action, mode) {
+  if (FORBIDDEN.has(action.name) || !UNAVAILABLE.has(action.name) && action.name !== "write_file") {
+    await appendJson(file, { type: "rejected" });
+    return { exitCode: 1, stdout: ROLE_TEXT.cannot, applied: false };
+  }
+  if (UNAVAILABLE.has(action.name)) {
+    await appendJson(file, { type: "unavailable" });
+    return { exitCode: 0, stdout: ROLE_TEXT.unavailable, applied: false };
+  }
+  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 { exitCode: 1, stdout: ROLE_TEXT.cannot, applied: false };
+  }
+  await writeText(join9(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) {
+  const action = final.action;
+  if (!action) return ok2(final.text, runId);
+  if (FORBIDDEN.has(action.name) || !UNAVAILABLE.has(action.name) && action.name !== "write_file") {
+    await appendJson(file, { type: "rejected" });
+    return fail2(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 ? ok2(stdout, runId) : fail2(stdout, runId);
+  }
+  const expiresAt = new Date(now.getTime() + minutes * 6e4).toISOString();
+  await appendJson(file, {
+    type: "pending",
+    action: { name: action.name, words: action.words, inputs: action.inputs },
+    expiresAt
+  });
+  if (role.askFirst) return ok2(linesOf(action.words, ROLE_TEXT.askFirst), runId);
+  return ok2(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 fail2(ROLE_TEXT.badYaml, runId);
+  return finishRun(
+    root,
+    file,
+    role,
+    { text: reply.text, gaps: [], changed: null, action: reply.action },
+    minutes,
+    now,
+    runId
+  );
+}
+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 ? join9(dir, last) : null;
+}
+async function runRole(root, input) {
+  const name = canonicalRoleName(input.name);
+  if (!name) return fail2(ROLE_TEXT.badName);
+  if (input.stop) {
+    if (!await readRole(root, name)) return fail2(ROLE_TEXT.notFound);
+    const latest = await latestRunFile(root, name);
+    if (!latest) return fail2(ROLE_TEXT.runNotFound);
+    await appendJson(latest, { type: "stopped" });
+    return ok2();
+  }
+  const role = await readRole(root, name);
+  if (!role) return fail2(ROLE_TEXT.notFound);
+  if (!role.job.trim()) return fail2(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 fail2(ROLE_TEXT.badName);
+    if (canonical === name) return fail2(ROLE_TEXT.self);
+    withName = canonical;
+  }
+  if (mentionsX(task)) return fail2(ROLE_TEXT.x);
+  const kind = input.kind?.trim() || "reading";
+  let section;
+  if (kind !== "reading") {
+    if (!DRAFT_KINDS.has(kind)) return fail2(ROLE_TEXT.needsSection);
+    const changeId = input.change?.trim() ?? "";
+    const sectionId = input.section?.trim() ?? "";
+    if (!safeChangeId(changeId) || !sectionId) return fail2(ROLE_TEXT.needsSection);
+    const acceptedPath = await acceptedFile(root, changeId);
+    if (!await pathExists(acceptedPath)) return fail2(ROLE_TEXT.needsSection);
+    const parsed = parseSection(await readText(acceptedPath), sectionId);
+    if (!parsed) return fail2(ROLE_TEXT.needsSection);
+    section = parsed;
+  }
+  let critic = null;
+  if (withName && section) {
+    critic = await readRole(root, withName);
+    if (!critic) return fail2(ROLE_TEXT.notFound);
+  }
+  const minutes = await timeoutMinutes(root);
+  if (minutes === "invalid") return fail2(ROLE_TEXT.badYaml);
+  if (!input.model) return fail2(ROLE_TEXT.noModel);
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const runId = runIdFrom(now);
+  const file = join9(conversationDir(root, name), `${runId}.jsonl`);
+  if (section) {
+    await appendJson(file, {
+      type: "checks",
+      ids: section.checks,
+      section: section.id,
+      decision: section.decision
+    });
+  }
+  const draft = await callModel(
+    input.model,
+    file,
+    role.name,
+    authorPrompt(role, task, kind, section),
+    1
+  );
+  if (!draft) return fail2("", runId);
+  let final = draft;
+  if (critic && section) {
+    const accepted = section;
+    const critique = await callModel(
+      input.model,
+      file,
+      critic.name,
+      critiquePrompt(critic, accepted, draft.text),
+      2
+    );
+    if (!critique) return fail2(draft.text, runId);
+    if (critique.gaps.some((gap) => !citeOk(gap.cite, accepted))) {
+      await appendJson(file, { type: "bad_call", roleId: critic.name });
+      return fail2(draft.text, runId);
+    }
+    if (critique.gaps.length > 0) {
+      const revision = await callModel(
+        input.model,
+        file,
+        role.name,
+        revisionPrompt(role, draft.text, critique.gaps),
+        3
+      );
+      if (!revision) return fail2(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 fail2(draft.text, runId);
+      }
+      final = revision;
+    }
+  }
+  return finishRun(root, file, role, final, minutes, now, runId);
+}
+function openPending(lines) {
+  let pending = null;
+  for (const line of lines) {
+    if (!line || typeof line !== "object" || Array.isArray(line)) continue;
+    const rec = line;
+    if (rec.type === "pending") {
+      const action = rec.action;
+      if (!action || typeof action !== "object" || Array.isArray(action)) {
+        pending = null;
+        continue;
+      }
+      const item = action;
+      if (typeof item.name !== "string") {
+        pending = null;
+        continue;
+      }
+      pending = {
+        name: item.name,
+        words: typeof item.words === "string" ? item.words : "",
+        inputs: item.inputs && typeof item.inputs === "object" && !Array.isArray(item.inputs) ? item.inputs : {},
+        expiresAt: typeof rec.expiresAt === "string" ? rec.expiresAt : ""
+      };
+      continue;
+    }
+    if (typeof rec.type === "string" && CLOSED.has(rec.type)) pending = null;
+  }
+  return pending;
+}
+async function findRun(root, runId) {
+  if (!safeRunId(runId)) return null;
+  const hits = [];
+  for (const roleName of await listConversationRoles(root)) {
+    const file = join9(conversationDir(root, roleName), `${runId}.jsonl`);
+    if (await pathExists(file)) hits.push({ file, roleName });
+  }
+  if (hits.length === 1) return hits[0];
+  const pendingHits = [];
+  for (const hit of hits) {
+    if (openPending(await readJsonLines(hit.file))) pendingHits.push(hit);
+  }
+  return pendingHits.length === 1 ? pendingHits[0] : null;
+}
+async function allowRole(root, input) {
+  const found = await findRun(root, input.runId);
+  if (!found) return fail2(ROLE_TEXT.runNotFound);
+  const pending = openPending(await readJsonLines(found.file));
+  if (!pending) return fail2(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 fail2(ROLE_TEXT.expired);
+  }
+  if (input.mode === "deny") {
+    await appendJson(found.file, { type: "denied" });
+    return ok2("", input.runId);
+  }
+  const role = await readRole(root, found.roleName);
+  if (!role) return fail2(ROLE_TEXT.notFound);
+  if (role.askFirst) return ok2(ROLE_TEXT.askFirst, input.runId);
+  const applied = await applyAction(root, found.file, found.roleName, pending, input.mode);
+  return applied.exitCode === 0 ? ok2(applied.stdout, input.runId) : fail2(applied.stdout, input.runId);
+}
+
+// src/role/handoff.ts
+var ID = /^[a-z][a-z0-9-]{0,39}$/;
+var ROLE_YAML = ["role.yaml"];
+function ok3(stdout = "", runId) {
+  return runId ? { exitCode: 0, stdout, runId } : { exitCode: 0, stdout };
+}
+function fail3(stdout, runId) {
+  return runId ? { exitCode: 1, stdout, runId } : { exitCode: 1, stdout };
+}
+function mentionsX2(task) {
+  return /@X|x\.com|twitter\.com/.test(task);
+}
+function safeChangeId2(id) {
+  if (!id || id.length > 200 || id === "." || id === "..") return false;
+  return !id.includes("/") && !id.includes("\\") && !id.includes("\0");
+}
+function yamlPath(root) {
+  return join10(root, ".sdd", ...ROLE_YAML);
+}
+function planPath(root, changeId, sectionId) {
+  return join10(root, ".sdd", "role-runs", "plans", changeId, `${sectionId}.json`);
+}
+async function loadYaml(root) {
+  const path = yamlPath(root);
+  if (!await pathExists(path)) return "missing";
+  let data;
+  try {
+    data = parseYaml3(await readText(path));
+  } catch {
+    return "invalid";
+  }
+  if (data == null) return {};
+  if (typeof data !== "object" || Array.isArray(data)) return "invalid";
+  const rec = data;
+  if ("approval_timeout_minutes" in rec && rec.approval_timeout_minutes != null) {
+    const minutes = rec.approval_timeout_minutes;
+    if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes < 0) return "invalid";
+  }
+  if ("role_messaging" in rec && rec.role_messaging != null && typeof rec.role_messaging !== "boolean") {
+    return "invalid";
+  }
+  return rec;
+}
+async function messagingOn(root) {
+  const loaded = await loadYaml(root);
+  if (loaded === "invalid") return "invalid";
+  if (loaded === "missing") return true;
+  return loaded.role_messaging !== false;
+}
+async function setRoleMessaging(root, enabled) {
+  const loaded = await loadYaml(root);
+  if (loaded === "invalid") return fail3(ROLE_TEXT.badYaml);
+  const raw = loaded === "missing" ? {} : loaded;
+  raw.role_messaging = enabled;
+  await writeText(yamlPath(root), stringifyYaml2(raw));
+  return ok3(enabled ? "Messaging between roles is on." : "Messaging between roles is off.");
+}
+function field(body, prefix) {
+  const found = [];
+  for (const row of body.split(/\r?\n/)) {
+    const trimmed = row.trim();
+    if (!trimmed.startsWith(prefix)) continue;
+    const value = trimmed.slice(prefix.length).trim();
+    if (value) found.push(value);
+  }
+  return found;
+}
+function unique(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const found = [];
+  for (const item of items) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    found.push(item);
+  }
+  return found;
+}
+function factsFrom(markdown) {
+  const ids = [];
+  for (const row of markdown.split(/\r?\n/)) {
+    if (row.startsWith("## ")) {
+      const id = row.slice(3).trim();
+      if (id) ids.push(id);
+    }
+  }
+  const facts = [];
+  for (const id of ids) {
+    const section = parseSection(markdown, id);
+    if (!section) continue;
+    const services = field(section.body, "service: ").filter((item) => ID.test(item));
+    const modules = field(section.body, "module: ").filter((item) => ID.test(item));
+    const owners = field(section.body, "owner: ").filter(
+      (item) => canonicalRoleName(item) === item
+    );
+    const leads = field(section.body, "lead: ").filter((item) => canonicalRoleName(item) === item);
+    const connection = connectionOf(section.body);
+    facts.push({
+      id: section.id,
+      decision: section.decision,
+      body: section.body,
+      services,
+      modules,
+      owners,
+      leads,
+      connection,
+      product: field(section.body, "scope: ").includes("product")
+    });
+  }
+  return facts;
+}
+function connectionOf(body) {
+  for (const value of field(body, "connection: ")) {
+    const parts = value.split(/\s+/);
+    if (parts.length === 2 && parts[0] && parts[1] && ID.test(parts[0]) && ID.test(parts[1])) {
+      return [parts[0], parts[1]];
+    }
+  }
+  return null;
+}
+async function acceptedFacts(root, changeId, sectionId) {
+  if (!safeChangeId2(changeId) || !sectionId) return null;
+  const path = await acceptedFile(root, changeId);
+  if (!await pathExists(path)) return null;
+  const markdown = await readText(path);
+  const all = factsFrom(markdown);
+  const current = all.find((item) => item.id === sectionId);
+  if (!current) return null;
+  return { markdown, current, all };
+}
+function handoffRecord(from, to, changeId, section) {
+  return {
+    type: "handoff",
+    from,
+    to,
+    change: changeId,
+    section: section.id,
+    decision: section.decision
+  };
+}
+function receiverPrompt(role, task, section) {
+  return [
+    `Job: ${role.job}`,
+    `Description: ${role.description}`,
+    `Task: ${task}`,
+    "Kind: handoff",
+    `Section: ${section.id}`,
+    `Decision: ${section.decision}`,
+    "Section text:",
+    section.body
+  ].join("\n");
+}
+async function handoffRole(root, input) {
+  const from = canonicalRoleName(input.from);
+  const to = canonicalRoleName(input.to);
+  if (!from || !to) return fail3(ROLE_TEXT.badName);
+  if (from === to) return fail3("A role cannot hand off to itself.");
+  const sender = await readRole(root, from);
+  const receiver = await readRole(root, to);
+  if (!sender || !receiver) return fail3(ROLE_TEXT.notFound);
+  const task = input.task ?? "";
+  if (mentionsX2(task)) return fail3(ROLE_TEXT.x);
+  const loaded = await acceptedFacts(root, input.change?.trim() ?? "", input.section?.trim() ?? "");
+  if (!loaded) return fail3(ROLE_TEXT.needsSection);
+  if (loaded.current.owners.length > 0 && !loaded.current.owners.includes(to)) {
+    return fail3("One owner handles this section.");
+  }
+  const messaging = await messagingOn(root);
+  if (messaging === false) return ok3("Messaging between roles is off.");
+  if (!input.model) return fail3(ROLE_TEXT.noModel);
+  if (messaging === "invalid") return fail3(ROLE_TEXT.badYaml);
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const runId = runIdFrom(now);
+  const senderFile = join10(conversationDir(root, from), `${runId}.jsonl`);
+  const receiverFile = join10(conversationDir(root, to), `${runId}.jsonl`);
+  const record = handoffRecord(from, to, input.change?.trim() ?? "", loaded.current);
+  await appendJson(senderFile, record);
+  await appendJson(receiverFile, record);
+  let raw;
+  try {
+    raw = await input.model.complete({
+      roleId: to,
+      prompt: receiverPrompt(receiver, task, loaded.current)
+    });
+  } catch {
+    await appendJson(receiverFile, { type: "bad_call", roleId: to });
+    return fail3("", runId);
+  }
+  const parsed = parseReply(raw);
+  if (!parsed) {
+    await appendJson(receiverFile, { type: "bad_call", roleId: to });
+    return fail3("", runId);
+  }
+  await appendJson(receiverFile, { type: "model", pass: 1, roleId: to, text: parsed.text });
+  const settled = await settleRoleReply(root, receiverFile, receiver, parsed, now, runId);
+  await appendJson(senderFile, {
+    type: "handoff_reply",
+    from: to,
+    to: from,
+    change: record.change,
+    section: record.section,
+    decision: record.decision,
+    summary: parsed.text
+  });
+  return settled;
+}
+async function showRoleGroup(root, changeId) {
+  const path = safeChangeId2(changeId) ? await acceptedFile(root, changeId) : "";
+  if (!path || !await pathExists(path)) return ok3("No roles in this group.");
+  const seen = /* @__PURE__ */ new Set();
+  const owners = [];
+  for (const section of factsFrom(await readText(path))) {
+    for (const owner of section.owners) {
+      if (seen.has(owner)) continue;
+      seen.add(owner);
+      owners.push(owner);
+    }
+  }
+  return ok3(owners.length > 0 ? owners.join("\n") : "No roles in this group.");
+}
+function distinctServices(all) {
+  const services = /* @__PURE__ */ new Map();
+  for (const section of all) {
+    for (const service of section.services) {
+      if (!services.has(service)) services.set(service, section);
+    }
+  }
+  return services;
+}
+function nodeLine(node) {
+  const after = node.after.length > 0 ? node.after.join(",") : "none";
+  return `${node.scope} ${node.owner} ${node.decision} after ${after} artifact ${node.artifact} boundary ${node.boundary}`;
+}
+function planLines(nodes) {
+  const lines = [];
+  for (const node of nodes) {
+    lines.push(nodeLine(node));
+    lines.push(...planLines(node.children));
+  }
+  return lines;
+}
+function artifactsOf(nodes) {
+  const artifacts = [];
+  for (const node of nodes) {
+    artifacts.push(node.artifact);
+    artifacts.push(...artifactsOf(node.children));
+  }
+  return artifacts;
+}
+async function readPlan(root, changeId, sectionId) {
+  const path = planPath(root, changeId, sectionId);
+  if (!await pathExists(path)) return null;
+  try {
+    const data = JSON.parse(await readText(path));
+    if (!data || !Array.isArray(data.nodes) || !Array.isArray(data.results)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+async function writePlan(root, changeId, sectionId, plan) {
+  await writeText(planPath(root, changeId, sectionId), `${JSON.stringify(plan, null, 2)}
+`);
+}
+function contextOf(all) {
+  const services = /* @__PURE__ */ new Set();
+  const modules = /* @__PURE__ */ new Set();
+  const decisions = /* @__PURE__ */ new Set();
+  for (const section of all) {
+    for (const service of section.services) services.add(service);
+    for (const moduleId of section.modules) modules.add(moduleId);
+    decisions.add(section.decision);
+  }
+  return { services, modules, decisions };
+}
+async function parsePlan(root, raw, ctx) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return "invalid";
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "invalid";
+  const rec = value;
+  if (typeof rec.text !== "string" || !Array.isArray(rec.plan)) return "invalid";
+  const seen = /* @__PURE__ */ new Set();
+  const nodes = await parseNodes(root, rec.plan, ctx, seen, true);
+  return nodes;
+}
+async function parseNodes(root, value, ctx, seen, roots) {
+  if (!Array.isArray(value)) return "invalid";
+  const nodes = [];
+  for (const item of value) {
+    const parsed = await parseNode(root, item, ctx, seen);
+    if (parsed === "invalid" || parsed === "deep") return parsed;
+    if (!roots && parsed.children.length > 0) return "deep";
+    for (const child of parsed.children) {
+      if (child.children.length > 0) return "deep";
+    }
+    nodes.push(parsed);
+  }
+  return nodes;
+}
+async function parseNode(root, value, ctx, seen) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "invalid";
+  const rec = value;
+  const scope = typeof rec.scope === "string" ? rec.scope : "";
+  const owner = typeof rec.owner === "string" ? rec.owner : "";
+  const decision = typeof rec.decision === "string" ? rec.decision : "";
+  const artifact = typeof rec.artifact === "string" ? rec.artifact : "";
+  const boundary = rec.boundary;
+  if (!ctx.services.has(scope) && !ctx.modules.has(scope)) return "invalid";
+  if (!await readRole(root, owner)) return "invalid";
+  if (!ctx.decisions.has(decision) || seen.has(decision)) return "invalid";
+  if (!Array.isArray(rec.after) || rec.after.some((id) => typeof id !== "string")) return "invalid";
+  if (rec.after.some((id) => !ctx.decisions.has(id))) return "invalid";
+  if (!isSafeProductPath(artifact)) return "invalid";
+  if (boundary !== "ask" && boundary !== "stop") return "invalid";
+  seen.add(decision);
+  let children = [];
+  if (rec.children !== void 0) {
+    const parsed = await parseNodes(root, rec.children, ctx, seen, false);
+    if (parsed === "invalid" || parsed === "deep") return parsed;
+    children = parsed;
+  }
+  return {
+    scope,
+    owner,
+    decision,
+    after: rec.after,
+    artifact,
+    boundary,
+    children
+  };
+}
+function leadPrompt(task, services) {
+  const rows = [`Task: ${task}`];
+  for (const [service, section] of services) {
+    const moduleId = section.modules[0] ?? "none";
+    const owner = section.owners[0] ?? "none";
+    rows.push(`${service} module ${moduleId} owner ${owner} decision ${section.decision}`);
+  }
+  return rows.join("\n");
+}
+async function connectionResult(root, changeId, section, now) {
+  const messaging = await messagingOn(root);
+  if (messaging === "invalid") return fail3(ROLE_TEXT.badYaml);
+  if (!messaging) return ok3("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(join10(conversationDir(root, from), `${runId}.jsonl`), record);
+    await appendJson(join10(conversationDir(root, to), `${runId}.jsonl`), record);
+  }
+  const lines = ["Connection hands off. Lead is absent.", ...owners];
+  return ok3(lines.join("\n"));
+}
+function freshPlan(task, nodes) {
+  return { status: "pending", rebuilds: 0, stalled: false, task, nodes, results: [] };
+}
+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 fail3(ROLE_TEXT.needsSection);
+  const task = input.task ?? "";
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const connection = loaded.all.find(
+    (item) => item.connection && (item.id === loaded.current.id || loaded.current.services.some((service) => item.connection?.includes(service)))
+  );
+  if (connection?.connection) return connectionResult(root, changeId, connection, now);
+  const services = distinctServices(loaded.all);
+  if (services.size === 0) return ok3("One scope. No lead.");
+  if (services.size === 1) {
+    const entry = [...services.entries()][0];
+    if (!entry) return ok3("One scope. No lead.");
+    const [name, section] = entry;
+    const owner = section.owners[0];
+    if (!owner) return fail3("This service needs an owner.");
+    if (!await readRole(root, owner)) return fail3(ROLE_TEXT.notFound);
+    return ok3(`Service ${name} runs ${owner}.`);
+  }
+  const picked = pickLead(loaded.all, services);
+  if (picked.kind === "none") return ok3("One scope. No lead.");
+  if (picked.kind === "missing") return fail3(picked.sentence);
+  const lead = await readRole(root, picked.name);
+  if (!lead) return fail3(ROLE_TEXT.notFound);
+  if (await messagingOn(root) === "invalid") return fail3(ROLE_TEXT.badYaml);
+  if (!input.model) return fail3(ROLE_TEXT.noModel);
+  return storeLeadPlan(
+    root,
+    changeId,
+    sectionId,
+    task,
+    lead,
+    services,
+    loaded.all,
+    input.model,
+    null
+  );
+}
+async function storeLeadPlan(root, changeId, sectionId, task, lead, services, all, model, previous) {
+  let raw;
+  try {
+    raw = await model.complete({ roleId: lead.name, prompt: leadPrompt(task, services) });
+  } catch {
+    return fail3("");
+  }
+  const parsed = await parsePlan(root, raw, contextOf(all));
+  if (previous && (parsed === "invalid" || parsed === "deep")) return fail3(planFailure(parsed));
+  if (parsed === "invalid") return fail3("The plan is not valid.");
+  if (parsed === "deep") return fail3("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 ok3("Stopped. The plan made no progress.");
+  }
+  const next = previous ? {
+    ...previous,
+    status: "pending",
+    stalled: false,
+    rebuilds: previous.rebuilds + 1,
+    nodes: parsed,
+    results: []
+  } : freshPlan(task, parsed);
+  await writePlan(root, changeId, sectionId, next);
+  return ok3(["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.";
+}
+function sameArtifacts(left, right) {
+  const a = artifactsOf(left).slice().sort();
+  const b = artifactsOf(right).slice().sort();
+  return a.length === b.length && a.every((item, index) => item === b[index]);
+}
+async function acceptNetwork(root, input) {
+  const changeId = input.change?.trim() ?? "";
+  const sectionId = input.section?.trim() ?? "";
+  if (!safeChangeId2(changeId) || !sectionId) return fail3("No plan is stored.");
+  const plan = await readPlan(root, changeId, sectionId);
+  if (!plan) return fail3("No plan is stored.");
+  if (plan.status !== "pending") return fail3("The plan is not waiting for acceptance.");
+  plan.status = "accepted";
+  await writePlan(root, changeId, sectionId, plan);
+  return ok3("Plan accepted.");
+}
+function walk(nodes) {
+  const flat = [];
+  for (const node of nodes) {
+    flat.push(node);
+    flat.push(...walk(node.children));
+  }
+  return flat;
+}
+function ready(node, results) {
+  if (results.some((item) => item.decision === node.decision)) return false;
+  const afterOk = node.after.every((id) => results.some((item) => item.decision === id));
+  const childrenOk = node.children.every(
+    (child) => results.some((item) => item.decision === child.decision)
+  );
+  return afterOk && childrenOk;
+}
+async function runNetwork(root, input) {
+  const changeId = input.change?.trim() ?? "";
+  const sectionId = input.section?.trim() ?? "";
+  if (!safeChangeId2(changeId) || !sectionId) return fail3("No plan is stored.");
+  const plan = await readPlan(root, changeId, sectionId);
+  if (!plan) return fail3("No plan is stored.");
+  if (plan.status === "pending") return ok3("Accept this plan before anyone writes.");
+  if (plan.status === "done") return ok3("The parent is done.");
+  if (plan.status !== "accepted" && plan.status !== "open") return fail3("No plan is stored.");
+  if (await messagingOn(root) === "invalid") return fail3(ROLE_TEXT.badYaml);
+  const minutes = await timeoutMinutes(root);
+  if (minutes === "invalid") return fail3(ROLE_TEXT.badYaml);
+  if (!input.model) return fail3(ROLE_TEXT.noModel);
+  const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
+  const summaries = [];
+  const called = /* @__PURE__ */ new Set();
+  let index = 0;
+  let progressed = true;
+  let missingOwner = false;
+  while (progressed && !missingOwner) {
+    progressed = false;
+    for (const node of walk(plan.nodes)) {
+      if (!ready(node, plan.results) || called.has(node.decision)) continue;
+      called.add(node.decision);
+      const owner = await readRole(root, node.owner);
+      if (!owner) {
+        missingOwner = true;
+        break;
+      }
+      const when = new Date(now.getTime() + index * 1e3);
+      index += 1;
+      const runId = runIdFrom(when);
+      const file = join10(conversationDir(root, owner.name), `${runId}.jsonl`);
+      let raw;
+      try {
+        raw = await input.model.complete({
+          roleId: owner.name,
+          prompt: [
+            `Job: ${owner.job}`,
+            `Description: ${owner.description}`,
+            `Task: ${plan.task}`,
+            `Artifact: ${node.artifact}`,
+            `Boundary: ${node.boundary}`
+          ].join("\n")
+        });
+      } catch {
+        continue;
+      }
+      const parsed = parseReply(raw);
+      if (!parsed) continue;
+      await appendJson(file, { type: "model", pass: 1, roleId: owner.name, text: parsed.text });
+      if (parsed.action) {
+        const expiresAt = new Date(when.getTime() + minutes * 6e4).toISOString();
+        await appendJson(file, {
+          type: "pending",
+          action: {
+            name: parsed.action.name,
+            words: parsed.action.words,
+            inputs: parsed.action.inputs
+          },
+          expiresAt
+        });
+      }
+      plan.results.push({
+        decision: node.decision,
+        artifact: node.artifact,
+        summary: parsed.text
+      });
+      summaries.push(`${owner.name}: ${parsed.text}`);
+      progressed = true;
+    }
+  }
+  const all = walk(plan.nodes);
+  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 fail3(ROLE_TEXT.notFound);
+  const lines = [...summaries];
+  if (waiting) {
+    lines.push("A branch is waiting for its prerequisites.");
+    lines.push("The parent stays open.");
+  } else {
+    lines.push("The parent is done.");
+  }
+  return ok3(lines.join("\n"));
+}
+async function rebuildNetwork(root, input) {
+  const changeId = input.change?.trim() ?? "";
+  const sectionId = input.section?.trim() ?? "";
+  if (!safeChangeId2(changeId) || !sectionId) return fail3("No plan is stored.");
+  const plan = await readPlan(root, changeId, sectionId);
+  if (!plan) return fail3("No plan is stored.");
+  const allowed = plan.rebuilds === 0 || plan.rebuilds === 1 && !plan.stalled && plan.status === "accepted";
+  if (!allowed) return fail3("A second rebuild does not start.");
+  const loaded = await acceptedFacts(root, changeId, sectionId);
+  if (!loaded) return fail3(ROLE_TEXT.needsSection);
+  if (!input.model) return fail3(ROLE_TEXT.noModel);
+  const services = distinctServices(loaded.all);
+  const picked = pickLead(loaded.all, services);
+  if (picked.kind === "missing") return fail3(picked.sentence);
+  if (picked.kind !== "lead") return fail3("This module needs a lead.");
+  const lead = await readRole(root, picked.name);
+  if (!lead) return fail3(ROLE_TEXT.notFound);
+  const before = JSON.stringify(plan);
+  const result = await storeLeadPlan(
+    root,
+    changeId,
+    sectionId,
+    plan.task,
+    lead,
+    services,
+    loaded.all,
+    input.model,
+    plan
+  );
+  if (result.exitCode !== 0) {
+    const current = await readPlan(root, changeId, sectionId);
+    if (current && JSON.stringify(current) !== before) {
+      await writePlan(root, changeId, sectionId, JSON.parse(before));
+    }
+  }
+  return result;
+}
+function pickLead(all, services) {
+  const modules = /* @__PURE__ */ new Set();
+  let missingModule = false;
+  for (const section of services.values()) {
+    const moduleId2 = section.modules[0];
+    if (!moduleId2) missingModule = true;
+    else modules.add(moduleId2);
+  }
+  const moduleId = [...modules][0];
+  if (!missingModule && modules.size === 1 && moduleId && services.size > 1) {
+    const name = all.find((item) => item.modules.includes(moduleId) && item.leads[0])?.leads[0] ?? "";
+    if (!name) return { kind: "missing", sentence: "This module needs a lead." };
+    return { kind: "lead", name };
+  }
+  if (modules.size > 1) {
+    const name = all.find((item) => item.product && item.leads[0])?.leads[0] ?? "";
+    if (!name) return { kind: "missing", sentence: "This product needs a lead." };
+    return { kind: "lead", name };
+  }
+  return { kind: "none" };
+}
+
+// src/stories.ts
+import { join as join11 } from "pathe";
+var STORY_ID = /^S-\d+$/i;
+var EPIC_KEY = /^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/;
+function validBranchName(name) {
+  if (!name || name === "." || name === ".." || name.includes(" ") || name.includes("..")) {
+    return false;
+  }
+  if (name.startsWith("/") || name.endsWith("/") || name.endsWith(".lock") || name.includes("@{")) {
+    return false;
+  }
+  if (/[\\~^:?*[]/.test(name)) return false;
+  return name.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+function parseStoryDraft(input) {
+  const epic = input.epic?.trim() ?? "";
+  const storyRaw = input.story?.trim() ?? "";
+  const dependsRaw = (input.depends ?? []).map((item) => item.trim()).filter((item) => item.length > 0);
+  if ((storyRaw || dependsRaw.length > 0) && !epic) {
+    return { ok: false, stdout: "A story needs an epic." };
+  }
+  if (epic && !EPIC_KEY.test(epic)) return { ok: false, stdout: "An epic key is not valid." };
+  if (dependsRaw.length > 0 && !storyRaw) return { ok: false, stdout: "A story id is not valid." };
+  if (storyRaw && !STORY_ID.test(storyRaw))
+    return { ok: false, stdout: "A story id is not valid." };
+  const depends = [];
+  for (const dep of dependsRaw) {
+    if (!STORY_ID.test(dep)) return { ok: false, stdout: "A story id is not valid." };
+    const id = dep.toUpperCase();
+    if (!depends.includes(id)) depends.push(id);
+  }
+  return {
+    ok: true,
+    draft: {
+      epic: epic || void 0,
+      story: storyRaw ? storyRaw.toUpperCase() : void 0,
+      depends
+    }
+  };
+}
+async function metasIn(dir) {
+  const out = [];
+  for (const id of await listDirs(dir)) {
+    const path = join11(dir, id, "meta.yaml");
+    if (!await pathExists(path)) continue;
+    try {
+      out.push(ChangeMetaSchema.parse(await readYaml(path)));
+    } catch {
+    }
+  }
+  return out;
+}
+async function loadEpicStories(projectRoot, config, epic) {
+  const metas = [
+    ...await metasIn(changesDir(projectRoot, config)),
+    ...await metasIn(archiveDir(projectRoot, config))
+  ];
+  const nodes = [];
+  for (const meta of metas) {
+    if (meta.epic !== epic || !meta.story) continue;
+    nodes.push({
+      changeId: meta.id,
+      title: meta.title,
+      story: meta.story.toUpperCase(),
+      epic: meta.epic,
+      depends: (meta.depends ?? []).map((item) => item.toUpperCase()),
+      status: meta.status
+    });
+  }
+  return nodes;
+}
+async function storyIdTaken(projectRoot, config, epic, story) {
+  const nodes = await loadEpicStories(projectRoot, config, epic);
+  return nodes.some((node) => node.story === story.toUpperCase());
+}
+function byStoryId(left, right) {
+  if (left.story < right.story) return -1;
+  if (left.story > right.story) return 1;
+  return 0;
+}
+function formatEpicGraph(nodes) {
+  const ordered = [...nodes].sort(byStoryId);
+  const byStory = /* @__PURE__ */ new Map();
+  for (const node of ordered) {
+    if (byStory.has(node.story))
+      return { exitCode: 1, stdout: `Story ${node.story} already exists.` };
+    byStory.set(node.story, node);
+  }
+  for (const node of ordered) {
+    for (const dep of [...node.depends].sort()) {
+      if (!byStory.has(dep)) {
+        return {
+          exitCode: 1,
+          stdout: `${node.story} depends on ${dep}, which is not in this epic.`
+        };
+      }
+    }
+  }
+  const wave = /* @__PURE__ */ new Map();
+  const stack = [];
+  const visit = (id) => {
+    if (wave.has(id)) return null;
+    if (stack.includes(id)) {
+      const at = stack.indexOf(id);
+      return `Story cycle: ${[...stack.slice(at), id].join(" -> ")}`;
+    }
+    stack.push(id);
+    const node = byStory.get(id);
+    if (!node) return null;
+    let deepest = 0;
+    for (const dep of [...node.depends].sort()) {
+      const err = visit(dep);
+      if (err) return err;
+      deepest = Math.max(deepest, wave.get(dep) ?? 0);
+    }
+    stack.pop();
+    wave.set(id, deepest + 1);
+    return null;
+  };
+  for (const node of ordered) {
+    const err = visit(node.story);
+    if (err) return { exitCode: 1, stdout: err };
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const node of ordered) {
+    const number = wave.get(node.story) ?? 1;
+    const list = groups.get(number) ?? [];
+    list.push(node);
+    groups.set(number, list);
+  }
+  const lines = [];
+  const parallel = [];
+  for (const number of [...groups.keys()].sort((left, right) => left - right)) {
+    const group = groups.get(number) ?? [];
+    lines.push(`Wave ${number}`);
+    for (const node of group) {
+      const deps = [...node.depends].sort();
+      lines.push(
+        deps.length > 0 ? `${node.story} ${node.title} after ${deps.join(", ")}` : `${node.story} ${node.title}`
+      );
+    }
+    if (group.length > 1) parallel.push(group.map((node) => node.story).join(", "));
+  }
+  if (parallel.length === 0) lines.push("Parallel: none");
+  for (const line of parallel) lines.push(`Parallel: ${line}`);
+  const serial = ordered.filter((node) => node.depends.length > 0);
+  if (serial.length === 0) lines.push("Serial: none");
+  for (const node of serial) {
+    lines.push(`Serial: ${node.story} after ${[...node.depends].sort().join(", ")}`);
+  }
+  return { exitCode: 0, stdout: lines.join("\n") };
+}
+function branchBlock(nodes, story) {
+  const graph = formatEpicGraph(nodes);
+  if (graph.exitCode !== 0) return graph.stdout;
+  const node = nodes.find((item) => item.story === story);
+  if (!node) return null;
+  const waiting = [...node.depends].sort().filter((dep) => {
+    const other = nodes.find((item) => item.story === dep);
+    return !other || other.status !== "completed";
+  });
+  if (waiting.length === 0) return null;
+  return `${story} waits on ${waiting.join(", ")}.`;
+}
 export {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
   AdapterRegistry,
+  AgentInstallPreflightError,
   ArtifactDefSchema,
   ChangeMetaSchema,
+  ChangeMetricsSchema,
   ConfigSchema,
   DEFAULT_CODE_CONTEXT_CAPS,
   DEFAULT_INIT_INTEGRATION,
+  EMBEDDINGS_UNAVAILABLE,
+  EMBEDDING_MODEL,
   GateSchema,
   McpConfigSchema,
   McpInvokeSchema,
   McpSourceSchema,
   McpWhenSchema,
   PROTOCOL_MD,
+  PhaseMetricSchema,
+  RRF_K,
   SDD_AGENT_ROLES,
   SDD_CORE_VERSION,
   SDD_DIR,
+  SUMMARY_TOKEN_CAP,
   SddError,
+  SearchConfigError,
   StageSchema,
+  TokenUsageMetricSchema,
   VerifyCommandSchema,
   WorkflowSchema,
+  acceptNetwork,
   activePointerPath,
   activeStages,
   addMcpSource,
   advanceStage,
   agentHostPaths,
   agentKickoffMessage,
+  allowRole,
   approveGate,
   archiveDir,
+  assertAgentInstallable,
+  assertSessionLogAllowed,
+  branchBlock,
+  budgetForStage,
   buildAgentPrompt,
   buildContext,
   buildRefinePlan,
+  buildRetrievedInner,
   callMcpSourceTool,
   canLeaveStage,
   changeDirName,
   changeMetaPath,
   changePath,
   changesDir,
+  changesPathRel,
+  chunkCode,
+  chunkMarkdown,
   classifyPath,
   clearActiveIf,
+  clearRegisteredSearchProviders,
+  compareChangesByFirstPhase,
   completeChange,
   configPath,
+  contentHash,
   copyDir,
   copyDirSkipExisting,
+  costFor,
+  countTokens,
+  createBuiltinProvider,
   createChange,
+  createFastembedEmbedder,
+  createRole,
   defaultConfig,
   defaultMcpConfig,
   defaultMcpYamlPath,
   defaultMemoryDir,
+  defaultPricesYamlPath,
+  defaultSearchYamlPath,
   defaultTemplatesDir,
   defaultWorkflowsDir,
   defaultsRoot,
+  deleteRole,
+  describeFsError,
+  describeKept,
+  displayArchivePath,
+  displayChangePath,
   domainsDir,
+  duplicateRole,
+  editRole,
+  embedSearchQuery,
+  emptyChangeMetrics,
   ensureDir,
   ensureMcpConfig,
   errorMessage,
+  executeSearch,
   explainMatch,
+  extractiveSummary,
   fallbackAdapter,
   fallbackIncompleteStageId,
+  fallbackWarning,
+  fastembedImportCount,
   findFeaturesBacklogPath,
   firstActiveStageId,
+  formatDuration,
+  formatEpicGraph,
   formatJsonSummary,
   formatMcpContextForHandoff,
   formatStatus,
+  ftsTokens,
+  fuseByRank,
+  fuseHits,
   gatherMcpContext,
   gatherMcpContextForChange,
   generateCodeContext,
+  generatedState,
   getActiveChangeId,
+  getHeadSha,
   getIntegration,
   getStage,
+  guidancePaths,
+  handoffRole,
+  hideRole,
+  importSessionMetrics,
   incompletePriorStageErrors,
+  indexDbPath,
   inferComplexity,
   initProject,
   installAgentIntegration,
@@ -2170,67 +4055,121 @@ export {
   integrationKeyFor,
   interpolate,
   interpolateArgs,
+  isHardDenied,
   isIgnoredPath,
   isInitialized,
+  isPrunedDir,
   isSddError,
   isSecretPath,
   isStageSkipped,
   isSubstantiveArtifactContent,
+  keywordHits,
   listBacklogFeatures,
   listChanges,
   listDirs,
   listFiles,
   listMatchingSourceIds,
   listMcpSourceTools,
+  listScopeHits,
   listWorkflowNames,
   loadChangeMeta,
   loadConfig,
+  loadEpicStories,
+  loadExcluder,
+  loadGeneratedManifest,
   loadInstalledAgent,
   loadMcpConfig,
+  loadPrices,
+  loadSearchConfig,
   loadWorkflow,
+  markGenerated,
   matchMcpSources,
   mcpConfigPath,
   mcpTimeoutMs,
   memoryDir,
+  memoryPathRel,
   mergeCaps,
+  mergeConfigDefaults,
+  mergeRankedHits,
   nextStageId,
   nowIso,
   optionForTarget,
+  packHits,
   parseAgentTargets,
   parseFeaturesBacklog,
   parseIntegration,
+  parseStoryDraft,
   pathExists,
+  phaseTiming,
+  pinRole,
+  planAgentIntegration,
+  planNetwork,
   promoteGreenfieldToMemory,
+  rankScope,
+  readChangeMetrics,
+  readHandoffCodePoints,
   readText,
   readYaml,
+  rebuildNetwork,
   recommendWorkflow,
+  reconcileGeneratedTree,
   refreshActiveAgentContext,
+  refreshConfiguredGuidance,
+  registerSearchProvider,
   removeMcpSource,
   removeOtherAgentHosts,
+  removeOtherAgentHostsDetailed,
   removePath,
+  renderAgentsMd,
+  renderBlock,
+  renderChangeReport,
+  renderMemoryIndex,
+  renderProtocolMd,
+  renderSddReadme,
   renderThinAgent,
+  repairRequiredIgnores,
+  reportAllChanges,
+  reportChange,
+  resolveActiveDirectory,
   resolveChangeId,
+  resolveEmbedder,
   resolveFocus,
+  resolveSearchProvider,
   resolveStages,
+  rrf,
   runLocalVerify,
+  runNetwork,
+  runRole,
   saveChangeMeta,
   saveConfig,
+  saveGeneratedManifest,
   saveMcpConfig,
+  scopeForPath,
   sddRoot,
+  searchConfigPath,
+  searchPreamble,
   setActiveChange,
+  setRoleMessaging,
   shouldAutoSkip,
+  showRoleGroup,
+  showRoles,
   skipStage,
   slugify,
   startFeatureFromBacklog,
   startGreenfield,
+  startPhase,
+  storyIdTaken,
   switchWorkflow,
+  syncChangeHead,
   templatesDir,
   toProcessEnv,
   todayIsoDate,
   tokenizeKeywords,
+  transitionPhase,
   typescriptAdapter,
   uniqueChangeDirName,
   updateFeatureStatus,
+  validBranchName,
   withMcpSource,
   workflowsDir,
   writeAgentHandoff,