@agentskit/doc-bridge 1.10.1 → 1.11.1

package/docs/agent-corpus/audit.md

@@ -0,0 +1,25 @@
+---
+type: module
+id: doc-bridge-audit
+editRoot: src/audit
+humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/audit
+validationPath: pnpm test && node bin/ak-docs.js audit documentation --json
+docbridge:
+  covers:
+    - area:src/audit
+---
+
+# Audit
+
+Owns deterministic documentation quality, coverage, and structural validation. Every finding maps to code evidence.
+
+`auditDocumentation` ingests a `DiscoverySnapshotV1`, declared snapshot, `ReconciliationReportV1`, and audit config,
+then produces a `DocumentationAuditReportV1` with findings categorized as quality, coverage, structure-gap, contradiction,
+stale, redundancy, generated-freshness, or limitation. It validates document metadata (owner, lifecycle, source-of-truth,
+validation-path), checks for title and example presence, verifies generated region integrity against stored hashes,
+detects exact content duplicates, and maps reconciliation diagnostics into audit findings. Coverage is measured against
+packages (or areas in single-package repositories). Generated documents receive freshness-boundary checking only;
+their semantic proof comes from their generation commands, not this audit.

package/docs/agent-corpus/bin.md

@@ -0,0 +1,26 @@
+---
+type: module
+id: doc-bridge-bin
+editRoot: bin
+humanDoc: /docs/spec/cli
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: bin
+validationPath: pnpm test && pnpm smoke:packaged
+docbridge:
+  covers:
+    - area:bin
+---
+
+# Entry points
+
+Owns the two executables `package.json` publishes, and nothing else. Both are deliberately thin: logic
+belongs in `src`, where it is typechecked and tested.
+
+`ak-docs.js` imports `runCli` from **`../dist/cli/program.js`** — the built output, not the source — and
+sets `process.exitCode` from what it returns, awaiting it when it is a promise. Running from `dist` is
+why `scripts/prepare.mjs` has to build on a git install; a change here that reaches into `src` would
+break the published package.
+
+`ak-verify.js` resolves the `@agentskit/harness` CLI through `import.meta.resolve` and spawns it as a
+child process with inherited stdio, so the harness owns its own output and exit code.

package/docs/agent-corpus/budget.md

@@ -0,0 +1,26 @@
+---
+type: module
+id: doc-bridge-budget
+editRoot: src/budget
+humanDoc: /docs/spec/config-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/budget
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/budget
+---
+
+# Budget
+
+Owns token counting and message trimming under a budget, mirroring `@agentskit/core` algorithms
+synchronously for MCP handlers.
+
+`compileBudget` drops oldest messages until the remainder fits a budget, keeping at least one
+recent message. The `approximateCounter` uses the four-characters-per-token rule and stays
+deterministic. `applyBudget` splits a payload into named sections, each costing one message,
+and drops sections front-to-back until the trimmed payload fits a token budget, reporting what
+was dropped and whether it all fit. Every call over the same payload and budget produces the
+same report.
+

package/docs/agent-corpus/config.md

@@ -0,0 +1,33 @@
+---
+type: module
+id: doc-bridge-config
+editRoot: src/config
+humanDoc: /docs/spec/config-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/config
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/config
+---
+
+# Config
+
+Owns finding, parsing, validating and defaulting the repository's configuration, and the enums every
+other area validates against.
+
+`loadConfig` walks up from a start directory for the first `doc-bridge.config.{ts,js,mjs,json}`, or a
+`package.json` carrying a `docBridge` key. A `.ts`/`.js` config is read as a **static object literal**
+through `parseStaticJsObject` — nothing is executed, so a config that computes its value at runtime
+will not load. `doc-bridge.config.yaml` is in the candidate list but rejected on purpose: the loader
+throws `YAML config is not supported yet`. Do not document YAML as a supported format.
+
+Input is validated by `DocBridgeConfigV1Schema`, then `applyConfigDefaults` fills what the caller left
+out — corpus `include`/`exclude`, `index.outFile` of `.doc-bridge/index.json`, `contentHash` of
+`sha256-normalized-v1`, the llms.txt and capabilities outputs, `gates.preset` of `minimal` and
+`rules.mode` of `default`.
+
+`schema.ts` is also where `RuleIdSchema` and the gate id enums live, so adding a gate or a rule means
+editing this area as well as the one that implements it. `resolveProjectRoot` climbs at most twelve
+levels and falls back to the directory it started from rather than failing.

package/docs/agent-corpus/federation.md

