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

package/README.md

@@ -4,8 +4,8 @@
 
 **Package:** <code>opencode-agent-skill</code>  
 **Host chính:** Pi Agent  
-**Phiên bản package hiện tại:** <code>14.2.0-beta.1</code>  
-**Nhánh phát triển hiện tại:** V14.2 Turbo Weak-Model Runtime  
+**Phiên bản package hiện tại:** <code>14.4.0</code>  
+**Release hiện tại:** V14.4 Stable Weak-Model Intelligence Runtime  
 **Runtime:** Node.js 22.19+  
 **License:** MIT
 
@@ -1352,7 +1352,22 @@ npm install -g @earendil-works/pi-coding-agent
 pi --version
 ~~~
 
-Cài UES trực tiếp từ GitHub:
+Cài UES stable từ npm (khuyến nghị):
+
+~~~cmd
+pi install npm:opencode-agent-skill
+pi list
+pi
+~~~
+
+Hoặc cài CLI toàn cục:
+
+~~~cmd
+npm install -g opencode-agent-skill@latest
+ues version
+~~~
+
+Cài trực tiếp từ GitHub main nếu muốn dùng source mới nhất:
 
 ~~~cmd
 pi install git:github.com/laivannha0202/opencode-agent-skill-
@@ -1396,18 +1411,18 @@ npm pack --dry-run
 npm pack
 ~~~
 
-Package version hiện tại trong <code>package.json</code> là:
+Package stable hiện tại trong <code>package.json</code> là:
 
 ~~~text
-14.2.0-beta.1
+14.4.0
 ~~~
 
-V14.2 Turbo Weak-Model Runtime hiện là incremental work trên package version đó.
+V14.4 gom V14/V14.1/V14.2 cùng code intelligence, hash-anchored editing, completion auditor, stable memory snapshots, reversible context/document ingestion và MCP health-aware routing thành release stable.
 
 Test file packed với Pi:
 
 ~~~cmd
-pi install .\opencode-agent-skill-14.2.0-beta.1.tgz
+pi install .\opencode-agent-skill-14.4.0.tgz
 pi list
 ~~~
 
@@ -1757,7 +1772,7 @@ UES cố ý **không**:
 
 ~~~cmd
 npm install -g @earendil-works/pi-coding-agent
-pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi install npm:opencode-agent-skill
 pi
 ~~~
 

package/docs/PI-COMPAT.md

@@ -10,13 +10,28 @@ Repository này hiện đóng gói UES cho **Pi Agent**.
 
 ## Install
 
+Stable npm release:
+
 ```cmd
 npm install -g @earendil-works/pi-coding-agent
-pi install git:github.com/laivannha0202/opencode-agent-skill-
+pi install npm:opencode-agent-skill
 pi list
 pi
 ```
 
