@agentskit/doc-bridge 1.9.0 → 1.10.1

package/docs/spec/config-v1.md

@@ -478,6 +478,8 @@ areas?: {
   depth?: number
   /** Directories that contain areas rather than being one. */
   roots?: string[]
+  /** Glob patterns for directories that hold code without being a unit of architecture. */
+  exclude?: string[]
 }
 ```
 
@@ -486,8 +488,16 @@ modules. `src` is not an area in any useful sense; `src/query` is. So `roots` na
 directories that hold areas — by default `src`, `lib`, `app`, `source`, `server`, `client`,
 `packages`, `apps` — and `depth` says how many levels below such a root an area sits.
 
+`exclude` names what the convention gets wrong in the other direction. A monorepo where every
+package keeps `tests/` and `fixtures/` beside `src/` derives an area per directory, and
+connectivity then asks for a document about a folder of test data — on one 26-package monorepo,
+43 of 81 undocumented areas were exactly that. A candidate matching an exclude pattern is not
+derived, and its modules fall to the most specific area that still encloses them, or to none,
+which is the honest answer for a folder of fixtures.
+
 Areas are derived, never declared, with one exception that matters: **any path an ownership record
-names becomes an area**, whatever the convention says. A configuration that reads
+names becomes an area**, whatever the convention says — including a path `exclude` matches, because
+a person saying a directory is a unit outranks a pattern saying it is not. A configuration that reads
 `path: "src/mcp"` is a human stating that the directory is a unit, and the graph should have an
 entity for it. Such an area carries `metadata.ownershipId`, which is what lets an agent document
 declaring `id` plus `editRoot` resolve to the thing it owns.

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.9.0",
+  "version": "1.10.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.9.0",
+  "version": "1.10.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",
@@ -123,28 +123,28 @@
   },
   "devDependencies": {
     "@agentskit/chat": "0.4.1",
-    "@agentskit/core": "1.12.8",
+    "@agentskit/core": "1.12.9",
     "@agentskit/ink": "0.10.9",
     "@agentskit/react": "0.8.3",
     "@anthropic-ai/mcpb": "2.1.2",
     "@changesets/cli": "^3.0.1",
     "@lhci/cli": "^0.15.1",
-    "@playwright/test": "1.62.1",
+    "@playwright/test": "1.63.0",
     "@tailwindcss/postcss": "4.3.3",
     "@types/mdast": "^4.0.4",
     "@types/node": "^26.4.0",
-    "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.5",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "4.1.11",
     "esbuild": "^0.28.2",
-    "fumadocs-core": "16.15.4",
+    "fumadocs-core": "16.15.10",
     "fumadocs-mdx": "15.4.0",
-    "fumadocs-ui": "16.15.4",
-    "lucide-react": "1.38.0",
-    "next": "16.3.3",
+    "fumadocs-ui": "16.15.10",
+    "lucide-react": "1.45.0",
+    "next": "16.3.5",
     "proxy-agent": "8.0.2",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "tailwindcss": "4.3.3",
     "tsup": "^8.5.0",
     "vitest": "^4.1.11"

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

package/src/config/schema.ts

@@ -249,12 +249,21 @@ export const AnalysisConfigSchema = z
     /**
      * How code areas are derived — the unit of architecture between a package and a file.
      * `roots` names directories that contain areas rather than being one (`src` holds
-     * `src/query`); `depth` is how many levels below such a root an area sits.
+     * `src/query`); `depth` is how many levels below such a root an area sits; `exclude`
+     * names directories that hold code without being a unit of architecture.
      */
     areas: z
       .object({
         depth: z.number().int().min(1).max(8).optional(),
         roots: z.array(z.string().min(1).max(128)).max(32).optional(),
+        /**
+         * Glob patterns for directories that are not areas. A monorepo where every package
+         * keeps `tests/` and `fixtures/` beside `src/` derives one area per directory, and
+         * then connectivity asks for a document about a folder of test data. An ownership
+         * record naming an excluded path still makes it an area: a person saying a directory
+         * is a unit outranks a pattern saying it is not.
+         */
+        exclude: z.array(z.string().min(1).max(256)).max(64).optional(),
       })
       .strict()
       .optional(),

package/src/discovery/areas.ts

@@ -1,3 +1,5 @@
+import { minimatch } from 'minimatch'
+
 import { toPosix } from '../lib/paths.js'
 import { entityId } from './identity.js'
 
@@ -58,6 +60,15 @@ export type DeriveAreasOptions = {
   readonly ownership?: readonly AreaOwnership[]
   readonly depth?: number
   readonly roots?: readonly string[]
+  /**
+   * Glob patterns for directories that hold code without being a unit of architecture.
+   *
+   * A candidate that matches is not derived as an area, and its modules fall to the most
+   * specific area that still encloses them — or to none, which is the honest answer for a
+   * folder of fixtures. An ownership record naming the same path still wins: a person saying
+   * a directory is a unit outranks a pattern saying it is not.
+   */
+  readonly exclude?: readonly string[]
 }
 
 /*
@@ -124,11 +135,15 @@ export const deriveAreas = (options: DeriveAreasOptions): readonly DerivedArea[]
   const roots = options.roots ?? [...DEFAULT_AREA_ROOTS]
   const ownership = (options.ownership ?? []).map((record) => ({ ...record, path: normalize(record.path) }))
 
+  const excluded = options.exclude ?? []
+  const isExcluded = (path: string): boolean =>
+    excluded.some((pattern) => minimatch(path, pattern, { dot: true }))
+
   /** Candidate path to the package it belongs to. */
   const candidates = new Map<string, string>()
   for (const module of options.modules) {
     const path = conventionalAreaPath(module, depth, roots)
-    if (path && !candidates.has(path)) candidates.set(path, module.packageId)
+    if (path && !candidates.has(path) && !isExcluded(path)) candidates.set(path, module.packageId)
   }
   // An ownership record naming a directory that holds observed code is an area by declaration.
   for (const record of ownership) {

package/src/discovery/repository.ts

@@ -648,6 +648,7 @@ export const discoverRepository = (opts: DiscoveryOptions = {}): DiscoverySnapsh
     ownership: Object.entries(opts.config?.routing?.options?.ownership ?? {}).map(([id, record]) => ({ id, path: record.path })),
     ...(opts.config?.analysis?.areas?.depth !== undefined ? { depth: opts.config.analysis.areas.depth } : {}),
     ...(opts.config?.analysis?.areas?.roots !== undefined ? { roots: opts.config.analysis.areas.roots } : {}),
+    ...(opts.config?.analysis?.areas?.exclude !== undefined ? { exclude: opts.config.analysis.areas.exclude } : {}),
   })
   const areasById = new Map(areas.map((area) => [area.id, area]))
   const areasByPath = new Map(areas.map((area) => [area.path, area.id]))

package/src/index.ts

@@ -104,6 +104,7 @@ export {
   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.9.0'
+export const PACKAGE_VERSION = '1.10.1'