@@ -0,0 +1,25 @@
+---
+type: module
+id: doc-bridge-federation
+editRoot: src/federation
+humanDoc: /docs/spec/config-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/federation
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/federation
+---
+
+# Federation
+
+Owns loading external llms.txt sources, parsing chunks from remote and local markdown, scoring
+them against queries, and formatting ecosystem product blocks for federation.
+
+`loadFederatedChunks` fetches llms.txt sources from configuration, parses markdown sections into
+searchable chunks, and follows same-origin links to collect more content. `retrieveHybridChunks`
+merges local retrieval results and federated chunks, deduplicating by key and re-ranking by
+query relevance. `parseLlmsTxtLinks` extracts markdown links and bare URLs from prose. The
+ecosystem formatter generates a canonical markdown block for llms.txt sections across products.
+

package/docs/agent-corpus/findings.md

@@ -0,0 +1,25 @@
+---
+type: module
+id: doc-bridge-findings
+editRoot: src/findings
+humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/findings
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/findings
+---
+
+# Findings
+
+Owns normalizing internal diagnostics to the ecosystem `Finding` shape. Severity and confidence remain independent.
+
+`findingFromDiagnostic` and `findingsFromDiagnostics` convert `KnowledgeDiagnostic`, `RuleFinding`, and
+`DocumentationAuditFinding` into a canonical shape that Code Review, dashboards, and language-model integrations
+consume without their own parser. Internal severities (error, warn, info, off) map to ecosystem levels
+(high, medium, low, info); critical is never emitted, since documentation findings do not interrupt production.
+Confidence derives from finding status: confirmed and undocumented are high-confidence; conflicts and unresolved
+are medium; stale or unverified are low; not-analyzed is lowest. Each Finding carries evidence path and line,
+remediation text, and source diagnostic code for traceability.

package/docs/agent-corpus/fixes.md

@@ -0,0 +1,25 @@
+---
+type: module
+id: doc-bridge-fixes
+editRoot: src/fixes
+humanDoc: /docs/POSITIONING
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/fixes
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/fixes
+---
+
+# Fixes
+
+Owns proposing and applying fix proposals with approval gates and integrity verification.
+
+`createMarkdownLinkFixProposal` and `createArtifactNormalizationProposal` generate `FixProposalV1` instances
+from detected issues: broken markdown links and JSON formatting. A proposal captures the base revision, affected
+file hashes, unified diffs, and pre/postconditions. `approveFixProposal` binds approval identity and timestamp
+to a proposal; `applyFixProposal` verifies the proposal content matches its approval, checks that affected
+files have not changed, writes atomically to temp files, and renames into place, or rolls back all changes on
+failure. The proposal always remains advisory: applications require explicit human or policy approval before
+execution, never automatic.

package/docs/agent-corpus/lib.md

@@ -0,0 +1,29 @@
+---
+type: module
+id: doc-bridge-lib
+editRoot: src/lib
+humanDoc: /docs/POSITIONING
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/lib
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/lib
+---
+
+# Lib
+
+Owns the small shared helpers the rest of the tree depends on. Nothing here reaches back into a feature
+area, which is what keeps it importable from anywhere.
+
+`bounded-text.ts` caps reads at `MAX_DOCUMENT_BYTES` (4 MiB) per file and `MAX_CORPUS_BYTES` (64 MiB)
+per corpus, both overridable per call — the budget is enforced while reading, not checked afterwards.
+`static-js-literal.ts` exports `parseStaticJsObject`, which is how a `.ts`/`.js` config becomes an
+object without being executed; comment stripping is a step inside it, not its purpose.
+
+`fuzzy-match.ts` implements Jaro-Winkler mirrored from `@agentskit/core` rather than imported, so
+discovery stays synchronous and never loads an optional peer. `paths.ts` normalises to POSIX and checks
+containment within the project root; `walk.ts` traverses by extension; `glob-expand.ts` turns workspace
+globs into directories; `markdown.ts` reads frontmatter; `package-manager.ts` detects the package
+manager from lockfiles and builds the matching check commands.

package/docs/agent-corpus/metrics.md

@@ -0,0 +1,26 @@
+---
+type: module
+id: doc-bridge-metrics
+editRoot: src/metrics
+humanDoc: /docs/query
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/metrics
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/metrics
+---
+
+# Metrics
+
+Owns benchmark measurement for entity, relation, and finding precision and recall, and efficiency
+metrics for agent latency, response bytes, and tokens.
+
+`measureBenchmark` compares observations against a fixture of supported and excluded items,
+counts true positives, false positives and negatives per category, and reports regressions when
+precision or recall falls below thresholds. `measureAgentEfficiency` calculates hit rate, latency
+percentiles, and response compression ratio from query runs. `measureAgentTaskEfficiency` tracks
+per-task correctness and resource cost. `compareBenchmarkSnapshots` diffs two snapshots by
+classification state.
+