+Optional global CLI:
+
+```cmd
+npm install -g opencode-agent-skill@latest
+ues version
+```
+
+GitHub main can still be installed when source-head testing is intended:
+
+```cmd
+pi install git:github.com/laivannha0202/opencode-agent-skill-
+```
+
 Project-local:
 
 ```cmd

package/lib/capability-fabric.mjs

@@ -106,6 +106,29 @@ export function defaultCapabilityRegistry(root = process.cwd()) {
       "code.search": [
         { id: "ues-semantic-index", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
       ],
+      "code.edit.anchored": [
+        { id: "ues-hashline", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { failClosed: true, staleAnchorReject: true } },
+      ],
+      "code.structure": [
+        { id: "ast-grep", kind: "command", command: "ast-grep", priority: 120, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "sg", kind: "command", command: "sg", priority: 115, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "ues-semantic-index", kind: "builtin", priority: 80, quality: 0.8, costClass: "low", latencyClass: "fast" },
+      ],
+      "code.diagnostics": [
+        { id: "typescript-language-server", kind: "command", command: "typescript-language-server", priority: 110, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pyright-langserver", kind: "command", command: "pyright-langserver", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pylsp", kind: "command", command: "pylsp", priority: 95, quality: 0.85, costClass: "low", latencyClass: "medium" },
+        { id: "gopls", kind: "command", command: "gopls", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "rust-analyzer", kind: "command", command: "rust-analyzer", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "clangd", kind: "command", command: "clangd", priority: 100, quality: 0.9, costClass: "low", latencyClass: "medium" },
+      ],
+      "document.ingestion": [
+        { id: "ues-builtin-text", kind: "builtin", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast", metadata: { formats: ["text", "markdown", "json", "csv", "html", "xml"] } },
+        { id: "markitdown-cli", kind: "command", command: "markitdown", priority: 95, quality: 0.95, costClass: "low", latencyClass: "medium", metadata: { optional: true, formats: ["pdf", "docx", "pptx", "xlsx", "epub", "zip"] } },
+      ],
+      "context.reversible": [
+        { id: "ues-evidence-context", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { reversible: true, searchable: true, levels: ["T1", "T2", "T3", "raw"] } },
+      ],
       memory: [
         { id: "ues-memory", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
       ],

package/lib/code-intelligence/edit-anchor.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto"
+
+const DEFAULT_HASH_CHARS = 8
+
+function normalizeNewlines(value) {
+  return String(value ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n")
+}
+
+function hashText(value, chars = DEFAULT_HASH_CHARS) {
+  return createHash("sha256").update(String(value ?? "")).digest("hex").slice(0, Math.max(6, Math.min(16, Number(chars || DEFAULT_HASH_CHARS))))
+}
+
+export function lineAnchor(lineNumber, lineText, options = {}) {
+  const line = Math.max(1, Math.trunc(Number(lineNumber || 1)))
+  return `L${line}:${hashText(lineText, options.hashChars)}`
+}
+
+export function parseLineAnchor(anchor) {
+  const match = String(anchor || "").trim().match(/^L([1-9]\d*):([a-f0-9]{6,16})$/i)
+  if (!match) return null
+  return { line: Number(match[1]), hash: match[2].toLowerCase() }
+}
+
+export function anchoredLines(source, options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  const startLine = Math.max(1, Math.trunc(Number(options.startLine || 1)))
+  const requestedEnd = options.endLine == null ? lines.length : Math.trunc(Number(options.endLine))
+  const endLine = Math.max(startLine, Math.min(lines.length, requestedEnd || lines.length))
+  const rows = []
+  for (let line = startLine; line <= endLine; line += 1) {
+    const value = lines[line - 1] ?? ""
+    rows.push({ line, anchor: lineAnchor(line, value, options), text: value })
+  }
+  return {
+    schemaVersion: 1,
+    startLine,
+    endLine,
+    lineCount: lines.length,
+    sourceHash: hashText(text, 16),
+    rows,
+    text: rows.map((row) => `${row.anchor}|${row.text}`).join("\n"),
+  }
+}
+
+function validateAnchor(lines, rawAnchor, label, options = {}) {
+  const parsed = parseLineAnchor(rawAnchor)
+  if (!parsed) throw new Error(`${label} must use L<line>:<hash> format`)
+  if (parsed.line > lines.length) throw new Error(`${label} points beyond end of file`)
+  const actual = lineAnchor(parsed.line, lines[parsed.line - 1] ?? "", options)
+  if (actual.toLowerCase() !== String(rawAnchor).toLowerCase()) {
+    const error = new Error(`${label} is stale or ambiguous; re-read anchored source before editing`)
+    error.code = "UES_STALE_ANCHOR"
+    error.expected = actual
+    error.received = String(rawAnchor)
+    throw error
+  }
+  return parsed
+}
+
+export function applyAnchoredEdits(source, edits = [], options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  if (!Array.isArray(edits) || edits.length === 0) throw new Error("at least one anchored edit is required")
+  const maxEdits = Math.max(1, Math.min(200, Number(options.maxEdits || 50)))
+  if (edits.length > maxEdits) throw new Error(`too many anchored edits; maximum is ${maxEdits}`)
+
+  const prepared = edits.map((edit, index) => {
+    const start = validateAnchor(lines, edit?.anchor || edit?.startAnchor, `edit[${index}].anchor`, options)
+    const end = edit?.endAnchor
+      ? validateAnchor(lines, edit.endAnchor, `edit[${index}].endAnchor`, options)
+      : start
+    if (end.line < start.line) throw new Error(`edit[${index}] endAnchor precedes anchor`)
+    return {
+      index,
+      startLine: start.line,
+      endLine: end.line,
+      replacement: normalizeNewlines(edit?.replacement ?? ""),
+    }
+  })
+
+  prepared.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine)
+  for (let index = 1; index < prepared.length; index += 1) {
+    if (prepared[index].startLine <= prepared[index - 1].endLine) {
+      throw new Error(`anchored edits overlap at edit[${prepared[index].index}]`)
+    }
+  }
+
+  const next = [...lines]
+  for (const edit of [...prepared].sort((a, b) => b.startLine - a.startLine)) {
+    const replacementLines = edit.replacement.split("\n")
+    next.splice(edit.startLine - 1, edit.endLine - edit.startLine + 1, ...replacementLines)
+  }
+  const output = next.join("\n")
+  return {
+    schemaVersion: 1,
+    sourceHash: hashText(text, 16),
+    outputHash: hashText(output, 16),
+    applied: prepared.length,
+    text: output,
+  }
+}

package/lib/code-intelligence/index.mjs

@@ -0,0 +1,95 @@
+import { lstat, readFile, realpath, rename, rm, writeFile } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { querySemanticIndex } from "../semantic-index.mjs"
+import { anchoredLines, applyAnchoredEdits } from "./edit-anchor.mjs"
+import { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"
+
+const AST_COMMANDS = ["ast-grep", "sg"]
+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("code path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("code path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("code symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+export function probeCodeIntelligence(file = "") {
+  const astProvider = AST_COMMANDS.find(commandExists) || null
+  return {
+    schemaVersion: 1,
+    anchoredEditing: true,
+    semanticIndex: true,
+    astProvider,
+    lsp: lspProviderStatus(file),
+  }
+}
+
+export async function readAnchoredCode(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-read limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  return { file: path.relative(target.base, target.file).replaceAll("\\", "/"), ...anchoredLines(source, options) }
+}
+
+export async function applyAnchoredFileEdits(root, relative, edits, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-edit limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  const result = applyAnchoredEdits(source, edits, options)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (options.dryRun === true) return { ...result, file: relativeFile, dryRun: true }
+  const temp = target.file + "." + process.pid + "." + Date.now() + ".ues.tmp"
+  await writeFile(temp, result.text, "utf8")
+  try { await rename(temp, target.file) } catch (error) { await rm(temp, { force: true }).catch(() => {}); throw error }
+  return { ...result, file: relativeFile, dryRun: false }
+}
+
+function runAstGrep(root, pattern, language, limit) {
+  const command = AST_COMMANDS.find(commandExists) || null
+  if (!command || !String(pattern || "").trim()) return { provider: null, results: [], error: null }
+  const args = ["run", "--pattern", String(pattern), "--json=stream"]
+  if (language) args.push("--lang", String(language))
+  args.push(".")
+  const result = spawnSync(command, args, { cwd: path.resolve(root), encoding: "utf8", timeout: 20_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true })
+  if (result.status !== 0) return { provider: command, results: [], error: String(result.stderr || ("ast-grep exit " + result.status)).trim().slice(0, 1000) }
+  const rows = String(result.stdout || "").split(/\r?\n/).filter(Boolean).slice(0, limit).map((line) => {
+    try { return JSON.parse(line) } catch { return { raw: line } }
+  })
+  return { provider: command, results: rows, error: null }
+}
+
+export async function searchCodeIntelligence(root, query, options = {}) {
+  const maxResults = Math.max(1, Math.min(50, Number(options.maxResults || 12)))
+  const semantic = await querySemanticIndex(root, query, { maxFiles: options.maxFiles || 6000, limit: maxResults })
+  const structural = options.structuralPattern ? runAstGrep(root, options.structuralPattern, options.language, maxResults) : { provider: null, results: [], error: null }
+  return {
+    schemaVersion: 1,
+    query: String(query || ""),
+    providers: probeCodeIntelligence(options.file || ""),
+    semantic: { ...semantic, results: (semantic.results || []).slice(0, maxResults) },
+    structural,
+  }
+}
+
+export { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"

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/document-ingestion.mjs

@@ -0,0 +1,60 @@
+import { lstat, readFile, realpath } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+const BUILTIN_TEXT_EXTENSIONS = new Set([
+  ".txt", ".md", ".markdown", ".json", ".jsonl", ".csv", ".tsv", ".xml", ".html", ".htm",
+  ".yaml", ".yml", ".toml", ".ini", ".log", ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx",
+  ".py", ".java", ".kt", ".kts", ".cs", ".go", ".rs", ".rb", ".php", ".sql", ".css", ".scss",
+])
+const MARKITDOWN_EXTENSIONS = new Set([".pdf", ".docx", ".pptx", ".xlsx", ".xls", ".epub", ".zip"])
+
+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("document path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("document path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("document symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+function runMarkItDown(file, options = {}) {
+  const timeout = Math.max(5_000, Math.min(120_000, Number(options.timeoutMs || 30_000)))
+  const maxBuffer = Math.max(256 * 1024, Math.min(16 * 1024 * 1024, Number(options.maxBuffer || 4 * 1024 * 1024)))
+  const attempts = process.platform === "win32"
+    ? [["markitdown.exe", [file]], ["markitdown", [file]], ["py", ["-m", "markitdown", file]], ["python", ["-m", "markitdown", file]]]
+    : [["markitdown", [file]], ["python3", ["-m", "markitdown", file]], ["python", ["-m", "markitdown", file]]]
+  for (const [command, args] of attempts) {
+    const result = spawnSync(command, args, { encoding: "utf8", timeout, maxBuffer, windowsHide: true })
+    if (result.status === 0 && String(result.stdout || "").trim()) return { provider: command.includes("python") || command === "py" ? "markitdown-python" : "markitdown-cli", markdown: String(result.stdout) }
+    if (result.error?.code !== "ENOENT" && result.status != null) return { provider: "markitdown-unavailable", error: String(result.stderr || result.error?.message || `exit ${result.status}`) }
+  }
+  return { provider: "markitdown-unavailable", error: "MarkItDown command/module was not found" }
+}
+
+export function documentIngestionSupport(file = "") {
+  const ext = path.extname(String(file)).toLowerCase()
+  return { schemaVersion: 1, extension: ext, builtin: BUILTIN_TEXT_EXTENSIONS.has(ext), markitdown: MARKITDOWN_EXTENSIONS.has(ext), supported: BUILTIN_TEXT_EXTENSIONS.has(ext) || MARKITDOWN_EXTENSIONS.has(ext) }
+}
+
+export async function ingestDocument(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const support = documentIngestionSupport(target.file)
+  const maxBytes = Math.max(16 * 1024, Math.min(32 * 1024 * 1024, Number(options.maxBytes || 4 * 1024 * 1024)))
+  if (target.info.size > maxBytes) throw new Error(`document exceeds ingestion limit (${target.info.size} > ${maxBytes} bytes)`)
+  if (support.builtin) {
+    const content = await readFile(target.file, "utf8")
+    return { schemaVersion: 1, provider: "builtin-text", file: path.relative(target.base, target.file).replaceAll("\\", "/"), bytes: target.info.size, markdown: content, optionalDependency: false }
+  }
+  if (support.markitdown) {
+    const converted = runMarkItDown(target.file, options)
+    if (converted.markdown) return { schemaVersion: 1, provider: converted.provider, file: path.relative(target.base, target.file).replaceAll("\\", "/"), bytes: target.info.size, markdown: converted.markdown, optionalDependency: true }
+    const error = new Error(`${converted.error}. Install Microsoft MarkItDown only when Office/PDF ingestion is needed.`)
+    error.code = "UES_MARKITDOWN_UNAVAILABLE"
+    throw error
+  }
+  throw new Error(`unsupported document extension: ${support.extension || "(none)"}`)
+}