@agentskit/doc-bridge 1.7.45 → 1.9.0

package/docs/spec/public-parity-v1.md

@@ -0,0 +1,119 @@
+---
+title: Public parity v1
+description: A registry of the claims this repository makes in public, the repository facts they stand for, and the gate that fails when a public surface states something the repository has moved past.
+---
+
+# Public parity v1
+
+Documentation drifts silently, and the drift reaches readers before it reaches anyone who could fix it.
+
+Four figures from the published A/B round appear in `README.md` and again in `docs/study/README.md`.
+They agree today. Nothing made them agree: an edit to one of them, or a new round replacing the
+artifact both quote, would leave two public surfaces stating a number the repository no longer
+measures — and the only mechanism for noticing was a person happening to read both pages on the same
+day.
+
+`ak-docs parity` is that mechanism. A registry names each public claim and the repository fact it
+stands for; the checker resolves the fact, finds the claim's occurrences, and reports the difference
+with a file, a line, an owner and a remediation.
+
+## The registry
+
+`docs/parity/public-claims-v1.json` is a sealed artifact — `createPublicClaims` computes its content
+hash, `parsePublicClaims` refuses a tampered one — holding claims and exceptions.
+
+| Field | Meaning |
+| --- | --- |
+| `claimId` | A slug. Stable across rounds, because findings are keyed on it. |
+| `statement` | What the claim asserts, for a reader of the report. Never a path or a URL. |
+| `owner` | Who answers for it: an ownership id, a team, a handle. Every finding carries it. |
+| `valueType` | `number`, `percent`, `semver` or `text`. Decides the capture. |
+| `template` | How the value appears in prose, with exactly one `{value}`. Omitted for a presence claim. |
+| `templates` | Per-surface wording, when one fact is stated differently in different places. |
+| `evidence` | Where the canonical value comes from. Below. |
+| `required` | Surfaces that must state the claim. One that omits it is a `missing` finding. |
+| `optional` | Surfaces that may. Checked when present, never required. |
+| `severity` | `error` blocks the gate; `warn` is reported and does not. |
+| `remediation` | What to do about a finding. Written once, in the registry, not per finding. |
+
+### Evidence
+
+Every resolver is deterministic and local. Nothing reaches the network, and nothing asks a model.
+
+| Kind | Resolves to |
+| --- | --- |
+| `package-field` | A scalar field in `package.json` — `version`, `description`. |
+| `artifact-field` | A dotted path into a committed JSON artifact: `arms.1.completedRate`. |
+| `artifact-sum` | The sum of one numeric field across an array in an artifact: prose states a total where the artifact stores the parts. |
+| `snapshot-count` | Entities of one kind in the snapshot this run produced. |
+| `doctor-metric` | A figure the doctor measured: the grade, the score, reachability, connectivity, hit@3, agent-doc coverage. |
+| `cli-command` | Whether the CLI's own usage offers a command. A presence claim: no template, no value to read. |
+
+A numeric value can be rendered the way prose states it: `round`, `percent-1dp`, `percent-0dp`, and
+two signed transforms. `negative-percent-2dp` and `negative-seconds-2dp` render the magnitude of a
+negative measurement — "18.46% fewer", "39.75 seconds lower" — and **refuse to render a positive
+one**. The direction of those claims lives in a word the checker cannot read, so a measurement that
+turns stops resolving instead of matching the same digits for the opposite result.
+
+## The four outcomes
+
+They are kept apart because they need different actions.
+
+| Code | Meaning | Blocks |
+| --- | --- | --- |
+| `PARITY_STALE` | A surface states a value the repository has moved past. | At `error` |
+| `PARITY_MISSING` | A required surface does not state the claim at all. | At `error` |
+| `PARITY_CONTRADICTION` | Two public surfaces state different values for one claim. | Always |
+| `PARITY_NOT_ANALYZED` | The canonical value could not be resolved. | Never |
+
+A contradiction is decided over the whole claim rather than per surface: two pages disagreeing is a
+finding even when neither matches the repository, and it is the one an agent reading the
+documentation cannot resolve on its own.
+
+`PARITY_NOT_ANALYZED` is reported and never counted as a pass. A claim nobody could check is not a
+claim anybody verified, and passing it quietly is how a parity report becomes decoration.
+
+## Exceptions
+
+An exception accepts a finding for one claim on one surface, and it must carry a `reason` of at
+least eight characters and an `acceptedBy`. The finding still appears in the report, marked
+`accepted` with its reason, and stops blocking. There is no way to silence a claim without saying
+why in the artifact — silence is what drift needs.
+
+## The gate
+
+```bash
+ak-docs parity                         # JSON: { ok, parity }
+ak-docs parity --text                  # one line per finding, with its remediation
+ak-docs parity --claims <file>         # a registry somewhere else
+```
+
+Exit 1 when any finding blocks, 0 otherwise, 2 on a broken registry or an unreadable surface. CI runs
+it in the dogfood step, next to the index, the gate, the doctor and the retrieval benchmark, so a
+pull request that edits a public number and not its siblings fails before review.
+
+The doctor is measured only when a claim asks for one of its figures: that costs an index and a
+benchmark run, and most registries never need it.
+
+## Publication safety
+
+The report is publication-safe by construction. It carries claim ids, repository-relative surface
+paths, line numbers, the stated and canonical values, and a bounded excerpt of the matching line —
+at most 160 characters, with secrets redacted through the same scanner the enrichment validators
+use. It never carries a document's contents and never an absolute path: the registry's surface
+paths are validated as repository-relative, so an operator's home directory cannot reach an
+artifact that is meant to be shareable. A test asserts all of it against a fixture whose README
+contains a secret-shaped string and a four-hundred-character line.
+
+## Invariants
+
+- The registry is sealed; a tampered hash is refused before anything is checked.
+- A template's literal halves are escaped, so a registry cannot smuggle a pattern into the checker,
+  and `{value}` becomes one bounded capture: no nesting, no ambiguity, nothing to backtrack over.
+- A claim that states a value has a template; a presence claim has none. The schema enforces both.
+- An exception needs a reason and an approver, and applies to one claim on one surface.
+- A signed transform refuses a value whose sign no longer matches the prose.
+- Two runs over one unchanged repository produce the same report content hash: findings are sorted,
+  and nothing in the report is a timestamp.
+- `missingSurfaces` names a surface the registry addresses that the checkout does not contain, so a
+  claim cannot pass by pointing at nothing.