package/docs/agent-corpus/parity.md

@@ -0,0 +1,33 @@
+---
+type: module
+id: doc-bridge-parity
+editRoot: src/parity
+humanDoc: /docs/RELEASE
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/parity
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/parity
+---
+
+# Parity
+
+Owns detecting when public sentences have drifted from repository facts and reporting findings
+with remediation.
+
+A `PublicClaim` binds a sentence to a canonical value by naming where the value lives (`evidence`),
+how it appears in prose (`template`), and which surfaces must carry it. Evidence kinds are
+`package-field`, `artifact-field`, `artifact-sum`, `snapshot-count`, `doctor-metric`, and
+`cli-command`. The registry carries its own `contentHash` over everything but that field, so a claim cannot be
+edited without resealing it.
+`checkPublicParity` compares what public surfaces state against what the registry resolves, reporting
+`PARITY_STALE` when a surface states a moved value, `PARITY_MISSING` when a surface omits a claim,
+and `PARITY_CONTRADICTION` when two surfaces disagree.
+
+The eight claims are keyed by `claimId`: `study-token-reduction`, `study-token-pairs`,
+`study-completion-bridge`, `study-completion-baseline`, `study-latency-p95`, `study-executions`,
+`cli-parity-command` and `checked-in-package-version`. Six resolve from an artifact field, one sums a
+field across artifacts, and one runs a CLI command.
+

package/docs/agent-corpus/playbook.md

@@ -0,0 +1,22 @@
+---
+type: module
+id: doc-bridge-playbook
+editRoot: src/playbook
+humanDoc: /docs/playbook/doc-bridge-pattern
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/playbook
+validationPath: pnpm test && node bin/ak-docs.js index
+docbridge:
+  covers:
+    - area:src/playbook
+---
+
+# Playbook
+
+Owns the Doc Bridge Pattern playbook content and metadata. Exports `DOC_BRIDGE_PATTERN_META`
+with pattern id, title, slug, license (CC-BY-4.0), and links to the public playbook URL and
+npm package. `docBridgePatternMarkdown()` generates the pattern description — problem, solution
+with three artifacts (AgentHandoff, DocBridgeIndex, self-describe), four operational loops
+(act, bridge, learn, explain), MCP contract, CI gate, coverage metrics, and use-case guidance.
+`docBridgePatternPayload()` returns the complete pattern object for registration.

package/docs/agent-corpus/plugins.md

@@ -0,0 +1,23 @@
+---
+type: module
+id: doc-bridge-plugins
+editRoot: src/plugins
+humanDoc: /docs/spec/config-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/plugins
+validationPath: pnpm test && node bin/ak-docs.js index
+docbridge:
+  covers:
+    - area:src/plugins
+---
+
+# Plugins
+
+Owns the analyzer plugin contract and registry. `AnalyzerPluginManifestSchema` defines a plugin's
+identity, languages, frameworks, capabilities, and resource limits. `AnalyzerPluginOutputSchema`
+validates entities, relations, coverage, and diagnostics. `createAnalyzerRegistry` registers
+plugins and routes `analyze` calls; it enforces pipeline major version compatibility, detects
+resource overruns (file count, byte size), and catches plugin failures gracefully — returning
+a coverage entry with failure reason rather than throwing. Output coverage records always
+include the analyzer id and version.

package/docs/agent-corpus/report.md

@@ -0,0 +1,27 @@
+---
+type: module
+id: doc-bridge-report
+editRoot: src/report
+humanDoc: /docs/for-agents
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/report
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/report
+---
+
+# Report
+
+Owns the offline HTML report: a snapshot and its reconciliation rendered into something a person can
+open without a server, an index, or the CLI. One file, `html.ts`.
+
+The exported surface is `renderOfflineReport` and `renderOfflineReportArtifact`, taking
+`OfflineReportInput` and `OfflineReportOptions` and returning an `OfflineReportArtifact` — a single
+self-contained page, or a directory of files with a manifest for an artifact store. The view model it
+renders from is built internally and is not part of the API; the artifact shape is.
+
+Options cover privacy (private and anonymised modes) and whether snippets are embedded, because a
+report is the one output likely to leave the repository and land in a CI artifact or a ticket. Large
+graphs are chunked per group and package so the page stays openable.

package/docs/agent-corpus/retrieval.md

