# Changelog ## 1.11.1 ### Patch Changes - faf29f5: Stop reporting a path an ignore rule rescues as unreproducible. `git check-ignore --verbose` emits a record for every path that *matched* a rule, including the path a `!` negation rescues — and such a path is precisely one Git does not ignore. The reproducibility check read the record without reading the pattern, so `dist/*` plus `!dist/keep.js` reported `dist/keep.js` as a reason the index could not be rebuilt from a clean checkout. The opposite of what the rule says, stated confidently. The window is narrow: `check-ignore` stops reporting a path once it is committed, and a path rescued by a negation is usually committed, which is the point of rescuing it. It shows up while such a path is still untracked — a file added but not yet committed. Found by turning the new `index-reproducible` gate on in this repository, which had to add `!.doc-bridge/index.json` to its own `.gitignore` to commit the index the gate verifies. ## 1.11.0 ### Minor Changes - 25f16f3: Say when a committed index could not have come from a clean checkout. A scan walks what is on disk and has no reason to consult `.gitignore`, so a generated module or document silently joins the corpus on a machine that has built and silently leaves it on one that has not. That is harmless while the index is rebuilt on every run. It is a defect the moment the index is committed so a gate can verify it — which is the setup `index-freshness` exists for: two checkouts of the same commit then produce different artifacts, the gate reports staleness that nothing caused, and regenerating cannot fix it because the next machine disagrees in the other direction. Dogfooding found this the expensive way. On a 25-package monorepo the freshness gate passed locally and failed in CI, twice, because `pnpm lint` had generated one `.ts` file into the corpus before the index was written; CI lints a narrower scope and never had the file. Diagnosing it took reading two CI logs and diffing file inventories. Git already knew the answer. `ak-docs index` now names those paths as it writes, and `ak-docs doctor` raises an `index-not-reproducible` warning, each with the ignore rule that matched — for example `apps/docs-next/lib/ask-context.ts (apps/docs-next/.gitignore:13:lib/ask-context.ts)` — so the fix is one lookup away: add the path to `safety.exclude`. Both are unconditional and neither changes an exit code or the doctor's score. Enforcement is the new `index-reproducible` gate, which is in no preset and has to be requested with `gates.include: ['index-reproducible']`, because turning it on for every consumer would fail gates that pass for good reasons. The check reports success rather than failure when the index is not committed or the project is not a Git checkout, since there is nothing to reproduce in either case, and it does not flag a file that is both tracked and matched by an ignore rule — being committed is the point. ## 1.10.1 ### Patch Changes - 0926c57: Keep a committed index fresh across commits. The retrieval projection sealed its content hash over the discovery snapshot's hash, and a snapshot's hash covers its `sourceRevision` — 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 the snapshot observed, not of where it observed it. The consequence only appears in a repository that commits `.doc-bridge/index.json`, which is the recommended setup: committing the index changes the revision that the next run hashes, so the artifact was stale the moment it landed — landing it is a commit. `ak-docs gate run` reported `index-freshness` failing on an index that nothing had invalidated, and no regenerate could fix it, because the fix was itself a commit. Dogfooding on a 25-package monorepo, the gate could not be made to pass twice in a row. The seal is now over what the snapshot observed: the entities, the relations and the analyzer identity that produced them, alongside the overlay and configuration hashes it already covered. The artifact still carries `snapshotHash`, now documented as provenance rather than a seal input, so a reader can still say which snapshot a projection came from. `RETRIEVAL_PROJECTION_VERSION` goes to 2, so no reader compares a hash across the change, and every index's content hash changes once on the next `ak-docs index`. ## 1.10.0 ### Minor Changes - 97851d0: Let a repository say which directories are not areas. An area is the unit of architecture between a package and a file, derived as the first directory level under a package's source roots. In a monorepo where every package keeps `tests/` and `fixtures/` beside `src/`, that derives one area per directory — and the doctor's connectivity dimension then asks for a document about a folder of test data. Dogfooding on a 26-package monorepo, 43 of its 81 undocumented areas were `tests/` or `fixtures/`: the metric was mostly measuring directories no documentation should describe. `analysis.areas.exclude` takes glob patterns for directories that hold code without being a unit of architecture. A matching candidate 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. 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. On that monorepo, excluding `**/tests`, `**/fixtures`, `**/__tests__` and `**/__fixtures__` took areas from 103 to 53 and the documented share from 21% to 34%, before a single document was written. ## 1.9.0 ### Minor Changes - 9a775a5: Add code areas — the unit of architecture between a package and a file — so reconciliation says something useful about a single-package repository. With `reconciliation.scope: "package"` and one package, every internal relation aggregated into a self-loop the comparison skips: a thousand observed relations, zero diagnostics, and a health score of 100 out of 100 that meant nothing. Most repositories are a single package. The ownership configuration already named the missing unit (`path: "src/mcp"`); the graph had no entity for it. `area:` entities are now derived from the first directory level under each package's source roots, plus any path an ownership record names, with `contains` relations from the package, to nested areas, and to each module. Each module belongs to exactly one area — the most specific — so containment stays a tree and an aggregation has one answer per module. `analysis.areas.depth` and `analysis.areas.roots` change what is derived without a code change. `reconciliation.scope: "area"` compares at that level. On this repository it turns 0 diagnostics into 177 `RELATION_UNDOCUMENTED` findings, each with file and line evidence. An area that an ownership record names carries `metadata.ownershipId`, which makes two things work that could not before. An ownership path no observed module or document lives under is now reported as `OWNERSHIP_PATH_UNOBSERVED` with status `stale-or-unverified` — a renamed directory was previously invisible, because the handoff still resolved. And an agent document declaring `id` plus `editRoot` now resolves to the area it owns: that pair has always filled the ownership map, but discovery never read it, so every such declaration became an unresolved reference. The documentation audit measures coverage against areas when a repository has exactly one package. It reported `Packages covered: 0/0` on this repository; it now reports `Areas covered: 9/36`, with `metrics.coverageUnit` naming the unit and `AREA_DOCUMENTATION_MISSING` for an uncovered area. A document naming a directory in inline code now produces a `mentions` relation to that area, completing the part of the Markdown analyzer that was waiting for areas to exist. `pipelineVersion` becomes `1.3.0` and the `repository` analyzer `1.2.0`. `DiscoverySnapshotV1`'s schema version is unchanged: the new kind travels through the existing generic envelope. - 9a775a5: Let a Registry agent enrich the knowledge graph without ever becoming an authority over it. `EnrichmentProposalV1` is a discriminated union of eleven typed claims — classify a document, summarize it, add an alias or an intent, mark it canonical for a scope, propose a relation, flag a contradiction, a redundancy or a gap, hint at relevance, suggest an area — each with its own deterministic validator and its own policy: low-risk kinds are accepted by policy, structural kinds wait for a person, a gap is accepted as a finding and never as a fact, and an unknown kind is rejected as `invalid-kind`. A proposal with no evidence, an unknown entity, an unknown diagnostic or evidence outside the supplied artifacts is rejected at the boundary. `proposalId` is derived from content, so re-running enrichment over an unchanged repository produces no duplicate entries. `EnrichmentOverlayV1` at `.doc-bridge/enrich/overlay.json` stores what became of every proposal: `accepted` with `acceptedAt` and `acceptedBy` (`policy` or a person, never the author), `pending` with its approval id, `rejected` with a reason, and `stats` by kind. Each entry binds to the content hash of the entity it describes: one changed file expires one entry at projection time, its siblings survive, and a read never rewrites the file. Re-running the validators over a stored overlay reproduces its partition. A new workflow stage `enrich` sits between `reconcile` and `evaluate` and runs only from `ak-docs enrich` or `check --enrich`. Agents receive context packs — one entity, its depth-one neighbours, the open diagnostics that touch it and a redacted excerpt, under a 64 KB budget (`intelligence.registry.maxPackBytes`) — over protocol `doc-bridge.registry-agent.v2`, batched by area. Answers are cached under `.doc-bridge/enrich/cache/` keyed on task, agent identity and version, prompt version and pack hash, so an unchanged repository makes zero agent calls and a one-document change re-runs only the affected packs. Roles are configuration under `intelligence.registry.roles` — curator for documents, reviewer for structure, adjudicator for canonical conflicts and disputed contradictions, which must be a different identity and may never judge its own proposals — and the default remains the existing corpus scanner as curator only. Human approvals go through `createApprovalGate` from `@agentskit/core/hitl` over a file-backed store under `.doc-bridge/approvals/`, shared by `ak-docs enrich approve|reject`, `ak-docs fix approve` and MCP `docbridge.proposals` (`enrich-list`, `enrich-approve`, `enrich-reject`), bound to both the proposal id and the target content hash. An approver equal to the author is refused. Accepted entries enter the retrieval projection: aliases, summaries where a document has none, intents and relations with `provenance: proposed` (drawn dashed in the HTML report), canonical markers and rank hints as a per-entry signal worth at most 15 percent of the exact-id boost, so an exact identifier match always outranks an overlay-boosted entry. With the Registry disabled, absent, timing out or answering garbage, `check`, `index`, `search`, `query` and MCP are byte-identical to a run with no overlay, and every observed entity and relation survives enrichment unchanged. - 9a775a5: Compute graph signals with a graph library instead of ad-hoc counting, and expose the repository graph through the ecosystem memory contract. `centrality-risk` in the rules engine derived from the number of undocumented-relation findings attached to an entity — documentation debt wearing the name of an architectural signal. A module every import path runs through scored zero if it happened to be documented. It is now betweenness over the import graph, and without a graph the rule reports nothing rather than reporting the wrong thing under a name people act on. On this repository it flags `src/cli/program.ts` first, which is the correct answer and one the old heuristic never gave. `src/graph/build.ts` adds, on graphology: - **canonicality** from PageRank over `links-to` and `covers`, so a documentation entry point outranks a leaf page; - **centrality** from normalized betweenness over `imports` and `re-exports`; - **proximity** from bounded shortest paths, excluding `contains`, which is hierarchy and would put every module in an area two hops from every other one; - **import cycles** with every edge that forms them as evidence, reported as a new `IMPORT_CYCLE` diagnostic — this repository has exactly one, between two `src/doctor` modules; - **area suggestions** from seeded Louvain communities, emitted only as `coverage` with `analyzer: graph` and `scope: area-suggestion:`, status `not-analyzed`. A clustering algorithm does not get to name the architecture. `createDocBridgeGraphMemory(snapshot, overlay)` in `src/graph/memory.ts` projects the graph behind `GraphMemory` from `@agentskit/memory`, so an agent built on AgentsKit walks repository structure with the same `getNode`, `findEdges` and `neighbors` calls it uses for its own memory. Writes land in a working layer above the projection and deletes mask rather than erase: the snapshot is an observation, and nothing a caller writes should be mistaken for something the repository said. The graph is never serialised and `DiscoverySnapshotV1` is unchanged. Insertion is sorted and every score rounded, so metrics are identical across runs and after the input order is shuffled. `pipelineVersion` becomes `1.4.0` with a `graph` analyzer version. - 9a775a5: Give every file-backed entity its own content hash, and reuse unchanged entities between scans. `EvidenceSchema.contentHash` had existed since the first schema and `discoverRepository` never filled it: on this repository 0 of 369 entities carried one. Every cache and every overlay could therefore be keyed only on "the whole repository changed", which is true between any two commits. Now every `module`, `document` and `package` entity carries the hash of its file in its first evidence item, and `external` entities carry none — a name in a manifest is not a file. `discoverRepository({ previous })` accepts a snapshot from a previous scan and skips the TypeScript and Markdown parses for files whose hash is unchanged. Reuse is only taken where it cannot change the answer: - an entity's own fields depend on its own bytes, so a hash match is enough for the entity; - a relation depends on what else exists, so relation reuse also requires that the universe the references resolve against is identical — module paths, packages and compiler options for a module, and additionally document paths, area paths and which module declares each exported symbol for a document. Both fingerprints are derived from the previous snapshot rather than stored in it; - the whole snapshot is refused unless it declares, and matches, this `pipelineVersion`, these `analyzerVersions` and this `configurationHash`. An analyzer that learns to read more produces different entities from identical bytes. A replayed edge whose internal target is gone is dropped rather than carried — a renamed file must not leave a graph asserting something the repository no longer contains — while an external or unresolved endpoint is re-added, because it is in the snapshot only because the reused entity referenced it. Two `js-ts` facts only ever lived in a local variable, which made the aggregate `dynamic-imports` and `runtime-wiring` entries unreproducible from the per-file ones — and a reused scan replays the per-file ones. A literal `require` now sets the resolved-dynamic-import flag it always recorded evidence for, and every observed runtime-wiring call leaves a per-file entry: `complete` when its target is statically known, `not-analyzed` when it is not, where before a resolved call left no record at all. Both make the aggregate derivable from what the snapshot actually carries. One `coverage` entry with `scope: reused-entities` reports what a run reused and what it re-parsed, so a fast run is explainable rather than suspicious. It is the only part of a snapshot that describes the run rather than the repository: the entities, the relations and every other coverage entry are byte-identical to a cold scan's. The CLI still scans cold, so its artifacts are unchanged apart from the new entry. `pipelineVersion` becomes `1.5.0`, the `repository` analyzer `1.3.0` and `js-ts` `1.3.5`. - 9a775a5: Read documentation with a real Markdown parser, and turn its prose into evidence-backed graph edges. Documentation used to be read with regular expressions: frontmatter by one, the `docbridge` block by a hand-written YAML subset, and the prose not at all. Headings, links and inline code were discarded — so on this repository, where 23 documents link to other documents and 14 cite source paths, none of it produced a single edge. A new `markdown` analyzer parses documents with remark (CommonMark plus GFM) and emits `observed` relations with the file and line each claim was made on: `links-to` between documents, `mentions` from a document to a module or package, and `mentions-symbol` from an inline code token to the module that exports it. On this repository that is 154 `links-to`, 93 `mentions` and 50 `mentions-symbol` where there were none, and 55 of 104 documents now have an outgoing edge. A symbol resolves to the module that declares it rather than a barrel that re-exports it, and a name declared by two modules resolves to neither — the reference and its lines are reported as a coverage note, because sending an agent to one of two possible definitions is worse than sending it nowhere. Unresolved path-shaped references are matched with Jaro-Winkler and accepted only at 0.92 or above with a single candidate, recorded as `confidence: 'fuzzy'`. Mentions inside a `` region are ignored, so Doc Bridge never reads its own output back in as evidence. A document referencing more than 64 entities records `evidenceTruncated`. Document entities now carry `title`, headings to depth three with their lines, a bounded `summary`, `wordCount`, the frontmatter subset (`type`, `audience`, `owner`, `lifecycle`, `tier`), any generated regions, and the file's content hash on its evidence. A document declaring `audience` overrides the path heuristic that classifies it. The `docbridge` block is now real YAML validated by a schema, so quoted lists, flow mappings, anchors and multi-line strings work as they do everywhere else, and a schema violation names the field. Every `DOCBRIDGE_*` diagnostic code is preserved, and a block YAML cannot read at all falls back to the previous line-oriented scanner, which reports per line. `pipelineVersion` becomes `1.2.0` and `analyzerVersions` gains `markdown`. The `DiscoverySnapshotV1` envelope is unchanged. Entity identity is consolidated into one module: `entityId` and `relationId` in `src/discovery/identity.ts`, shared by the discovery analyzers and the retrieval projection, which had grown a second copy. `projectedEntityId` (added in the unreleased corpus projection and never published) is gone in favour of `entityId`. - 9a775a5: Render the canonical artifacts as Markdown people can read, from templates rather than string concatenation, and close the loop between what Doc Bridge writes and what it reads. `ak-docs render