opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/lib/code-intelligence/lsp-provider.mjs

@@ -0,0 +1,189 @@
+import { spawn, spawnSync } from "node:child_process"
+import { lstat, readFile, realpath } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+const PROVIDERS = [
+  { id: "typescript-language-server", extensions: new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]), commands: [["typescript-language-server", ["--stdio"]]], languageId: (ext) => [".ts", ".tsx"].includes(ext) ? "typescript" : "javascript" },
+  { id: "pyright-langserver", extensions: new Set([".py"]), commands: [["pyright-langserver", ["--stdio"]], ["pylsp", []]], languageId: () => "python" },
+  { id: "gopls", extensions: new Set([".go"]), commands: [["gopls", []]], languageId: () => "go" },
+  { id: "rust-analyzer", extensions: new Set([".rs"]), commands: [["rust-analyzer", []]], languageId: () => "rust" },
+  { id: "clangd", extensions: new Set([".c", ".cc", ".cpp", ".cxx", ".h", ".hpp"]), commands: [["clangd", []]], languageId: (ext) => [".c", ".h"].includes(ext) ? "c" : "cpp" },
+]
+
+const commandCache = new Map()
+const COMMAND_TTL_MS = 60_000
+
+function commandExists(command) {
+  const now = Date.now()
+  const cached = commandCache.get(command)
+  if (cached && now - cached.at < COMMAND_TTL_MS) return cached.available
+  const finder = process.platform === "win32" ? "where" : "which"
+  const available = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true }).status === 0
+  commandCache.set(command, { available, at: now })
+  return available
+}
+
+function inside(root, target) {
+  return target === root || target.startsWith(root + path.sep)
+}
+
+async function safeFile(root, relative) {
+  const base = await realpath(path.resolve(root)).catch(() => path.resolve(root))
+  const requested = path.resolve(base, String(relative || ""))
+  if (!inside(base, requested)) throw new Error("diagnostic path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("diagnostic path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("diagnostic symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+function providerFor(file) {
+  const ext = path.extname(file).toLowerCase()
+  for (const provider of PROVIDERS) {
+    if (!provider.extensions.has(ext)) continue
+    for (const [command, args] of provider.commands) {
+      if (commandExists(command)) return { ...provider, command, args, languageId: provider.languageId(ext) }
+    }
+    return { ...provider, command: null, args: [], languageId: provider.languageId(ext) }
+  }
+  return null
+}
+
+export function lspProviderStatus(file = "") {
+  const ext = path.extname(String(file || "")).toLowerCase()
+  const providers = PROVIDERS
+    .filter((provider) => !ext || provider.extensions.has(ext))
+    .map((provider) => {
+      const selected = provider.commands.find(([command]) => commandExists(command)) || null
+      return { id: provider.id, available: Boolean(selected), command: selected?.[0] || null, extensions: [...provider.extensions] }
+    })
+  return { schemaVersion: 1, extension: ext, available: providers.some((row) => row.available), providers }
+}
+
+function encodeMessage(payload) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8")
+  return Buffer.concat([Buffer.from("Content-Length: " + body.length + "\r\n\r\n", "ascii"), body])
+}
+
+function sanitizeDiagnostic(value = {}) {
+  return {
+    range: value.range || null,
+    severity: Number.isFinite(Number(value.severity)) ? Number(value.severity) : null,
+    code: value.code == null ? null : String(value.code),
+    source: value.source == null ? null : String(value.source),
+    message: String(value.message || "").slice(0, 4000),
+  }
+}
+
+export async function diagnoseCode(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const provider = providerFor(target.file)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (!provider?.command) {
+    return { schemaVersion: 1, file: relativeFile, available: false, provider: provider?.id || null, diagnostics: [], reason: provider ? "lsp-command-unavailable" : "unsupported-extension" }
+  }
+
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 1024 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("diagnostic file exceeds limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  const uri = pathToFileURL(target.file).href
+  const rootUri = pathToFileURL(target.base + path.sep).href
+  const timeoutMs = Math.max(500, Math.min(10_000, Number(options.timeoutMs || 3000)))
+  const maxDiagnostics = Math.max(1, Math.min(500, Number(options.maxDiagnostics || 100)))
+
+  return await new Promise((resolve) => {
+    const child = spawn(provider.command, provider.args, { cwd: target.base, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, shell: false })
+    let buffer = Buffer.alloc(0)
+    let stderr = ""
+    let settled = false
+    let initialized = false
+    let diagnostics = []
+    let timer = null
+
+    const finish = (reason, error = null) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      try {
+        if (initialized && child.stdin.writable) {
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", id: 2, method: "shutdown", params: null }))
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "exit", params: null }))
+        }
+      } catch {}
+      setTimeout(() => { try { child.kill() } catch {} }, 50).unref?.()
+      resolve({
+        schemaVersion: 1,
+        file: relativeFile,
+        available: true,
+        provider: provider.id,
+        command: provider.command,
+        diagnostics: diagnostics.slice(0, maxDiagnostics),
+        reason,
+        stderr: stderr.trim().slice(0, 2000) || null,
+        error: error ? String(error instanceof Error ? error.message : error).slice(0, 1000) : null,
+      })
+    }
+
+    const handle = (message) => {
+      if (message?.id === 1 && message?.result) {
+        initialized = true
+        try {
+          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "initialized", params: {} }))
+          child.stdin.write(encodeMessage({
+            jsonrpc: "2.0",
+            method: "textDocument/didOpen",
+            params: { textDocument: { uri, languageId: provider.languageId, version: 1, text: source } },
+          }))
+        } catch (error) {
+          finish("write-failed", error)
+        }
+        return
+      }
+      if (message?.method === "textDocument/publishDiagnostics" && message?.params?.uri === uri) {
+        diagnostics = Array.isArray(message.params.diagnostics) ? message.params.diagnostics.map(sanitizeDiagnostic).slice(0, maxDiagnostics) : []
+        finish("publishDiagnostics")
+      }
+    }
+
+    const parse = () => {
+      while (!settled) {
+        const headerEnd = buffer.indexOf("\r\n\r\n")
+        if (headerEnd < 0) return
+        const header = buffer.subarray(0, headerEnd).toString("ascii")
+        const match = header.match(/Content-Length:\s*(\d+)/i)
+        if (!match) { buffer = buffer.subarray(headerEnd + 4); continue }
+        const length = Number(match[1])
+        const bodyStart = headerEnd + 4
+        if (buffer.length < bodyStart + length) return
+        const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf8")
+        buffer = buffer.subarray(bodyStart + length)
+        try { handle(JSON.parse(body)) } catch {}
+      }
+    }
+
+    child.stdout.on("data", (chunk) => { buffer = Buffer.concat([buffer, Buffer.from(chunk)]); parse() })
+    child.stderr.on("data", (chunk) => { if (stderr.length < 64 * 1024) stderr += chunk.toString() })
+    child.on("error", (error) => finish("spawn-error", error))
+    child.on("close", (code) => { if (!settled) finish("server-exit:" + (code ?? "unknown")) })
+
+    try {
+      child.stdin.write(encodeMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          processId: process.pid,
+          rootUri,
+          capabilities: { textDocument: { publishDiagnostics: { relatedInformation: true } } },
+          workspaceFolders: [{ uri: rootUri, name: path.basename(target.base) || "workspace" }],
+        },
+      }))
+    } catch (error) {
+      finish("initialize-write-failed", error)
+    }
+    timer = setTimeout(() => finish("timeout"), timeoutMs)
+    timer.unref?.()
+  })
+}

