@agentskit/doc-bridge 1.6.4 → 1.7.45

package/docs/spec/config-v1.md

@@ -7,6 +7,10 @@ description: Configure documentation corpora, ownership routing, conformance, an
 
 `doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the alpha integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.
 
+Reconciliation summaries also expose deterministic `diagnosticsByCode` and
+`diagnosticsByStatus` maps. They are additive rollups for agents and dashboards;
+the canonical `diagnostics` array remains the source of evidence.
+
 | npm package | `@agentskit/doc-bridge` |
 | CLI binary | `ak-docs` |
 | Config file | `doc-bridge.config.ts` |
@@ -34,6 +38,12 @@ package.json → "docBridge" field (subset, JSON only)
 
 TypeScript/JavaScript configs are static in v0.1 alpha: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.
 
+Dynamic-loading coverage is evidence-backed. Literal strings, constant aliases,
+parenthesized strings, and string concatenations are resolved without executing
+repository code. Runtime-dependent `import()` and `require()` expressions remain
+`partial`/`not-analyzed`, and the coverage entry records representative
+file-and-line evidence for each observed loading site (up to the schema limit).
+
 ## TypeScript shape (authoritative)
 
 ```ts
@@ -71,6 +81,18 @@ export default {
 
   /** Optional deterministic documentation conformance profiles */
   conformance?: ConformanceConfig
+
+  /** Optional language analyzers and runtime-wiring coverage */
+  analysis?: AnalysisConfig
+
+  /** Optional reconciliation scope and orphan-document policy */
+  reconciliation?: ReconciliationConfig
+
+  /** Optional resumable workflow state */
+  workflow?: WorkflowConfig
+
+  /** Optional report publication privacy; private is the default */
+  report?: { privacy?: 'private' | 'anonymized' }
 } satisfies DocBridgeConfigV1
 ```
 
@@ -386,6 +408,122 @@ report status, commands, and the recorded stable-publication HITL decision.
 
 ---
 
+## `reconciliation` (optional)
+
+```ts
+type ReconciliationConfig = {
+  /** Semantic comparison level; discovery still preserves raw file relations. */
+  scope?: 'file' | 'module' | 'package'
+  /** Observed relation kinds that require documentation declarations. */
+  requiredRelationKinds?: string[]
+  /** Limit missing-declaration findings to relations between internal project entities. */
+  requiredRelationTargets?: 'all' | 'internal'
+  /** Emit info findings for documentation with no observed package/module join. */
+  includeOrphanedDocuments?: boolean
+}
+```
+
+Use `scope: 'package'` for monorepos where file imports should be compared as package-level architecture evidence. Omit `requiredRelationKinds` to require all observed kinds; an empty array intentionally disables undocumented-relation findings and must be treated as an explicit exemption.
+
+Use `requiredRelationTargets: 'internal'` when the repository wants package or module architecture declarations without requiring Markdown to enumerate every external library import. External relations remain in the raw snapshot and report as evidence; they simply do not generate missing-declaration findings.
+
+The reconciliation documentation summary reports package health separately from
+relation findings: `fresh` means the package has coverage documentation and no
+known discrepancy; `stale` means a declared relation conflicts with observed
+architecture; `missing` means no coverage document was found; and `unverified`
+means coverage exists but at least one relevant relation or analyzer boundary
+could not be verified. Package-level aggregation preserves the relation
+endpoints used for this classification, so an undocumented relation cannot be
+reported alongside a falsely `fresh` package.
+
+The same summary keeps document inventory separate from coverage claims:
+`documentCount` and `documentClassificationCounts` describe every discovered
+Markdown document, while `documentedDocumentCount` and
+`documentedDocumentClassificationCounts` describe documents that declare a
+knowledge relation. The classification keys are analyzer output (for example
+`agent`, `human`, `project`, `archive`, and `unclassified`); consumers must not
+interpret total repository Markdown coverage as agent-corpus coverage. Use the
+`agent` pair when measuring the configured agent documentation surface.
+
+## `report` (optional)
+
+```ts
+report?: {
+  /** Replace project identity, names, paths, snippets, and finding text in HTML output. */
+  privacy?: 'private' | 'anonymized'
+}
+```
+
+`private` is the default and keeps local evidence useful for debugging. `anonymized` is intended for reports shared outside the repository: it preserves counts, relation kinds, topology, and coverage status while removing project-specific identity and evidence content. The generated HTML and every lazy chunk use the same mode.
+
+## `safety` (optional)
+
+```ts
+type RepositorySafetyConfig = {
+  /** Additional project-relative glob patterns excluded from repository discovery. */
+  exclude?: string[]
+  maxFiles?: number
+  maxBytes?: number
+  maxTimeMs?: number
+  maxMemoryMb?: number
+  redactSecrets?: boolean
+}
+```
+
+Discovery always excludes unsafe or generated trees by default, including
+`.git`, `node_modules`, `dist`, `build`, `coverage`, `.doc-bridge`, `.next`,
+`out`, `.turbo`, `.svelte-kit`, `.mcpb-build`, and `.mcpb-output`, plus common
+secret files. `safety.exclude` adds project-specific patterns; it does not
+replace the built-in safety boundary. Excluded files remain outside the
+snapshot and are represented by analyzer coverage when relevant.
+
+## `analysis` (optional)
+
+```ts
+type AnalysisConfig = {
+  /** Ordered language/framework analyzer plugins. */
+  plugins?: Array<{
+    id: string
+    enabled?: boolean
+    order?: number
+    options?: Record<string, unknown>
+    reason?: string
+  }>
+  jsTs?: {
+    /** Property-access methods considered runtime wiring entry points. */
+    runtimeWiringMethods?: string[]
+    /** Additional adapter methods that represent runtime wiring. */
+    runtimeWiringAdapters?: Array<{ id: string; methods: string[] }>
+    /** Include test/spec modules in runtime-wiring coverage. Default: false. */
+    includeTestRuntimeWiring?: boolean
+  }
+}
+```
+
+The JS/TS analyzer defaults to `register`, `use`, `mount`, and `attach`.
+Generic APIs such as `bind` and `listen` are intentionally opt-in to avoid
+classifying ordinary function binding and server startup as architecture.
+When a configured method receives an identifier bound to a
+static import, Doc Bridge records a `runtime-wiring` relation with
+`metadata.detection: 'runtime-wiring-static'`. Reflective, computed, or
+otherwise unbound targets remain explicit `not-analyzed` coverage entries.
+Dynamic `import()` and `require()` targets are resolved when their specifier is
+a literal, a `const` string binding, a parenthesized static expression, or a
+concatenation of other statically known strings. Expressions that depend on
+runtime values remain explicit `not-analyzed` coverage entries; Doc Bridge does
+not execute repository code to guess their targets.
+Test/spec modules are excluded from this signal by default because their
+registrations usually construct fixtures rather than production architecture;
+set `includeTestRuntimeWiring: true` when test wiring is part of the contract.
+This keeps runtime behavior useful without claiming that arbitrary dependency
+injection or reflection was resolved. Analyzer plugins must implement the
+versioned contract in `docs/spec/analyzer-plugin-v1.md`; malformed or
+unsupported output remains explicit `not-analyzed` evidence.
+
+`workflow.stateDir` optionally relocates the content-addressed workflow
+artifacts. Runs are resumable and idempotent; pipeline and analyzer versions
+are part of the run identity.
+
 ## `surfaces` (optional)
 
 ```ts
