@structured-vibe-coding/core 0.9.1 → 0.10.1

package/dist/index.js

@@ -2,35 +2,16 @@ import {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
-  ArtifactDefSchema,
-  ChangeMetaSchema,
-  ConfigSchema,
   DEFAULT_INIT_INTEGRATION,
-  GateSchema,
   PROTOCOL_MD,
   SDD_AGENT_ROLES,
-  SDD_DIR,
-  StageSchema,
-  VerifyCommandSchema,
-  WorkflowSchema,
-  activePointerPath,
   activeStages,
   agentHostPaths,
   agentKickoffMessage,
-  archiveDir,
   buildAgentPrompt,
   buildContext,
   changeDirName,
-  changeMetaPath,
-  changePath,
-  changesDir,
   clearActiveIf,
-  configPath,
-  copyDir,
-  copyDirSkipExisting,
-  defaultConfig,
-  domainsDir,
-  ensureDir,
   firstActiveStageId,
   formatStatus,
   getActiveChangeId,
@@ -40,47 +21,72 @@ import {
   installAgentIntegration,
   installAgentIntegrations,
   integrationKeyFor,
-  isInitialized,
   isStageSkipped,
   listChanges,
-  listDirs,
-  listFiles,
   listWorkflowNames,
   loadChangeMeta,
-  loadConfig,
   loadInstalledAgent,
   loadWorkflow,
-  memoryDir,
   nextStageId,
   nowIso,
   optionForTarget,
   parseAgentTargets,
   parseIntegration,
-  pathExists,
-  readText,
-  readYaml,
   recommendWorkflow,
   refreshActiveAgentContext,
   removeOtherAgentHosts,
-  removePath,
   renderThinAgent,
   resolveChangeId,
   resolveStages,
   saveChangeMeta,
-  saveConfig,
-  sddRoot,
   setActiveChange,
   shouldAutoSkip,
   slugify,
-  templatesDir,
   todayIsoDate,
   uniqueChangeDirName,
-  workflowsDir,
-  writeAgentHandoff,
+  writeAgentHandoff
+} from "./chunk-UAOFNSLQ.js";
+import {
+  ArtifactDefSchema,
+  ChangeMetaSchema,
+  ConfigSchema,
+  GateSchema,
+  StageSchema,
+  VerifyCommandSchema,
+  WorkflowSchema,
+  defaultConfig,
+  isInitialized,
+  loadConfig,
+  saveConfig
+} from "./chunk-KZHNYGD6.js";
+import {
+  SDD_DIR,
+  activePointerPath,
+  archiveDir,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  configPath,
+  domainsDir,
+  memoryDir,
+  sddRoot,
+  templatesDir,
+  workflowsDir
+} from "./chunk-7MJYPJMR.js";
+import {
+  copyDir,
+  copyDirSkipExisting,
+  ensureDir,
+  listDirs,
+  listFiles,
+  pathExists,
+  readText,
+  readYaml,
+  removePath,
   writeText,
   writeTextIfMissing,
   writeYaml
-} from "./chunk-M245MC6E.js";
+} from "./chunk-EPFURATC.js";
 
 // src/change.ts
 import { join as join2 } from "pathe";
@@ -277,7 +283,7 @@ async function createChange(input) {
   await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
   await setActiveChange(projectRoot, config, id);
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-IB37YJX6.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -360,7 +366,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
         stage2
       );
       try {
-        const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
+        const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-IB37YJX6.js");
         await refreshActiveAgentContext2(projectRoot);
       } catch {
       }
@@ -407,7 +413,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     stage
   );
   try {
-    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-BA7WVN35.js");
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-IB37YJX6.js");
     await refreshActiveAgentContext2(projectRoot);
   } catch {
   }
