@agentskit/doc-bridge 1.6.4 → 1.7.44

package/docs/validation-cycle-plan.md

@@ -0,0 +1,236 @@
+---
+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.
+
+### 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.

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,14 @@ 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.
 
+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.44",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.6.4",
+  "version": "1.7.44",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",

package/scripts/report-visual-check.mjs

@@ -1,5 +1,6 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { chromium } from '@playwright/test'
@@ -15,6 +16,7 @@ const themes = ['light', 'dark']
 const failures = []
 const checks = []
 const networkRequests = []
+const clock = () => performance.now()
 
 mkdirSync(outputDir, { recursive: true })
 
@@ -99,25 +101,46 @@ const inspect = async (frame, width, height) => frame.evaluate(({ width: viewpor
 }, { width, height })
 
 const poll = async (read, predicate, label, timeoutMs = interactionTimeoutMs) => {
-  const started = Date.now()
-  while (Date.now() - started < timeoutMs) {
-    if (predicate(await read())) return Date.now() - started
+  const started = clock()
+  while (clock() - started < timeoutMs) {
+    if (predicate(await read())) return Math.round(clock() - started)
     await new Promise((resolve) => setTimeout(resolve, 50))
   }
   throw new Error(`${label} did not reach the expected state within ${timeoutMs}ms`)
 }
 
 const exercise = async (frame, result) => {
-  const run = async (label, action, verify) => {
-    const started = Date.now()
+  result.interactionDurationsMs ??= []
+  const run = async (label, action, verify, browserEvent) => {
+    const started = clock()
     try {
+      if (browserEvent) await frame.evaluate((type) => {
+        document.documentElement.dataset.docBridgeInteractionStartedAt = ''
+        window.addEventListener(type, () => {
+          document.documentElement.dataset.docBridgeInteractionStartedAt = String(performance.now())
+        }, { capture: true, once: true })
+      }, browserEvent)
       await Promise.race([
         (async () => { await action(); if (verify) await verify() })(),
         new Promise((_, reject) => setTimeout(() => reject(new Error('interaction timeout')), interactionTimeoutMs)),
       ])
-      const durationMs = Date.now() - started
+      const gestureDurationMs = Math.round(clock() - started)
+      const durationMs = browserEvent
+        ? await frame.evaluate(() => {
+          const startedAt = Number(document.documentElement.dataset.docBridgeInteractionStartedAt)
+          return Number.isFinite(startedAt) ? Math.round(performance.now() - startedAt) : null
+        })
+        : gestureDurationMs
+      if (durationMs == null) throw new Error(`${browserEvent} event was not observed`)
+      result.interactionDurationsMs.push({ label, durationMs, ...(browserEvent ? { gestureDurationMs } : {}) })
+      if (browserEvent) {
+        const renderTimings = await frame.evaluate(() => JSON.parse(document.documentElement.dataset.docBridgeRenderTimings || '{}'))
+        result.renderTimings ??= []
+        result.renderTimings.push({ label, ...renderTimings })
+      }
       if (durationMs > 2000) result.failures.push(`${label} took ${durationMs}ms`)
     } catch (error) {
+      result.interactionDurationsMs.push({ label, durationMs: Math.round(clock() - started), failed: true })
       result.failures.push(`${label}: ${error instanceof Error ? error.message : String(error)}`)
     }
   }
@@ -165,7 +188,7 @@ const exercise = async (frame, result) => {
         await poll(() => frame.locator('[data-level][aria-pressed="true"]').getAttribute('data-level'), (actual) => actual === expectedLevel, `drill-down ${expectedLevel}`)
         const details = await frame.locator('#details').innerText()
         if (/Select a node in the map/i.test(details)) throw new Error('details panel did not update')
-      })
+      }, 'dblclick')
     }
     if (await frame.locator('#breadcrumbs [data-breadcrumb-level]').count() < 1) result.failures.push('drill-down did not create usable breadcrumbs')
     await run('breadcrumb back to repository', () => frame.locator('#breadcrumbs [data-breadcrumb-level="overview"]').click(), async () => {
@@ -189,6 +212,9 @@ const exercise = async (frame, result) => {
 let browser
 try {
   browser = await chromium.launch()
+  const warmup = await browser.newPage()
+  await warmup.goto('about:blank')
+  await warmup.close()
   for (const theme of themes) {
     for (const viewport of viewports) {
       const page = await browser.newPage()
@@ -203,10 +229,12 @@ try {
       try {
         await page.setViewportSize({ width: viewport[0], height: viewport[1] })
         await page.emulateMedia({ colorScheme: theme })
+        const renderStarted = clock()
         await page.goto(pathToFileURL(reportPath).href, { waitUntil: 'load' })
         const frame = page.frames().find((candidate) => candidate !== page.mainFrame() && candidate.url().endsWith('/report/index.html')) ?? page.mainFrame()
         await frame.locator('#graph').waitFor({ state: 'visible', timeout: interactionTimeoutMs })
         result = await inspect(frame, viewport[0], viewport[1])
+        result.firstRenderMs = Math.round(clock() - renderStarted)
         await exercise(frame, result)
         result.pageErrors = pageErrors
         result.consoleErrors = consoleErrors
@@ -229,8 +257,15 @@ try {
 }
 
 const status = failures.length || checks.some((check) => check.failures.length) ? 'failed' : humanApproved ? 'passed' : 'pending-human-review'
+const artifacts = checks.map((check) => {
+  const path = join(outputDir, `${check.viewport}-${check.theme}.png`)
+  return existsSync(path) ? { type: 'screenshot', path: relative(process.cwd(), path), sha256: createHash('sha256').update(readFileSync(path)).digest('hex'), viewport: check.viewport, theme: check.theme } : null
+}).filter(Boolean)
 const result = {
   status,
+  capability: 'real-browser',
+  artifacts,
+  criteria: { 'report-ui': { status: status === 'failed' ? 'failed' : 'passed' } },
   reportPath,
   outputDir,
   viewports,
@@ -246,5 +281,5 @@ const result = {
 }
 writeFileSync(join(outputDir, 'result.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8')
 console.log(JSON.stringify(result, null, 2))
-console.log(JSON.stringify({ status }))
+console.log(JSON.stringify(result))
 if (status === 'failed') process.exitCode = 1