@agentskit/doc-bridge 1.10.0 → 1.11.0

package/docs/spec/config-v1.md

@@ -343,6 +343,7 @@ type GatesConfig = {
 
 type GateId =
   | 'index-freshness'
+  | 'index-reproducible'           // opt-in; in no preset
   | 'human-guide-links'
   | 'link-rot'                    // reserved; emits a diagnostic and is not executed
   | 'okf-type'
@@ -358,7 +359,7 @@ type GateId =
 | `standard` | + `human-guide-links` in v1 |
 | `strict` | + `okf-type` in v1 |
 
-Implemented gates include `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`, and the opt-in `documentation-standard-v1`. For v1 compatibility, `link-rot`, `routing-currency`, and `bootstrap-size` remain accepted as reserved IDs; including one emits `AK_DOCS_RESERVED_GATE` and does not claim that the gate ran. Unknown IDs are rejected.
+Implemented gates include `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`, and the opt-in `index-reproducible` and `documentation-standard-v1`. For v1 compatibility, `link-rot`, `routing-currency`, and `bootstrap-size` remain accepted as reserved IDs; including one emits `AK_DOCS_RESERVED_GATE` and does not claim that the gate ran. Unknown IDs are rejected.
 
 ### Structural vs style validation
 
@@ -367,10 +368,31 @@ These gates are deterministic lint checks, not editorial grading:
 | Gate | Kind | What it proves |
 |------|------|----------------|
 | `index-freshness` | structural | Generated index matches current docs/config |
+| `index-reproducible` | structural | Every indexed path is committed, so a clean checkout rebuilds the same index |
 | `human-guide-links` | structural | Local `humanDoc` links resolve through configured human-doc adapters |
 | `okf-type` | OKF lint | Agent docs have required `type:` frontmatter when strict/required |
 | `docs-style` | style lint | Opt-in deterministic profile checks for title, purpose, audience, examples, owner/source, task orientation, and stale wording |
 
+### Why `index-reproducible` is opt-in
+
+A scan walks what is on disk and has no reason to consult `.gitignore`, so a generated module or
+document joins the corpus on a machine that has built and leaves it on one that has not. That is
+harmless while the index is regenerated on every run, and a defect the moment the index is
+committed for a gate to verify: two checkouts of the same commit produce different artifacts,
+`index-freshness` reports staleness that nothing caused, and regenerating cannot fix it because the
+next machine disagrees in the other direction.
+
+`index-reproducible` asks Git which of the indexed paths it ignores, and names each one with the
+rule that matched (`apps/docs-next/.gitignore:13:lib/ask-context.ts`) so the fix is one lookup
+away: add the path to `safety.exclude`. It reports success, not failure, when the index is not
+committed or the project is not a Git checkout — there is nothing to reproduce in either case. A
+file that is both tracked and matched by an ignore rule is not flagged; being committed is the
+point.
+
+It is in no preset, because enabling it for every consumer would fail gates that pass for good
+reasons. `ak-docs index` and `ak-docs doctor` report the same finding unconditionally — as a
+diagnostic and a `warn` issue — so a repository learns about it before deciding to enforce it.
+
 `docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.
 
 ---

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -127,7 +127,7 @@
     "@agentskit/ink": "0.10.9",
     "@agentskit/react": "0.8.3",
     "@anthropic-ai/mcpb": "2.1.2",
-    "@changesets/cli": "^3.0.1",
+    "@changesets/cli": "^3.0.3",
     "@lhci/cli": "^0.15.1",
     "@playwright/test": "1.63.0",
     "@tailwindcss/postcss": "4.3.3",

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from 'node:child_process'
 import { isAbsolute } from 'node:path'
 
-const VERSION = '1.10.0'
+const VERSION = '1.11.0'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]

package/src/cli/program.ts

@@ -99,6 +99,7 @@ import { independentlyAdjudicateStudyLedger, persistIndependentlyAdjudicatedLedg
 import { formatStudyProviderCliText, parseStudyProviderCliConfig } from '../study/provider-cli.js'
 import { calculateStudyMetrics, formatStudyMetricsText } from '../study/metrics.js'
 import { formatStudyVerificationText, parseStudyVerificationBinding } from '../study/verification.js'
+import { checkIndexReproducibility } from '../discovery/reproducibility.js'
 
 type Command =
   | 'help'
@@ -469,7 +470,11 @@ const loadProject = (configPath?: string) => {
   return { config, configPath: path, root }
 }
 
-const indexDiagnostics = (config: DocBridgeConfigV1, result: ReturnType<typeof buildDocBridgeIndex>): string[] => {
+const indexDiagnostics = (
+  root: string,
+  config: DocBridgeConfigV1,
+  result: ReturnType<typeof buildDocBridgeIndex>,
+): string[] => {
   const diagnostics: string[] = []
   const onlyDoc = result.index.knowledge.length === 1 ? result.index.knowledge[0] : undefined
   if (onlyDoc?.path === config.corpus.agent.index) {
@@ -484,6 +489,22 @@ const indexDiagnostics = (config: DocBridgeConfigV1, result: ReturnType<typeof b
       'No ownership handoffs yet. Add routing.options.ownership, package frontmatter (package + editRoot), or a monorepo plugin.',
     )
   }
+  /*
+   * Said at write time, because this is the moment the unreproducible artifact is created and the
+   * only moment the operator can see what their machine had that another will not.
+   */
+  const reproducibility = checkIndexReproducibility(
+    root,
+    config.index?.outFile ?? '.doc-bridge/index.json',
+    result.index.knowledge.map((entry) => entry.path),
+  )
+  if (reproducibility.ignored.length > 0) {
+    const sample = reproducibility.ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    diagnostics.push(
+      `${reproducibility.ignored.length} indexed path(s) are ignored by Git: ${sample.join(', ')}${reproducibility.ignored.length > sample.length ? `, and ${reproducibility.ignored.length - sample.length} more` : ''}.`,
+      'A clean checkout will not have them, so it builds a different index. Add them to safety.exclude in doc-bridge.config.json.',
+    )
+  }
   return diagnostics
 }
 
@@ -1749,7 +1770,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         })
       }
       const result = buildDocBridgeIndex({ root, config })
-      const diagnostics = indexDiagnostics(config, result)
+      const diagnostics = indexDiagnostics(root, config, result)
       const handoffCount = Object.keys(result.index.handoffs ?? {}).length
       writeJson({
         ok: true,

package/src/config/schema.ts

@@ -122,6 +122,7 @@ export const GatesConfigSchema = z
       .array(
         z.enum([
           'index-freshness',
+          'index-reproducible',
           'human-guide-links',
           'link-rot',
           'okf-type',
@@ -137,6 +138,7 @@ export const GatesConfigSchema = z
       .array(
         z.enum([
           'index-freshness',
+          'index-reproducible',
           'human-guide-links',
           'link-rot',
           'okf-type',

package/src/discovery/reproducibility.ts

@@ -0,0 +1,109 @@
+/**
+ * Whether a committed index could have been produced by a clean checkout.
+ *
+ * The recommended setup commits `.doc-bridge/index.json` so a gate can verify it, and that only
+ * works while the index is a function of committed content. A scan has no reason to know about
+ * `.gitignore` — it walks what is on disk — so a generated module or document silently joins the
+ * corpus on any machine that has built, and silently leaves it on one that has not. The index then
+ * disagrees with itself between two checkouts of the same commit, `index-freshness` reports an
+ * artifact that nothing invalidated, and regenerating cannot fix it because the next machine
+ * disagrees in the other direction.
+ *
+ * Dogfooding found this the expensive way: a 25-package monorepo whose gate passed locally and
+ * failed in CI because `pnpm lint` had generated one `.ts` file into the corpus before the index
+ * was written. The scan cannot guess which files are generated, but Git already knows, so the
+ * check is: of the paths this index carries, which ones does Git ignore?
+ *
+ * It only applies when the index is itself tracked. A consumer who regenerates on every run has
+ * nothing to reproduce, and reporting generated files to them would be noise.
+ */
+
+import { execFileSync } from 'node:child_process'
+
+export type IgnoredIndexEntry = {
+  readonly path: string
+  /** The ignore rule that matched, as `.gitignore:12:pattern`, so the fix is one lookup away. */
+  readonly rule: string
+}
+
+export type IndexReproducibility = {
+  /**
+   * Whether the question was answerable. False outside a Git checkout, when Git is unavailable, or
+   * when the index is not tracked — in all three cases `ignored` is empty and means nothing.
+   */
+  readonly checked: boolean
+  /** Why the check did not run, for a caller that wants to say so. */
+  readonly skipped?: 'no-git' | 'index-untracked'
+  /** Indexed paths that Git ignores, in path order. */
+  readonly ignored: readonly IgnoredIndexEntry[]
+}
+
+const NOT_CHECKED = (skipped: 'no-git' | 'index-untracked'): IndexReproducibility => ({
+  checked: false,
+  skipped,
+  ignored: [],
+})
+
+/**
+ * `undefined` means the command did not answer.
+ *
+ * `allowExit1` is for `check-ignore` alone, which exits 1 when nothing matched — the common answer
+ * rather than a failure, and it still writes whatever did match to stdout. The probes must not
+ * share that tolerance: `ls-files --error-unmatch` exits 1 precisely to say "not tracked", and
+ * reading that as success made the untracked case look checked.
+ */
+const git = (
+  root: string,
+  args: readonly string[],
+  options: { readonly input?: string; readonly allowExit1?: boolean } = {},
+): string | undefined => {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+      ...(options.input === undefined ? {} : { input: options.input }),
+    })
+  } catch (error) {
+    const status = (error as { status?: number }).status
+    if (options.allowExit1 && status === 1) return (error as { stdout?: string }).stdout ?? ''
+    return undefined
+  }
+}
+
+/**
+ * The paths a committed index carries that Git ignores.
+ *
+ * `git check-ignore` consults the index by default, so a tracked file that also matches an ignore
+ * pattern is correctly reported as not ignored — being committed is the whole point. A test pins
+ * that behaviour rather than trusting it.
+ */
+export const checkIndexReproducibility = (
+  root: string,
+  indexPath: string,
+  paths: readonly string[],
+): IndexReproducibility => {
+  if (git(root, ['rev-parse', '--is-inside-work-tree']) === undefined) return NOT_CHECKED('no-git')
+  if (git(root, ['ls-files', '--error-unmatch', '--', indexPath]) === undefined) {
+    return NOT_CHECKED('index-untracked')
+  }
+  if (paths.length === 0) return { checked: true, ignored: [] }
+
+  const unique = [...new Set(paths)].sort()
+  const output = git(root, ['check-ignore', '--verbose', '-z', '--stdin'], {
+    input: `${unique.join('\0')}\0`,
+    allowExit1: true,
+  })
+  if (output === undefined) return NOT_CHECKED('no-git')
+
+  /* `-z --verbose` emits four NUL-terminated fields per match: source, line, pattern, path. */
+  const fields = output.split('\0')
+  const ignored: IgnoredIndexEntry[] = []
+  for (let index = 0; index + 3 < fields.length; index += 4) {
+    const [source, line, pattern, path] = [fields[index], fields[index + 1], fields[index + 2], fields[index + 3]]
+    if (!path) continue
+    ignored.push({ path, rule: `${source ?? '?'}:${line ?? '?'}:${pattern ?? '?'}` })
+  }
+  return { checked: true, ignored: ignored.sort((left, right) => left.path.localeCompare(right.path)) }
+}

package/src/doctor/run-doctor.ts

@@ -8,6 +8,7 @@ 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 { checkIndexReproducibility, type IndexReproducibility } from '../discovery/reproducibility.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import type { DiscoverySnapshotV1 } from '../schemas/knowledge.js'
 import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
@@ -104,6 +105,8 @@ export type DoctorCoverage = {
     readonly hasIndex: boolean
   }
   readonly gates: GateRunResult
+  /** Whether a clean checkout would rebuild this index, or whether generated files leak into it. */
+  readonly reproducibility: IndexReproducibility
 }
 
 export type DoctorReport = {
@@ -265,6 +268,22 @@ const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
     })
   }
 
+  /*
+   * A warning, not an error: the index is not wrong, it is unreproducible, and every reader of it
+   * on another machine is the one who finds out. The fix belongs to the repository's
+   * `safety.exclude`, so the message names the rule that matched and lets the operator decide.
+   */
+  const { ignored } = coverage.reproducibility
+  if (ignored.length > 0) {
+    const sample = ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    issues.push({
+      severity: 'warn',
+      code: 'index-not-reproducible',
+      message: `${ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index: ${sample.join(', ')}${ignored.length > sample.length ? `, and ${ignored.length - sample.length} more` : ''}.`,
+      action: 'edit doc-bridge.config.json  # add the generated paths to safety.exclude',
+    })
+  }
+
   for (const id of coverage.packages.missingAgentDoc) {
     issues.push({
       severity: 'warn',
@@ -423,6 +442,11 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
       hasIndex,
     },
     gates,
+    reproducibility: checkIndexReproducibility(
+      root,
+      config.index?.outFile ?? '.doc-bridge/index.json',
+      index.knowledge.map((entry) => entry.path),
+    ),
   }
 
   const issues = buildIssues(coverage)

package/src/gates/run-gates.ts

@@ -9,9 +9,11 @@ import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
 import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import { checkIndexReproducibility } from '../discovery/reproducibility.js'
 
 export type GateId =
   | 'index-freshness'
+  | 'index-reproducible'
   | 'human-guide-links'
   | 'okf-type'
   | 'docs-style'
@@ -54,6 +56,48 @@ export const runGate = (
   if (id === 'human-guide-links') return runHumanGuideLinksGate(root, config)
   if (id === 'okf-type') return runOkfTypeGate(root, config)
   if (id === 'docs-style') return runDocsStyleGate(root, config)
+  if (id === 'index-reproducible') {
+    /*
+     * Opt-in, and in no preset: a repository that regenerates the index on every run has nothing
+     * to enforce, and turning this on for everyone would fail gates that were passing for good
+     * reasons. `gates.include: ['index-reproducible']` is how a repository that commits the index
+     * says it wants the guarantee enforced rather than merely reported.
+     */
+    let index
+    try {
+      index = loadDocBridgeIndex(root, config)
+    } catch (error) {
+      if (error instanceof IndexNotFoundError) return { id, ok: false, message: error.message }
+      throw error
+    }
+    const result = checkIndexReproducibility(
+      root,
+      config.index?.outFile ?? '.doc-bridge/index.json',
+      index.knowledge.map((entry) => entry.path),
+    )
+    if (!result.checked) {
+      return {
+        id,
+        ok: true,
+        message:
+          result.skipped === 'index-untracked'
+            ? 'Index is not committed, so nothing has to reproduce it'
+            : 'Not a Git checkout; reproducibility was not checked',
+      }
+    }
+    if (result.ignored.length === 0) {
+      return { id, ok: true, message: 'Every indexed path is committed' }
+    }
+    const sample = result.ignored.slice(0, 5).map((entry) => `${entry.path} (${entry.rule})`)
+    return {
+      id,
+      ok: false,
+      message: `${result.ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index. Add them to safety.exclude.`,
+      expected: 'every indexed path is committed',
+      actual: sample.join(', '),
+    }
+  }
+
   if (id !== 'index-freshness') throw new Error(`Unsupported gate "${id}"`)
 
   let current: string

package/src/index.ts

@@ -98,12 +98,18 @@ export {
   repositoryInputs,
   type RepositoryInputsV1,
 } from './index-builder/project-corpus.js'
+export {
+  checkIndexReproducibility,
+  type IgnoredIndexEntry,
+  type IndexReproducibility,
+} from './discovery/reproducibility.js'
 export {
   DOCUMENT_BODY_LIMIT,
   EMPTY_OVERLAY_HASH,
   RETRIEVAL_PROJECTION_VERSION,
   projectRetrievalIndex,
   relationConfidence,
+  snapshotObservationHash,
   toKnowledgeEntry,
   weakerConfidence,
   type CuratedDocument,

package/src/retrieval/project.ts

@@ -37,7 +37,7 @@ import { resolveSearchParams, resolveSearchWeights } from './weights.js'
  * from what the snapshot says about it rather than from what is on disk now.
  */
 
-export const RETRIEVAL_PROJECTION_VERSION = 1 as const
+export const RETRIEVAL_PROJECTION_VERSION = 2 as const
 
 /** Documentation body kept for search. Long enough to answer a question, short enough to ship. */
 export const DOCUMENT_BODY_LIMIT = 4_000
@@ -51,6 +51,31 @@ const MAX_SUMMARY = 400
 /** The overlay hash when there is no overlay: the hash of an empty accepted set. */
 export const EMPTY_OVERLAY_HASH = sha256NormalizedV1({ accepted: [] })
 
+/**
+ * What the snapshot observed, without the revision it observed it at.
+ *
+ * `snapshot.contentHash` seals the whole artifact, `sourceRevision` included — the commit SHA when
+ * the working tree is clean, a digest of the scanned files when it is not. That is right for an
+ * artifact whose job is to say what one revision looked like, and wrong as a projection input: the
+ * projection is a function of what was found, not of where it was found. Sealing the revision into
+ * it made an index that any commit invalidates without one thing it describes having changed — so
+ * an index committed to a repository was stale the moment it landed, because landing it is a
+ * commit, and a freshness gate could never pass twice.
+ *
+ * Entities and relations are the projection's whole input; the analyzer identity comes with them,
+ * because two analyzer versions that observe the same entities and relations have nothing left to
+ * disagree about, and one that observes different ones is caught by the entities.
+ */
+export const snapshotObservationHash = (
+  snapshot: Pick<DiscoverySnapshotV1, 'entities' | 'relations' | 'pipelineVersion' | 'analyzerVersions'>,
+): string =>
+  sha256NormalizedV1({
+    pipelineVersion: snapshot.pipelineVersion,
+    analyzerVersions: snapshot.analyzerVersions,
+    entities: snapshot.entities,
+    relations: snapshot.relations,
+  })
+
 const CONFIDENCE_RANK: Readonly<Record<Confidence, number>> = { observed: 0, declared: 1, fuzzy: 2, proposed: 3 }
 
 /** The weaker of two confidences: a chain is as trustworthy as its least trustworthy link. */
@@ -115,7 +140,7 @@ export type RetrievalOverlayInput = {
 }
 
 export type ProjectRetrievalOptions = {
-  readonly snapshot: Pick<DiscoverySnapshotV1, 'contentHash' | 'entities' | 'relations'>
+  readonly snapshot: Pick<DiscoverySnapshotV1, 'contentHash' | 'entities' | 'relations' | 'pipelineVersion' | 'analyzerVersions'>
   readonly config: DocBridgeConfigV1 | undefined
   readonly routes?: RetrievalRoutes
   readonly curated?: readonly CuratedDocument[]
@@ -459,13 +484,15 @@ export const projectRetrievalIndex = (options: ProjectRetrievalOptions): Retriev
     entries,
   }
   /*
-   * The hash is over the inputs, not the output: the projection is a function, so three equal
-   * input hashes mean an equal artifact, and a reader checking freshness compares three hashes
-   * instead of re-projecting.
+   * The hash is over the inputs, not the output: the projection is a function, so equal input
+   * hashes mean an equal artifact, and a reader checking freshness compares hashes instead of
+   * re-projecting. `snapshotHash` stays on the artifact as provenance — which snapshot this came
+   * from — but the seal uses the observation, so the same repository projects to the same hash
+   * whatever revision it was scanned at.
    */
   const contentHash = sha256NormalizedV1({
     projectionVersion: RETRIEVAL_PROJECTION_VERSION,
-    snapshotHash: base.snapshotHash,
+    observationHash: snapshotObservationHash(snapshot),
     overlayHash: base.overlayHash,
     configurationHash: base.configurationHash,
     lexiconVersion: base.lexiconVersion,

package/src/schemas/retrieval-index.ts

@@ -136,8 +136,13 @@ export const RetrievalIndexV1Schema = z
     schemaVersion: z.literal(RETRIEVAL_INDEX_SCHEMA_VERSION),
     contentHash: hash,
     contentHashAlgo: z.literal('sha256-normalized-v1'),
-    /** The three inputs the projection is a function of. Same three hashes, same projection. */
+    /**
+     * Which snapshot this was projected from. Provenance, not a seal input: it carries the
+     * snapshot's `sourceRevision`, and the projection is a function of what the snapshot observed
+     * rather than of the revision it was observed at.
+     */
     snapshotHash: hash,
+    /** The inputs the projection is a function of. Same hashes, same projection. */
     overlayHash: hash,
     configurationHash: hash,
     lexiconVersion: z.number().int().nonnegative().max(1_000),

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.10.0'
+export const PACKAGE_VERSION = '1.11.0'