package/docs/spec/registry-agents.md

@@ -68,3 +68,9 @@ mergePolicy:
 - `knowledge-promoter` may draft PR content, but must never merge.
 - `code-review` runs after gates so reviewers see deterministic failures first.
 - Future RAG mode should inject `createDocBridgeRetriever(index)` and keep exact handoff resolution ahead of semantic results.
+
+## Grounding and approval boundary
+
+The adapter accepts only a typed `AgentProposalV1` whose base snapshot and report hashes match the supplied artifacts. A proposal must identify the configured Registry agent and exact installed version, reference known diagnostics, and include evidence present in the supplied snapshot or reconciliation report. When `ak-docs suggest --documentation` is used, the bounded documentation-audit context is also supplied; the proposal must bind `baseDocumentationAuditHash` and may reference audit finding IDs and evidence. Unknown diagnostics, out-of-scope evidence, malformed output, timeout, response limits, and token limits fail closed.
+
+The adapter returns advisory evidence only. It does not apply documentation changes, mark findings resolved, or approve its own output. Convert an accepted suggestion into the existing human-gated fix-proposal flow, run post-apply verification, and treat the new source revision as a new evidence run. An alternate Registry agent is selected by changing `intelligence.registry.agentId` and installing matching metadata under `agentRoot`; the common adapter and evidence contract remain unchanged.

package/docs/spec/render-v1.md

