@agentskit/doc-bridge 1.7.44 → 1.9.0

package/docs/loop-workflow.md

@@ -0,0 +1,117 @@
+---
+title: Keep-pushing loop for the knowledge-retrieval workstreams
+description: How the @agentskit/harness loop and Orca develop the KR-01…KR-11 workstreams one at a time, and what a human still has to do.
+---
+
+# Keep-pushing loop for the knowledge-retrieval workstreams
+
+`ak-harness loop` drains one person's Linear queue through Orca worktrees: it freezes an orchestrator contract per issue, opens a worker terminal in a fresh worktree, then drives the resulting pull request through checks, adversarial review and squash merge. This repository ships [`loop.config.example.yaml`](../loop.config.example.yaml) with every project-specific value already tuned.
+
+**The real `loop.config.yaml` is gitignored.** Its `linear` block names a workspace, a team and a person by id, and this repository is public, so the working config stays local:
+
+```bash
+cp loop.config.example.yaml loop.config.yaml
+ak-harness loop install -f loop.config.yaml   # fills the identity block interactively
+```
+
+`loop install` lists the Linear team members through Orca and asks whose queue this machine drains, so the identifiers never have to be typed by hand or pasted into a commit.
+
+Two facts decide how everything below is laid out:
+
+- **The queue is Linear, not GitHub.** GitHub is where a pull request is reviewed and merged, and `github.intakeLabel` (`loop:review`) lets a human ask the loop to review a pull request it never dispatched. It is not a work queue.
+- **The loop runs on a machine with Orca**, not in CI and not in an ephemeral container. `orca.runtime` is a blocking doctor check.
+
+So the eleven workstreams live in two places on purpose: the GitHub sub-issues of [#169](https://github.com/AgentsKit-io/doc-bridge/issues/169) are the **specification**, and the Linear issues are the **queue item** the orchestrator actually reads. Each Linear issue carries the scope, the acceptance checklist, the verify command and a "do not" section, and links back to its GitHub spec.
+
+## Workstream map
+
+| Workstream | Linear | GitHub spec | Start state | Blocked by |
+| --- | --- | --- | --- | --- |
+| KR-07 Retrieval benchmark and CI gate | AGE-1660 | [#176](https://github.com/AgentsKit-io/doc-bridge/issues/176) | Todo, Urgent | — |
+| KR-01 Lexical ranking and full corpus | AGE-1661 | [#170](https://github.com/AgentsKit-io/doc-bridge/issues/170) | Todo, High | — |
+| KR-02 Markdown analyzer on remark | AGE-1662 | [#171](https://github.com/AgentsKit-io/doc-bridge/issues/171) | Todo, High | — |
+| KR-03 Code areas and area scope | AGE-1663 | [#172](https://github.com/AgentsKit-io/doc-bridge/issues/172) | Todo, High | — |
+| KR-05 Per-entity hashes, incremental scan | AGE-1664 | [#174](https://github.com/AgentsKit-io/doc-bridge/issues/174) | Todo, High | — |
+| KR-04 Graph layer on graphology | AGE-1665 | [#173](https://github.com/AgentsKit-io/doc-bridge/issues/173) | Backlog | KR-02, KR-03 |
+| KR-06 Retrieval projection and ranking | AGE-1666 | [#175](https://github.com/AgentsKit-io/doc-bridge/issues/175) | Backlog | KR-01…KR-05 |
+| KR-08 Budgeted MCP tools, measured doctor | AGE-1667 | [#177](https://github.com/AgentsKit-io/doc-bridge/issues/177) | Backlog | KR-06, KR-07 |
+| KR-09 Markdown renderings on knap | AGE-1668 | [#178](https://github.com/AgentsKit-io/doc-bridge/issues/178) | Backlog | KR-03, KR-05, KR-06 |
+| KR-10 Enrichment overlay | AGE-1669 | [#179](https://github.com/AgentsKit-io/doc-bridge/issues/179) | Backlog | KR-04, KR-05, KR-06 |
+| KR-11 Overlay stats, assisted study arm | AGE-1670 | [#180](https://github.com/AgentsKit-io/doc-bridge/issues/180) | Backlog | KR-07, KR-10 |
+
+## One workstream at a time
+
+Two mechanisms, both deliberate:
+
+1. **`machine.ceiling: 1`.** The loop admits at most one worker regardless of how many CPUs or how much RAM the machine has. Six of the eleven workstreams extend a contract an earlier one defines (the retrieval projection, the ranking formula, the proposal schema), so two concurrent workers would write conflicting schemas.
+2. **Dependency gating through Linear state.** `linear.states: [Todo, Ready]` is the dispatchable set. A blocked workstream sits in **Backlog**, which the loop never reads, and carries a `blockedBy` relation so the reason is visible in Linear. Priority orders the five that are dispatchable today.
+
+**Promoting a workstream** when its dependencies have merged: move it from Backlog to Todo in Linear. Nothing else is needed; the next tick picks it up. Never promote a workstream whose `blockedBy` issues are not yet Done: its contract would be frozen against code that does not exist.
+
+## Prerequisites on the operating machine
+
+None of these live in this repository, and the loop doctor blocks on the first two.
+
+| Requirement | Why | Check |
+| --- | --- | --- |
+| Orca runtime at or above 1.4.200 | worktrees, terminals, Linear access, scheduling | `orca --version`, `orca status --json` |
+| `ak-harness` resolvable in Orca's environment | the scheduled automations invoke it | `npm i -g @agentskit/harness` |
+| `agentskit-review` on PATH | the deliver stage reviews every green head before merge | `agentskit-review --help` |
+| `gh` authenticated | pull request status and the merge call | `gh auth status` |
+| At least one provider CLI logged in | orchestrator, builder, reviewer and watcher roles | `claude`, `codex`, `grok` or `opencode` |
+| A built Doc Bridge index in the main checkout | deterministic context for the orchestrator | `node bin/ak-docs.js index` |
+
+`orca.bin` is set to `orca`. **On Linux outside an Orca terminal, change it to `orca-ide`**: bare `orca` is the GNOME screen reader and the doctor will report that it did not answer `--version`.
+
+The Doc Bridge index is gitignored, so a fresh clone has none until `ak-docs index` runs. `contract.docBridgeMaxAgeHours` (168) warns when it goes stale, and `contract.requireDocBridge` is `false`, so a missing index degrades context rather than blocking a dispatch. That default is deliberate for these workstreams: their whole point is that Doc Bridge retrieval is currently weak. Revisit it once KR-01 and KR-06 have merged.
+
+## First run
+
+```bash
+# from the main checkout
+cp loop.config.example.yaml loop.config.yaml          # then fill in the linear: identity block
+node bin/ak-docs.js index                                  # deterministic context for the orchestrator
+ak-harness loop validate -f loop.config.yaml               # schema + effective config + hash
+ak-harness loop doctor   -f loop.config.yaml --json        # readiness; exit 1 on a blocking check
+ak-harness loop tick --dry-run --max 1                     # plan one dispatch, print the orca argv, write nothing
+```
+
+`loop install` is the guided path: it offers to create the gitignored `loop.config.local.yaml` overlay, runs the doctor and the automation-environment checks, offers a dry-run rehearsal, and only then creates the two Orca automations (`loop-docbridge-tick` and `loop-docbridge-deliver`). Both run under `schedule.runner: precheck`, so the stage *is* the precheck command: Orca records each run as `skipped_precheck` with the report in its output and never opens an agent session.
+
+```bash
+ak-harness loop install -f loop.config.yaml                # guided; --dry-run to see the plan only
+ak-harness loop status                                     # what Orca knows: enabled, trigger, last run
+```
+
+## Daily operation
+
+```bash
+ak-harness loop debrief                    # in flight, held, escalated, cooldowns — reads local state only
+ak-harness loop watch --issue AGE-1661     # DONE | FAILED | ACTION_REQUIRED | PROGRESS
+ak-harness loop paused                     # workstreams auto-paused after repeated failures
+ak-harness loop resume AGE-1661            # clear a pause, or remove the loop:paused label in Linear
+ak-harness loop retro --since 7d           # digest plus one knob to turn in loop.config.yaml
+```
+
+`loop debrief` touches neither Orca nor `gh`, so it is safe from a session hook or a chat agent that needs context before acting.
+
+## What a human still decides
+
+- **Promoting a blocked workstream** out of Backlog. The loop never reorders its own queue.
+- **Anything touching `delivery.selfEditPaths`.** A pull request that edits `loop.config.yaml`, `.github/**`, `.codex/verification.json` or the PRD is held with a comment and never auto-merged, even with a clean review.
+- **A workstream that exhausts `maxFixRounds` (2).** It is labelled `blocked`, commented, returned to Todo, and its worktree and pull request are kept for inspection.
+- **A `needs-info` escalation.** The orchestrator could not freeze a contract with at least one executable outcome and no blocking ambiguity, so it commented instead of consuming a slot. Usually the Linear description needs a decision a human owns.
+- **Review findings the loop cannot resolve.** `delivery.review.minSeverity: med` is the floor that blocks auto-merge.
+
+## Configuration notes specific to this repository
+
+| Setting | Value | Why |
+| --- | --- | --- |
+| `delivery.verifyCommand` | `pnpm typecheck && pnpm test` | doc-bridge has no `lint` script; this is what CI enforces on `master` |
+| `project.setup.command` | `pnpm install --frozen-lockfile` | a fresh Orca worktree has no `node_modules`; without it every dispatch loses its first minutes |
+| `contract.briefScopes` | `[agent-corpus]` | `corpus.agent.root` is `docs/agent-corpus`, the only surface in the index, so it is the only scope worth listing in a brief |
+| `brief.skills` | `CONTRIBUTING.md`, `docs/for-agents.md`, `docs/agent-corpus/OVERVIEW.md`, `docs/skills/doc-bridge.md` | pinned verbatim and hashed into `dispatch.json`; a missing path fails the dispatch rather than sending a worker without promised guidance. This repository has no root `AGENTS.md`, so the routing convention comes from the corpus overview |
+| `models.effort.builder` | `high` | these workstreams are contract-heavy (schema compatibility, hashing, determinism); a wrong contract costs a full fix round |
+| `memory.enabled` | `false` | no approved learnings exist yet; enable after the first `loop retro` promotes some |
+
+`loop.config.yaml`, `loop.config.local.yaml` and `.codex/loop/` are all gitignored: the first identifies a Linear workspace and person, the second is machine-specific (queue owner, RAM reserve, worker ceiling), and the third is runtime state (ledger, contracts, cooldowns, `events.ndjson`). Only `loop.config.example.yaml` is tracked, so a change to the tuned settings is reviewable without publishing anyone's identifiers. When you change a tuned setting locally, mirror it into the example file; a pull request touching either is held by `delivery.selfEditPaths` and never auto-merged.

package/docs/mcp.md

@@ -61,12 +61,17 @@ The stdio server accepts the newline-delimited JSON transport used by current MC
 | Tool | Purpose |
 |------|---------|
 | `handoff.resolve` | Package/ownership → AgentHandoff |
-| `doc.search` | Deterministic index search |
+| `doc.search` | Deterministic index search; set `agent: true` with `mode` and `contextBudgetTokens` for bounded agent context |
 | `doc.get` | Read an indexed agent doc |
 | `gate.status` | Freshness / configured gates |
 | `retriever.query` | Local retriever chunks |
 | `memory.classify` / `memory.promoteDraft` | Memory pipeline |
 | `registry.topology` | Static curator and delegate topology |
+| `knowledge.search` | Ranked entries for a query, by kind, explained, within a `budgetTokens` |
+| `knowledge.lookup` | One entity with neighbours, documents, handoff, open diagnostics and evidence, within a `budgetTokens` |
+| `docbridge.diagnostics { format: 'finding' }` | Diagnostics as ecosystem `Finding`s |
+
+Budgets, the drop order and the lookup shape are specified in [MCP knowledge tools v1](./spec/mcp-knowledge-tools-v1.md).
 
 Every tool is annotated read-only. None of these MCP calls writes project files or publishes a memory promotion.
 

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

@@ -0,0 +1,145 @@
+{
+  "type": "public-claims",
+  "schemaVersion": 1,
+  "registryVersion": "v1",
+  "claims": [
+    {
+      "claimId": "study-token-reduction",
+      "statement": "The published A/B round measured fewer paired provider token-equivalent units for the deterministic arm",
+      "owner": "platform",
+      "valueType": "percent",
+      "template": "{value}% fewer paired provider token-equivalent units",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "field": "pairedDeltas.providerTokenCostUnitsRelative",
+        "transform": "negative-percent-2dp"
+      },
+      "required": [
+        "README.md",
+        "docs/study/README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the figure from pairedDeltas.providerTokenCostUnitsRelative in the published A/B result, on every surface that quotes it."
+    },
+    {
+      "claimId": "study-token-pairs",
+      "statement": "The token comparison rests on the token-complete pairs the round recorded",
+      "owner": "platform",
+      "valueType": "number",
+      "template": "across {value} token-complete pairs",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "field": "pairedDeltas.providerTokenPairCount"
+      },
+      "required": [
+        "README.md",
+        "docs/study/README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the pair count from pairedDeltas.providerTokenPairCount; a denominator that drifts makes the percentage unreadable."
+    },
+    {
+      "claimId": "study-completion-bridge",
+      "statement": "Operational completion in the deterministic Doc Bridge arm",
+      "owner": "platform",
+      "valueType": "percent",
+      "template": "{value}% operationally completed executions",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "field": "arms.1.completedRate",
+        "transform": "percent-1dp"
+      },
+      "templates": {
+        "docs/study/README.md": "Operational completion was {value}% versus"
+      },
+      "required": [
+        "README.md",
+        "docs/study/README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the completion rate from arms[1].completedRate in the published A/B result."
+    },
+    {
+      "claimId": "study-completion-baseline",
+      "statement": "Operational completion in the repository-only arm",
+      "owner": "platform",
+      "valueType": "percent",
+      "template": "operationally completed executions vs. {value}%",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "field": "arms.0.completedRate",
+        "transform": "percent-1dp"
+      },
+      "templates": {
+        "docs/study/README.md": "versus {value}%"
+      },
+      "required": [
+        "README.md",
+        "docs/study/README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the baseline completion rate from arms[0].completedRate; a comparison needs both arms."
+    },
+    {
+      "claimId": "study-latency-p95",
+      "statement": "The P95 latency difference the round measured",
+      "owner": "platform",
+      "valueType": "number",
+      "template": "{value} seconds lower P95 latency",
+      "evidence": {
+        "kind": "artifact-field",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "field": "pairedDeltas.latencyP95Ms",
+        "transform": "negative-seconds-2dp"
+      },
+      "required": [
+        "docs/study/README.md"
+      ],
+      "optional": [
+        "README.md"
+      ],
+      "severity": "error",
+      "remediation": "Restate the P95 difference from pairedDeltas.latencyP95Ms, in seconds, and drop the word \"lower\" if the sign ever turns."
+    },
+    {
+      "claimId": "study-executions",
+      "statement": "The size of the published controlled round",
+      "owner": "platform",
+      "valueType": "number",
+      "template": "controlled A/B study with {value} executions",
+      "evidence": {
+        "kind": "artifact-sum",
+        "path": "docs/study/ab-adjudicated-cost-result-v1.json",
+        "arrayField": "arms",
+        "field": "observationCount"
+      },
+      "required": [
+        "docs/study/README.md"
+      ],
+      "severity": "warn",
+      "remediation": "Restate the execution count as the sum of both arms' observationCount in the published A/B result."
+    },
+    {
+      "claimId": "cli-parity-command",
+      "statement": "The CLI offers the parity gate this registry drives",
+      "owner": "platform",
+      "valueType": "text",
+      "evidence": {
+        "kind": "cli-command",
+        "command": "ak-docs parity"
+      },
+      "required": [
+        "docs/spec/cli.md"
+      ],
+      "severity": "error",
+      "remediation": "Document `ak-docs parity` in the CLI reference, or remove the command."
+    }
+  ],
+  "exceptions": [],
+  "contentHash": "e188a7b2776a3c7c495016b462fd2c053faec9d29d0b824b607458b922fbd118",
+  "contentHashAlgo": "sha256-normalized-v1"
+}

package/docs/playbook/doc-bridge-pattern.md

@@ -77,7 +77,7 @@ Agents call `handoff.resolve` before editing `packages/*`:
 ## CI gate
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.4.0
+- uses: AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 # v1.7.45
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.

package/docs/query.md

@@ -5,7 +5,7 @@ description: Deterministic ownership and documentation lookup — no model, no r
 
 # Query
 
-The query layer reads `.doc-bridge/index.json` only. It does **not** re-scan the repository and does **not** call a model.
+The query layer reads `.doc-bridge/index.json` and performs a deterministic freshness check against the current repository inputs. It does **not** call a model. CLI and MCP query surfaces reject stale indexes before returning results; when it is stale, run `ak-docs index` first.
 
 ## Commands
 
@@ -32,9 +32,96 @@ An **AgentHandoff** (v1) with stable fields:
 | `editRoots` | Allowed write paths |
 | `checks` | Verification commands |
 | `humanDoc` | Parallel human documentation |
+| `related` | The areas this unit's code depends on and that depend on it, with the import that proves each |
+| `explain` | Which relation produced each field |
+
+A handoff answers for a package, an area, a module or a document — by ownership id, entity id,
+alias or path (`ak-docs query ownership src/query --agent` works). `startHere` is the document that
+covers the target, then one that mentions it, then one linking to those; `checks` report their
+origin in `metadata.checksSource`. See [Retrieval index v1](./spec/retrieval-index-v1.md#handoffs-for-any-entity).
 
 Schema: [AgentHandoff v1](./schemas/agent-handoff-v1.md) · Index: [DocBridgeIndex v1](./schemas/doc-bridge-index-v1.md)
 
+`ak-docs search <term> --agent` returns a bounded **AgentSearch** payload. The
+default discovery mode keeps up to eight matches; task-specific modes reduce
+that ceiling further:
+
+```bash
+ak-docs search "authentication" --agent --mode=editing --context-budget=128
+```
+
+Supported modes are `discovery`, `editing`, `debugging`, and `documentation`.
+`context-budget` is measured in estimated tokens for the selected matches and
+next commands. Summaries and follow-up commands are removed before matches are
+dropped. If even the minimum grounded result does not fit, the command fails
+closed instead of exceeding the budget. The response telemetry reports
+`contextBudgetTokens`, `mode`, and `truncated` so a benchmark can distinguish
+an intentionally bounded result from a complete result.
+
+Agent searches default to a compact 32-token budget. Increase it explicitly
+when the task requires additional alternatives or follow-up commands.
+
+The agent shape omits ranking scores because they are diagnostic, not routing
+instructions. `telemetry.contextBytes` and `telemetry.estimatedTokens` measure
+only the selected context fields; `tokenMethod: "estimate"` is explicit and
+must not be reported as provider usage.
+
+Natural-language discovery is deterministic as well: terms such as `find package`
+can resolve a declared intent route, while change-oriented queries such as
+`change zod schema` can resolve a declared change route. When one of these
+routes is the best match, the agent payload is focused on up to three routes of
+that type and provides the corresponding follow-up command. A change route is
+demoted when the query expresses no change intent, so it stays reachable when
+nothing better matches without crowding an ordinary question.
+
+## How results are ranked
+
+Ranking is deterministic — no model, no embeddings — and reads the
+[retrieval projection](./spec/retrieval-index-v1.md) of the snapshot: every document, module,
+area and package discovery observed, plus the routes the configuration declares. Each result carries
+evidence, provenance and a confidence.
+
+**Evidence** is field-weighted BM25 over each entry's title, headings, exported symbols, path,
+aliases, summary and body. BM25 is what makes a term appearing in nearly every document worth almost
+nothing, and a term in a short title worth more than the same term buried in a long body. Weights
+and parameters are [configuration](./spec/config-v1.md#retrieval-optional), recorded in the index
+so a retuned ranking is a visibly different artifact.
+
+**Identity** boosts a record the query names rather than describes: an exact id or alias, an exact
+file path, a directory, or an exported symbol. This is why `reconcileKnowledge` resolves to the
+module that exports it and `src/mcp/server.ts` resolves to that file, instead of to whichever
+document mentions them most often.
+
+**Graph** signals come from the snapshot's relations: proximity to what the query clearly found,
+and canonicality — the page other pages point at outranks the leaf that mentions the same thing.
+
+**Priors** nudge toward the kind of record the query shape asks for — an ownership route for a
+routing question, a module for a symbol or path, a document for a sentence. They multiply the
+evidence rather than adding to it, so a favoured record still needs a real match: a prior can
+never invent an answer, only order the ones that exist.
+
+Results below a third of the best score are dropped. Retrieval exists to spend fewer tokens, and
+a list of weak matches spends them for nothing.
+
+`ak-docs search <term> --explain` names every scoring component with its contribution and the
+terms that matched in each field, so a wrong ranking is reportable as a bug rather than argued as
+an opinion. Explaining never changes the ranking.
+
+### What the lexicon does
+
+Queries and indexed text go through one tokenizer, so a term can never be present on one side and
+absent on the other:
+
+- English and Portuguese stopwords are dropped, which is why `search and` returns nothing at all
+- `reconcileKnowledge` also indexes `reconcile` and `knowledge`; `src/mcp/server.ts` also indexes
+  its segments
+- accents fold, so `reconciliação` and `reconciliacao` are the same term
+- plurals collapse, so `schema` finds `schemas`
+- CJK text, which has no spaces, is indexed by character and character bigram
+
+The lexicon's version is recorded in `index.retrieval.lexiconVersion` and is part of the index
+content hash, so changing it is a new artifact rather than a silent change of behaviour.
+
 ## When to use which surface
 
 | Need | Surface |
@@ -48,10 +135,11 @@ Schema: [AgentHandoff v1](./schemas/agent-handoff-v1.md) · Index: [DocBridgeInd
 
 - Same inputs → same handoff JSON (deterministic)  
 - Breaking field meaning requires a **new schema version**, not silent reinterpretation of v1  
-- Gate/CI can require a fresh index so agents never see stale ownership  
+- Query surfaces and Gate/CI require a fresh index so agents never receive stale ownership
 
 ## Related
 
+- [Retrieval benchmark](./bench/README.md) — what "the right result" measures, and the gate  
 - [Guide: Index and query](./guides/index-and-query.md)  
 - [For agents](./for-agents.md)  
 - [CLI reference](./spec/cli.md)  

package/docs/recipes/index-pipeline.md

@@ -71,7 +71,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.4.0
+- uses: AgentsKit-io/doc-bridge@ee756a13c006c597445c31e2643c1e8cece715d7 # v1.7.45
 ```
 
 Or manual:

package/docs/schemas/agent-handoff-v1.md

@@ -26,6 +26,21 @@ Portable JSON Schema export: `AgentHandoffV1JsonSchema`.
 }
 ```
 
+## Optional additions
+
+`related`, `explain`, `evidence` and `metadata` are optional, and `target.type` also accepts `area`
+and `document`. A handoff written without them is still a valid handoff, and a reader that predates
+them sees the same fields it always did.
+
+```json
+{
+  "related": [{ "id": "area:src/ranking", "path": "src/ranking", "direction": "imports", "strength": 3, "evidence": ["src/query/search.ts → src/ranking/bm25.ts"] }],
+  "explain": { "startHere": ["covers area:src/query"], "checks": ["routing.options.ownership.doc-bridge-query.checks"] },
+  "evidence": [{ "source": "derived", "path": "src/query", "contentHash": "…" }],
+  "metadata": { "entityId": "area:src/query", "kind": "area", "checksSource": "ownership", "confidence": "observed" }
+}
+```
+
 ## Legacy compatibility
 
 Legacy `--agent` payloads may omit `schemaVersion`. Use `normalizeAgentHandoff()` or `safeParseAgentHandoff()` to upgrade.

package/docs/schemas/doc-bridge-index-v1.md

@@ -25,6 +25,24 @@ Portable JSON Schema export: `DocBridgeIndexV1JsonSchema`.
       "title": "Authentication",
       "path": "docs/for-agents/auth.md",
       "description": "Auth ownership and edit workflow."
+    },
+    {
+      "id": "document:docs/auth.md",
+      "type": "document",
+      "title": "Authentication",
+      "path": "docs/auth.md",
+      "description": "How sign-in works.",
+      "tags": ["document", "human"],
+      "contentHash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
+    },
+    {
+      "id": "module:packages/auth/src/session.ts",
+      "type": "module",
+      "title": "session.ts",
+      "path": "packages/auth/src/session.ts",
+      "symbols": ["createSession", "revokeSession"],
+      "tags": ["module", "ts", "src"],
+      "contentHash": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"
     }
   ],
   "handoffs": {
@@ -50,10 +68,55 @@ Portable JSON Schema export: `DocBridgeIndexV1JsonSchema`.
         "agentDoc": "docs/for-agents/auth.md"
       }
     }
+  },
+  "inputs": {
+    "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+    "fileCount": 318,
+    "projectionVersion": 1
+  },
+  "retrieval": {
+    "lexiconVersion": 1,
+    "weights": { "id": 8, "symbols": 7, "title": 6, "path": 4, "tags": 3, "description": 2, "body": 1 },
+    "params": { "k1": 1.2, "b": 0.75 }
   }
 }
 ```
 
+## Entry kinds
+
+`knowledge` holds two kinds of record, and ranking treats them differently.
+
+**Curated** entries (`type: "agent-doc"`) come from the agent corpus a human wrote. They are what
+`llms.txt` lists, and ranking favours them slightly, because they were authored to be the answer
+to a question.
+
+**Projected** entries (`type: "document"` or `"module"`) are every documentation file and source
+module the [discovery snapshot](../knowledge-engine-runbook.md) observed, projected from it rather
+than scanned again, so the two cannot disagree about what exists. A module carries its exported
+`symbols`; both carry the `contentHash` of the file they were projected from, so a single stale
+entry is detectable without rebuilding. Body text is not here: it lives once, in the projection.
+`retrieval.corpus.enabled: false` omits them.
+
+## Projection
+
+`projection` is the [retrieval index](../spec/retrieval-index-v1.md): what search ranks. It holds
+every snapshot entity — documents, modules, areas, packages — and the routes the configuration
+declares, each with the text the ranker indexes, its graph position, its content hash, provenance
+and confidence. It is a pure function of the snapshot, the accepted overlay and the configuration,
+and its `contentHash` is over those three inputs. `knowledge[]` above stays in step with it for
+readers that predate it.
+
+## Freshness
+
+`inputs` fingerprints the repository the index was built from: every input file and its content
+hash, plus the configuration sections the index derives from, hashed together. Query surfaces
+verify freshness by re-hashing those inputs rather than rebuilding the index, which is what keeps
+a search cheap on a large repository. `retrieval.lexiconVersion` is checked too, because a changed
+stopword list changes ranking without changing a single file.
+
+An index written before `inputs` existed is still validated, by the full rebuild-and-compare it
+always used.
+
 ## Content Hash
 
 `contentHashAlgo` is `sha256-normalized-v1`.
@@ -64,6 +127,8 @@ The hash input is deterministic JSON containing only:
 - `knowledge`
 - `handoffs`
 - `lookup`
+- `retrieval`
+- `inputs` (when the corpus projection is enabled)
 
 `generatedAt` is not part of the hash input. When the hash is unchanged, `ak-docs index` preserves the existing `generatedAt` so regenerated `index.json` bytes stay stable.
 

package/docs/spec/benchmark-v1.md

@@ -27,4 +27,42 @@ The fixture contains only stable identifiers and explicitly supported cases:
 
 The observation contains the same three sets, plus optional evidence identifiers and finding-category counts. The result reports true positives, false positives, false negatives, precision, recall, duplicate observations, evidence ratio, finding density, excluded cases, thresholds, and regressions. Excluded cases are removed from denominators only because they are explicitly listed and their counts remain visible.
 
-Benchmark output is aggregate by default: it does not include repository contents, prompts, credentials, or the member lists used to calculate the result. Baselines are not changed by `benchmark` or by a verification run. Use the verification harness's explicit audited baseline command when a new baseline is intentionally approved.
+Benchmark output is aggregate by default: it does not include repository contents, prompts, credentials, or the member lists used to calculate the result. Baselines are not changed by `benchmark` or by a verification run. When a new baseline is intentionally approved, use the study tooling's separate audited baseline operation and record its artifact hash and human decision; the official `@agentskit/harness@0.9.0` verification CLI does not replace baselines.
+
+## Deterministic agent retrieval gate
+
+The query contract also measures the real `--agent` payload for a fixed query
+fixture. It records hit rate, p95 estimated tokens, p95 response bytes, and
+context reduction relative to the indexed fixture. This proves bounded,
+repeatable retrieval behavior; it does not prove that a model completed a
+semantic task correctly or that estimated tokens equal provider usage.
+
+The task-efficiency contract adds a separate, deterministic layer: each fixed
+task declares an expected evidence identifier, and the benchmark records task
+count, exact-evidence correctness rate, p95 tokens/bytes, and p95 tokens/time
+among correctly grounded tasks. A retrieval hit is not automatically a task
+success. These fixture results measure whether the bounded context is
+sufficient for the declared task; they are not LLM semantic-success data.
+
+The repository verification contract runs the same class of check through the
+real CLI artifact (`scripts/agent-task-efficiency-check.mjs`). This is a
+required regression gate for bounded retrieval and measurement, but it remains
+separate from semantic adjudication of an agent's prose or implementation.
+
+The CLI check also records p95 wall-clock latency for each isolated baseline and
+optimized invocation. These latency values are operational measurements, not a
+claim that the optimized context is faster: process startup, indexing, and host
+load are included, so latency must be compared separately from token and
+context-size reduction. The provider pilot independently records process
+duration and time to the first observed tool event; neither is a semantic
+correctness metric.
+
+## Semantic reconciliation gate
+
+The semantic gate runs labeled, synthetic cases through the real reconciliation implementation. The required v1 cases are `confirmed`, `undocumented`, `stale`, `not-analyzed`, `conflict`, and `unresolved`. Each case declares its exact expected diagnostic-code set and requires every emitted diagnostic to contain evidence.
+
+The gate is passing only when finding precision, finding recall, and evidence ratio are all `1.000`, with no regressions. The conflict case may legitimately emit the additional `RELATION_CONFIRMED` and `RELATION_NOT_ANALYZED` diagnostics because both declarations are evaluated independently; the expected set records that behavior explicitly. These cases prove classifier behavior, not coverage of every language analyzer or runtime-only relationship.
+
+Study task success also requires exact coverage of the task's required evidence
+identifiers. Matching only the number of evidence items is insufficient and is
+treated as partial, preventing inflated correctness or token-efficiency claims.