paqad-ai 1.59.0 → 1.60.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # paqad-ai
 
+## 1.60.0
+
+### Minor Changes
+
+- 2b2ee2c: Planning now sees the codebase: on the feature-development route, the background context
+  worker composes a token-capped `## Existing surface` section into the session-context
+  artifact. It lists the exported symbols that already exist for the files/modules the prompt
+  and working set implicate — as signature cards (`name(signature) — file:line · called from N
+places · module`) ranked by the repo-map's structural importance (PageRank) — so the model
+  reuses what exists instead of rewriting it. Signatures and caller counts come from the
+  code-knowledge index when present, falling back to name-only cards otherwise. The section is
+  budget-capped (config `existing_surface_tokens`, default 1000) with an honest truncation
+  line, appears only for feature-development (every other route stays token-neutral), and rides
+  the existing artifact so Codex/Gemini/advisory hosts get it through the same file. This gives
+  the built-but-unconsumed repo-map its first live consumer.
+
 ## 1.59.0
 
 ### Minor Changes

package/dist/cli/index.js

@@ -359,6 +359,7 @@ function defaultIntelligenceConfig() {
     rag_relief_floor: 0.35,
     rag_top_n: 20,
     rag_max_file_size: 153600,
+    existing_surface_tokens: DEFAULT_EXISTING_SURFACE_TOKENS,
     benchmark_gates: { ...DEFAULT_BENCHMARK_GATES },
     benchmark_eval: { ...DEFAULT_BENCHMARK_EVAL },
     adaptive_retrieval: {
@@ -384,6 +385,7 @@ function normalizeIntelligenceConfig(input3) {
     rag_relief_floor: input3.rag_relief_floor ?? defaults.rag_relief_floor,
     rag_top_n: input3.rag_top_n ?? defaults.rag_top_n,
     rag_max_file_size: input3.rag_max_file_size ?? defaults.rag_max_file_size,
+    existing_surface_tokens: input3.existing_surface_tokens ?? defaults.existing_surface_tokens,
     rag_base_branch: input3.rag_base_branch ?? defaults.rag_base_branch,
     benchmark_gates: {
       ...DEFAULT_BENCHMARK_GATES,
@@ -421,7 +423,7 @@ function normalizeIntelligenceConfig(input3) {
   }
   return normalized;
 }
-var EMBEDDING_PROVIDERS, LOCAL_EMBEDDING_MODELS, DEFAULT_LOCAL_EMBEDDING_MODEL, DEFAULT_BENCHMARK_EVAL, DEFAULT_ADAPTIVE_RETRIEVAL, DEFAULT_RERANKING, DEFAULT_METADATA_FILTERS, DEFAULT_ACTION_ROUTING, DEFAULT_BENCHMARK_GATES;
+var EMBEDDING_PROVIDERS, LOCAL_EMBEDDING_MODELS, DEFAULT_LOCAL_EMBEDDING_MODEL, DEFAULT_BENCHMARK_EVAL, DEFAULT_ADAPTIVE_RETRIEVAL, DEFAULT_RERANKING, DEFAULT_METADATA_FILTERS, DEFAULT_ACTION_ROUTING, DEFAULT_EXISTING_SURFACE_TOKENS, DEFAULT_BENCHMARK_GATES;
 var init_project_intelligence = __esm({
   "src/core/project-intelligence.ts"() {
     "use strict";
@@ -461,6 +463,7 @@ var init_project_intelligence = __esm({
     DEFAULT_ACTION_ROUTING = {
       enabled: false
     };
+    DEFAULT_EXISTING_SURFACE_TOKENS = 1e3;
     DEFAULT_BENCHMARK_GATES = {
       hit_at_5_improvement_pct: 20,
       task_success_rate_improvement_pct: 10,
@@ -665,7 +668,8 @@ function resolveFrameworkConfigFromMap(raw) {
     rag_relief_floor: rn("rag_relief_floor"),
     rag_top_n: rn("rag_top_n"),
     rag_max_file_size: rn("rag_max_file_size"),
-    rag_base_branch: raw.get("rag_base_branch")?.trim() || void 0
+    rag_base_branch: raw.get("rag_base_branch")?.trim() || void 0,
+    existing_surface_tokens: rn("existing_surface_tokens")
   });
   return {
     paqad: { enabled: rb("paqad_enable") },
@@ -1029,6 +1033,11 @@ function frameworkOverridesToFlat(overrides) {
     put("rag_top_n", i.rag_top_n, d.intelligence.rag_top_n);
     put("rag_max_file_size", i.rag_max_file_size, d.intelligence.rag_max_file_size);
     put("rag_base_branch", i.rag_base_branch, d.intelligence.rag_base_branch);
+    put(
+      "existing_surface_tokens",
+      i.existing_surface_tokens,
+      d.intelligence.existing_surface_tokens
+    );
   }
   if (overrides.strictness) {
     const s = overrides.strictness;
@@ -1388,6 +1397,15 @@ var init_framework_config = __esm({
         section: "Intelligence / RAG",
         comment: "Base branch for branch-aware RAG. Unset auto-detects main->master."
       },
+      {
+        key: "existing_surface_tokens",
+        env: "PAQAD_EXISTING_SURFACE_TOKENS",
+        type: "number",
+        default: 1e3,
+        group: "rag",
+        section: "Intelligence / RAG",
+        comment: 'Token budget for the feature-development "Existing surface" planning digest (existing symbols the model should reuse). Cards drop by rank past this budget.'
+      },
       // ── models group ───────────────────────────────────────────────────────
       {
         key: "research_depth",
@@ -1640,7 +1658,8 @@ var init_framework_config = __esm({
           "rag_relief_floor",
           "rag_top_n",
           "rag_max_file_size",
-          "rag_base_branch"
+          "rag_base_branch",
+          "existing_surface_tokens"
         ]
       },
       {
@@ -3638,6 +3657,7 @@ var init_project_profile_schema = __esm({
             rag_top_n: { type: "integer", minimum: 1 },
             rag_max_file_size: { type: "integer", minimum: 1 },
             rag_base_branch: { type: "string" },
+            existing_surface_tokens: { type: "integer", minimum: 1 },
             benchmark_gates: {
               type: "object",
               additionalProperties: false,
@@ -25067,10 +25087,12 @@ ${blocks}
 async function writeRuleContext(projectRoot, options = {}) {
   const loadRules = options.loadRules ?? true;
   const store = loadRules ? await readCompiledRules(projectRoot) : null;
+  const existingSurfaceSection = loadRules ? options.existingSurfaceSection?.trim() ?? "" : "";
   const memorySection = options.memorySection?.trim() ?? "";
   const retrievalSection = options.retrievalSection?.trim() ?? "";
   const driftSection = options.driftSection?.trim() ?? "";
-  if (!store && !memorySection && !retrievalSection && !driftSection) return null;
+  if (!store && !existingSurfaceSection && !memorySection && !retrievalSection && !driftSection)
+    return null;
   let markdown = "";
   if (store) {
     const changedPaths = (await loadChangeEvidence(projectRoot)).files;
@@ -25082,7 +25104,7 @@ ${DECISION_PAUSE_REMINDER}
 `;
     }
   }
-  for (const section of [memorySection, retrievalSection, driftSection]) {
+  for (const section of [existingSurfaceSection, memorySection, retrievalSection, driftSection]) {
     if (section) {
       markdown = markdown ? `${markdown}
 ${section}
@@ -30338,7 +30360,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.59.0";
+var VERSION = "1.60.0";
 
 // src/cli/commands/audit.ts
 init_esm_shims();
@@ -33251,7 +33273,8 @@ var FIELD_CHECKS = {
   rag_similarity_threshold: (value) => typeof value === "number" && value >= 0 && value <= 1 ? null : "Expected a number between 0 and 1.",
   rag_top_n: (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? null : "Expected a positive integer.",
   rag_max_file_size: (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? null : "Expected a positive integer.",
-  rag_base_branch: (value) => typeof value === "string" ? null : "Expected a string."
+  rag_base_branch: (value) => typeof value === "string" ? null : "Expected a string.",
+  existing_surface_tokens: (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? null : "Expected a positive integer."
 };
 function putRagConfig(projectRoot, candidate) {
   if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
@@ -42488,6 +42511,7 @@ var KNOB_CONSUMERS = {
   rag_top_n: "RAG retrieval depth",
   rag_max_file_size: "RAG index build",
   rag_base_branch: "branch-aware RAG index",
+  existing_surface_tokens: "existing-surface planning digest",
   research_depth: NOTHING,
   model_default: "model selection (skills/model-selector)",
   model_reasoning: "model routing (budget optimizer)",
@@ -42659,8 +42683,8 @@ function createDecisionCommand() {
 // src/cli/commands/rag.ts
 init_esm_shims();
 init_project_intelligence();
-import { readFileSync as readFileSync103 } from "fs";
-import { isAbsolute as isAbsolute11, join as join207 } from "path";
+import { readFileSync as readFileSync104 } from "fs";
+import { isAbsolute as isAbsolute11, join as join208 } from "path";
 import { confirm, input as input2, select as select3 } from "@inquirer/prompts";
 import { Command as Command28 } from "commander";
 
@@ -42996,6 +43020,293 @@ ${lines}
 `;
 }
 
+// src/context/existing-surface.ts
+init_esm_shims();
+import { readFileSync as readFileSync101 } from "fs";
+import { join as join204 } from "path";
+init_project_intelligence();
+
+// src/rag/repo-map.ts
+init_esm_shims();
+var PAGERANK_DAMPING = 0.85;
+function pageRank(seedNodes, edges, options = {}) {
+  const damping = options.damping ?? PAGERANK_DAMPING;
+  const iterations = options.iterations ?? 50;
+  const tolerance = options.tolerance ?? 1e-6;
+  const nodes = new Set(seedNodes);
+  for (const edge of edges) {
+    nodes.add(edge.from);
+    nodes.add(edge.to);
+  }
+  const nodeList = [...nodes];
+  const n = nodeList.length;
+  if (n === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const outLinks = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.from === edge.to) {
+      continue;
+    }
+    const list = outLinks.get(edge.from) ?? [];
+    list.push(edge.to);
+    outLinks.set(edge.from, list);
+  }
+  let rank = new Map(nodeList.map((node) => [node, 1 / n]));
+  const base = (1 - damping) / n;
+  for (let iteration = 0; iteration < iterations; iteration++) {
+    const next = new Map(nodeList.map((node) => [node, base]));
+    let danglingMass = 0;
+    for (const node of nodeList) {
+      const links = outLinks.get(node);
+      if (!links || links.length === 0) {
+        danglingMass += rank.get(node) ?? 0;
+      }
+    }
+    const danglingShare = damping * danglingMass / n;
+    for (const node of nodeList) {
+      if (danglingShare > 0) {
+        next.set(node, (next.get(node) ?? 0) + danglingShare);
+      }
+      const links = outLinks.get(node);
+      if (!links || links.length === 0) {
+        continue;
+      }
+      const contribution = damping * (rank.get(node) ?? 0) / links.length;
+      for (const target of links) {
+        next.set(target, (next.get(target) ?? 0) + contribution);
+      }
+    }
+    let delta = 0;
+    for (const node of nodeList) {
+      delta += Math.abs((next.get(node) ?? 0) - (rank.get(node) ?? 0));
+    }
+    rank = next;
+    if (delta < tolerance) {
+      break;
+    }
+  }
+  return rank;
+}
+var DEFAULT_REPO_MAP_TOKEN_BUDGET = 1500;
+var MAX_SYMBOLS_PER_FILE = 6;
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function formatEntryLine2(entry) {
+  const parts = [`- \`${entry.path}\``];
+  if (entry.module) {
+    parts.push(`\xB7 ${entry.module}`);
+  }
+  if (entry.symbols.length > 0) {
+    parts.push(`\xB7 ${entry.symbols.slice(0, MAX_SYMBOLS_PER_FILE).join(", ")}`);
+  }
+  return parts.join(" ");
+}
+function buildRepoMap(files, edges, options = {}) {
+  const tokenBudget = options.tokenBudget ?? DEFAULT_REPO_MAP_TOKEN_BUDGET;
+  const ranks = pageRank(
+    files.map((file) => file.path),
+    edges
+  );
+  const entries = files.map((file) => ({
+    path: file.path,
+    module: file.module,
+    symbols: file.symbols ?? [],
+    rank: ranks.get(file.path) ?? 0
+  })).sort((left, right) => {
+    if (right.rank !== left.rank) {
+      return right.rank - left.rank;
+    }
+    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+  });
+  if (entries.length === 0) {
+    return { entries, skeleton: "", truncated: false };
+  }
+  const header = `## Repo map \u2014 ${entries.length} files ranked by structural importance
+> Embedding-free orientation. Use it to decide where to read or grep; verify against the live files.
+`;
+  let tokens = estimateTokens(header);
+  const lines = [];
+  let truncated = false;
+  for (const entry of entries) {
+    const line = formatEntryLine2(entry);
+    const lineTokens = estimateTokens(line) + 1;
+    if (lines.length > 0 && tokens + lineTokens > tokenBudget) {
+      truncated = true;
+      break;
+    }
+    lines.push(line);
+    tokens += lineTokens;
+  }
+  const body = truncated ? `${lines.join("\n")}
+\u2026[repo map truncated to fit the token budget]` : lines.join("\n");
+  return { entries, skeleton: `${header}
+${body}
+`, truncated };
+}
+async function buildProjectRepoMap(projectRoot, options) {
+  const edges = await scanImports({
+    projectRoot,
+    files: options.files,
+    aliases: options.aliases ?? { "@/": "src/" }
+  });
+  const files = options.files.map((path11) => ({
+    path: path11,
+    module: options.moduleOf?.(path11),
+    symbols: options.symbolsOf?.(path11)
+  }));
+  return buildRepoMap(files, edges, { tokenBudget: options.tokenBudget });
+}
+
+// src/context/existing-surface.ts
+init_contextual_blurb();
+var EXISTING_SURFACE_HEADING = "## Existing surface";
+var EXISTING_SURFACE_FRAMING = "> Before writing new helpers, check this surface \u2014 these already exist in this project.";
+function estimateTokens2(text) {
+  return Math.ceil(text.length / 4);
+}
+function formatCardLine(card) {
+  const head = card.signature?.trim() ? card.signature.trim() : card.name;
+  const location = card.line ? `${card.file}:${card.line}` : card.file;
+  const parts = [`- \`${head}\` \u2014 ${location}`];
+  if (typeof card.callerCount === "number") {
+    parts.push(`\xB7 called from ${card.callerCount} ${card.callerCount === 1 ? "place" : "places"}`);
+  }
+  if (card.module) {
+    parts.push(`\xB7 ${card.module}`);
+  }
+  return parts.join(" ");
+}
+function headerFor(shown) {
+  return `${EXISTING_SURFACE_HEADING} \u2014 ${shown} existing symbol${shown === 1 ? "" : "s"} for the files in play`;
+}
+function composeExistingSurfaceSection(cards, options = {}) {
+  if (cards.length === 0) {
+    return "";
+  }
+  const tokenBudget = options.tokenBudget ?? DEFAULT_EXISTING_SURFACE_TOKENS;
+  let tokens = estimateTokens2(EXISTING_SURFACE_FRAMING) + estimateTokens2(headerFor(cards.length));
+  const lines = [];
+  let truncated = false;
+  for (const card of cards) {
+    const line = formatCardLine(card);
+    const lineTokens = estimateTokens2(line) + 1;
+    if (lines.length > 0 && tokens + lineTokens > tokenBudget) {
+      truncated = true;
+      break;
+    }
+    lines.push(line);
+    tokens += lineTokens;
+  }
+  const remaining = cards.length - lines.length;
+  const trailer = truncated && remaining > 0 ? `
+\u2026and ${remaining} more exported symbol${remaining === 1 ? "" : "s"} \u2014 run \`paqad-ai index query <name>\` to look one up.` : "";
+  return `${headerFor(lines.length)}
+${EXISTING_SURFACE_FRAMING}
+
+${lines.join("\n")}${trailer}
+`;
+}
+var SOURCE_EXT_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|php|dart)$/;
+function toPosix(path11) {
+  return path11.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function modulePrefix(path11) {
+  return path11.split("/").slice(0, 2).join("/");
+}
+function basenameNoExt(path11) {
+  const base = path11.slice(path11.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot <= 0 ? base : base.slice(0, dot);
+}
+function selectCandidateFiles(allFiles, workingSet, query, index) {
+  const working = new Set(workingSet);
+  const workingModules = new Set([...working].map(modulePrefix));
+  if (working.size === 0 && query.trim().length === 0) {
+    return [];
+  }
+  const queryLower = query.toLowerCase();
+  const wanted = /* @__PURE__ */ new Set();
+  for (const file of allFiles) {
+    if (working.has(file) || workingModules.size > 0 && workingModules.has(modulePrefix(file))) {
+      wanted.add(file);
+      continue;
+    }
+    const base = basenameNoExt(file).toLowerCase();
+    if (base.length >= 4 && queryLower.includes(base)) {
+      wanted.add(file);
+    }
+  }
+  if (index && queryLower.length > 0) {
+    for (const symbol of index.symbols) {
+      if (symbol.name.length >= 5 && queryLower.includes(symbol.name.toLowerCase())) {
+        wanted.add(symbol.file);
+      }
+    }
+  }
+  const universe = new Set(allFiles);
+  return [...wanted].filter((file) => universe.has(file));
+}
+async function gatherExistingSurface(projectRoot, options = {}) {
+  try {
+    const tokenBudget = options.tokenBudget ?? DEFAULT_EXISTING_SURFACE_TOKENS;
+    const query = options.query ?? "";
+    const index = readCodeKnowledgeIndex(projectRoot);
+    const workingSet = (options.changedPaths ?? []).map(toPosix).filter((path11) => SOURCE_EXT_RE.test(path11));
+    const allFiles = index ? index.files.map((file) => file.path) : scanWorkingTree(projectRoot, SOURCE_GLOBS).map(toPosix);
+    const candidates = selectCandidateFiles(allFiles, workingSet, query, index);
+    if (candidates.length === 0) {
+      return "";
+    }
+    const symbolsByFile = /* @__PURE__ */ new Map();
+    if (index) {
+      for (const symbol of index.symbols) {
+        const list = symbolsByFile.get(symbol.file) ?? [];
+        list.push(symbol);
+        symbolsByFile.set(symbol.file, list);
+      }
+    }
+    const moduleResolver = buildModuleRoleResolver(projectRoot);
+    const repoMap = await buildProjectRepoMap(projectRoot, {
+      files: candidates,
+      moduleOf: (path11) => moduleResolver(path11),
+      symbolsOf: index ? (path11) => (symbolsByFile.get(path11) ?? []).map((symbol) => symbol.name) : (path11) => extractNames(projectRoot, path11)
+    });
+    const cards = [];
+    for (const entry of repoMap.entries) {
+      if (index) {
+        const symbols = (symbolsByFile.get(entry.path) ?? []).slice().sort((a, b) => b.caller_count - a.caller_count || a.name.localeCompare(b.name));
+        for (const symbol of symbols) {
+          cards.push({
+            name: symbol.name,
+            signature: symbol.signature,
+            file: symbol.file,
+            line: symbol.line,
+            callerCount: symbol.caller_count,
+            module: symbol.module_slug ?? entry.module ?? void 0
+          });
+        }
+      } else {
+        for (const name of entry.symbols) {
+          cards.push({ name, file: entry.path, module: entry.module });
+        }
+      }
+    }
+    return composeExistingSurfaceSection(cards, { tokenBudget });
+  } catch {
+    return "";
+  }
+}
+function extractNames(projectRoot, relPath) {
+  try {
+    const content = readFileSync101(join204(projectRoot, relPath), "utf8");
+    return extractSymbols(relPath, content).map((symbol) => symbol.name);
+  } catch {
+    return [];
+  }
+}
+
 // src/context/retrieval-context.ts
 init_esm_shims();
 init_project_intelligence();
@@ -43165,11 +43476,11 @@ async function gatherWorkingSetSlices(projectRoot, options = {}) {
 // src/pipeline/session-route.ts
 init_esm_shims();
 init_paths();
-import { mkdirSync as mkdirSync51, readFileSync as readFileSync101, writeFileSync as writeFileSync43 } from "fs";
-import { dirname as dirname86, join as join204 } from "path";
+import { mkdirSync as mkdirSync51, readFileSync as readFileSync102, writeFileSync as writeFileSync43 } from "fs";
+import { dirname as dirname86, join as join205 } from "path";
 var SESSION_ROUTE_FILE = ".session-route.json";
 function sessionRouteDir(projectRoot) {
-  return join204(projectRoot, dirname86(PATHS.CONTEXT_SESSION_ARTIFACT));
+  return join205(projectRoot, dirname86(PATHS.CONTEXT_SESSION_ARTIFACT));
 }
 var VALID_WORKFLOWS2 = new Set(ROUTED_WORKFLOWS);
 function compositionForRoute(route) {
@@ -43184,7 +43495,7 @@ function compositionForRoute(route) {
 function readSessionRoute(projectRoot) {
   try {
     const parsed = JSON.parse(
-      readFileSync101(join204(sessionRouteDir(projectRoot), SESSION_ROUTE_FILE), "utf8")
+      readFileSync102(join205(sessionRouteDir(projectRoot), SESSION_ROUTE_FILE), "utf8")
     );
     if (typeof parsed.workflow !== "string" || !VALID_WORKFLOWS2.has(parsed.workflow)) {
       return null;
@@ -43203,12 +43514,12 @@ init_recorder();
 
 // src/rag/background-sync.ts
 init_esm_shims();
-import { join as join205 } from "path";
+import { join as join206 } from "path";
 init_paths();
 init_service();
 var STALE_LOCK_MS2 = 10 * 60 * 1e3;
 async function backgroundIndexSync(projectRoot, providerFactory) {
-  const lockDir = join205(projectRoot, PATHS.LOCKS_DIR, "rag-sync.lock");
+  const lockDir = join206(projectRoot, PATHS.LOCKS_DIR, "rag-sync.lock");
   const lock = tryAcquireLock(lockDir, { staleLockMs: STALE_LOCK_MS2 });
   if (!lock.acquired) {
     return { synced: false, reason: "in-flight" };
@@ -43235,8 +43546,8 @@ async function backgroundIndexSync(projectRoot, providerFactory) {
 init_esm_shims();
 init_atomic_artifact();
 import { execFileSync as execFileSync10 } from "child_process";
-import { readFileSync as readFileSync102 } from "fs";
-import { join as join206 } from "path";
+import { readFileSync as readFileSync103 } from "fs";
+import { join as join207 } from "path";
 
 // src/background/debounce-marker.ts
 init_esm_shims();
@@ -43312,11 +43623,11 @@ function computeBaseDrift(projectRoot, options = {}) {
 async function refreshBaseDrift(projectRoot, options = {}) {
   const now = options.now ?? Date.now;
   const minIntervalMs = options.minIntervalMs ?? DEFAULT_BASE_DRIFT_INTERVAL_MS;
-  const markerPath = join206(projectRoot, PATHS.BASE_DRIFT_MARKER);
+  const markerPath = join207(projectRoot, PATHS.BASE_DRIFT_MARKER);
   if (shouldDebounce(markerPath, minIntervalMs, now)) {
     return { refreshed: false, reason: "debounced" };
   }
-  const lockDir = join206(projectRoot, PATHS.BASE_DRIFT_LOCK);
+  const lockDir = join207(projectRoot, PATHS.BASE_DRIFT_LOCK);
   const lock = tryAcquireLock(lockDir, { staleLockMs: STALE_LOCK_MS3 });
   if (!lock.acquired) {
     return { refreshed: false, reason: "in-flight" };
@@ -43340,7 +43651,7 @@ async function refreshBaseDrift(projectRoot, options = {}) {
     const snapshot = computeBaseDrift(projectRoot, options);
     if (snapshot) {
       await atomicWriteFile(
-        join206(projectRoot, PATHS.BASE_DRIFT_STATE),
+        join207(projectRoot, PATHS.BASE_DRIFT_STATE),
         `${JSON.stringify(snapshot, null, 2)}
 `
       );
@@ -43355,7 +43666,7 @@ async function refreshBaseDrift(projectRoot, options = {}) {
 function loadBaseDrift(projectRoot) {
   try {
     const parsed = JSON.parse(
-      readFileSync102(join206(projectRoot, PATHS.BASE_DRIFT_STATE), "utf8")
+      readFileSync103(join207(projectRoot, PATHS.BASE_DRIFT_STATE), "utf8")
     );
     if (typeof parsed === "object" && parsed !== null && typeof parsed.base_branch === "string" && typeof parsed.ahead === "number") {
       return parsed;
@@ -43853,9 +44164,18 @@ function createRagCommand() {
     }
     const route = readSessionRoute(options.projectRoot);
     const { loadRules, retrieves } = compositionForRoute(route);
-    const ragEnabled = resolveFrameworkConfig(options.projectRoot).intelligence.rag_enabled;
+    const intelligence = resolveFrameworkConfig(options.projectRoot).intelligence;
+    const existingSurfaceSection = loadRules ? await gatherExistingSurface(options.projectRoot, {
+      changedPaths: (await loadChangeEvidence(options.projectRoot)).files,
+      query: route?.query,
+      tokenBudget: intelligence.existing_surface_tokens
+    }) : "";
+    const ragEnabled = intelligence.rag_enabled;
     if (!ragEnabled) {
-      const target2 = await refreshRuleContext(options.projectRoot, { loadRules });
+      const target2 = await refreshRuleContext(options.projectRoot, {
+        existingSurfaceSection,
+        loadRules
+      });
       if (!options.quiet) {
         process.stdout.write(
           `${target2 ? `wrote ${target2}` : "nothing to compose"}; rule-only (rag off)
@@ -43873,8 +44193,8 @@ function createRagCommand() {
     const packEntries = usesContextPack ? distillSlices(slices, {
       readFile: (path11) => {
         try {
-          return readFileSync103(
-            isAbsolute11(path11) ? path11 : join207(options.projectRoot, path11),
+          return readFileSync104(
+            isAbsolute11(path11) ? path11 : join208(options.projectRoot, path11),
             "utf8"
           );
         } catch {
@@ -43890,6 +44210,7 @@ function createRagCommand() {
       driftSection = composeBaseDriftSection(loadBaseDrift(options.projectRoot));
     }
     const target = await refreshRuleContext(options.projectRoot, {
+      existingSurfaceSection,
       memorySection,
       retrievalSection,
       driftSection,
@@ -43995,7 +44316,7 @@ function createRagCommand() {
       }
       if (options.baseline) {
         const baselineSnapshot = JSON.parse(
-          readFileSync103(options.baseline, "utf8")
+          readFileSync104(options.baseline, "utf8")
         );
         comparison = compareConfigurations(baselineSnapshot, candidateSnapshot, mode);
       }
@@ -44177,8 +44498,8 @@ function createRagEvidenceCommand() {
 // src/cli/commands/refresh.ts
 init_esm_shims();
 import { Command as Command30 } from "commander";
-import { existsSync as existsSync108, readFileSync as readFileSync104, writeFileSync as writeFileSync45 } from "fs";
-import { join as join208 } from "path";
+import { existsSync as existsSync108, readFileSync as readFileSync105, writeFileSync as writeFileSync45 } from "fs";
+import { join as join209 } from "path";
 init_paths();
 init_project_profile2();
 init_service();
@@ -44308,7 +44629,7 @@ async function refreshProviderEntries(projectRoot) {
   removeObsoleteContractDocs(projectRoot);
   for (const type of ADAPTER_TYPES) {
     const adapter = AdapterFactory.create(type);
-    const configPath = join208(projectRoot, adapter.getConfigPath());
+    const configPath = join209(projectRoot, adapter.getConfigPath());
     if (!existsSync108(configPath)) {
       continue;
     }
@@ -44321,14 +44642,14 @@ async function refreshProviderEntries(projectRoot) {
   }
 }
 function writeRefreshDrift(projectRoot, refreshDrift) {
-  const path11 = join208(projectRoot, PATHS.STACK_DRIFT);
+  const path11 = join209(projectRoot, PATHS.STACK_DRIFT);
   const current = readExistingJson(path11);
   writeFileSync45(path11, `${JSON.stringify({ ...current ?? {}, ...refreshDrift }, null, 2)}
 `);
 }
 function readExistingJson(path11) {
   try {
-    return JSON.parse(readFileSync104(path11, "utf8"));
+    return JSON.parse(readFileSync105(path11, "utf8"));
   } catch {
     return null;
   }
@@ -44337,12 +44658,12 @@ function resolveChangedFiles(projectRoot, contextChangedFiles) {
   if (contextChangedFiles.length > 0) {
     return [...new Set(contextChangedFiles)].sort();
   }
-  const trackedPath = join208(projectRoot, PATHS.CHANGED_FILES);
+  const trackedPath = join209(projectRoot, PATHS.CHANGED_FILES);
   if (!existsSync108(trackedPath)) {
     return [];
   }
   try {
-    const parsed = JSON.parse(readFileSync104(trackedPath, "utf8"));
+    const parsed = JSON.parse(readFileSync105(trackedPath, "utf8"));
     if (!Array.isArray(parsed)) {
       return [];
     }
@@ -44410,7 +44731,7 @@ function createRulesCommand() {
 
 // src/cli/commands/spec.ts
 init_esm_shims();
-import { readFileSync as readFileSync105 } from "fs";
+import { readFileSync as readFileSync106 } from "fs";
 import { basename as basename16 } from "path";
 import { Command as Command33 } from "commander";
 
@@ -44555,7 +44876,7 @@ function createSpecCommand() {
     (specFile, options) => {
       let markdown;
       try {
-        markdown = readFileSync105(specFile, "utf8");
+        markdown = readFileSync106(specFile, "utf8");
       } catch {
         console.error(`could not read spec file "${specFile}"`);
         process.exitCode = 1;