@@ -466,6 +604,18 @@ type IntelligenceConfig = {
   /** Reference runtime; custom path for non-AgentsKit engines later */
   runtime?: 'agentskit' | 'custom'
   runtimeModule?: string
+
+  registry?: {
+    enabled?: boolean
+    agentId?: string
+    agentRoot?: string
+    runnerModule?: string
+    deterministic?: boolean
+    timeoutMs?: number
+    maxTokens?: number
+    maxResponseBytes?: number
+    maxConcurrency?: number
+  }
 }
 
 type MemoryAdapterId =
@@ -475,6 +625,12 @@ type MemoryAdapterId =
   | 'bootstrap-delta'              // git diff on AGENTS.md
 ```
 
+Registry agents are advisory and must come from the AgentsKit Registry. The
+adapter redacts secrets, validates the proposal contract, bounds execution and
+response size, and requires human approval before any change is applied. The
+default agent is `ecosystem-doc-bridge-corpus-scanner`; compatible Registry
+agents may be selected explicitly.
+
 ---
 
 ## `federation` (optional — ecosystem)

package/docs/validation-cycle-plan.md

@@ -0,0 +1,255 @@
+---
+title: Doc Bridge validation cycle plan
+description: Evidence-driven validation of Doc Bridge against the AgentsKit OS repository.
+---
+
+# Doc Bridge validation cycle plan
+
+## Objective
+
+Validate the complete Doc Bridge change against `agentskit-os`, not only the published package or the HTML report. The validation must prove the bridge between repository structure, documentation, agents, and humans:
+
+1. repository architecture is discovered at package, module, and file levels;
+2. documentation is classified, indexed, and checked for freshness;
+3. documentation claims are reconciled with observed code relationships;
+4. disconnected, stale, conflicting, unresolved, and not-analyzed areas are visible;
+5. the Registry agent proposes grounded follow-up work without becoming an unverified authority;
+6. the report makes those results useful and navigable;
+7. runs are reproducible, resumable, versioned, idempotent, and cost-bounded.
+
+This plan is a validation contract. A green result from one cycle never substitutes for a missing cycle.
+
+## Evidence rules
+
+- Every result is tied to the source revision, configuration hash, snapshot hash, report hash, and verification run ID.
+- `not-analyzed` is visible and counts against coverage unless an explicit, human-approved exemption exists.
+- Unit tests and compilation are supporting evidence. They do not prove repository behavior, documentation agreement, endpoint/database behavior, or UI behavior.
+- Deterministic agent runs and assisted agent runs are separate evidence classes. Deterministic output proves replayability; it does not prove semantic quality.
+- No agent proposal is applied without human approval and a fresh post-apply verification run.
+
+## Cycle gates and success metrics
+
+### Cycle 0 — Contract and scope gate
+
+**Purpose:** map the human request to verifiable outcomes before changing the product or narrowing the target.
+
+**Required evidence:** task contract, acceptance matrix, repository/surface matrix, explicit exemptions, validation budget, and the decision for architecture declaration granularity.
+
+**Success metrics:**
+
+- 100% of requested outcomes mapped to one or more executable checks;
+- 0 unresolved scope, authorization, or behavior ambiguities;
+- 0 unapproved surface exclusions;
+- 100% of required checks have an evidence location and an expected result;
+- the contract names what the report must show for architecture, stale docs, doc/code drift, disconnected areas, Registry proposals, and UI.
+
+**Stop condition:** any unmapped outcome returns the task to `CLARIFYING`.
+
+### Cycle 1 — Real consumer and reproducibility
+
+**Purpose:** prove the published package is the artifact used by `agentskit-os` and that the pipeline is repeatable.
+
+**Checks:** install the declared package version, run discovery, index, reconcile, check, report, and Registry agent using the target repository.
+
+**Success metrics:**
+
+- installed version equals the declared and published version;
+- two unchanged runs produce identical snapshot, report, and deterministic proposal hashes;
+- every generated artifact is linked from the workflow run;
+- resume after an interrupted stage completes without duplicating or corrupting artifacts;
+- local execution is used unless a contract explicitly requires network or CI.
+
+### Cycle 2 — Architecture discovery
+
+**Purpose:** validate the project topology rather than merely listing dependencies.
+
+**Checks:** compare discovered packages/apps/modules/files and relations with the monorepo manifests, workspace configuration, representative source imports/exports, and known application boundaries.
+
+**Success metrics:**
+
+- 100% of in-scope workspace packages and apps are classified;
+- package, module, and file graph levels are independently navigable;
+- relation kinds and direction are preserved;
+- disconnected nodes and high-connectivity/SPOF candidates are reported with code evidence;
+- dynamic imports, runtime wiring, and generated code are either analyzed or explicitly reported as `not-analyzed`;
+- no architecture claim is inferred from `package.json` dependencies alone.
+
+### Cycle 3 — Documentation inventory and freshness
+
+**Purpose:** distinguish document presence from document usefulness and freshness.
+
+**Checks:** inventory agent and human docs, resolve links, compare documentation ownership and referenced paths with the current repository, and run generated-doc freshness checks.
+
+**Success metrics:**
+
+- 100% of in-scope docs have a classification and source evidence;
+- 100% of in-scope packages/apps have an explicit documentation status: `fresh`, `stale`, `missing`, or `unverified`;
+- every `stale` result has at least one content/path/code evidence item;
+- 0 stale decisions based only on filename keywords, dates, or the presence of words such as “old” or “deprecated”;
+- generated and internal documentation checks pass, or each failure is surfaced as a finding.
+
+### Cycle 4 — Documentation/code reconciliation
+
+**Purpose:** prove that documented architecture and observed architecture agree at the declared semantic level.
+
+**Checks:** use representative package/module declarations and known-positive, known-negative, stale, conflicting, unresolved, and dynamic relation cases; run the same policy against `agentskit-os`.
+
+**Success metrics:**
+
+- 100% of declared static relations are classified as confirmed, stale, conflicting, unresolved, or not-analyzed;
+- undocumented observed relations are grouped at a useful package/module scope instead of producing unbounded raw noise;
+- intentional exclusions are explicit and counted, never hidden by an empty required-kind list;
+- the known-case fixture matrix has 100% detection of expected findings and 0 unsupported findings;
+- the real target report does not show zero findings merely because reconciliation was disabled.
+
+### Phase 3 — Real-artifact documentation inventory
+
+The first AKOS audit exposed that the repository contains multiple documentation
+surfaces. A single `documentedDocumentCount / documentCount` ratio mixed the 27
+agent-corpus documents with human guides, project files, archives, and
+unclassified Markdown. Doc Bridge now reports deterministic document counts by
+classification and marks `docs-archive` as `archive`; the report highlights the
+agent-corpus ratio separately. This keeps the metric useful without hiding the
+full inventory.
+
+The phase gate is satisfied only when the real AKOS artifact reports the
+classification totals, the agent-corpus numerator/denominator, and evidence for
+the classification rule. A changed source revision or configuration invalidates
+the evidence and requires a new workflow and verification run.
+
+### Cycle 5 — Registry agent quality
+
+**Purpose:** validate the configured agent from the AgentsKit Registry as an evidence-grounded assistant to discovery and classification.
+
+**Checks:** run deterministic replay, inspect proposal origin/version/hashes/evidence, and run an assisted mode only when authorized credentials and budget are available.
+
+**Success metrics:**
+
+- proposal origin is the configured Registry agent ID and provider;
+- base snapshot/report hashes match the run that produced the proposal;
+- every intended change maps to an observed diagnostic or evidence item;
+- deterministic replay is hash-stable;
+- no proposal invents a path, claim, or remediation unsupported by the snapshot/report;
+- human approval is required before any proposal application.
+
+### Cycle 6 — Report and interaction validation
+
+**Purpose:** prove that the evidence can be understood and explored by a human.
+
+**Checks:** real-browser interaction, responsive layouts, keyboard access, contrast, text overflow, loading/latency, console/network errors, level navigation, selection, filters, zoom/pan, and evidence drilldown.
+
+**Success metrics:**
+
+- 0 automated failures across all configured viewport/theme scenarios;
+- 0 console errors, failed requests, horizontal page overflow, clipped controls, or contrast violations;
+- package → module → file navigation preserves context and breadcrumbs;
+- every visible finding has evidence and an actionable explanation;
+- human visual approval is recorded for the current report hash.
+
+### Cycle 7 — Enterprise completion gate
+
+**Purpose:** close the loop without overstating readiness.
+
+**Success metrics:**
+
+- all required cycles are `COMPLETE` for the same source revision and contract;
+- no required surface remains `not-analyzed` without an approved exemption;
+- source, target, config, docs, and generated artifacts have been reconciled;
+- issue/PR tracking is updated only after authorization and includes the exact run ID;
+- task-owned temporary artifacts are cleaned while user-owned or ambiguous artifacts remain untouched;
+- structural decisions are documented in the relevant ADR/RFC;
+- final report states residual risks and the next human action; enterprise readiness is not claimed while any required gate is pending.
+
+## Initial baseline to collect
+
+The first cycle records counts and timings without treating them as success: entities by kind, relations by kind, declared relations, findings by code/severity/status, coverage states, document classifications, proposal evidence ratio, report load time, interaction latency, generated artifact size, and agent-output token/byte counts. Later cycles ratchet these metrics against the baseline instead of hiding regressions behind aggregate pass/fail status.
+
+The executable benchmark stores an anonymization-safe baseline at `.doc-bridge/benchmarks/baseline.json`. The baseline contains numeric metrics and rule definitions only; it must not contain repository paths, document contents, package names, credentials, or agent prompts. It is created or replaced only by an explicit human-authorized command (`--write-baseline` or `--replace-baseline`).
+
+### Efficiency metric contract
+
+| Metric family | Measurements | Initial gate |
+|---|---|---|
+| Pipeline | total, discovery, comparison, and proposal milliseconds | no more than 10% regression |
+| Artifact | total bytes, initial HTML bytes, overview/levels/findings chunk bytes | initial HTML and total bytes no more than 10% regression |
+| Agent context | hit rate, p50/p95 latency, p50/p95 response bytes, estimated p95 tokens, corpus-to-context reduction | 100% fixture hit rate; p95 bytes/tokens no more than 10% regression |
+| Report UX | p95 first render, application response after real browser events, gesture duration, render-phase p95, and lazy-chunk bytes | first render ≤ 2s; application response ≤ 200ms; gesture is reported separately; phase/chunk data explains regressions |
+| Analysis quality | analyzed ratio, documented/evidence ratios, overview node/edge counts, raw/compared relation ratio, finding density | tracked as evidence; fixture precision/recall gates semantic correctness |
+| Reliability | UI failures, console errors, failed requests, incomplete stages | zero |
+
+The report exposes aggregate insights suitable for case studies, but publication requires a separate redaction review. A benchmark passing means the measured contract passed; it does not prove semantic quality without the fixture set or prove enterprise readiness when surfaces are exempted.
+
+## Latest measured cycle
+
+Cycle 2 shipped Doc Bridge `1.7.20` to `agentskit-os` and added deterministic resolution of literal dynamic imports. The official workflow run is `1787934948972-14360`; the verification run is `1787935063723-14641`.
+
+- discovered entities: `12,930 → 12,937`;
+- raw relations: `40,921 → 41,300`;
+- package-level compared relations: `2,663 → 2,698`;
+- findings: `2,580 → 2,615`, all with evidence;
+- benchmark: passed against baseline with pipeline `6,052ms`, initial HTML `68,069B`, report artifact `26,338,177B`, first render p95 `113ms`, application response p95 `92ms`, gesture p95 `76ms`, and zero UI failures;
+- agent search remained at `100%` hit rate and `1,067` estimated p95 tokens with `99%` context reduction;
+- all 10 automated viewport/theme scenarios passed; human approval is still required for the current report hash.
+
+The result is an improvement in semantic discovery, not proof that runtime wiring or non-literal loading is resolved. The next cycle should measure and improve those boundaries or add an explicit configuration/adapter path for projects that can provide runtime architecture evidence.
+
+Cycle 3 shipped Doc Bridge `1.7.21` to `agentskit-os` and added explicit `dynamic-literal` relation metadata plus benchmark counters for unresolved dynamic loading and runtime-wiring candidates. The official workflow run is `1787937333636-16849`; the verification run is `1787937404198-17113`.
+
+- `379` literal dynamic-import relations are now identifiable in the snapshot;
+- `56` files contain non-literal loading that remains unresolved;
+- `46` files contain runtime-wiring candidates that remain explicitly not analyzed;
+- benchmark passed with first render p95 `59ms`, application response p95 `79ms`, gesture p95 `76ms`, and zero UI failures;
+- entity/relation/documentation and agent-search metrics remained grounded, with agent search at `100%` hit rate and `1,067` estimated p95 tokens;
+- automated UI evidence passed across all 10 viewport/theme scenarios; human approval is required for the current report hash.
+
+Cycle 4 shipped Doc Bridge `1.7.24` to `agentskit-os` and added configurable JS/TS runtime-wiring detection for statically imported targets, explicit unresolved-wiring coverage, a runtime-wiring benchmark counter, and browser-runtime warmup for stable visual timing. The official workflow run is `1787938291045-21432`; the verification run is `1787938325493-21506`.
+
+- the real repository produced `12,937` entities and `41,300` raw relations;
+- package-level reconciliation compared `2,774` relations and produced `2,691` findings, all with evidence;
+- `379` literal dynamic-import relations were identified and `56` files still contain unresolved non-literal loading;
+- `116` files contain unresolved runtime-wiring candidates; no real target wiring was resolved automatically, confirming the conservative boundary rather than overstating coverage;
+- the benchmark passed without replacing the anonymization-safe baseline: pipeline `6,094ms`, artifact `26,441,496B`, initial HTML `68,069B`, first render p95 `110ms`, application response p95 `71ms`, gesture p95 `76ms`, and zero UI failures;
+- agent search remained at `100%` hit rate and `1,067` estimated p95 tokens with `99%` context reduction;
+- all 10 automated viewport/theme scenarios passed with no console errors, failed requests, overflow, clipping, or contrast violations; the screenshots were reviewed locally and the harness is awaiting explicit human approval.
+
+Cycle 5 shipped Doc Bridge `1.7.25` to `agentskit-os` and tightened the default runtime-wiring heuristic by making generic `bind` and `listen` calls opt-in while preserving explicit configuration. The official workflow run is `1787938899030-22694`; the verification run is `1787938967570-22837`.
+
+- the real repository remained stable at `12,937` entities, `41,300` raw relations, `2,774` compared relations, and `2,691` evidence-backed findings;
+- unresolved runtime-wiring candidates fell from `116` to `54` (`53.4%` reduction) by removing generic API false positives;
+- the benchmark passed against the unchanged baseline: pipeline `6,042ms`, first render p95 `58ms`, application response p95 `71ms`, gesture p95 `75ms`, report artifact `26,422,816B`, and zero UI failures;
+- agent search remained at `100%` hit rate and `1,067` estimated p95 tokens with `99%` context reduction;
+- the explicit configuration path was covered by a fixture: `listen` is ignored by default and produces a relation when configured;
+- all 10 automated viewport/theme scenarios passed; the verification run is awaiting human visual approval.
+
+Cycle 6 shipped Doc Bridge `1.7.26` to `agentskit-os` and tightened unresolved-wiring coverage to require a potential target argument, excluding inline registrations and no-argument calls from architectural gaps while preserving identifiers, property accesses, and factory calls. The official workflow run is `1787939273593-23788`; the verification run is `1787939317943-23884`.
+
+- the real repository remained stable at `12,937` entities, `41,300` raw relations, `2,774` compared relations, and `2,691` evidence-backed findings;
+- unresolved runtime-wiring candidates fell from `54` to `22` (`59.3%` reduction; `81.0%` reduction from the `116`-file starting point);
+- the benchmark passed against the unchanged baseline: pipeline `5,903ms`, first render p95 `106ms`, application response p95 `71ms`, gesture p95 `77ms`, report artifact `26,412,971B`, and zero UI failures;
+- agent search remained at `100%` hit rate and `1,067` estimated p95 tokens with `99%` context reduction;
+- the known-case fixture retained both unresolved identifier detection and the explicit custom-method configuration path;
+- all 10 automated viewport/theme scenarios passed; the verification run is awaiting human visual approval.
+
+Cycle 7 shipped Doc Bridge `1.7.28` to `agentskit-os` and made the large-report overview payload package-scoped. The first load now carries package topology plus compact diagnostic indexes; module/file detail remains lazy. The official workflow run is `1787940069560-26699`; the verification run is `1787940112369-26783`.
+
+- the real repository remained stable at `12,937` entities, `41,300` raw relations, `2,774` compared relations, and `2,691` evidence-backed findings;
+- unresolved runtime-wiring candidates fell from `22` to `9` (`59.1%` additional reduction; `92.2%` reduction from the `116`-file starting point); test/spec runtime wiring is excluded by default and covered by an explicit opt-in fixture;
+- the overview payload contains `83` package entities and `627` package relations instead of the full canonical entity/relation set, while retaining `2,691` diagnostic group indexes and `2,691` relation-finding indexes;
+- the benchmark passed against the unchanged baseline: pipeline `5,910ms`, first render p95 `113ms`, application response p95 `71ms`, gesture p95 `78ms`, report artifact `26,370,691B`, initial HTML `68,170B`, overview chunk `843,002B`, and zero UI failures;
+- agent search remained at `100%` hit rate and `1,067` estimated p95 tokens with `99%` context reduction; reconciliation evidence coverage remained `100%`;
+- all 10 automated viewport/theme scenarios passed with no console errors, failed requests, overflow, clipping, or contrast violations; screenshots were reviewed locally and the run is awaiting explicit human visual approval.
+
+## Current known blockers after the measured dogfood cycle
+
+- package `1.7.28` is installed and verified in `agentskit-os`; the workflow run is `1787940069560-26699` and the verification run is `1787940112369-26783`;
+- the benchmark passed against the original anonymization-safe baseline; the detailed cycle measurements are recorded above;
+- the agent search fixture returned a grounded match for `100%` of queries, with p95 `1,067` estimated tokens and `99%` context reduction; reconciliation evidence coverage was `100%` for the `2,691` findings;
+- the visual check passed all automated checks across 10 viewport/theme scenarios, but the current verification run remains `AWAITING_HUMAN_APPROVAL` until a human reviews the screenshots and approves run `1787940112369-26783`;
+- only `3%` of reported analyzer scopes are complete in this target, so non-literal dynamic loading, unresolved runtime wiring, and generated code remain explicit coverage limitations;
+- the current verification contract covers the package dogfood target, not the complete Doc Bridge enterprise objective.
+
+The current run is `AWAITING_HUMAN_APPROVAL`, not complete. Discovery, package-level reconciliation, Registry-agent proof, documentation cohesion, export accuracy, CLI execution, and measured efficiency passed. The benchmark baseline was not replaced. After human approval, the next cycle should use these numbers as the comparison point and focus on classifying the remaining 9 production runtime-wiring candidates and improving documentation usefulness rather than report transport performance.
+
+### Phase 2 — Semantic classification measurement
+
+The next cycle adds a small, deterministic labeled benchmark around the real reconciliation function. It covers confirmed, undocumented, stale, not-analyzed, conflicting, and unresolved declarations. The acceptance threshold is exact per-case diagnostic classification with non-empty evidence, plus `1.000` finding precision, `1.000` finding recall, and `1.000` evidence ratio. The AKOS verification contract runs this gate directly against the checked-out Doc Bridge source so a later change cannot silently preserve only the aggregate report counts.

package/docs/verification-harness.md

@@ -5,25 +5,44 @@ description: Fail-closed, evidence-backed verification for humans and agents.
 
 # Verification harness
 
-`ak-verify` is the executable completion gate for work that must be proven, not merely compiled.
+`ak-verify` is the executable completion gate for work that must be proven, not merely compiled. Harness 1.3 also blocks failed contract outcomes and measured regressions.
 
 ```bash
 ak-verify run --config .codex/verification.json --json
 ak-verify status --config .codex/verification.json --json
 ak-verify approve <run-id> approved --by human --config .codex/verification.json
 ak-verify authorize <run-id> approved --by human --config .codex/verification.json