@@ -0,0 +1,122 @@
+---
+title: Render v1
+description: The canonical artifacts rendered as Markdown people can read, from templates a project can replace.
+---
+
+# Render v1
+
+Doc Bridge writes JSON for agents and HTML for browsing. `ak-docs render` writes the Markdown for
+people: the same artifacts, through templates rather than string concatenation, so a project can
+change the house style without a code change and every rendering is a function of its inputs.
+
+```bash
+ak-docs render llms.txt
+ak-docs render area --output docs/areas
+ak-docs render ownership --output docs/agent-corpus/generated
+ak-docs render change-digest --data .doc-bridge/previous-snapshot.json
+ak-docs render overlay-review --output review.md
+ak-docs render area --print-template > templates/area.md
+```
+
+Rendering never calls an agent and never reads the Registry. Its inputs are the index, built in
+memory from the working tree or read from the artifact `--data` names, the workflow's last
+reconciliation report and snapshot, and an overlay file. Lists are sorted, nothing carries a
+timestamp, and equal inputs render to equal bytes — every bundled template has a golden file, and
+a test renders the same data twice.
+
+## Templates
+
+| Name | Renders | `--data` |
+| --- | --- | --- |
+| `llms.txt` | the curated reading order for agents, exactly as `ak-docs index` writes it | a `DocBridgeIndex` |
+| `area` | one page per code area: purpose, modules, documents, related areas, checks, open findings | a `DocBridgeIndex` |
+| `ownership` | one sidecar per ownership record: start page, what to read, edit roots, checks, related areas | a `DocBridgeIndex` |
+| `change-digest` | entities and documents whose content hash moved since the last scan, and the documents that should have moved with them | the previous snapshot |
+| `overlay-review` | pending agent proposals with their evidence links, for a human to judge | an enrichment overlay |
+
+Without `--output`, the pages go to standard output; `--json` wraps them as `{ template, source,
+pages: [{ path, content }] }`. With `--output`, a single page is written to that path and a
+multi-page template under it as a directory; the command prints what it wrote.
+
+Templates use [knap](https://github.com/obsidianmd/knap) syntax: `{{ variable }}`, `{% if %}`,
+`{% for item in list %}`, and knap's standard filters. They parse to an abstract syntax tree and
+are interpreted without `eval`; the application computes every variable before rendering, and a
+template cannot call anything. knap renders asynchronously and the index pipeline is synchronous,
+so Doc Bridge walks knap's AST with a synchronous evaluator of its own; a test renders every
+bundled template through knap's engine as well and holds the two to byte-identical output.
+
+## Overriding a template
+
+```json
+{
+  "render": {
+    "templates": {
+      "area": "templates/area.md"
+    }
+  }
+}
+```
+
+The path is relative to the project root. `ak-docs render <name> --print-template` prints the
+bundled template to start from, and the variables each template sees are the exported view types
+(`AreaPageView`, `OwnershipPageView`, `ChangeDigestView`, `OverlayReviewView`, `LlmsTxtVariables`).
+An override replaces the bundled template entirely and is compiled by the same engine, so one that
+does not parse fails before anything is written. The `llms.txt` override is also what
+`ak-docs index` writes and what the documentation-standard profile re-renders to check freshness:
+the two always agree.
+
+## Generated regions
+
+Every Markdown page carries a marker around what the generator owns:
+
+```markdown
+<!-- doc-bridge:generated hash=2dc9b98ec7b986b0 -->
+…
+<!-- /doc-bridge:generated -->
+```
+
+A template places the markers with `{{ region.open }}` and `{{ region.close }}`; a template that
+prints neither is wrapped whole. The hash is the first sixteen hex characters of the SHA-256 of
+the lines between the markers, with line endings normalised, so an editor converting a file to
+CRLF has not changed what the generator wrote.
+
+The marker is what closes the loop with the rest of the pipeline. The Markdown analyzer skips
+mentions and links inside a generated region (`docs/spec/markdown-analyzer-v1.md`), so Doc Bridge
+never reads its own output back in as evidence about the repository. The documentation audit
+recomputes the hash of every region and reports one that no longer matches its marker as
+`GENERATED_REGION_EDITED` under `generated-freshness`, with the region's lines as evidence: a
+manual edit inside a region is a finding, never something a regeneration silently discards. Text
+outside the markers is a person's and is left alone.
+
+`llms.txt` carries no marker. It is a whole-file artifact with consumers of its own — the
+federation retriever and the freshness gate — and its bytes are unchanged from before.
+
+## The change digest
+
+The digest compares two discovery snapshots by the content hash each file-backed entity carries
+(`docs/spec/incremental-scan-v1.md`): an entity in both with a different hash is *changed*, one
+only in the current snapshot is *added*, one only in the previous is *removed*. An entity without
+a hash — an external package, an area — has nothing to move and is not listed.
+
+"Documentation to review" answers which documents this change should have touched: every document
+that covers, mentions, links to or references a symbol of something that moved, and did not move
+itself. A document that changed alongside its subject is in *changed*, not there.
+
+The previous snapshot is the one `--data` names, otherwise the last `ak-docs scan` (the
+workflow's `normalize` output under `.doc-bridge/workflow`). The current one is a cold scan of the
+working tree. Rendering does not move the baseline — only a scan does — so the digest can be
+rendered as many times as a review needs. With no previous snapshot the command says so and
+exits 2.
+
+## The overlay review page
+
+The page reads an enrichment overlay's `pending` proposals — id, kind, entity, reason, confidence
+and evidence locations — and renders each with links of the form `path#L10-L12`. It is
+deliberately loose about the overlay's shape, which the enrichment workstream owns. With no
+overlay it renders an explicit empty state rather than failing; `.doc-bridge/enrich/overlay.json`
+is read when it exists, and `--data` names any other file.
+
+## Boundaries
+
+Nothing under `src/render` imports anything under `src/agents`; a test walks the imports.
+Rendering works with the Registry disabled, because it never consults it.

package/docs/spec/retrieval-index-v1.md

@@ -0,0 +1,164 @@
+---
+title: Retrieval index v1
+description: The retrieval index as a projection of the snapshot, the ranking that reads it, and the handoffs derived from its graph.
+---
+
+# Retrieval index v1
+
+The retrieval index is what search ranks. It is a projection of the discovery snapshot — a pure
+function of the snapshot, the accepted enrichment overlay and the effective configuration — and it
+has no scanner of its own.
+
+That sentence closes a gap that had been in the design since the first index. `buildDocBridgeIndex`
+walked the repository a second time, parsed every module and document again, and produced records
+that shared nothing with the snapshot but a file path. Two views of one repository, built by two
+pipelines, could disagree; the index held eleven sidecars while the snapshot held hundreds of
+entities. Now an entity retrieval can find is an entity discovery observed — same id, same content
+hash, same evidence — and the routes the configuration declares (intents, changes, ownership) are
+projected next to them.
+
+## The artifact
+
+`RetrievalIndexV1` lives inside `DocBridgeIndexV1` as `projection`, so every reader of the index
+receives it with the same freshness check. `knowledge[]` is still written for every reader that
+predates it and now carries every projected document and module — without body text, which lives
+once in the projection.
+
+```json
+{
+  "type": "retrieval-index",
+  "schemaVersion": 1,
+  "contentHash": "…",
+  "snapshotHash": "…",
+  "overlayHash": "…",
+  "configurationHash": "…",
+  "lexiconVersion": 1,
+  "graphMetricsVersion": "1.0.0",
+  "weights": { "title": 4, "headings": 3, "symbols": 3, "path": 2, "aliases": 2, "summary": 2, "body": 1 },
+  "params": { "k1": 1.2, "b": 0.75 },
+  "lexical": { "version": 1, "documentCount": 364, "fieldNames": ["…"], "averageFieldLength": { "…": 0 } },
+  "entries": [
+    {
+      "id": "module:src/query/search.ts",
+      "kind": "module",
+      "path": "src/query/search.ts",
+      "title": "search.ts",
+      "aliases": [],
+      "symbols": ["searchIndex"],
+      "tags": ["module", "ts", "query"],
+      "fields": { "title": "search.ts", "headings": "", "path": "src/query/search.ts", "symbols": "searchIndex", "summary": "", "body": "", "aliases": "module ts query" },
+      "graph": { "pagerank": 0, "inboundLinks": 3, "coveredBy": ["document:docs/agent-corpus/query.md"], "mentionedBy": ["…"], "areaId": "area:src/query", "packageId": "package:@agentskit/doc-bridge", "inbound": [], "outbound": [] },
+      "contentHash": "…",
+      "provenance": "observed",
+      "confidence": "observed",
+      "ownershipId": "doc-bridge-query"
+    }
+  ]
+}
+```
+
+`contentHash` is over the inputs — snapshot hash, overlay hash, configuration hash, lexicon and
+graph-metrics versions, weights and parameters — because the projection is a function: equal
+inputs, equal artifact. `IndexStaleError` keeps working from the same three hashes.
+
+Every entry carries the entity's own `contentHash`, its `provenance`, and a `confidence`. An entry
+kind is one of `document`, `module`, `area`, `package`, `intent`, `change`. An ownership record
+attaches to the entity at its path and lends it its id as an alias; the unit then inherits its
+agent document's title, headings, summary and body, because that document is the documentation of
+that unit. A record whose path matches no entity is projected as a declared `package` entry, so a
+query for it still has an answer.
+
+The postings are not stored. `fields` already is the serialised index: tokenisation is versioned
+(`lexiconVersion`) and deterministic, so the postings a reader rebuilds are the postings the writer
+would have stored, and `lexical` records the shape of the collection so a reader can check it
+rebuilt the same one.
+
+The one thing read from disk is the body of a document the snapshot already names — bounded by the
+same text budget as before — and the read is verified against the entity's content hash. A file
+that changed since the scan is projected from what the snapshot recorded about it, not from what is
+on disk now.
+
+## Ranking
+
+`src/retrieval/rank.ts` replaces the internals of `searchIndex` and keeps its signature. The score
+has named parts:
+
+```
+score = lexical × prior
+      + exactId + exactPath + exactSymbol
+      + graphProximity + canonicality + audienceFit + acceptedAgentSignals
+```
+
+- **lexical** — BM25 over the projected fields, with the weights above. Configurable under
+  `retrieval.weights`; recorded in the artifact.
+- **prior** — the query-shape heuristics, as a multiplier: a curated (agent-audience) document, an
+  ownership record for a routing question, an intent or change route whose title covers the query,
+  a module for a symbol- or path-shaped query. A prior can only amplify evidence that exists.
+- **exactId / exactPath / exactSymbol** — the query names the thing: an alias or id, a path or
+  filename, an exported symbol. Per-token identity applies to queries of at most two tokens; a
+  sentence does not name a thing by containing one of its tokens.
+- **graphProximity** — within two hops of one of the ten strongest lexical hits, over covers,
+  mentions, links and imports. Scaled by the anchor's share of the best score, so a hub page that
+  barely matched cannot lift everything it links to.
+- **canonicality** — log-scaled PageRank over `links-to` and `covers`: the page other pages point
+  at outranks the leaf that mentions the same thing. A tie-breaker among answers, never an answer:
+  it applies only to lexical hits.
+- **audienceFit** — the `--agent` prior for documentation written for an agent.
+- **acceptedAgentSignals** — the overlay hook, carried at zero weight until the overlay workstream
+  lands, so the code path and the explain view already exist.
+
+A result that only a relation surfaced earns proximity and nothing else. Results below a third of
+the best score are dropped; a caller assembling a neighbourhood rather than an answer passes
+`floor: 0`.
+
+**Confidence** on a result is the entry's own when the query matched it directly, and the weaker
+of the entry and the surfacing relation when a relation alone surfaced it — a `fuzzy` mention makes
+a `fuzzy` result. Every result carries evidence (the entity's path and content hash), provenance and
+confidence.
+
+`ak-docs search <term> --explain`, or `explain: true` over the API, attaches the matched terms and
+fields and every component's contribution to each result. Explaining never changes the ranking.
+
+```
+$ ak-docs search "workflow transitions persisted" --explain --text
+  [module] module:src/workflow/engine.ts score=115.27 confidence=observed
+    src/workflow/engine.ts
+    why: lexical=115.27
+    matched: aliases: workflow | path: workflow | symbols: workflow
+```
+
+## Handoffs for any entity
+
+`handoffForEntity(index, id, config, { root })` in `src/query/handoff.ts` answers for a package, an
+area, a module or a document — by entity id, ownership id, alias or path — and replaces
+`handoffForPackage`. `runQuery` and MCP `handoff.resolve` go through it.
+
+| Field | Derived from |
+| --- | --- |
+| `editRoots` | the area or package itself; a module's area; a document's own path |
+| `startHere` | the ownership record's agent document, then documents that `cover` the target, then those that `mention` it, then one `links-to` hop from those, then the corpus index; within each tier the more canonical page first |
+| `readBeforeEditing` | the next two, plus `AGENTS.md` |
+| `checks` | an ownership override, then what the index recorded when it merged frontmatter, package scripts and defaults, then the package-manager default for the unit's package |
+| `related` | the strongest importing and imported areas, with the import that proves each |
+| `explain` | which relation produced each field |
+| `evidence` | the target's path and content hash, and the documents behind `startHere` |
+| `metadata` | `entityId`, `kind`, `checksSource`, `confidence`, `areaId`, `packageId` |
+
+`AgentHandoffV1` stays byte-compatible: `related`, `explain`, `evidence` and `metadata` are optional
+additions, and `target.type` gains `area` and `document`. A handoff written before they existed is
+still a valid handoff.
+
+## The retriever
+
+`createDocBridgeRetriever(index)` returns `RetrievedDocument[]` from `@agentskit/core` — content is
+the projected title, summary and body, `metadata` carries `kind`, `path`, `evidence`, `explain` and
+`confidence` — so `createHybridRetriever`, `createRerankedRetriever` and `formatRetrievedDocuments`
+consume Doc Bridge with no adapter. The contract is mirrored in-repo (the core package is an optional
+peer) and a test asserts assignability against the real package and runs the real hybrid retriever
+over it. `retrieve('query', { limit })` still works.
+
+## Boundaries
+
+Nothing reachable from `search`, `query` or the projection imports anything under `src/agents`; a
+test walks the imports. The deterministic layer is complete on its own, and the enrichment stage
+never sits on its path.

package/docs/spec/study-metrics-v1.md

@@ -0,0 +1,58 @@
+---
+title: Longitudinal study metrics v1
+description: Deterministic, content-addressed comparison of controlled study rounds.
+---
+
+# Longitudinal study metrics v1
+
+`ak-docs study metrics <observation-ledger.json>` calculates an anonymization-safe report from `ControlledStudyObservationV1` records. It groups observations by task, repository, category, difficulty, model, scenario, replicate, and aggregate, then compares the selected baseline and current rounds. When a round contains retries or recovery runs, pass `--baseline-run-id` and `--current-run-id` to bind each side to an exact run without rewriting ledger history.
+
+When both sides intentionally share one round (for example, two arms of a pairwise run), the same-round selection keeps only the explicitly named run IDs. A same-round report exposes the scenario groups for arm-level analysis; it does not manufacture a round comparison.
+
+```bash
+ak-docs study metrics docs/study/observation-ledger-v1.json --text
+ak-docs study metrics docs/study/observation-ledger-v1.json --baseline-round baseline --current-round cycle-1 --json
+ak-docs study metrics docs/study/observation-ledger-v1.json --baseline-round baseline --baseline-run-id baseline-run-01 --current-round cycle-1 --current-run-id cycle-1-run-01 --json
+```
+
+## Metric contract
+
+The report keeps metric families separate. Counts are sums, rates are weighted ratios or means as stated below, and latency/answer-cost distributions use p95.
+
+| Family | Metrics | Collection |
+| --- | --- | --- |
+| Discovery/context | `providerTokens`, `estimatedTokens`, `tokensToCorrectAnswerP95`, `timeToCorrectAnswerP95Ms`, `contextBytesP95`, `responseBytesP95`, `searchHitRate`, `evidenceCitationRate`, `averageToolCalls`, `clarificationRate` | provider or explicitly labeled observation measurements |
+| Task/delivery | `successRate`, `completedRate`, `acceptanceCheckRate`, `errorRate`, `reworkRate`, `safetyRate` | adjudication and observation measurements |
+| Documentation | `documentationFindingCount`, `documentationExampleRate`, `documentationFreshnessRate`, `documentationCorrectnessRate`, `documentationCompletenessRate`, `documentationClarityRate`, `documentationMaintainabilityRate` | audit or human/adjudicator measurements |
+| Operations/cost | `latencyP95Ms`, `analysisCostUsd`, `agentCostUsd`, `adjudicatorCostUsd`, `totalCostUsd`, `providerTokenCostUnits`, `adjudicatorTokenCostUnits` | runner and explicitly labeled cost measurements |
+
+Provider token totals and estimated token totals are never combined. An estimate is valid only when the observation says `tokenMethod: estimate`. Known values are retained in partial totals; if any observation is missing a value, the metric is marked with a `-partial` entry in `missingMetrics` and must not be used as a complete-round comparison. A value that was not collected at all is `null`, listed in `missingMetrics`, and excluded from its denominator.
+
+Observations may carry additional bounded numeric values in `measurements`. The reserved keys above have the following meanings:
+
+- `searchHitRate`, `errorRate`, and documentation `*Rate` values are ratios from `0` to `1`.
+- `acceptanceChecksPassed` and `acceptanceChecksTotal` form a weighted acceptance ratio.
+- `documentationFindingCount`, `analysisCostUsd`, `agentCostUsd`, `adjudicatorCostUsd`, `providerTokenCostUnits`, and `adjudicatorTokenCostUnits` are additive values. Token-unit fields are one unit per provider-reported input or output token and are not currency values. USD fields are valid only when the run records configured rates and provider-reported usage.
+- `safetyOutcome` is preferred for the safety rate; `safe` is `1`, `unsafe` is `0`, and `not-applicable` is excluded.
+
+## Comparison rules
+
+Each comparison contains baseline and current values, absolute change, relative change when the baseline is non-zero, sample sizes, limitations, and one of `improved`, `unchanged`, `regressed`, `inconclusive`, or `not-analyzed`.
+
+- Fewer tokens, lower latency, less context, fewer clarifications, less rework, and lower cost are directionally better.
+- Higher success, evidence, safety, acceptance, search-hit, and documentation-quality rates are directionally better.
+- A lower-efficiency value cannot make a round `improved` when success, evidence citation, evidence quality, acceptance, safety, or rework regresses.
+- A comparison with fewer than two observations on either side is `inconclusive`, not a pass.
+- Missing baseline/current groups are `not-analyzed`; the calculator does not invent values or backfill historical data.
+
+Wilson 95% intervals are emitted for completion and task success rates. They communicate uncertainty; they do not establish causality. Aggregate results must be read with the subgroup results because model, scenario, repository, task difficulty, and documentation changes can confound a round.
+
+## Provenance and immutability
+
+The report is normalized and content-hashed with `sha256-normalized-v1`. JSON and text output expose the same group/comparison metric values and report hash. Calculating metrics never writes or replaces a baseline. Baseline approval and replacement remain explicit, audited harness operations.
+
+The report contains identifiers, versions, hashes, counts, timings, and classifications only. It must not contain repository contents, private paths, prompts, credentials, or raw agent responses.
+
+The CLI exits non-zero for a comparison classified as `regressed`. Structural verification that only checks report generation may pass `--allow-regressions`; regressions remain present in the report and should still fail a quality gate that is intended to enforce improvement.
+
+The first anonymized deterministic documentation snapshot is [Audit round 2026-08-31](../study/documentation-audit-round-2026-08-31.json). It is an observational inventory, not the controlled baseline: all six consumers still require semantic review, and its missing metrics must remain missing rather than being inferred.

package/docs/spec/study-protocol-v1.md

@@ -0,0 +1,46 @@
+---
+title: Study protocol v1
+description: Versioned and anonymization-safe contracts for measuring documentation quality and agent efficiency.
+---
+
+# Study protocol v1
+
+Phase 0 defines two content-addressed JSON artifacts:
+
+- `StudyProtocolV1` defines the population, evidence classes, task categories, model slots, scenarios, metrics, executable outcome checks, budget, privacy policy, and stopping rules.
+- `HistoricalEvidenceRegistryV1` preserves historical observations, available numeric measurements, explicit missing measurements, limitations, and validation state.
+
+The contracts are validated by the real Doc Bridge CLI:
+
+```bash
+ak-docs study protocol docs/study/protocol-v1.json --text
+ak-docs study history docs/study/historical-evidence-v1.json --protocol docs/study/protocol-v1.json --text
+```
+
+Both artifacts contain a SHA-256 normalized content hash. A hash mismatch, unknown cross-reference, duplicate identifier, unsafe public field, or incompatible schema fails closed.
+
+## Evidence classes
+
+`historical` records preserve observations from prior cycles. They may show evolution but cannot support causal claims because the task suite, models, and metrics were not fixed.
+
+`controlled` records belong to the approved benchmark protocol and can be compared only when the source revision, protocol, model, scenario, and validation contract match.
+
+## Outcome coverage
+
+Every protocol outcome must map to one or more executable checks. An outcome outside the current phase must instead declare an explicit `notApplicableReason`; an empty mapping is never silently accepted.
+
+## Privacy contract
+
+Public study artifacts use anonymized repository identifiers. They do not contain repository contents, paths, prompts, credentials, private identifiers, or raw agent responses. Publication always requires human review. The schema deliberately uses bounded identifiers and safe source references instead of arbitrary URLs or file paths.
+
+## Missing data
+
+Unavailable historical metrics are represented in `missingMetrics` with one of `missing`, `not-analyzed`, `blocked`, or `not-applicable` plus a reason. The importer never derives a missing value from another metric.
+
+## Protocol changes
+
+Changing task definitions, metric formulas, model identity, scenario behavior, privacy rules, or validation requirements changes the protocol hash. Existing baseline and historical evidence remains immutable; a changed protocol starts a new controlled evidence series.
+
+## Human authority
+
+The protocol and historical registry can be discovered and summarized by agents, but agents cannot approve protocol changes, replace a baseline, adjudicate their own output, or publish a report. Those actions remain human-gated through the verification harness.

package/docs/spec/study-provider-cli-v1.md

@@ -0,0 +1,116 @@
+---
+title: Study provider CLI contract v1
+description: Generic, bounded command contract for model and agent execution in controlled studies.
+---
+
+# Study provider CLI contract v1
+
+The provider adapter lets a study use a hosted model CLI, a vendor CLI, or an AgentsKit Registry agent without adding that provider to Doc Bridge. It does not install a model runtime and does not assume Ollama.
+
+## Configuration
+
+Create a content-addressed configuration with `createStudyProviderCliConfig` or validate one with:
+
+```bash
+ak-docs study providers path/to/provider-cli.json --text
+```
+
+Each provider entry contains:
+
+| Field | Meaning |
+| --- | --- |
+| `modelId` | Must match one pinned model in the run plan. |
+| `scenarioIds` | One or more of `repository-only`, `deterministic-doc-bridge`, `registry-assisted`. |
+| `command` | Executable name or path. It is launched without a shell. |
+| `args` | Ordered arguments passed unchanged to the executable. |
+| `envAllowlist` | Names copied from the parent environment. Credentials must be named explicitly. |
+| `providerNetwork` | Audit declaration that the provider may send input to an external service. |
+| `maxInputBytes` / `maxOutputBytes` | Provider-specific bounds; the lower bound wins against the run-plan budget. |
+| `pricing` | Optional configured USD rates used only to derive auditable `agentCostUsd`; omitted rates produce no currency claim. |
+
+The optional top-level `adjudicator` uses the same bounded command fields and adds `id` and `modelId`. It is a separate process from the provider under evaluation. Its output is used to record an independent rubric decision; the provider cannot approve its own result.
+
+```json
+{
+  "adjudicator": {
+    "id": "independent-reviewer",
+    "modelId": "reference-model",
+    "command": "/absolute/path/to/adjudicator",
+    "args": [],
+    "envAllowlist": [],
+    "providerNetwork": true,
+    "maxInputBytes": 1000000,
+    "maxOutputBytes": 50000,
+    "pricing": {
+      "currency": "USD",
+      "inputPerMillionUsd": 1,
+      "cachedInputPerMillionUsd": 0.5,
+      "outputPerMillionUsd": 3
+    }
+  }
+}
+```
+
+The cost formula is `(uncached input × input rate + cached input × cached rate + output × output rate) / 1,000,000`. Rates are study configuration, not a vendor billing assertion; the report must preserve the configuration hash and run ID. Cost is emitted only when the process reports both input and output token counts. `providerTokenCostUnits` remains the provider-reported input plus output total and is never presented as currency.
+
+The parser rejects stale content hashes, duplicate model/scenario mappings, unsafe environment names, and invalid command arguments. A command must exist and be executable before any task starts.
+
+## Provider process contract
+
+The child process receives one JSON request on stdin and must emit exactly one JSON object on stdout. Human-readable logs must go to stderr. The request contains the task, scenario, expected outcome, evidence requirements, acceptance checks, allowed tools, and forbidden actions. It does not contain the configured repository path.
+
+The generic runner does not enforce scenario tool semantics. A provider mapping must enforce its own scenario contract: a `repository-only` command must not query Doc Bridge, while a `deterministic-doc-bridge` command must execute the configured deterministic query or handoff and pass its bounded result to the model. A scenario label or `allowedTools` field alone is not evidence that Doc Bridge was used.
+
+The response may contain the bounded metrics below. Unknown fields are ignored by the generic runner, while unknown numeric measurements are preserved by the observation schema for future metric versions. The bundled Codex adapter additionally passes a JSON Schema to the provider CLI and requires the semantic fields (`taskOutcome`, `evidenceQuality`, `safetyOutcome`, evidence IDs, clarification/rework counts, an observed latency or explicit `null`, and measurements) so missing output is visible as a provider failure rather than silently becoming an empty result. When observed, measurements must use canonical names: `searchHitRate`, `acceptanceChecksPassed`, `acceptanceChecksTotal`, `errorRate`, `documentationFindingCount`, the documentation `*Rate` fields, `analysisCostUsd`, and `agentCostUsd`.
+
+```json
+{
+  "inputTokens": 1200,
+  "outputTokens": 340,
+  "tokenMethod": "provider",
+  "toolCalls": 4,
+  "firstEvidenceLatencyMs": 820,
+  "taskOutcome": "success",
+  "evidenceQuality": "high",
+  "safetyOutcome": "safe",
+  "evidenceIds": ["artifact-hash:abc123"],
+  "clarificationRequests": 0,
+  "reworkCount": 0,
+  "measurements": {
+    "searchHitRate": 1,
+    "timeToCorrectAnswerP95Ms": 820
+  }
+}
+```
+
+Raw prompts, responses, repository contents, paths, and credentials are not written to the observation ledger. The ledger stores status, hashes, timing, labeled token counts, context-token attribution, first-evidence latency when observed, tool counts, metric fields, and automated or pending human adjudication. The runner derives `providerTokenCostUnits` from provider-reported input plus output tokens; this is a transparent token-equivalent cost metric and must not be presented as currency. Context-token estimates are stored separately with `contextTokenMethod: "estimate"`; they are never combined with provider usage.
+
+The bundled Codex adapter also records privacy-safe aggregate context telemetry: `observedToolEventCount`, `observedToolInputBytes`, `observedToolOutputBytes`, `observedProviderInputBytes`, `observedAgentMessageBytes`, `observedContextBytes`, `observedProviderDurationMs`, and (when a tool event is observed) `timeToFirstToolEventMs`. These are byte counts and durations only; commands, paths, prompts, responses, and repository content are not emitted by the adapter. The duration is wall-clock time for the isolated provider process, while `timeToFirstToolEventMs` measures the first observed tool event, not semantic answer quality. The deterministic handoff is serialized as compact JSON before it is passed to the model, and the adapter explicitly tells the model to use its `startHere` and `readBeforeEditing` paths before exploring the repository. This preserves canonical content while removing formatting-only bytes and makes the intended low-context path measurable. Gzip and a cross-process cache are intentionally not used for model context: the model must receive readable content, and the current adapter starts an isolated process per observation, so either mechanism would add complexity without reducing billed model tokens. The public `--agent` CLI path also emits compact JSON, so machine consumers do not pay for presentation-only whitespace.
+
+## Independent adjudication
+
+Adjudicate a persisted ledger in a separate process:
+
+```bash
+ak-docs study adjudicate docs/study/observation-ledger-v1.json docs/study/task-suite-v1.json \
+  --adjudicator path/to/provider-cli.json --output .tmp/adjudicated-ledger.json \
+  --run-id cycle-1 --offset 24 --limit 24 --json
+```
+
+The adjudicator receives only anonymized task metadata and the bounded structured candidate record: outcomes, evidence IDs, per-requirement evidence presence, acceptance execution state, numeric measurements, execution status, duration, and response size. It does not receive repository paths, raw stdout, prompts, repository contents, or credentials. Automated adjudication records the adjudicator configuration hash in addition to its actor and method. A timeout, unavailable command, oversized output, or invalid JSON leaves the adjudication `pending`; no deterministic fallback silently converts that failure into a success. `--offset` and `--limit` support deterministic low-cost samples while preserving all unselected observations in the output ledger; offset counts only observations matching `--run-id`.
+
+## Running a study
+
+First validate the complete plan without invoking a provider:
+
+```bash
+ak-docs study run docs/study/run-plan-v1.json docs/study/task-suite-v1.json \
+  --providers path/to/provider-cli.json \
+  --repositories path/to/repositories.json \
+  --ledger path/to/observation-ledger.json \
+  --dry-run --text
+```
+
+The canonical run plan dry run validates the configured 24-task balanced sample, repository roots, executable commands, and input limits. It writes no ledger and makes no provider call. To execute, omit `--dry-run`. The ledger is persisted after each observation, so an interrupted run can resume and skip completed task executions idempotently. Reduced pilots may use fewer population identifiers and tasks, but require their own hashed suite, run plan, repository configuration, run ID, and explicit pilot label. A full 288-execution matrix requires a separately hashed run plan with `sampling.sampleSize` set to 288.
+
+Provider configuration and repository-root configuration are local operational inputs. Do not commit credentials, private paths, raw provider output, or consumer repository content to a publication artifact.