@@ -0,0 +1,33 @@
+---
+type: module
+id: doc-bridge-retrieval
+editRoot: src/retrieval
+humanDoc: /docs/query
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/retrieval
+validationPath: pnpm test && node bin/ak-docs.js index
+docbridge:
+  covers:
+    - area:src/retrieval
+---
+
+# Retrieval
+
+Owns the projection from a discovery snapshot to the sealed retrieval index, and the ranking over it.
+
+`projectRetrievalIndex` is the only writer of `RetrievalIndexV1`. It seals over **what the snapshot
+observed** — `pipelineVersion`, `analyzerVersions`, entities and relations, hashed by
+`snapshotObservationHash` — and never over the revision the snapshot was taken at. `snapshotHash`
+survives in the projection as provenance only; reading it as a seal input is what made a committed
+index go stale the moment it landed, fixed in 1.10.1 by bumping `RETRIEVAL_PROJECTION_VERSION` to 2.
+
+Each area and module carries `graph.coveredBy` and `graph.mentionedBy`, built from the `covers`,
+`mentions` and `mentions-symbol` relations pointing into it. The doctor reads exactly those two
+lists to decide whether an area is documented, so a document earns connectivity by declaring an
+edge, never by sitting in the corpus.
+
+Ranking is deterministic: `bm25.ts` builds a field-weighted BM25 index at `BM25_VERSION`, `rank.ts`
+scores an entry from named components and returns a `RankExplanation` for every hit, and
+`weights.ts` holds the shares those components divide. A hit below `RELEVANCE_FLOOR` is dropped
+rather than returned with a low score, so the benchmark measures answers, not near-misses.

package/docs/agent-corpus/rules.md

@@ -0,0 +1,30 @@
+---
+type: module
+id: doc-bridge-rules
+editRoot: src/rules
+humanDoc: /docs/spec/documentation-standard-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/rules
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/rules
+---
+
+# Rules
+
+Owns turning reconciliation diagnostics into severity-carrying findings. One file, `engine.ts`.
+
+`evaluateRules` maps a diagnostic code to a rule id through `diagnosticRules` and gives it a severity.
+The eleven rule ids are defined by `RuleIdSchema` in `src/config/schema.ts`, not here, so this area
+evaluates ids it does not own: `documentation-quality`, `graph-undocumented-relation`,
+`declared-unobserved-relation`, `unresolved-reference`, `conflicting-declaration`,
+`not-analyzed-coverage`, `stale-documentation`, `centrality-risk`, `critical-path-risk`, `freshness`
+and `ownership`. The mapping is not one-to-one: `OWNERSHIP_GAP` and `OWNERSHIP_PATH_UNOBSERVED` both
+become `ownership`, and `IMPORT_CYCLE` and `CENTRALITY_RISK` both become `centrality-risk`.
+
+Severity comes from the mode — `default` reports everything as `info`, `recommended` raises it to
+`warn`, `strict` to `error` — with `not-analyzed-coverage` held one step lower in both raised modes,
+because a suite that does not exist is not a failure to report. An explicit `severity` override beats
+the mode, and an `ignore` entry drops the rule entirely.

package/docs/agent-corpus/safety.md

@@ -0,0 +1,23 @@
+---
+type: module
+id: doc-bridge-safety
+editRoot: src/safety
+humanDoc: /docs/spec/config-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/safety
+validationPath: pnpm test && node bin/ak-docs.js index
+docbridge:
+  covers:
+    - area:src/safety
+---
+
+# Safety
+
+Owns safe file discovery and secret detection. The `safeWalkFiles` function walks a repository
+with resource limits (file count, byte size, memory, time) and respects exclusion globs from
+`safety.exclude` in config or `DEFAULT_SAFETY_EXCLUDES` — paths matching `.git`, `node_modules`,
+dist, build, coverage directories, and patterns for `.env`, `.pem`, `.key`, and secret-like names.
+`redactSecrets` detects and redacts patterns for API keys (Stripe, GitHub, AWS) and
+credentials (password, token, api-key style). Symbolic links are skipped; containment checks
+prevent escapes via symlink resolution.

package/docs/agent-corpus/schemas.md