+ak-verify baseline replace benchmarks/new.json approved --by human --config .codex/verification.json
 ak-verify clean --periodic --config .codex/verification.json
 ```
 
 The contract is JSON so it works without adding a YAML runtime. It declares the artifact surfaces that apply to the run, executable checks, explicit non-applicable reasons, the verification profile, and tracking policy.
 
+## Global policy and project contract
+
+The `ak-verify` executable is portable: any repository can run it from the
+published Doc Bridge package. The verification contract remains project-local
+at `.codex/verification.json` because endpoints, databases, UI flows, checks,
+acceptance criteria, and tracking targets differ by repository.
+
+The host-level agent policy is global and requires that every repository have
+this project contract before implementation or verification. A repository
+without it is `CLARIFYING`; agents must ask the human to define or authorize
+the contract instead of selecting a default profile or inventing checks. This
+combination provides one global completion rule without pretending that one
+set of repository-specific checks fits every project.
+
+Before implementation, the human intent and acceptance criteria must be explicit. Every criterion must map to an executable check and its expected evidence. If a criterion is not mapped, the run is `CLARIFYING` or `BLOCKED`; a project may not silently shrink the scope to the checks that are easiest to run.
+
 ## States
 
-`PLANNED` → `VERIFYING` → `AWAITING_HUMAN_APPROVAL` → `AWAITING_AUTHORIZATION` → `COMPLETE`.
+`CLARIFYING` → `PLANNED` → `VERIFYING` → `AWAITING_HUMAN_APPROVAL` / `AWAITING_AUTHORIZATION` → `COMPLETE`.
+
+Any failed required check, unavailable required surface, or unmapped acceptance criterion produces `BLOCKED` or `CLARIFYING`. The harness never promotes a run from `BLOCKED`, `AWAITING_HUMAN_APPROVAL`, or `AWAITING_AUTHORIZATION` to `COMPLETE` without the corresponding evidence and intent. A `COMPLETE` result applies only to the declared contract and must not be described as broader product validation when the broader scope was not declared.
 
-Any failed required check or unavailable required surface produces `BLOCKED`. The harness never promotes a run from `BLOCKED`, `AWAITING_HUMAN_APPROVAL`, or `AWAITING_AUTHORIZATION` to `COMPLETE` without the corresponding evidence and intent.
+`default` is the low-friction profile used when `profile` is omitted. `strict` keeps fail-closed validation for the declared contract. `poc` and `custom` require explicit exemptions, which are included in the run evidence and cannot be silently hidden. `enterprise` requires all seven surfaces to be declared, requires measurement and tracking, and does not accept silent exemptions.
 
-`strict` is the default profile. `poc` and `custom` require explicit exemptions, which are included in the run evidence and cannot be silently hidden.
+The seven applicability surfaces are `logic`, `cli`, `mcp`, `ui`, `docs`, `endpoint`, and `database`. A surface marked not applicable must include a reason. Endpoint and database validation remains conditional on the target: if the target uses one, declare a required real check; otherwise declare why it is not applicable.
 
 ## Evidence and recovery
 
@@ -33,4 +52,18 @@ Checks may emit one final JSON line with `status` set to `passed`, `failed`, or
 
 Visual checks must use a real browser or an explicitly configured equivalent. A passing build is not visual approval. Endpoint, database, CLI, and MCP checks must execute their real artifact when the contract marks that surface as required.
 
+UI checks fail closed unless the check declares the `real-browser` and `screenshot` capabilities and its final structured result contains `capability: "real-browser"`, screenshot artifacts with project-relative paths, SHA-256 hashes and viewports, plus a passing result for every contract outcome mapped to that check. Missing files, stale hashes, placeholder pending results, and unmapped criteria block the run before human approval is available.
+
+Delegated work does not weaken the gate. Subagents receive the parent contract hash, assigned criterion IDs, allowed scope, required capabilities, and expected evidence. Their output remains provisional until the orchestrator reruns this harness against the combined current source revision.
+
+The final evidence ledger must distinguish `validated`, `partially validated`, `not analyzed`, `blocked`, and `not applicable`. Counts such as indexed documents, package presence, or rendered reports do not prove semantic documentation/code agreement, stale-content detection, runtime wiring, or UI behavior.
+
+When a report is shared outside its repository, configure `report.privacy: 'anonymized'`. This is separate from `safety.redactSecrets`: secret redaction does not anonymize project names, paths, identifiers, snippets, or finding messages. The privacy check must inspect the generated HTML and all lazy chunks, not only the configuration.
+
+When `measurement.required` is enabled, the named required check must emit structured evidence with `status: "passed"`, a numeric `metrics` object, a `baselineHash`, and an empty `regressions` array. Missing or regressed measurements block completion. Baselines are explicit, versioned artifacts and are never updated implicitly by a verification run.
+
+Baseline replacement is an explicit, human-intended operation. `baseline replace` copies a JSON baseline into the configured target only when the source and target are inside the project root and appends a hash, actor, intent, and timestamp to `.codex/verification/baseline-audit.jsonl`.
+
+The run JSON exposes `profile`, `profilePolicy`, `applicability`, `exemptions`, `checks`, `evidenceReferences`, `metrics`, `transitions`, `sourceRevision`, `contractHash`, `outputHash`, and the exact `runId`. Approval records are bound to the input, source, contract, and output hashes of that run.
+
 The harness only removes paths listed as task-owned and contained by configured cleanup roots. It never performs broad workspace deletion.

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.6.4",
+  "version": "1.7.45",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {