opencode-agent-skill 13.0.0-beta.1 → 14.2.0-beta.1

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,
   }
-}
-
+}

package/lib/control-center.mjs

@@ -4,6 +4,8 @@ import path from "node:path"
 import { readLearningState } from "./learning-engine.mjs"
 import { readRuntimeEvents } from "./runtime-events.mjs"
 import { evidenceStoreStatus } from "./evidence-store.mjs"
+import { memoryStatus } from "./memory-engine.mjs"
+import { capabilityFabricStatus } from "./capability-fabric.mjs"
 
 function escapeHtml(value) {
   return String(value ?? "")
@@ -65,11 +67,13 @@ async function collectEvalSummary(root) {
 
 export async function collectControlCenterData(root = process.cwd()) {
   root = path.resolve(root)
-  const [work, learning, evals, evidenceStore] = await Promise.all([
+  const [work, learning, evals, evidenceStore, memory, capabilityFabric] = await Promise.all([
     collectWork(root),
     readLearningState(root),
     collectEvalSummary(root),
     evidenceStoreStatus(root),
+    memoryStatus(root),
+    capabilityFabricStatus(root),
   ])
   return {
     schemaVersion: 2,
@@ -82,6 +86,16 @@ export async function collectControlCenterData(root = process.cwd()) {
       evidenceStore,
       runtime: "perception-adaptive-execution",
     },
+    v14: {
+      memory,
+      capabilityFabric: {
+        healthyCapabilities: capabilityFabric.healthyCapabilities,
+        totalCapabilities: capabilityFabric.totalCapabilities,
+        rows: capabilityFabric.rows,
+        observationState: capabilityFabric.observationState,
+      },
+      runtime: "context-memory-capability-fabric",
+    },
   }
 }
 
@@ -110,6 +124,7 @@ details{margin-top:10px;border-top:1px solid #243049;padding-top:8px}summary{cur
 <div class="section"><h2>Long-horizon work</h2><div class="grid" id="work"></div></div>
 <div class="section"><h2>Learning loop</h2><div class="grid" id="learning"></div></div>
 <div class="section"><h2>V11 runtime efficiency</h2><div class="grid" id="v11"></div></div>
+<div class="section"><h2>V14 context & memory fabric</h2><div class="grid" id="v14"></div></div>
 <div class="section"><h2>Recent runtime events</h2><div class="card"><table><thead><tr><th>Work</th><th>Event</th><th>Task</th><th>Time</th></tr></thead><tbody id="events"></tbody></table></div></div>
 <div class="section"><h2>Recent evaluations</h2><div class="card"><table><thead><tr><th>Suite</th><th>Model</th><th>Baseline</th><th>UES</th></tr></thead><tbody id="evals"></tbody></table></div></div>
 </div>
@@ -136,6 +151,9 @@ function render(next){
  const v11=document.querySelector("#v11");
  const store=data.v11?.evidenceStore||{};
  v11.innerHTML='<div class="card"><h3>Evidence store</h3><strong>'+esc(store.entries||0)+'</strong><div class="muted">'+esc(store.bytes||0)+' bytes externalized</div></div><div class="card"><h3>Runtime</h3><strong>V11</strong><div class="muted">'+esc(data.v11?.runtime||'adaptive')+'</div></div>';
+ const v14=document.querySelector("#v14");
+ const memory=data.v14?.memory||{};
+ v14.innerHTML='<div class="card"><h3>Verified memory</h3><strong>'+esc(memory.byStatus?.verified||0)+'</strong><div class="muted">'+esc(memory.entries||0)+' total entries</div></div><div class="card"><h3>Runtime</h3><strong>V14</strong><div class="muted">'+esc(data.v14?.runtime||'context-memory-fabric')+'</div></div>';
  const eventBody=document.querySelector("#events");
  eventBody.innerHTML="";
  for(const item of data.work){

package/lib/dynamic-workflow.mjs

@@ -50,6 +50,7 @@ function conflict(a, b) {
 
 function executionMode(classification, options) {
   if (classification.kind === "deterministic") return "deterministic"
+  if (options.allowInline === false) return "agent"
   if (classification.kind === "vision") {
     return classification.estimatedCost >= options.minVisionAgentCost ? "agent" : "inline"
   }
@@ -81,6 +82,7 @@ export function planDynamicWorkflow(tasks = [], inputOptions = {}) {
     minAgentCost: clampInt(inputOptions.minAgentCost, 5, 2, 12),
     minVisionAgentCost: clampInt(inputOptions.minVisionAgentCost, 4, 2, 12),
     deterministicFirst: inputOptions.deterministicFirst !== false,
+    allowInline: inputOptions.allowInline !== false,
   }
 
   const byID = new Map(tasks.map((task) => [task.id, task]))
@@ -176,4 +178,4 @@ export function planDynamicWorkflow(tasks = [], inputOptions = {}) {
     visionAgentTaskCount: flat.filter((task) => task.spawnAgent && task.kind === "vision").length,
     estimatedCoordinationSaved: flat.filter((task) => task.execution !== "agent").reduce((sum, task) => sum + task.estimatedCost, 0),
   }
-}
+}

package/lib/evidence-store.mjs

@@ -99,6 +99,87 @@ export async function getEvidence(root, ref, options = {}) {
   }
 }
 
+
+function evidenceSelector(ref) {
+  const value = String(ref || "").trim()
+  const index = value.indexOf("#")
+  if (index < 0) return { ref: value, selector: null }
+  return {
+    ref: value.slice(0, index),
+    selector: value.slice(index + 1),
+  }
+}
+
+function selectorParts(selector) {
+  const value = String(selector || "").trim()
+  if (!value) return []
+  if (value.startsWith("/")) {
+    return value
+      .split("/")
+      .slice(1)
+      .map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
+  }
+  return value
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .map((part) => part.trim())
+    .filter(Boolean)
+}
+
+function selectJsonValue(value, selector) {
+  let current = value
+  for (const part of selectorParts(selector)) {
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(part)) throw new Error("Invalid array selector segment: " + part)
+      const index = Number(part)
+      if (index < 0 || index >= current.length) throw new Error("Evidence selector index out of range: " + part)
+      current = current[index]
+      continue
+    }
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, part)) {
+      throw new Error("Evidence selector path not found: " + part)
+    }
+    current = current[part]
+  }
+  return current
+}
+
+export async function getEvidenceSelected(root, refWithSelector, options = {}) {
+  const split = evidenceSelector(refWithSelector)
+  if (!split.selector) return getEvidence(root, split.ref, options)
+
+  const hash = normalizeHash(split.ref)
+  const target = evidencePaths(root, hash)
+  const metadata = JSON.parse(await readFile(target.meta, "utf8"))
+  if (metadata.encoding !== "utf8" || !String(metadata.mediaType || "").includes("json")) {
+    throw new Error("Evidence selectors require JSON evidence")
+  }
+
+  const maxObjectBytes = Math.max(1024, Math.min(16 * 1024 * 1024, Number(options.maxObjectBytes || 4 * 1024 * 1024)))
+  if (Number(metadata.bytes || 0) > maxObjectBytes) {
+    throw new Error("JSON evidence is too large for selector retrieval; use byte slices instead")
+  }
+  const source = await readFile(target.data, "utf8")
+  const selected = selectJsonValue(JSON.parse(source), split.selector)
+  const encoded = typeof selected === "string"
+    ? selected
+    : JSON.stringify(stableValue(selected), null, 2)
+  const maxBytes = Math.max(1, Number(options.maxBytes || options.maxChars || 24_000))
+  const bytes = Buffer.from(encoded, "utf8")
+  const start = Math.max(0, Number(options.start || 0))
+  const slice = bytes.subarray(start, Math.min(bytes.length, start + maxBytes))
+  return {
+    ...metadata,
+    ref: split.ref + "#" + split.selector,
+    selector: split.selector,
+    selectedBytes: bytes.length,
+    truncated: start + slice.length < bytes.length,
+    start,
+    returnedBytes: slice.length,
+    content: slice.toString("utf8"),
+  }
+}
+
 async function metadataFiles(root) {
   const base = evidenceStoreRoot(root)
   const prefixes = await readdir(base, { withFileTypes: true }).catch(() => [])
@@ -175,4 +256,4 @@ export async function evidenceExists(root, ref) {
   } catch {
     return false
   }
-}
+}

package/lib/hierarchical-context.mjs

@@ -0,0 +1,215 @@
+import path from "node:path"
+import { buildSemanticIndex } from "./semantic-index.mjs"
+
+const DEFAULT_L0 = 256
+const DEFAULT_L1 = 4000
+const STOP = new Set([
+  "this","that","with","from","into","then","than","when","where","what","your","have","will",
+  "task","code","file","files","fix","update","change","changes","được","các","cho","với","trong","này","một","những","không","theo",
+])
+
+function terms(value) {
+  return [...new Set(
+    String(value || "")
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}_$.-]+/u)
+      .map((item) => item.replace(/^[-.$]+|[-.$]+$/g, ""))
+      .filter((item) => item.length >= 2 && !STOP.has(item)),
+  )].slice(0, 32)
+}
+
+function ancestors(file) {
+  const parts = String(file || "").replaceAll("\\", "/").split("/").filter(Boolean)
+  const result = ["."]
+  let current = ""
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    current = current ? `${current}/${parts[index]}` : parts[index]
+    result.push(current)
+  }
+  return result
+}
+
+function parentDir(dir) {
+  if (!dir || dir === ".") return null
+  const value = path.posix.dirname(dir)
+  return value === "." ? "." : value
+}
+
+function clip(value, limit) {
+  const text = String(value || "")
+  return text.length <= limit ? text : text.slice(0, Math.max(0, limit - 15)) + "...[truncated]"
+}
+
+function topCounts(map, limit) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([name, count]) => ({ name, count }))
+}
+
+function buildNodeSummary(node, children, options = {}) {
+  const l0Limit = Math.max(96, Number(options.l0Chars || DEFAULT_L0))
+  const l1Limit = Math.max(512, Number(options.l1Chars || DEFAULT_L1))
+  const symbols = topCounts(node.symbols, 18)
+  const extensions = topCounts(node.extensions, 10)
+  const files = [...node.files].sort()
+  const childNames = (children.get(node.path) || []).sort()
+  const l0 = clip([
+    `${node.path}: ${files.length} source file(s), ${node.bytes} bytes.`,
+    symbols.length ? `Key symbols: ${symbols.slice(0, 8).map((item) => item.name).join(", ")}.` : "",
+    childNames.length ? `Child areas: ${childNames.slice(0, 6).join(", ")}.` : "",
+  ].filter(Boolean).join(" "), l0Limit)
+  const l1 = clip([
+    l0,
+    childNames.length ? `Children: ${childNames.join(", ")}` : "",
+    extensions.length ? `Extensions: ${extensions.map((item) => `${item.name || "(none)"}:${item.count}`).join(", ")}` : "",
+    symbols.length ? `Symbols: ${symbols.map((item) => `${item.name}:${item.count}`).join(", ")}` : "",
+    files.length ? `Files: ${files.slice(0, 60).join(", ")}` : "",
+  ].filter(Boolean).join("\n"), l1Limit)
+  return {
+    path: node.path,
+    fileCount: files.length,
+    bytes: node.bytes,
+    files,
+    symbols,
+    children: childNames,
+    l0,
+    l1,
+  }
+}
+
+export async function buildContextHierarchy(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const built = options.builtIndex || await buildSemanticIndex(root, {
+    maxFiles: options.maxFiles ?? 6000,
+    maxDepth: options.maxDepth ?? 14,
+  })
+  const nodes = new Map()
+  const children = new Map()
+  const ensure = (dir) => {
+    if (!nodes.has(dir)) {
+      nodes.set(dir, { path: dir, files: new Set(), bytes: 0, symbols: new Map(), extensions: new Map() })
+    }
+    return nodes.get(dir)
+  }
+
+  ensure(".")
+  for (const [file, entry] of Object.entries(built.index.files || {})) {
+    const dirs = ancestors(file)
+    const extension = path.posix.extname(file).toLowerCase()
+    for (const dir of dirs) {
+      const node = ensure(dir)
+      node.files.add(file)
+      node.bytes += Number(entry.bytes || 0)
+      node.extensions.set(extension, (node.extensions.get(extension) || 0) + 1)
+      for (const symbol of entry.symbols || []) {
+        const name = String(symbol.name || "")
+        if (!name) continue
+        node.symbols.set(name, (node.symbols.get(name) || 0) + 1)
+      }
+    }
+  }
+
+  for (const dir of nodes.keys()) {
+    const parent = parentDir(dir)
+    if (!parent) continue
+    const list = children.get(parent) || []
+    if (!list.includes(dir)) list.push(dir)
+    children.set(parent, list)
+  }
+
+  const summaries = [...nodes.values()]
+    .map((node) => buildNodeSummary(node, children, options))
+    .sort((a, b) => a.path.localeCompare(b.path))
+
+  return {
+    schemaVersion: 1,
+    kind: "ues-context-hierarchy",
+    root,
+    generatedAt: new Date().toISOString(),
+    levels: {
+      L0: { maxChars: Math.max(96, Number(options.l0Chars || DEFAULT_L0)), purpose: "routing abstract" },
+      L1: { maxChars: Math.max(512, Number(options.l1Chars || DEFAULT_L1)), purpose: "scope overview" },
+      L2: { purpose: "source excerpts loaded on demand by the context manifest" },
+    },
+    nodes: summaries,
+    stats: built.stats,
+  }
+}
+
+function containsFile(scope, file) {
+  if (scope === ".") return true
+  return file === scope || file.startsWith(scope + "/")
+}
+
+function scopesOverlap(left, right) {
+  if (left === "." || right === ".") return true
+  return left === right || left.startsWith(right + "/") || right.startsWith(left + "/")
+}
+
+export function selectDiverseHierarchyScopes(rows = [], maxScopes = 6) {
+  const limit = Math.max(1, Math.min(Number(maxScopes || 6), 20))
+  const selected = []
+  for (const row of rows) {
+    if (selected.length >= limit) break
+    if (selected.some((item) => scopesOverlap(item.path, row.path))) continue
+    selected.push(row)
+  }
+  if (!selected.length && rows.length) selected.push(rows[0])
+  return selected
+}
+
+export async function queryContextHierarchy(root, query, options = {}) {
+  const hierarchy = await buildContextHierarchy(root, options)
+  const wanted = terms(query)
+  const declared = (options.declaredFiles || []).map((file) => String(file || "").replaceAll("\\", "/")).filter(Boolean)
+  const scored = hierarchy.nodes.map((node) => {
+    const lowerPath = node.path.toLowerCase()
+    const symbolText = node.symbols.map((item) => item.name.toLowerCase()).join(" ")
+    const fileText = node.files.slice(0, 100).join(" ").toLowerCase()
+    let score = node.path === "." ? 0.25 : 0
+    const reasons = []
+    for (const term of wanted) {
+      if (lowerPath.includes(term)) {
+        score += 8
+        reasons.push("path:" + term)
+      }
+      if (symbolText.includes(term)) {
+        score += 5
+        reasons.push("symbol:" + term)
+      }
+      if (fileText.includes(term)) {
+        score += 2
+        reasons.push("file:" + term)
+      }
+    }
+    const declaredHits = declared.filter((file) => containsFile(node.path, file)).length
+    if (declaredHits) {
+      score += 20 + declaredHits * 4
+      reasons.push("declared:" + declaredHits)
+    }
+    const depth = node.path === "." ? 0 : node.path.split("/").length
+    if (score > 0) score += Math.min(3, depth * 0.4)
+    score -= Math.min(2.5, Math.log1p(node.fileCount) * 0.15)
+    return { ...node, score: Number(score.toFixed(3)), reasons: [...new Set(reasons)].slice(0, 12) }
+  })
+
+  const maxScopes = Math.max(1, Math.min(Number(options.maxScopes || 6), 20))
+  const positive = scored
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.fileCount - b.fileCount || a.path.localeCompare(b.path))
+  const scopes = selectDiverseHierarchyScopes(
+    positive.length ? positive : scored.filter((item) => item.path === "."),
+    maxScopes,
+  )
+
+  return {
+    schemaVersion: 1,
+    kind: "ues-context-hierarchy-query",
+    query: String(query || ""),
+    terms: wanted,
+    levels: hierarchy.levels,
+    scopes,
+    stats: hierarchy.stats,
+  }
+}