@@ -0,0 +1,34 @@
+---
+type: module
+id: doc-bridge-schemas
+editRoot: src/schemas
+humanDoc: /docs/schemas/doc-bridge-index-v1
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/schemas
+validationPath: pnpm test && pnpm typecheck
+docbridge:
+  covers:
+    - area:src/schemas
+---
+
+# Schemas
+
+Owns the artifact contracts: every sealed artifact this repository writes or reads is shaped here, and
+the schema is the contract, not the code that happens to produce it.
+
+`knowledge.ts` holds `DiscoverySnapshotV1Schema` and the shared `Provenance` and finding vocabulary;
+`retrieval-index.ts` the projection, including `ConfidenceSchema` and `AudienceSchema` and the bounded
+`coveredBy`/`mentionedBy` lists the doctor reads; `doc-bridge-index.ts` the committed index that wraps
+both; `agent-handoff.ts`, `memory-candidate.ts`, `enrichment.ts` and `budget.ts` the remaining
+artifacts; `json-schemas.ts` the published JSON Schema forms of three of them.
+
+Get the two hashes the right way round. **`contentHash` is the seal**: `contentHashForArtifactV1`
+removes that field and hashes everything else, so the value is a hash *of the rest of the artifact*.
+`snapshotHash` inside the projection is **provenance** and deliberately not a seal input — sealing over
+it was the 1.10.0 defect, because the snapshot's revision changes when the tree does and a committed
+index then went stale the moment it landed. 1.10.1 replaced it with `snapshotObservationHash` and bumped
+`RETRIEVAL_PROJECTION_VERSION`.
+
+Field bounds are part of the contract, not hygiene: shortening a `max()` here rejects artifacts that
+were valid before.

package/docs/agent-corpus/scripts.md

@@ -0,0 +1,29 @@
+---
+type: module
+id: doc-bridge-scripts
+editRoot: scripts
+humanDoc: /docs/RELEASE
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: scripts
+validationPath: pnpm test && pnpm check:ecosystem-upstream
+docbridge:
+  covers:
+    - area:scripts
+---
+
+# Scripts
+
+Owns the repository's build, release and verification tasks — the checks that cannot live in the test
+suite because they reach outside the process: a packed tarball, a built docsite, an upstream digest.
+
+`prepare.mjs` builds when `dist/cli/program.js` is missing, so a git install works; a published tarball
+already ships `dist` and it no-ops. `sync-version.mjs` propagates one version across `package.json`,
+`action.yml`, and the plugin, MCP and manifest files, so the published surfaces cannot disagree about
+which release they are. `check-ecosystem-upstream.mjs` compares `ecosystem.json` and
+`ecosystem-claims.json` against their upstream digests, failing when this repository has drifted from
+the contract it claims to implement.
+
+The `smoke-*.mjs` scripts exercise what is actually shipped — the packed tarball, the docsite builds,
+the MCP bundle — and the `*-contract.test.mjs` scripts assert the artifact shapes consumers depend on.
+A check belongs here when passing it requires the real thing, and in `tests/` otherwise.

package/docs/agent-corpus/shims.md

@@ -0,0 +1,26 @@
+---
+type: module
+id: doc-bridge-shims
+editRoot: src/shims
+humanDoc: /docs/POSITIONING
+owner: doc-bridge-maintainers
+lifecycle: active
+sourceOfTruth: src/shims
+validationPath: pnpm typecheck && pnpm test
+docbridge:
+  covers:
+    - area:src/shims
+---
+
+# Shims
+
+Owns ambient type declarations for what the published packages do not type correctly themselves. Two
+files, and both exist to keep `pnpm typecheck` honest rather than to change behaviour.
+
+`agentskit-peers.d.ts` declares the optional AgentsKit peers (`@agentskit/rag`, `memory`, `adapters`,
+`core`, `ink`) plus `ink` and `react`, so the tree typechecks whether or not those packages are
+installed. `graphology.d.ts` covers the mismatch between the library's CommonJS declarations and its
+ESM build under `moduleResolution: NodeNext`.
+
+A shim is a claim about someone else's API, so it can drift silently: nothing here fails when the
+upstream types change, only the code that trusted them.

package/docs/parity/public-claims-v1.json

@@ -137,9 +137,26 @@
       ],
       "severity": "error",
       "remediation": "Document `ak-docs parity` in the CLI reference, or remove the command."
+    },
+    {
+      "claimId": "checked-in-package-version",
+      "statement": "The README states which package version this checkout carries",
+      "owner": "platform",
+      "valueType": "semver",
+      "template": "checked-in package version is `{value}`",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "package.json",
+        "field": "version"
+      },
+      "required": [
+        "README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the version from package.json on every surface that quotes it, or drop the sentence."
     }
   ],
   "exceptions": [],
-  "contentHash": "e188a7b2776a3c7c495016b462fd2c053faec9d29d0b824b607458b922fbd118",
+  "contentHash": "981acc99a59c6ba5d3cf79ac3c6d040353c4733d60800f48c22ed4756d0fdd99",
   "contentHashAlgo": "sha256-normalized-v1"
 }

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.1",
+  "version": "1.11.1",
   "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.1",
+  "version": "1.11.1",
   "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.1'
+const VERSION = '1.11.1'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]