@@ -921,13 +927,1606 @@ ${output}`
     ok
   };
 }
+
+// src/code-context/index.ts
+import { extname as extname4, join as join8, normalize as normalize5 } from "pathe";
+
+// src/code-context/adapters/registry.ts
+import { extname as extname2 } from "pathe";
+
+// src/code-context/adapters/typescript.ts
+import ts from "typescript";
+import { extname } from "pathe";
+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());
+  }
+};
+
+// 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");
+  lines.push("");
+  lines.push(
+    "> Generated on-demand for agents. Not a substitute for process context"
+  );
+  lines.push(
+    "> (.sdd/protocol.md, active-context, change packs)."
+  );
+  lines.push(
+    "> Regenerable \u2014 run `sdd context --out change` (or pass `--path` / `--symbol`)."
+  );
+  lines.push("");
+  lines.push("## Summary");
+  lines.push(
+    `- Change: ${input.changeTitle ?? input.plan.changeId ?? "(none)"}`
+  );
+  lines.push(
+    `- Focus paths: ${input.summary.focusPaths.length ? input.summary.focusPaths.join(", ") : "(none)"}`
+  );
+  lines.push(
+    `- Focus symbols: ${input.summary.focusSymbols.length ? input.summary.focusSymbols.join(", ") : "(none)"}`
+  );
+  lines.push(
+    `- Keywords: ${input.summary.keywords.length ? input.summary.keywords.join(", ") : "(none)"}`
+  );
+  lines.push(
+    `- Files analyzed: ${input.summary.filesAnalyzed} \xB7 Symbols: ${input.summary.symbolsExtracted} \xB7 Slices: ${input.summary.slicesEmitted}`
+  );
+  lines.push(`- Truncated: ${input.summary.truncated ? "yes" : "no"}`);
+  if (input.plan.notes.length) {
+    lines.push(`- Notes: ${input.plan.notes.join("; ")}`);
+  }
+  lines.push("");
+  lines.push("## Gaps");
+  if (!input.gaps.length) {
+    lines.push("_None._");
+  } else {
+    for (const g of input.gaps) {
+      const pathPart = g.path ? ` \u2014 \`${g.path}\`` : "";
+      lines.push(`- (\`${g.code}\`) ${g.message}${pathPart}`);
+    }
+  }
+  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 };
+}
+function formatJsonSummary(summary, gaps, slices, ok) {
+  return JSON.stringify(
+    {
+      ok,
+      summary,
+      gaps,
+      slices: slices.map((s) => ({
+        id: s.id,
+        filePath: s.filePath,
+        startLine: s.startLine,
+        endLine: s.endLine,
+        symbolName: s.symbolName,
+        reason: s.reason
+      }))
+    },
+    null,
+    2
+  );
+}
+
+// src/code-context/focus.ts
+import { promises as fs } from "fs";
+import { isAbsolute, join as join6, 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
+var KEYWORD_STOPWORDS = new Set(
+  [
+    "a",
+    "an",
+    "the",
+    "and",
+    "or",
+    "to",
+    "for",
+    "of",
+    "in",
+    "on",
+    "at",
+    "by",
+    "with",
+    "from",
+    "as",
+    "is",
+    "are",
+    "be",
+    "this",
+    "that",
+    "it",
+    "we",
+    "i",
+    "you",
+    "our",
+    "add",
+    "want",
+    "feature",
+    "using",
+    "like",
+    "lets",
+    "let",
+    "explore",
+    "proper",
+    "get",
+    "code",
+    "context",
+    "agent",
+    "agents",
+    "ai",
+    "sota",
+    "state",
+    "art",
+    "techniques",
+    "change",
+    "stage",
+    "implement",
+    "please",
+    "should",
+    "must",
+    "will",
+    "can",
+    "via",
+    "into",
+    "over",
+    "under"
+  ].map((s) => s.toLowerCase())
+);
+var SOURCE_ROOTS = ["packages", "src", "lib"];
+var PATH_LIKE_RE = /(?:packages|src|lib)\/[\w./@+-]+\.\w{1,10}|`([^`]+\.\w{1,10})`|([\w./@+-]+\.(?:ts|tsx|js|jsx|mts|cts|mjs|cjs))/g;
+function tokenizeKeywords(text) {
+  const raw = text.toLowerCase().replace(/[^a-z0-9_./-]+/g, " ").split(/\s+/).filter(Boolean);
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const t of raw) {
+    if (t.length < 3) continue;
+    if (/^\d+$/.test(t)) continue;
+    if (KEYWORD_STOPWORDS.has(t)) continue;
+    if (seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+function extractPathLikeTokens(text) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  const re = new RegExp(PATH_LIKE_RE.source, "g");
+  while ((m = re.exec(text)) !== null) {
+    const p = (m[1] || m[2] || m[0]).replace(/`/g, "");
+    if (!p || seen.has(p)) continue;
+    seen.add(p);
+    found.push(p);
+  }
+  return found;
+}
+function toRepoRelative(projectRoot, p) {
+  const abs = isAbsolute(p) ? p : join6(projectRoot, p);
+  const rel = relative(projectRoot, abs);
+  return normalize3(rel).replace(/\\/g, "/");
+}
+function toAbsolute(projectRoot, p) {
+  return isAbsolute(p) ? p : join6(projectRoot, p);
+}
+async function walkFiles(absDir, projectRoot, maxFiles, out, gaps) {
+  if (out.length >= maxFiles) return;
+  if (!await pathExists(absDir)) return;
+  let entries;
+  try {
+    entries = await fs.readdir(absDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (out.length >= maxFiles) return;
+    const abs = join6(absDir, entry.name);
+    const rel = toRepoRelative(projectRoot, abs);
+    const kind = classifyPath(rel);
+    if (kind === "secret" || kind === "ignored") continue;
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".") && entry.name !== ".") continue;
+      await walkFiles(abs, projectRoot, maxFiles, out, gaps);
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+}
+async function collectUnderPaths(projectRoot, paths, maxWalk, gaps) {
+  const files = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of paths) {
+    const abs = toAbsolute(projectRoot, p);
+    const rel = toRepoRelative(projectRoot, abs);
+    const kind = classifyPath(rel);
+    if (kind === "secret") {
+      gaps.push({
+        code: "path_denied_secret",
+        message: `Skipped potential secret path: ${rel}`,
+        path: rel
+      });
+      continue;
+    }
+    if (kind === "ignored") {
+      gaps.push({
+        code: "path_ignored",
+        message: `Skipped ignored path: ${rel}`,
+        path: rel
+      });
+      continue;
+    }
+    if (!await pathExists(abs)) {
+      gaps.push({
+        code: "path_missing",
+        message: `Path not found: ${rel}`,
+        path: rel
+      });
+      continue;
+    }
+    const st = await fs.stat(abs);
+    if (st.isDirectory()) {
+      await walkFiles(abs, projectRoot, maxWalk, files, gaps);
+    } else if (st.isFile()) {
+      if (!seen.has(rel)) {
+        seen.add(rel);
+        files.push(rel);
+      }
+    }
+  }
+  const uniq = [];
+  const s = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    if (s.has(f)) continue;
+    s.add(f);
+    uniq.push(f);
+  }
+  return uniq;
+}
+async function readBounded(absPath, maxChars) {
+  if (!await pathExists(absPath)) return null;
+  try {
+    const text = await readText(absPath);
+    return text.slice(0, maxChars);
+  } catch {
+    return null;
+  }
+}
+async function resolveChangeMeta(projectRoot, changeId, gaps) {
+  let config;
+  try {
+    config = await loadConfig(projectRoot);
+  } catch {
+    return null;
+  }
+  let id = changeId ?? null;
+  if (!id) {
+    try {
+      id = await getActiveChangeId(projectRoot, config);
+    } catch {
+      id = null;
+    }
+  }
+  if (!id) {
+    gaps.push({
+      code: "no_active_change",
+      message: "No active change; focusing without change-pack signals."
+    });
+    return null;
+  }
+  const cpath = changePath(projectRoot, config, id);
+  const metaPath = join6(cpath, "meta.yaml");
+  if (!await pathExists(metaPath)) {
+    if (!await pathExists(cpath)) {
+      gaps.push({
+        code: "change_not_found",
+        message: `Change not found: ${id}`,
+        path: id
+      });
+      return null;
+    }
+  }
+  try {
+    const meta = await readYaml(metaPath);
+    return {
+      id,
+      title: meta.title ?? id,
+      path: cpath,
+      stage: meta.stage
+    };
+  } catch {
+    gaps.push({
+      code: "change_not_found",
+      message: `Could not load change meta: ${id}`,
+      path: id
+    });
+    return null;
+  }
+}
+async function searchByKeywords(projectRoot, keywords, symbols, maxFiles) {
+  const out = [];
+  const terms = [...keywords, ...symbols.map((s) => s.toLowerCase())];
+  if (!terms.length) return out;
+  for (const root of SOURCE_ROOTS) {
+    const abs = join6(projectRoot, root);
+    if (!await pathExists(abs)) continue;
+    const files = [];
+    await walkFiles(abs, projectRoot, maxFiles * 4, files, []);
+    for (const rel of files) {
+      if (out.length >= maxFiles) return out;
+      const lower = rel.toLowerCase();
+      const base = lower.split("/").pop() ?? lower;
+      if (terms.some((t) => lower.includes(t) || base.includes(t))) {
+        out.push(rel);
+        continue;
+      }
+      if (symbols.length) {
+        try {
+          const text = await readText(join6(projectRoot, rel));
+          if (symbols.some((s) => text.includes(s))) {
+            out.push(rel);
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  return out;
+}
+async function resolveFocus(request, options) {
+  const gaps = [];
+  const notes = [];
+  const projectRoot = request.projectRoot;
+  const maxWalk = options?.maxCandidateWalk ?? 200;
+  const seedSymbols = [...request.symbols ?? []].filter(Boolean);
+  let keywords = tokenizeKeywords(request.query ?? "");
+  let seedPaths = [];
+  let candidatePaths = [];
+  let changeId = request.changeId ?? null;
+  if (request.paths?.length) {
+    notes.push(`Focus from explicit paths (${request.paths.length})`);
+    const files = await collectUnderPaths(projectRoot, request.paths, maxWalk, gaps);
+    seedPaths = [...files];
+    candidatePaths = [...files];
+  }
+  const change = await resolveChangeMeta(projectRoot, request.changeId, gaps);
+  if (change) {
+    changeId = change.id;
+    const titleKw = tokenizeKeywords(change.title);
+    for (const k of titleKw) {
+      if (!keywords.includes(k)) keywords.push(k);
+    }
+    notes.push(`Change signals from: ${change.id}`);
+    for (const artifact of ["tasks.md", "feature.md", "stories.md", "lld.md"]) {
+      const body = await readBounded(join6(change.path, artifact), 8e3);
+      if (!body) continue;
+      if (!request.paths?.length) {
+        for (const p of extractPathLikeTokens(body)) {
+          const abs = toAbsolute(projectRoot, p);
+          if (await pathExists(abs)) {
+            const rel = toRepoRelative(projectRoot, abs);
+            const kind = classifyPath(rel);
+            if (kind === "allowed" && !candidatePaths.includes(rel)) {
+              candidatePaths.push(rel);
+              if (!seedPaths.includes(rel)) seedPaths.push(rel);
+            }
+          }
+        }
+      }
+      if (artifact === "tasks.md" && body) {
+        const more = tokenizeKeywords(body.slice(0, 2e3));
+        for (const k of more.slice(0, 12)) {
+          if (!keywords.includes(k)) keywords.push(k);
+        }
+      }
+    }
+    if (!request.paths?.length && (keywords.length || seedSymbols.length)) {
+      const found = await searchByKeywords(
+        projectRoot,
+        keywords,
+        seedSymbols,
+        maxWalk
+      );
+      for (const f of found) {
+        if (!candidatePaths.includes(f)) candidatePaths.push(f);
+        if (!seedPaths.includes(f) && seedPaths.length < 20) seedPaths.push(f);
+      }
+      if (found.length) notes.push(`Keyword/path search found ${found.length} candidates`);
+    }
+  }
+  if (!request.paths?.length && !change && (request.query || seedSymbols.length)) {
+    notes.push("Focus from query/symbols only");
+    const found = await searchByKeywords(
+      projectRoot,
+      keywords,
+      seedSymbols,
+      maxWalk
+    );
+    for (const f of found) {
+      if (!candidatePaths.includes(f)) candidatePaths.push(f);
+      if (!seedPaths.includes(f)) seedPaths.push(f);
+    }
+  }
+  const filteredSeeds = [];
+  for (const p of seedPaths) {
+    const kind = classifyPath(p);
+    if (kind !== "allowed") continue;
+    if (await pathExists(toAbsolute(projectRoot, p))) filteredSeeds.push(p);
+  }
+  const filteredCandidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of [...filteredSeeds, ...candidatePaths]) {
+    if (seen.has(p)) continue;
+    const kind = classifyPath(p);
+    if (kind !== "allowed") continue;
+    if (!await pathExists(toAbsolute(projectRoot, p))) continue;
+    seen.add(p);
+    filteredCandidates.push(p);
+  }
+  keywords = keywords.slice(0, 40);
+  if (seedSymbols.length && !filteredCandidates.length) {
+    notes.push("Symbols provided but no matching files found yet");
+  }
+  return {
+    plan: {
+      seedPaths: filteredSeeds,
+      seedSymbols,
+      keywords,
+      candidatePaths: filteredCandidates,
+      changeId,
+      notes
+    },
+    gaps
+  };
+}
+
+// src/code-context/graph.ts
+import { dirname as dirname2, join as join7, 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(join7(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,
+  maxSymbols: 30,
+  maxSlices: 20,
+  maxLinesPerSlice: 80,
+  maxOutputLines: 8e3,
+  maxTokensApprox: 12e3,
+  maxImportHops: 1
+};
+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);
+    return {
+      ok: true,
+      language: "text",
+      symbols: [
+        {
+          name: "(file-header)",
+          kind: "unknown",
+          filePath: input.filePath,
+          startLine: 1,
+          endLine: headEnd,
+          exported: false
+        }
+      ],
+      imports: [],
+      exports: [],
+      errors: ["fallback: no AST; shallow header only"]
+    };
+  }
+};
+
+// src/code-context/index.ts
+function emptySummary(partial) {
+  return {
+    focusPaths: [],
+    focusSymbols: [],
+    keywords: [],
+    filesAnalyzed: 0,
+    symbolsExtracted: 0,
+    slicesEmitted: 0,
+    truncated: false,
+    ...partial
+  };
+}
+function hardFailure(gaps, message, summary) {
+  const markdown = [
+    "# Code context",
+    "",
+    "> Generated on-demand for agents. Not a substitute for process context.",
+    "",
+    "## Summary",
+    `- Error: ${message}`,
+    "",
+    "## Gaps",
+    ...gaps.map(
+      (g) => `- (\`${g.code}\`) ${g.message}${g.path ? ` \u2014 \`${g.path}\`` : ""}`
+    ),
+    "",
+    "## Slices",
+    "",
+    "_None (hard failure)._",
+    "",
+    "## Structural notes",
+    "- Pipeline did not complete analysis.",
+    ""
+  ].join("\n");
+  return {
+    ok: false,
+    markdown,
+    summary: emptySummary(summary),
+    slices: [],
+    gaps
+  };
+}
+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
+      });
+    }
+    gaps.push({
+      code: "no_focus",
+      message: "Focus signals present but no candidate source files resolved. Pass --path to a file or directory."
+    });
+    return hardFailure(gaps, "No candidate files", {
+      focusSymbols: plan.seedSymbols,
+      keywords: plan.keywords,
+      focusPaths: plan.seedPaths
+    });
+  }
+  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}.`
+    });
+  }
+  const graph = new GraphLite();
+  let filesAnalyzed = 0;
+  let symbolsExtracted = 0;
+  for (const rel of candidates) {
+    const kind = classifyPath(rel);
+    if (kind === "secret") {
+      gaps.push({
+        code: "path_denied_secret",
+        message: `Skipped potential secret path: ${rel}`,
+        path: rel
+      });
+      continue;
+    }
+    if (kind === "ignored") {
+      gaps.push({
+        code: "path_ignored",
+        message: `Skipped ignored path: ${rel}`,
+        path: rel
+      });
+      continue;
+    }
+    const abs = join8(projectRoot, rel);
+    if (!await pathExists(abs)) {
+      gaps.push({
+        code: "path_missing",
+        message: `Path not found: ${rel}`,
+        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) {
+      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 summary = {
+    focusPaths: plan.seedPaths,
+    focusSymbols: plan.seedSymbols,
+    keywords: plan.keywords,
+    filesAnalyzed,
+    symbolsExtracted,
+    slicesEmitted: sliceResult.slices.length,
+    truncated
+  };
+  let changeTitle = plan.changeId;
+  if (plan.changeId) {
+    try {
+      const { readYaml: readYaml2 } = await import("./fs-J6DIV6CX.js");
+      const metaPath = join8(
+        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-4QZMRSL3.js");
+      const { changePath: changePath2 } = await import("./paths-64GA32IZ.js");
+      const config = await loadConfig2(projectRoot);
+      const mp = join8(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,
+    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
+  });
+  let artifactPath;
+  if (request.writeArtifactTo) {
+    await writeText(request.writeArtifactTo, finalFormat.markdown);
+    artifactPath = request.writeArtifactTo;
+  }
+  return {
+    ok: true,
+    markdown: finalFormat.markdown,
+    summary,
+    slices: sliceResult.slices,
+    gaps,
+    artifactPath
+  };
+}
+
+// src/refine.ts
+import { join as join9 } from "pathe";
+function stageArtifactRefs(ctx, stageId) {
+  const stage = getStage(ctx.workflow, ctx.meta, stageId);
+  if (!stage) return [];
+  return stage.artifacts.map((a) => ({
+    stageId,
+    path: a.path,
+    required: Boolean(a.required),
+    absPath: join9(ctx.path, a.path)
+  }));
+}
+function listMarkdown(refs) {
+  if (!refs.length) return "_None._";
+  return refs.map(
+    (r) => `- \`${r.path}\` (stage \`${r.stageId}\`${r.required ? ", required" : ""}) \u2192 \`${r.absPath}\``
+  ).join("\n");
+}
+async function buildRefinePlan(opts) {
+  const ctx = await buildContext(
+    opts.projectRoot,
+    opts.config,
+    opts.changeId
+  );
+  const mode = opts.mode ?? "refine";
+  const focusOnly = Boolean(opts.focusOnly);
+  const focusStageId = opts.stageId?.trim() || ctx.meta.stage;
+  const all = resolveStages(ctx.workflow, ctx.meta);
+  const focusIdx = all.findIndex((s) => s.id === focusStageId);
+  if (focusIdx < 0) {
+    const ids = all.map((s) => s.id).join(", ");
+    throw new Error(
+      `Unknown stage "${focusStageId}" for workflow "${ctx.meta.workflow}". Stages: ${ids || "(none)"}`
+    );
+  }
+  if (isStageSkipped(ctx.meta, focusStageId) || shouldAutoSkip(all[focusIdx], ctx.meta)) {
+    throw new Error(
+      `Stage "${focusStageId}" is skipped for this change. Un-skip it or pick another stage.`
+    );
+  }
+  const focusStage = all[focusIdx];
+  const priorArtifacts = [];
+  for (let i = 0; i < focusIdx; i++) {
+    const s = all[i];
+    if (isStageSkipped(ctx.meta, s.id) || shouldAutoSkip(s, ctx.meta)) continue;
+    priorArtifacts.push(...stageArtifactRefs(ctx, s.id));
+  }
+  const laterArtifacts = [];
+  for (let i = focusIdx + 1; i < all.length; i++) {
+    const s = all[i];
+    if (isStageSkipped(ctx.meta, s.id) || shouldAutoSkip(s, ctx.meta)) continue;
+    laterArtifacts.push(...stageArtifactRefs(ctx, s.id));
+  }
+  const focusArtifacts = stageArtifactRefs(ctx, focusStageId);
+  const constitutionPath = join9(memoryDir(opts.projectRoot, opts.config), "constitution.md");
+  const constitutionExists = await pathExists(constitutionPath);
+  const briefPath = join9(ctx.path, "refine-brief.md");
+  const reportPath = join9(ctx.path, "quality-report.md");
+  const openItemsPath = join9(ctx.path, "open-items.md");
+  const briefMarkdown = buildRefineBriefMarkdown({
+    ctx,
+    focusStageId,
+    focusStageTitle: focusStage.title ?? focusStageId,
+    mode,
+    focusOnly,
+    focusArtifacts,
+    priorArtifacts,
+    laterArtifacts,
+    constitutionPath,
+    constitutionExists,
+    reportPath,
+    openItemsPath
+  });
+  const kickoff = [
+    `SDD: ${mode} stage \`${focusStageId}\`.`,
+    `Title: ${ctx.meta.title}`,
+    `Change: ${ctx.id}`,
+    `Read first: ${briefPath}`,
+    `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.`,
+    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 {
+    changeId: ctx.id,
+    title: ctx.meta.title,
+    workflow: ctx.meta.workflow,
+    focusStageId,
+    focusStageTitle: focusStage.title ?? focusStageId,
+    mode,
+    focusOnly,
+    focusArtifacts,
+    priorArtifacts,
+    laterArtifacts,
+    constitutionPath,
+    constitutionExists,
+    changePath: ctx.path,
+    briefPath,
+    reportPath,
+    openItemsPath,
+    kickoff,
+    briefMarkdown
+  };
+}
+function buildRefineBriefMarkdown(opts) {
+  const {
+    ctx,
+    focusStageId,
+    focusStageTitle,
+    mode,
+    focusOnly,
+    focusArtifacts,
+    priorArtifacts,
+    laterArtifacts,
+    constitutionPath,
+    constitutionExists,
+    reportPath,
+    openItemsPath
+  } = opts;
+  return `# Refine brief (auto-generated)
+
+> Change: **${ctx.meta.title}** \xB7 \`${ctx.id}\`  
+> Workflow: \`${ctx.meta.workflow}\` \xB7 Focus stage: **${focusStageId}** (${focusStageTitle})  
+> Mode: **${mode}** \xB7 focusOnly: **${focusOnly}**  
+> Regenerable: run \`sdd refine${focusStageId !== ctx.meta.stage ? ` ${focusStageId}` : ""}\` again.
+
+## Mission
+
+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.
+
+## Constitution (READ-ONLY)
+
+${constitutionExists ? `- Path: \`${constitutionPath}\` \u2014 **read only**. Conflicts \u2192 highlight in report / open items; do not "fix" constitution.` : `- No constitution at \`${constitutionPath}\` \u2014 skip.`}
+
+## Focus stage artifacts (primary ${mode === "analyze" ? "review" : "edit"} target)
+
+${listMarkdown(focusArtifacts)}
+
+## Prior stage artifacts (pack trail \u2014 always read)
+
+${listMarkdown(priorArtifacts)}
+
+${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).
+- **Highlight** (do not silently rewrite) product/scope judgment calls \u2014 put them under Open items only if the human should explicitly accept/defer.
+- Keep prior edits **minimal** \u2014 no drive-by rewrites of history.`}
+
+## Later stage artifacts (usually leave alone)
+
+${listMarkdown(laterArtifacts)}
+
+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).
+
+## Mode-specific rules
+
+### analyze
+- Write/update \`${reportPath}\` with findings (markdown).
+- Sections: Summary \xB7 Findings (with IDs AMB-001\u2026) \xB7 Open items (explicitly accepted only) \xB7 Disposition suggestions.
+- **Do not** edit focus/prior pack artifacts (report only).
+
+### refine
+- Improve **focus** stage artifacts so this step is clear, consistent, and useful.
+- Run impact scan on **prior** pack artifacts (unless focusOnly); fix mechanical issues; highlight judgment calls.
+- Append a short "Refine log" at the bottom of \`${reportPath}\` (what changed, prior fixes, highlights).
+- **Open items:** only move something into \`${openItemsPath}\` (or an Open items section) when the human has **explicitly accepted** deferral/acceptance with a note \u2014 or list candidates under "Proposed open items (awaiting human)" in the report. Never silently park hard questions as open items.
+
+## Tools
+
+- Prefer reading full pack markdown for specs.
+- Use \`rg\`/\`grep\` for impact after edits (old terms, paths, API names).
+- Optional product code context: \`sdd context --path \u2026 --symbol \u2026\` (AST slices) \u2014 do not dump the whole repo.
+
+## Done when
+
+- Focus stage artifacts are coherent for stage \`${focusStageId}\`.
+- Prior trail has no unaddressed **mechanical** contradictions (or focusOnly + highlights).
+- Constitution was not modified.
+- User can continue with \`sdd next\` when *they* are ready (you do not advance).
+`;
+}
+async function writeRefineBrief(plan, projectRoot) {
+  await writeText(plan.briefPath, plan.briefMarkdown);
+  const pointer = join9(sddRoot(projectRoot), "refine-brief.md");
+  await writeText(
+    pointer,
+    `# Refine brief pointer
+
+Active refine brief: \`${plan.briefPath}\`
+
+Run: \`sdd refine${plan.focusStageId ? ` ${plan.focusStageId}` : ""}\`
+
+`
+  );
+  return plan.briefPath;
+}
 export {
   AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
+  AdapterRegistry,
   ArtifactDefSchema,
   ChangeMetaSchema,
   ConfigSchema,
+  DEFAULT_CODE_CONTEXT_CAPS,
   DEFAULT_INIT_INTEGRATION,
   GateSchema,
   PROTOCOL_MD,
@@ -945,11 +2544,13 @@ export {
   archiveDir,
   buildAgentPrompt,
   buildContext,
+  buildRefinePlan,
   canLeaveStage,
   changeDirName,
   changeMetaPath,
   changePath,
   changesDir,
+  classifyPath,
   clearActiveIf,
   completeChange,
   configPath,
@@ -963,9 +2564,12 @@ export {
   defaultsRoot,
   domainsDir,
   ensureDir,
+  fallbackAdapter,
   fallbackIncompleteStageId,
   firstActiveStageId,
+  formatJsonSummary,
   formatStatus,
+  generateCodeContext,
   getActiveChangeId,
   getIntegration,
   getStage,
@@ -975,7 +2579,9 @@ export {
   installAgentIntegration,
   installAgentIntegrations,
   integrationKeyFor,
+  isIgnoredPath,
   isInitialized,
+  isSecretPath,
   isStageSkipped,
   isSubstantiveArtifactContent,
   listChanges,
@@ -987,6 +2593,7 @@ export {
   loadInstalledAgent,
   loadWorkflow,
   memoryDir,
+  mergeCaps,
   nextStageId,
   nowIso,
   optionForTarget,
@@ -1001,6 +2608,7 @@ export {
   removePath,
   renderThinAgent,
   resolveChangeId,
+  resolveFocus,
   resolveStages,
   runLocalVerify,
   saveChangeMeta,
@@ -1013,9 +2621,12 @@ export {
   switchWorkflow,
   templatesDir,
   todayIsoDate,
+  tokenizeKeywords,
+  typescriptAdapter,
   uniqueChangeDirName,
   workflowsDir,
   writeAgentHandoff,
+  writeRefineBrief,
   writeText,
   writeTextIfMissing,
   writeYaml