@agentskit/doc-bridge 1.7.44 → 1.9.0

package/src/doctor/run-doctor.ts

@@ -1,11 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
 import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { parseRetrievalSuite, runRetrievalBench } from '../bench/retrieval.js'
+import { discoverRepository } from '../discovery/repository.js'
 import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
 import { runGates, type GateRunResult } from '../gates/run-gates.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import type { DiscoverySnapshotV1 } from '../schemas/knowledge.js'
 import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
 
+/** Where the golden retrieval suite lives unless `retrieval.benchmark.suite` says otherwise. */
+export const DEFAULT_RETRIEVAL_SUITE = 'docs/bench/retrieval-suite-v1.json'
+
+/**
+ * What an A requires beyond the score, as fractions the doctor measured rather than declared.
+ *
+ * Reachability must be complete: a document retrieval cannot find is a document the product does
+ * not deliver, and no other dimension compensates for it. Connectivity and the benchmark have a
+ * floor rather than a ceiling, because a repository with a few undocumented utility areas is
+ * still healthy and a suite that misses a hard case in ten is still a good ranker.
+ */
+export const A_GRADE_REQUIREMENTS = { reachabilityPct: 100, connectivityPct: 80, benchmarkHitAt3: 0.8 } as const
+
+/** How many offenders a dimension lists, so the report stays readable on a large repository. */
+const MAX_LISTED = 20
+
 export type DoctorIssue = {
   readonly severity: 'error' | 'warn' | 'info'
   readonly code: string
@@ -13,7 +35,57 @@ export type DoctorIssue = {
   readonly action?: string
 }
 
+/** The share of the snapshot's documents an agent can retrieve: present in the retrieval projection. */
+export type DoctorReachability = {
+  readonly documentsTotal: number
+  readonly documentsReachable: number
+  readonly unreachable: readonly string[]
+  readonly pct: number
+}
+
+/**
+ * Whether the graph connects documentation to code both ways: an area with at least one document
+ * that covers or mentions it, and a document with at least one edge into code (an area, a module
+ * or a package it covers or mentions). `pct` is the mean of the two shares.
+ */
+export type DoctorConnectivity = {
+  readonly areasTotal: number
+  readonly areasDocumented: number
+  readonly undocumentedAreas: readonly string[]
+  readonly documentsTotal: number
+  readonly documentsLinked: number
+  readonly unlinkedDocuments: readonly string[]
+  readonly pct: number
+}
+
+export type DoctorBenchmark =
+  | {
+      readonly status: 'measured'
+      readonly suite: string
+      readonly caseCount: number
+      readonly hitAt1: number
+      readonly hitAt3: number
+      readonly meanReciprocalRank: number
+    }
+  | {
+      /** No golden suite, or one that could not be run: reported, never silently omitted. */
+      readonly status: 'not-analyzed'
+      readonly suite: string
+      readonly reason: string
+    }
+
+/** Which of the three measured dimensions meet the bar an A requires, and why not when one does not. */
+export type DoctorGrading = {
+  readonly reachability: boolean
+  readonly connectivity: boolean
+  readonly benchmark: boolean
+  readonly unmet: readonly string[]
+}
+
 export type DoctorCoverage = {
+  readonly reachability: DoctorReachability
+  readonly connectivity: DoctorConnectivity
+  readonly benchmark: DoctorBenchmark
   readonly packages: {
     readonly total: number
     readonly withAgentDoc: number
@@ -38,6 +110,7 @@ export type DoctorReport = {
   readonly ok: boolean
   readonly score: number
   readonly grade: 'A' | 'B' | 'C' | 'D' | 'F'
+  readonly grading: DoctorGrading
   readonly coverage: DoctorCoverage
   readonly badge: DoctorBadgeMetrics
   readonly issues: readonly DoctorIssue[]
@@ -52,41 +125,127 @@ const gradeForScore = (score: number): DoctorReport['grade'] => {
   return 'F'
 }
 
-const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
-  const paths = new Set<string>()
-  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
-    if (owner.agentDoc) paths.add(owner.agentDoc)
-  }
-  for (const handoff of Object.values(index.handoffs ?? {})) {
-    if (handoff.startHere) paths.add(handoff.startHere)
-  }
-  return paths
-}
-
-const computeScore = (coverage: DoctorCoverage): number => {
+/**
+ * One hundred points, each traceable to something measured.
+ *
+ * The index (present, fresh), the handoff corpus (agent docs, human guides) and the gates were
+ * the whole score once, and it reported 100/100 on a repository where most documents were
+ * unreachable, because nothing in it measured what retrieval could see. Forty of the hundred now
+ * come from reachability, connectivity and the benchmark; a suite that does not exist scores
+ * nothing, since an unmeasured ranker is not a good ranker.
+ */
+export const computeScore = (coverage: DoctorCoverage): number => {
   let score = 0
 
-  if (coverage.freshness.hasIndex) score += 15
-  if (coverage.freshness.ok) score += 15
+  if (coverage.freshness.hasIndex) score += 10
+  if (coverage.freshness.ok) score += 10
 
   const { total, withAgentDoc, withHumanDoc } = coverage.packages
   if (total > 0) {
-    score += Math.round((withAgentDoc / total) * 35)
-    score += Math.round((withHumanDoc / total) * 20)
+    score += Math.round((withAgentDoc / total) * 20)
+    score += Math.round((withHumanDoc / total) * 10)
   } else if (coverage.agentDocs.indexed > 0) {
-    score += 35
+    score += 20
   }
 
-  if (coverage.gates.ok) score += 15
+  if (coverage.gates.ok) score += 10
   else {
     const passed = coverage.gates.results.filter((gate) => gate.ok).length
     const totalGates = coverage.gates.results.length || 1
-    score += Math.round((passed / totalGates) * 10)
+    score += Math.round((passed / totalGates) * 7)
   }
 
+  score += Math.round((coverage.reachability.pct / 100) * 15)
+  score += Math.round((coverage.connectivity.pct / 100) * 15)
+  if (coverage.benchmark.status === 'measured') score += Math.round(coverage.benchmark.hitAt3 * 10)
+
   return Math.min(100, Math.max(0, score))
 }
 
+const pct = (part: number, whole: number): number => (whole > 0 ? Math.round((part / whole) * 100) : 0)
+
+/**
+ * An A requires all three measured dimensions, whatever the score says. A repository with no
+ * golden suite tops out at B: the ranker may be excellent, but nobody has checked.
+ */
+export const gradeFor = (score: number, coverage: DoctorCoverage): { readonly grade: DoctorReport['grade']; readonly grading: DoctorGrading } => {
+  const reachability = coverage.reachability.pct >= A_GRADE_REQUIREMENTS.reachabilityPct
+  const connectivity = coverage.connectivity.pct >= A_GRADE_REQUIREMENTS.connectivityPct
+  const benchmark = coverage.benchmark.status === 'measured' && coverage.benchmark.hitAt3 >= A_GRADE_REQUIREMENTS.benchmarkHitAt3
+  const unmet = [
+    ...(reachability ? [] : [`reachability ${coverage.reachability.pct}% < ${A_GRADE_REQUIREMENTS.reachabilityPct}%`]),
+    ...(connectivity ? [] : [`connectivity ${coverage.connectivity.pct}% < ${A_GRADE_REQUIREMENTS.connectivityPct}%`]),
+    ...(benchmark
+      ? []
+      : coverage.benchmark.status === 'measured'
+        ? [`benchmark hit@3 ${(coverage.benchmark.hitAt3 * 100).toFixed(1)}% < ${A_GRADE_REQUIREMENTS.benchmarkHitAt3 * 100}%`]
+        : ['benchmark not-analyzed']),
+  ]
+  const grade = gradeForScore(score)
+  return { grade: grade === 'A' && unmet.length ? 'B' : grade, grading: { reachability, connectivity, benchmark, unmet } }
+}
+
+/** The documents an agent can retrieve: those the projection carries, of those the snapshot observed. */
+export const measureReachability = (snapshot: DiscoverySnapshotV1, index: DocBridgeIndexV1): DoctorReachability => {
+  const projected = new Set((index.projection?.entries ?? []).filter((entry) => entry.kind === 'document').map((entry) => entry.id))
+  const documents = snapshot.entities.filter((entity) => entity.kind === 'document').map((entity) => entity.id).sort()
+  const unreachable = documents.filter((id) => !projected.has(id))
+  return {
+    documentsTotal: documents.length,
+    documentsReachable: documents.length - unreachable.length,
+    unreachable: unreachable.slice(0, MAX_LISTED),
+    pct: pct(documents.length - unreachable.length, documents.length),
+  }
+}
+
+/** Both directions of the documentation graph, from the projection's own edges. */
+export const measureConnectivity = (index: DocBridgeIndexV1): DoctorConnectivity => {
+  const entries = index.projection?.entries ?? []
+  const byId = new Map(entries.map((entry) => [entry.id, entry]))
+  const areas = entries.filter((entry) => entry.kind === 'area').sort((a, b) => a.id.localeCompare(b.id))
+  const undocumentedAreas = areas.filter((entry) => !entry.graph.coveredBy.length && !entry.graph.mentionedBy.length).map((entry) => entry.id)
+  const documents = entries.filter((entry) => entry.kind === 'document').sort((a, b) => a.id.localeCompare(b.id))
+  const linksToCode = (entry: (typeof entries)[number]): boolean =>
+    entry.graph.outbound.some((edge) => {
+      const target = byId.get(edge.id)
+      return target !== undefined && target.kind !== 'document'
+    })
+  const unlinkedDocuments = documents.filter((entry) => !linksToCode(entry)).map((entry) => entry.id)
+  const areaShare = areas.length ? (areas.length - undocumentedAreas.length) / areas.length : 0
+  const documentShare = documents.length ? (documents.length - unlinkedDocuments.length) / documents.length : 0
+  return {
+    areasTotal: areas.length,
+    areasDocumented: areas.length - undocumentedAreas.length,
+    undocumentedAreas: undocumentedAreas.slice(0, MAX_LISTED),
+    documentsTotal: documents.length,
+    documentsLinked: documents.length - unlinkedDocuments.length,
+    unlinkedDocuments: unlinkedDocuments.slice(0, MAX_LISTED),
+    pct: Math.round(((areaShare + documentShare) / 2) * 100),
+  }
+}
+
+/** hit@3 over the golden suite when the repository has one; the honest `not-analyzed` when it does not. */
+export const measureBenchmark = (root: string, config: DocBridgeConfigV1, index: DocBridgeIndexV1): DoctorBenchmark => {
+  const suite = config.retrieval?.benchmark?.suite ?? DEFAULT_RETRIEVAL_SUITE
+  const suitePath = resolve(root, suite)
+  if (!existsSync(suitePath)) return { status: 'not-analyzed', suite, reason: `No retrieval suite at ${suite}` }
+  if (!index.projection) return { status: 'not-analyzed', suite, reason: 'The index carries no retrieval projection. Run: ak-docs index' }
+  try {
+    const parsed = parseRetrievalSuite(JSON.parse(readFileSync(suitePath, 'utf8')) as unknown)
+    const result = runRetrievalBench({ index, suite: parsed })
+    return {
+      status: 'measured',
+      suite,
+      caseCount: result.metrics.caseCount,
+      hitAt1: result.metrics.hitAt1,
+      hitAt3: result.metrics.hitAt3,
+      meanReciprocalRank: result.metrics.meanReciprocalRank,
+    }
+  } catch (error) {
+    return { status: 'not-analyzed', suite, reason: `The retrieval suite could not be run: ${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
 const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
   const issues: DoctorIssue[] = []
 
@@ -133,6 +292,47 @@ const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
     })
   }
 
+  const { reachability, connectivity, benchmark } = coverage
+  if (reachability.pct < A_GRADE_REQUIREMENTS.reachabilityPct) {
+    issues.push({
+      severity: 'warn',
+      code: 'documents-unreachable',
+      message: `${reachability.documentsTotal - reachability.documentsReachable} of ${reachability.documentsTotal} documents are not in the retrieval projection (${reachability.pct}% reachable).`,
+      action: 'ak-docs index',
+    })
+  }
+  if (connectivity.undocumentedAreas.length) {
+    issues.push({
+      severity: 'info',
+      code: 'areas-undocumented',
+      message: `${connectivity.areasTotal - connectivity.areasDocumented} of ${connectivity.areasTotal} areas have no document that covers or mentions them.`,
+      action: 'ak-docs check --json --format finding',
+    })
+  }
+  if (connectivity.unlinkedDocuments.length) {
+    issues.push({
+      severity: 'info',
+      code: 'documents-unlinked',
+      message: `${connectivity.documentsTotal - connectivity.documentsLinked} of ${connectivity.documentsTotal} documents have no edge into code.`,
+      action: 'ak-docs audit documentation',
+    })
+  }
+  if (benchmark.status === 'not-analyzed') {
+    issues.push({
+      severity: 'info',
+      code: 'benchmark-not-analyzed',
+      message: benchmark.reason,
+      action: `ak-docs bench retrieval ${benchmark.suite}`,
+    })
+  } else if (benchmark.hitAt3 < A_GRADE_REQUIREMENTS.benchmarkHitAt3) {
+    issues.push({
+      severity: 'warn',
+      code: 'benchmark-below-target',
+      message: `Retrieval hit@3 is ${(benchmark.hitAt3 * 100).toFixed(1)}% over ${benchmark.caseCount} case(s); an A requires ${A_GRADE_REQUIREMENTS.benchmarkHitAt3 * 100}%.`,
+      action: `ak-docs bench retrieval ${benchmark.suite} --text`,
+    })
+  }
+
   return issues
 }
 
@@ -166,11 +366,14 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   let index: DocBridgeIndexV1 | undefined
   let hasIndex = true
   let freshnessOk = false
-  let freshnessMessage = 'Index is fresh'
+  let freshnessMessage: string
+
+  // One discovery serves both the freshness rebuild and the reachability denominator.
+  const snapshot = discoverRepository({ root, config })
 
   try {
     index = loadDocBridgeIndex(root, config)
-    const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash
+    const next = buildDocBridgeIndex({ root, config, write: false, snapshot }).index.contentHash
     freshnessOk = index.contentHash === next
     freshnessMessage = freshnessOk ? 'Index is fresh' : 'Index is stale. Run: ak-docs index'
   } catch (error) {
@@ -178,7 +381,7 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
       hasIndex = false
       freshnessOk = false
       freshnessMessage = error.message
-      index = buildDocBridgeIndex({ root, config, write: false }).index
+      index = buildDocBridgeIndex({ root, config, write: false, snapshot }).index
     } else {
       throw error
     }
@@ -191,8 +394,6 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
 
   const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
-  const expectedAgentDocs = agentDocPaths(index)
-  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
 
   const corpusDocs = scanAgentCorpus(root, config).filter(
     (doc) => doc.path !== config.corpus.agent.index,
@@ -201,6 +402,9 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   const gates = runGates(root, config)
 
   const coverage: DoctorCoverage = {
+    reachability: measureReachability(snapshot, index),
+    connectivity: measureConnectivity(index),
+    benchmark: measureBenchmark(root, config, index),
     packages: {
       total: ownership.length,
       withAgentDoc: ownership.length - missingAgentDoc.length,
@@ -223,14 +427,16 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
 
   const issues = buildIssues(coverage)
   const score = computeScore(coverage)
+  const { grade, grading } = gradeFor(score, coverage)
   const nextActions = buildNextActions(issues, coverage)
 
   const report: DoctorReport = {
     ok: issues.every((issue) => issue.severity !== 'error') && gates.ok,
     score,
-    grade: gradeForScore(score),
+    grade,
+    grading,
     coverage,
-    badge: { handoffPct: 0, bridgePct: 0, score, grade: gradeForScore(score), packages: 0 },
+    badge: { handoffPct: 0, bridgePct: 0, score, grade, packages: 0 },
     issues,
     nextActions,
   }
@@ -261,8 +467,21 @@ export const formatDoctorText = (report: DoctorReport): string[] => {
     `  Index freshness: ${coverage.freshness.ok ? 'fresh' : 'stale or missing'}`,
     `  Gates:           ${coverage.gates.results.filter((g) => g.ok).length}/${coverage.gates.results.length} passing`,
     `  Badge:           handoff ${report.badge.handoffPct}% · bridge ${report.badge.bridgePct}%`,
+    '',
+    'Retrieval',
+    `  Reachability:    ${coverage.reachability.documentsReachable}/${coverage.reachability.documentsTotal} documents in the retrieval projection (${coverage.reachability.pct}%)`,
+    `  Connectivity:    ${coverage.connectivity.areasDocumented}/${coverage.connectivity.areasTotal} areas documented · ${coverage.connectivity.documentsLinked}/${coverage.connectivity.documentsTotal} documents link to code (${coverage.connectivity.pct}%)`,
+    `  Benchmark:       ${
+      coverage.benchmark.status === 'measured'
+        ? `hit@3 ${(coverage.benchmark.hitAt3 * 100).toFixed(1)}% · hit@1 ${(coverage.benchmark.hitAt1 * 100).toFixed(1)}% over ${coverage.benchmark.caseCount} case(s) (${coverage.benchmark.suite})`
+        : `not-analyzed — ${coverage.benchmark.reason}`
+    }`,
   ]
 
+  if (report.grading.unmet.length) {
+    lines.push('', `Grade ${report.grade}: an A requires`, ...report.grading.unmet.map((reason) => `  • ${reason}`))
+  }
+
   if (coverage.packages.missingHumanDoc.length) {
     lines.push('', 'Missing humanDoc (bridge gap)', ...coverage.packages.missingHumanDoc.map((id) => `  • ${id}`))
   }
@@ -283,4 +502,4 @@ export const formatDoctorText = (report: DoctorReport): string[] => {
 
   lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
   return lines
-}
+}

package/src/enrich/approvals.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { PeerMissingError, importPeer } from '../intelligence/peers.js'
+
+/**
+ * Approvals through the ecosystem gate.
+ *
+ * `createApprovalGate` from `@agentskit/core/hitl` is the contract every AgentsKit surface uses
+ * to pause at a decision point and record what a person decided. Doc Bridge records its
+ * approvals through it — the enrichment overlay's, and `ak-docs fix approve`'s — so the CLI,
+ * MCP and a rendered review page share one record rather than three ways of writing "approved".
+ *
+ * The store is a directory of JSON files, one per approval, because the repository is the only
+ * persistence Doc Bridge has. The gate contract is mirrored here for the same reason every other
+ * ecosystem contract is: `@agentskit/core` is an optional peer, and the real `createApprovalGate`
+ * is used through `importPeer` when it is installed. A test runs both over the same store and
+ * asserts the same records.
+ */
+
+export type ApprovalDecision = 'approved' | 'rejected'
+
+export type Approval<TPayload = unknown> = {
+  id: string
+  name: string
+  payload: TPayload
+  status: 'pending' | ApprovalDecision | 'cancelled'
+  createdAt: string
+  decidedAt?: string
+  decisionMetadata?: Record<string, unknown>
+}
+
+export type ApprovalStore = {
+  put: <T>(approval: Approval<T>) => Promise<void>
+  get: <T>(id: string) => Promise<Approval<T> | null>
+  patch: <T>(id: string, update: Partial<Approval<T>>) => Promise<Approval<T> | null>
+}
+
+export type RequestApprovalInput<TPayload> = { name: string; payload: TPayload; id: string }
+
+export type ApprovalGate<TPayload = unknown> = {
+  request: (input: RequestApprovalInput<TPayload>) => Promise<Approval<TPayload>>
+  await: (id: string, options?: { timeoutMs?: number; pollMs?: number; signal?: AbortSignal }) => Promise<Approval<TPayload>>
+  decide: (id: string, decision: ApprovalDecision, metadata?: Record<string, unknown>) => Promise<Approval<TPayload>>
+  cancel: (id: string) => Promise<Approval<TPayload>>
+}
+
+export const APPROVALS_DIR = '.doc-bridge/approvals'
+export const ENRICHMENT_APPROVAL_GATE = 'doc-bridge.enrichment'
+export const FIX_APPROVAL_GATE = 'doc-bridge.fix'
+
+export const approvalsDir = (root: string): string => join(resolve(root), APPROVALS_DIR)
+
+/** An approval id is a hash; anything else would be a path. */
+const safeId = (id: string): string => {
+  if (!/^[a-f0-9]{16,64}$/.test(id)) throw new Error(`Approval ids are content hashes; received "${id}".`)
+  return id
+}
+
+/** The id an enrichment approval binds to: the proposal and the exact content it was made about. */
+export const enrichmentApprovalId = (proposalId: string, targetContentHash: string): string => sha256NormalizedV1({ proposalId, targetContentHash })
+
+/** The id a fix approval binds to: the proposal id and the hash of its exact content. */
+export const fixApprovalId = (proposalId: string, proposalHash: string): string => sha256NormalizedV1({ proposalId, proposalHash })
+
+export const createFileApprovalStore = (dir: string): ApprovalStore => {
+  const pathFor = (id: string): string => join(dir, `${safeId(id)}.json`)
+  const write = (approval: Approval): void => {
+    mkdirSync(dir, { recursive: true })
+    const path = pathFor(approval.id)
+    const temporary = `${path}.tmp-${process.pid}`
+    writeFileSync(temporary, `${JSON.stringify(approval, null, 2)}\n`, 'utf8')
+    renameSync(temporary, path)
+  }
+  const read = (id: string): Approval | null => {
+    const path = pathFor(id)
+    if (!existsSync(path)) return null
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as Approval
+    } catch {
+      return null
+    }
+  }
+  return {
+    async put<T>(approval: Approval<T>): Promise<void> {
+      write(approval as Approval)
+    },
+    async get<T>(id: string): Promise<Approval<T> | null> {
+      return read(id) as Approval<T> | null
+    },
+    async patch<T>(id: string, update: Partial<Approval<T>>): Promise<Approval<T> | null> {
+      const current = read(id)
+      if (!current) return null
+      const next = { ...current, ...update } as Approval
+      write(next)
+      return next as Approval<T>
+    },
+  }
+}
+
+/** Every approval in the store, by id. For a reviewer listing what is waiting. */
+export const listApprovals = (dir: string): Approval[] => {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((name) => /^[a-f0-9]{16,64}\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      try {
+        return [JSON.parse(readFileSync(join(dir, name), 'utf8')) as Approval]
+      } catch {
+        return []
+      }
+    })
+}
+
+/** The mirror of `createApprovalGate`: create-or-load, poll, patch. */
+export const createApprovalGateMirror = <TPayload = unknown>(store: ApprovalStore): ApprovalGate<TPayload> => {
+  const load = async (id: string): Promise<Approval<TPayload>> => {
+    const approval = await store.get<TPayload>(id)
+    if (!approval) throw new Error(`Unknown approval "${id}".`)
+    return approval
+  }
+  return {
+    async request(input) {
+      const existing = await store.get<TPayload>(input.id)
+      if (existing) return existing
+      const approval: Approval<TPayload> = { id: input.id, name: input.name, payload: input.payload, status: 'pending', createdAt: new Date().toISOString() }
+      await store.put(approval)
+      return approval
+    },
+    async await(id, options = {}) {
+      const pollMs = options.pollMs ?? 500
+      const started = Date.now()
+      for (;;) {
+        const approval = await load(id)
+        if (approval.status !== 'pending') return approval
+        if (options.signal?.aborted) throw new Error(`Approval "${id}" wait aborted.`)
+        if (options.timeoutMs !== undefined && Date.now() - started >= options.timeoutMs) throw new Error(`Approval "${id}" timed out.`)
+        await new Promise((resolveWait) => setTimeout(resolveWait, pollMs))
+      }
+    },
+    async decide(id, decision, metadata) {
+      const updated = await store.patch<TPayload>(id, { status: decision, decidedAt: new Date().toISOString(), ...(metadata ? { decisionMetadata: metadata } : {}) })
+      if (!updated) throw new Error(`Unknown approval "${id}".`)
+      return updated
+    },
+    async cancel(id) {
+      const updated = await store.patch<TPayload>(id, { status: 'cancelled', decidedAt: new Date().toISOString() })
+      if (!updated) throw new Error(`Unknown approval "${id}".`)
+      return updated
+    },
+  }
+}
+
+type CoreHitl = { createApprovalGate: <T>(store: ApprovalStore) => ApprovalGate<T> }
+
+/**
+ * The gate over a store: the ecosystem's when the peer is installed, the mirror otherwise.
+ *
+ * Both write the same records to the same files, which is the point — a record written by one
+ * is read by the other, and by any AgentsKit surface that opens the same store.
+ */
+export const loadApprovalGate = async <TPayload = unknown>(store: ApprovalStore): Promise<{ readonly gate: ApprovalGate<TPayload>; readonly source: 'ecosystem' | 'mirror' }> => {
+  try {
+    const core = await importPeer<CoreHitl>('@agentskit/core/hitl')
+    if (typeof core.createApprovalGate === 'function') return { gate: core.createApprovalGate<TPayload>(store), source: 'ecosystem' }
+  } catch (error) {
+    if (!(error instanceof PeerMissingError)) throw error
+  }
+  return { gate: createApprovalGateMirror<TPayload>(store), source: 'mirror' }
+}
+
+export type RecordedApproval = { readonly approval: Approval; readonly source: 'ecosystem' | 'mirror' }
+
+/**
+ * Record a decision a person already made — the shape `ak-docs fix approve` needs: request
+ * (idempotent, so a re-run finds the same record) then decide, in one call.
+ */
+export const recordApproval = async (
+  root: string,
+  input: { readonly id: string; readonly name: string; readonly payload: unknown; readonly decision: ApprovalDecision; readonly by: string; readonly reason?: string },
+): Promise<RecordedApproval> => {
+  const store = createFileApprovalStore(approvalsDir(root))
+  const { gate, source } = await loadApprovalGate(store)
+  const existing = await gate.request({ id: input.id, name: input.name, payload: input.payload })
+  if (existing.status !== 'pending') throw new Error(`Approval ${input.id} was already ${existing.status}.`)
+  const approval = await gate.decide(input.id, input.decision, { by: input.by, ...(input.reason ? { reason: input.reason } : {}) })
+  return { approval, source }
+}

package/src/enrich/cache.ts

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { z } from 'zod'
+
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import type { EnrichmentTask } from './context-pack.js'
+import { enrichmentCacheDir } from './overlay.js'
+
+/**
+ * The persistent enrichment cache.
+ *
+ * The old deterministic cache was an in-process `Map`: it saved a second call inside one
+ * process and nothing across two. This one is keyed on everything that could change an answer —
+ * the task, the agent identity and version, the prompt version, and the pack hash, which covers
+ * the target and every neighbour by content hash — and lives under `.doc-bridge/enrich/cache/`,
+ * so an unchanged repository makes zero agent calls and a one-document change re-runs only the
+ * packs whose hash moved. An empty answer is cached like any other: "the agent had nothing to
+ * say about this" is an answer, and asking again costs the same.
+ */
+
+export type EnrichmentCacheKeyInput = {
+  readonly task: EnrichmentTask
+  readonly agentId: string
+  readonly agentVersion: string
+  readonly promptVersion: string
+  readonly packHash: string
+}
+
+export const enrichmentCacheKey = (input: EnrichmentCacheKeyInput): string =>
+  sha256NormalizedV1({ task: input.task, agentId: input.agentId, agentVersion: input.agentVersion, promptVersion: input.promptVersion, packHash: input.packHash })
+
+const CacheEntrySchema = z
+  .object({
+    type: z.literal('enrichment-cache-entry'),
+    key: z.string().regex(/^[a-f0-9]{64}$/),
+    task: z.enum(['curate', 'review', 'adjudicate']),
+    agentId: z.string().min(1).max(256),
+    agentVersion: z.string().min(1).max(64),
+    promptVersion: z.string().min(1).max(64),
+    packHash: z.string().regex(/^[a-f0-9]{64}$/),
+    proposals: z.array(z.unknown()).max(1_024),
+  })
+  .strict()
+export type EnrichmentCacheEntry = z.infer<typeof CacheEntrySchema>
+
+export type EnrichmentCache = {
+  readonly read: (input: EnrichmentCacheKeyInput) => readonly unknown[] | undefined
+  readonly write: (input: EnrichmentCacheKeyInput, proposals: readonly unknown[]) => string
+}
+
+/** A file-backed cache under the enrich directory. A read never writes; a corrupt entry is a miss. */
+export const createEnrichmentCache = (root: string): EnrichmentCache => {
+  const dir = enrichmentCacheDir(root)
+  const pathFor = (key: string): string => join(dir, `${key}.json`)
+  return {
+    read: (input) => {
+      const key = enrichmentCacheKey(input)
+      const path = pathFor(key)
+      if (!existsSync(path)) return undefined
+      try {
+        const entry = CacheEntrySchema.parse(JSON.parse(readFileSync(path, 'utf8')) as unknown)
+        // A file renamed into place under another key is not that key's answer.
+        return entry.key === key && entry.packHash === input.packHash && entry.agentId === input.agentId ? entry.proposals : undefined
+      } catch {
+        return undefined
+      }
+    },
+    write: (input, proposals) => {
+      const key = enrichmentCacheKey(input)
+      mkdirSync(dir, { recursive: true })
+      const entry: EnrichmentCacheEntry = { type: 'enrichment-cache-entry', key, ...input, proposals: [...proposals] }
+      const path = pathFor(key)
+      const temporary = `${path}.tmp-${process.pid}`
+      writeFileSync(temporary, `${JSON.stringify(entry, null, 2)}\n`, 'utf8')
+      renameSync(temporary, path)
+      return path
+    },
+  }
+}
+
+/** An in-memory cache with the same contract, for callers that must not touch disk. */
+export const createMemoryEnrichmentCache = (): EnrichmentCache => {
+  const entries = new Map<string, readonly unknown[]>()
+  return {
+    read: (input) => entries.get(enrichmentCacheKey(input)),
+    write: (input, proposals) => {
+      const key = enrichmentCacheKey(input)
+      entries.set(key, [...proposals])
+      return key
+    },
+  }
+}