package/lib/completion-auditor.mjs

@@ -0,0 +1,82 @@
+function text(value) {
+  return String(value ?? "").trim()
+}
+
+function reportSections(run) {
+  const sections = run?.report?.sections
+  return sections && typeof sections === "object" ? sections : {}
+}
+
+function passRun(run) {
+  return Boolean(run && Number(run.exitCode) === 0 && run.verdict === "PASS")
+}
+
+function benignEmptySection(value) {
+  const normalized = text(value)
+    .toLowerCase()
+    .replace(/[`*_#]/g, "")
+    .replace(/[.!:;]+$/g, "")
+    .trim()
+  return !normalized || /^(?:none(?: observed| found| remaining)?|n\/a|na|nil|0|no failures?(?: observed| found| remaining)?|no unresolved gaps?(?: observed| found| remaining)?|no gaps?(?: observed| found| remaining)?|not applicable)$/.test(normalized)
+}
+
+function receiptPassed(row = {}) {
+  const receipt = row?.receipt || row
+  return Boolean(receipt?.passed === true && Number(receipt?.exitCode) === 0)
+}
+
+export function auditCompletion(input = {}) {
+  const failures = []
+  const warnings = []
+  const verification = input.verification || null
+  const integration = input.integration || null
+  const visual = input.visual || null
+  const requireIntegration = input.requireIntegration === true
+  const requireVisual = input.requireVisual === true
+  const receipts = Array.isArray(input.behavioralReceipts) ? input.behavioralReceipts : []
+
+  if (!passRun(verification)) failures.push("primary-verification-not-pass")
+  if (requireIntegration && !passRun(integration)) failures.push("integration-verification-not-pass")
+  if (requireVisual && !passRun(visual)) failures.push("visual-verification-not-pass")
+
+  const sections = reportSections(verification)
+  for (const key of ["checks-run", "acceptance-criteria-proven", "completion-evidence"]) {
+    if (!text(sections[key])) failures.push(`missing-report-section:${key}`)
+  }
+  if (Object.hasOwn(sections, "failures") && !benignEmptySection(sections.failures)) failures.push("verification-reports-failures")
+  if (Object.hasOwn(sections, "unresolved-gaps") && !benignEmptySection(sections["unresolved-gaps"])) failures.push("verification-reports-unresolved-gaps")
+  if (Object.hasOwn(sections, "checks-not-run") && !benignEmptySection(sections["checks-not-run"])) warnings.push("verification-reports-checks-not-run")
+
+  const snapshot = input.workspaceSnapshot || null
+  if (snapshot) {
+    if (snapshot.cacheable === true && !text(snapshot.fingerprint)) failures.push("workspace-fingerprint-missing")
+    if (Array.isArray(snapshot.changedFiles) && snapshot.changedFiles.length === 0) warnings.push("workspace-has-no-detected-changes")
+  } else {
+    warnings.push("workspace-snapshot-unavailable")
+  }
+
+  const passingReceipts = receipts.filter(receiptPassed)
+  if (input.requireBehavioralReceipt === true && passingReceipts.length === 0) failures.push("fresh-behavioral-receipt-missing")
+  else if (passingReceipts.length === 0) warnings.push("no-fresh-behavioral-receipt-attached")
+
+  const verifierOutput = text(verification?.output)
+  if (verification?.report?.valid === false) failures.push("verification-report-invalid")
+  if (verification?.report?.verdict && verification.report.verdict !== "PASS") failures.push("verification-report-verdict-mismatch")
+  if (/UES_VERDICT:\s*FAIL/i.test(verifierOutput)) failures.push("verifier-output-contains-fail-verdict")
+
+  return {
+    schemaVersion: 1,
+    passed: failures.length === 0,
+    failures: [...new Set(failures)],
+    warnings: [...new Set(warnings)],
+    evidence: {
+      primary: passRun(verification),
+      integration: requireIntegration ? passRun(integration) : null,
+      visual: requireVisual ? passRun(visual) : null,
+      reportSections: Object.keys(sections).sort(),
+      passingReceiptCount: passingReceipts.length,
+      workspaceFingerprint: snapshot?.fingerprint || null,
+      changedFiles: Array.isArray(snapshot?.changedFiles) ? snapshot.changedFiles.slice(0, 200) : [],
+    },
+  }
+}

package/lib/context-engine-v11.mjs

@@ -4,6 +4,8 @@ import { putEvidence } from "./evidence-store.mjs"
 import { inferTaskCapabilities } from "./capability-registry.mjs"
 import { buildPromptEnvelope, comparePromptEnvelopes } from "./prompt-cache.mjs"
 import { measureContextQuality } from "./context-quality.mjs"
+import { retrieveMemories } from "./memory-engine.mjs"
+import { capabilityFabricStatus } from "./capability-fabric.mjs"
 
 function taskText(task = {}) {
   return [
@@ -14,6 +16,20 @@ function taskText(task = {}) {
   ].filter(Boolean).join(" ")
 }
 
+function taskFilesForMemory(task = {}) {
+  const files = task.files
+  const values = []
+  if (Array.isArray(files)) values.push(...files)
+  else if (files && typeof files === "object") {
+    for (const value of Object.values(files)) {
+      if (Array.isArray(value)) values.push(...value)
+      else if (typeof value === "string") values.push(value)
+    }
+  }
+  if (Array.isArray(task.requiredFiles)) values.push(...task.requiredFiles)
+  return [...new Set(values.filter(Boolean))]
+}
+
 function rankExcerpt(item = {}, task = {}) {
   const text = taskText(task).toLowerCase()
   const pathValue = String(item.path || "").toLowerCase()
@@ -91,6 +107,8 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     strategy: options.strategy || policy?.profile?.contextStrategy || "incremental-semantic+git",
     semanticMaxFiles: options.semanticMaxFiles,
     maxFiles: options.maxFiles,
+    changedFiles: options.changedFiles,
+    workspaceFingerprint: options.workspaceFingerprint,
   })
 
   const externalized = await externalizeContextExcerpts(root, manifest, {
@@ -99,6 +117,24 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     inlineChars: options.inlineChars,
   })
 
+  const memoryRetrieval = await retrieveMemories(root, taskText(task), {
+    files: taskFilesForMemory(task),
+    limit: options.memoryLimit ?? 6,
+    taskClass: options.taskClass || task.type || policy.executionProfile || policy.profile?.name || null,
+    touch: options.touchMemories !== false,
+  }).catch(() => ({ schemaVersion: 1, query: taskText(task), eligible: 0, results: [] }))
+  const memories = memoryRetrieval.results || []
+  const fabric = await capabilityFabricStatus(root).catch(() => null)
+  const providerHints = (fabric?.rows || [])
+    .filter((row) => row.selected)
+    .slice(0, 12)
+    .map((row) => ({
+      capability: row.capability,
+      selected: row.selected,
+      status: row.status,
+      fallbacks: (row.fallbacks || []).slice(0, 3),
+    }))
+
   const promptEnvelope = buildPromptEnvelope({
     invariants: options.invariants || "evidence-first; scoped edits; fresh verification; no unsupported completion claims",
     role: options.role || "executor",
@@ -114,6 +150,23 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
       ...(externalized.manifest?.rankedReferences || []).slice(0, 12).map((item) => item.path),
       ...(options.evidence || []),
     ],
+    memories: memories.map((item) => ({
+      id: item.id,
+      type: item.type,
+      scope: item.scope,
+      content: item.content,
+      confidence: item.confidence,
+      files: item.files,
+      retrieval: item.retrieval,
+    })),
+    contextHints: {
+      hierarchy: (externalized.manifest?.hierarchy?.scopes || []).slice(0, 6).map((item) => ({
+        path: item.path,
+        score: item.score,
+        l0: item.l0,
+      })),
+      providers: providerHints,
+    },
     recentFailure: options.recentFailure || null,
     nextAction: options.nextAction || null,
     recentMessages: options.recentMessages || [],
@@ -132,6 +185,17 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
     evidenceBudget,
     contextManifest: externalized.manifest,
     contextQuality,
+    memories,
+    memoryRetrieval: {
+      schemaVersion: memoryRetrieval.schemaVersion || 1,
+      eligible: memoryRetrieval.eligible || 0,
+      returned: memories.length,
+    },
+    capabilityFabric: {
+      healthyCapabilities: fabric?.healthyCapabilities || 0,
+      totalCapabilities: fabric?.totalCapabilities || 0,
+      providers: providerHints,
+    },
     evidenceStore: {
       refs: externalized.externalized.length,
       externalizedBytes: externalized.externalizedBytes,
@@ -147,4 +211,4 @@ export async function buildAdaptiveTaskContext(root, task, options = {}) {
       ...(cache || {}),
     },
   }
-}
+}

package/lib/context-graph-rank.mjs

@@ -0,0 +1,118 @@
+function normalizePath(value) {
+  return String(value || "").replaceAll("\\", "/")
+}
+
+function normalizeSeeds(nodes, semanticResults = [], declared = [], changed = []) {
+  const raw = new Map(nodes.map((node) => [node, 0]))
+  const semanticMax = Math.max(1, ...semanticResults.map((item) => Number(item.score || 0)))
+  for (const item of semanticResults) {
+    const file = normalizePath(item.path)
+    if (!raw.has(file)) continue
+    raw.set(file, raw.get(file) + Number(item.score || 0) / semanticMax)
+  }
+  for (const file of declared.map(normalizePath)) {
+    if (raw.has(file)) raw.set(file, raw.get(file) + 1.25)
+  }
+  for (const file of changed.map(normalizePath)) {
+    if (raw.has(file)) raw.set(file, raw.get(file) + 0.75)
+  }
+
+  let total = [...raw.values()].reduce((sum, value) => sum + value, 0)
+  if (total <= 0) {
+    const uniform = nodes.length ? 1 / nodes.length : 0
+    return new Map(nodes.map((node) => [node, uniform]))
+  }
+  return new Map([...raw.entries()].map(([key, value]) => [key, value / total]))
+}
+
+export function rankContextGraph(graph = {}, options = {}) {
+  const nodes = [...new Set((graph.nodes || []).map((node) => normalizePath(node.path)).filter(Boolean))]
+  if (!nodes.length) return []
+
+  const nodeSet = new Set(nodes)
+  const neighbors = new Map(nodes.map((node) => [node, new Map()]))
+  const addEdge = (from, to, weight) => {
+    if (!nodeSet.has(from) || !nodeSet.has(to) || from === to) return
+    const row = neighbors.get(from)
+    row.set(to, Number(row.get(to) || 0) + weight)
+  }
+
+  for (const edge of graph.edges || []) {
+    const from = normalizePath(edge.from)
+    const to = normalizePath(edge.to)
+    // Imports carry relevance in both directions: the dependency is relevant to
+    // its caller, while callers are useful when a dependency itself is seeded.
+    addEdge(from, to, 1)
+    addEdge(to, from, 0.55)
+  }
+
+  const seeds = normalizeSeeds(
+    nodes,
+    options.semanticResults || [],
+    options.declared || [],
+    options.changed || [],
+  )
+  const damping = Math.max(0.5, Math.min(0.95, Number(options.damping || 0.85)))
+  const iterations = Math.max(4, Math.min(40, Number(options.iterations || 14)))
+  let scores = new Map(seeds)
+
+  for (let iteration = 0; iteration < iterations; iteration += 1) {
+    const next = new Map(nodes.map((node) => [node, (1 - damping) * Number(seeds.get(node) || 0)]))
+    let dangling = 0
+
+    for (const node of nodes) {
+      const score = Number(scores.get(node) || 0)
+      const row = neighbors.get(node)
+      const totalWeight = [...row.values()].reduce((sum, weight) => sum + weight, 0)
+      if (totalWeight <= 0) {
+        dangling += score
+        continue
+      }
+      for (const [target, weight] of row) {
+        next.set(target, Number(next.get(target) || 0) + damping * score * (weight / totalWeight))
+      }
+    }
+
+    if (dangling > 0) {
+      for (const node of nodes) {
+        next.set(
+          node,
+          Number(next.get(node) || 0) + damping * dangling * Number(seeds.get(node) || 0),
+        )
+      }
+    }
+    scores = next
+  }
+
+  const semantic = new Map(
+    (options.semanticResults || []).map((item) => [normalizePath(item.path), Number(item.score || 0)]),
+  )
+  const maxRank = Math.max(1e-12, ...scores.values())
+  const maxSemantic = Math.max(1, ...semantic.values())
+
+  return nodes
+    .map((file) => {
+      const pageRank = Number(scores.get(file) || 0)
+      const seed = Number(seeds.get(file) || 0)
+      const semanticScore = Number(semantic.get(file) || 0)
+      const normalizedRank = pageRank / maxRank
+      const normalizedSemantic = semanticScore / maxSemantic
+      const score = normalizedRank * 60 + normalizedSemantic * 40
+      return {
+        path: file,
+        score: Number(score.toFixed(6)),
+        pageRank: Number(pageRank.toFixed(10)),
+        personalization: Number(seed.toFixed(10)),
+        semanticScore,
+        reasons: [
+          semanticScore > 0 ? "semantic-seed" : null,
+          (options.declared || []).map(normalizePath).includes(file) ? "declared" : null,
+          (options.changed || []).map(normalizePath).includes(file) ? "changed" : null,
+          Number(neighbors.get(file)?.size || 0) > 0 ? "dependency-graph" : null,
+        ].filter(Boolean),
+      }
+    })
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+    .slice(0, Math.max(1, Math.min(100, Number(options.limit || 32))))
+}

package/lib/context-manifest.mjs

@@ -2,9 +2,11 @@ import { existsSync } from "node:fs"
 import { readFile, stat } from "node:fs/promises"
 import { spawnSync } from "node:child_process"
 import path from "node:path"
-import { buildRepoGraph } from "./repo-graph.mjs"
+import { buildRepoGraphCached } from "./repo-graph.mjs"
 import { taskFiles } from "./task-graph.mjs"
-import { querySemanticIndex } from "./semantic-index.mjs"
+import { buildSemanticIndexCached, querySemanticIndex } from "./semantic-index.mjs"
+import { queryContextHierarchy } from "./hierarchical-context.mjs"
+import { rankContextGraph } from "./context-graph-rank.mjs"
 
 const ROOT_INSTRUCTIONS = [
   "AGENTS.md",
@@ -247,7 +249,9 @@ export async function buildContextManifest(root, task, options = {}) {
   const evidenceBudget = options.evidenceBudget || null
   const declared = taskFiles(task)
   const terms = taskTerms(task)
-  const changed = gitChangedFiles(root)
+  const changed = Array.isArray(options.changedFiles)
+    ? options.changedFiles.map((file) => String(file || "").replaceAll("\\", "/")).filter(Boolean)
+    : gitChangedFiles(root)
   const strategy = String(options.strategy || "semantic+graph+git")
   const queryText = [
     task?.title,
@@ -256,15 +260,45 @@ export async function buildContextManifest(root, task, options = {}) {
     ...(task?.verification || []),
   ].filter(Boolean).join(" ")
 
+  const semanticSnapshot = await buildSemanticIndexCached(root, {
+    maxFiles: options.semanticMaxFiles ?? 6000,
+    maxDepth: options.semanticMaxDepth ?? 14,
+    workspaceFingerprint: options.workspaceFingerprint,
+  }).catch(() => null)
+
+  const hierarchy = await queryContextHierarchy(root, queryText, {
+    declaredFiles: declared,
+    maxScopes: options.hierarchyMaxScopes ?? 6,
+    maxFiles: options.semanticMaxFiles ?? 6000,
+    builtIndex: semanticSnapshot || undefined,
+  }).catch(() => null)
+  const hierarchyScopes = hierarchy?.scopes?.map((item) => item.path) || []
+
   const semantic = await querySemanticIndex(root, queryText, {
     limit: 32,
     maxFiles: options.semanticMaxFiles ?? 6000,
+    builtIndex: semanticSnapshot || undefined,
   }).catch(() => null)
-  const semanticPaths = semantic?.results?.map((item) => item.path) || []
+  const scopedSemanticResults = (semantic?.results || []).map((item) => {
+    const scopeRank = hierarchyScopes.findIndex((scope) =>
+      scope === "." || item.path === scope || item.path.startsWith(scope + "/"),
+    )
+    const scopeBoost = scopeRank >= 0 ? Math.max(2, 12 - scopeRank * 2) : 0
+    return {
+      ...item,
+      baseScore: item.score,
+      scopeBoost,
+      score: Number((Number(item.score || 0) + scopeBoost).toFixed(3)),
+    }
+  }).sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+  const semanticPaths = scopedSemanticResults.map((item) => item.path)
 
   const useGraph = strategy.includes("graph")
   const graph = useGraph
-    ? await buildRepoGraph(root, { maxFiles: options.maxFiles ?? 2500 })
+    ? await buildRepoGraphCached(root, {
+        maxFiles: options.maxFiles ?? 2500,
+        workspaceFingerprint: options.workspaceFingerprint,
+      })
     : { nodes: [], edges: [], hotspots: [], scannedFiles: 0, truncated: false }
   const nodeMap = new Map(graph.nodes.map((node) => [node.path, node]))
   const incoming = new Map()
@@ -297,17 +331,46 @@ export async function buildContextManifest(root, task, options = {}) {
     .map((item) => item.file)
 
   const instructions = await nearbyInstructions(root, declared)
-  const ranked = semantic?.results?.length
-    ? semantic.results.map((item) => ({
-        path: item.path,
-        score: item.score,
-        matches: item.reasons || [],
-        symbolHits: item.definitions || [],
-        evidenceLevel: semantic.evidenceLevel,
-      }))
-    : useGraph
-      ? await rankedReferences(root, graph.nodes, terms, declared, changed)
-      : []
+  const graphRanked = useGraph
+    ? rankContextGraph(graph, {
+        semanticResults: scopedSemanticResults,
+        declared,
+        changed,
+        limit: 32,
+      })
+    : []
+
+  const semanticByPath = new Map(scopedSemanticResults.map((item) => [item.path, item]))
+  const ranked = graphRanked.length
+    ? graphRanked.map((item) => {
+        const semanticItem = semanticByPath.get(item.path)
+        return {
+          path: item.path,
+          score: item.score,
+          pageRank: item.pageRank,
+          personalization: item.personalization,
+          baseScore: semanticItem?.baseScore ?? semanticItem?.score ?? item.semanticScore,
+          scopeBoost: semanticItem?.scopeBoost || 0,
+          matches: [...new Set([...(semanticItem?.reasons || []), ...(item.reasons || [])])],
+          symbolHits: semanticItem?.definitions || [],
+          evidenceLevel: semanticItem
+            ? String(semantic?.evidenceLevel || "syntax-aware-lexical") + "+dependency-graph-rank"
+            : "dependency-graph-rank",
+        }
+      })
+    : scopedSemanticResults.length
+      ? scopedSemanticResults.map((item) => ({
+          path: item.path,
+          score: item.score,
+          baseScore: item.baseScore ?? item.score,
+          scopeBoost: item.scopeBoost || 0,
+          matches: item.reasons || [],
+          symbolHits: item.definitions || [],
+          evidenceLevel: semantic.evidenceLevel,
+        }))
+      : useGraph
+        ? await rankedReferences(root, graph.nodes, terms, declared, changed)
+        : []
   const changedRelevant = changed
     .filter((file) =>
       declared.includes(file) ||
@@ -372,6 +435,18 @@ export async function buildContextManifest(root, task, options = {}) {
     rankedReferences: ranked,
     files,
     excerpts,
+    hierarchy: hierarchy ? {
+      schemaVersion: hierarchy.schemaVersion,
+      levels: hierarchy.levels,
+      scopes: hierarchy.scopes.slice(0, 6).map((item) => ({
+        path: item.path,
+        score: item.score,
+        reasons: item.reasons,
+        fileCount: item.fileCount,
+        l0: item.l0,
+        l1: item.l1,
+      })),
+    } : null,
     semantic: semantic ? {
       evidenceLevel: semantic.evidenceLevel,
       resultCount: semantic.results.length,
@@ -382,11 +457,15 @@ export async function buildContextManifest(root, task, options = {}) {
       scannedFiles: graph.scannedFiles,
       truncated: graph.truncated,
       hotspots: graph.hotspots.slice(0, 12),
+      ranking: graphRanked.length ? {
+        strategy: "personalized-dependency-graph-rank",
+        resultCount: graphRanked.length,
+        top: graphRanked.slice(0, 12),
+      } : null,
     },
     budget,
     evidenceBudget,
     categoryRemaining,
     used: budget - remaining,
   }
-}
-
+}