@agentskit/doc-bridge 1.6.2 → 1.6.4

package/docs/knowledge-engine-runbook.md

@@ -42,3 +42,17 @@ Set `intelligence.registry.enabled: true` and `runnerModule` in `doc-bridge.conf
 Rerunning an unchanged command reuses valid stage artifacts. A changed source revision, configuration hash, or tool version creates a stale/superseding run. CI can use `ak-docs check --json`; non-zero rule findings fail the command while unsupported analysis is reported as explicit coverage.
 
 The first implementation analyzes JavaScript/TypeScript and Markdown. Other languages should add analyzers that emit the same canonical entity, relation, evidence, coverage, and hash contracts.
+
+## Relation coverage policy
+
+Missing declarations are configurable because not every implementation import is useful documentation. In the root configuration, `reconciliation.requiredRelationKinds` selects the observed relation kinds that must be declared in Markdown:
+
+```json
+{
+  "reconciliation": {
+    "requiredRelationKinds": []
+  }
+}
+```
+
+Omit the option to preserve the original all-relation behavior. Use an empty list for low-friction adoption when package/app coverage and explicitly declared claims matter more than documenting every module, test, or external-library import. Existing declarations are still checked for stale, conflicting, and unresolved references.

package/docs/verification-harness.md

@@ -0,0 +1,36 @@
+---
+title: Verification harness
+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.
+
+```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 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.
+
+## States
+
+`PLANNED` → `VERIFYING` → `AWAITING_HUMAN_APPROVAL` → `AWAITING_AUTHORIZATION` → `COMPLETE`.
+
+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.
+
+`strict` is the default profile. `poc` and `custom` require explicit exemptions, which are included in the run evidence and cannot be silently hidden.
+
+## Evidence and recovery
+
+Runs live under `.codex/verification/runs/<run-id>/run.json`. The latest pointer is `.codex/verification/latest.json`. Commands are captured with exit code, duration, stdout, stderr, source revision, configuration hash, and input hash. Re-running an unchanged pending or completed run is idempotent; changed source or contract creates a new run.
+
+Checks may emit one final JSON line with `status` set to `passed`, `failed`, or `pending-human-review`. Structured `failed` evidence blocks the run even when the process exits with code 0; structured pending evidence remains explicitly awaiting human approval. This prevents a visual checker from being mistaken for a successful verification merely because it launched.
+
+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 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.2",
+  "version": "1.6.4",
   "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,11 +1,12 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "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",
   "bin": {
-    "ak-docs": "bin/ak-docs.js"
+    "ak-docs": "bin/ak-docs.js",
+    "ak-verify": "bin/ak-verify.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,6 +25,8 @@
     "bin",
     "action.yml",
     "scripts/prepare.mjs",
+    "scripts/verification-harness.mjs",
+    "scripts/report-visual-check.mjs",
     "scripts/check-ecosystem-upstream.mjs",
     "ecosystem.json",
     "ecosystem-claims.json",
@@ -43,6 +46,51 @@
     "src",
     "skills"
   ],
+  "scripts": {
+    "prebuild": "node scripts/sync-version.mjs",
+    "build": "tsup",
+    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
+    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
+    "typecheck": "tsc --noEmit",
+    "smoke:packaged": "node scripts/smoke-packaged.mjs",
+    "smoke:docsites": "node scripts/smoke-docsites.mjs",
+    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
+    "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
+    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
+    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
+    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
+    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
+    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
+    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
+    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
+    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
+    "coverage:badge": "node scripts/update-coverage-badge.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-version.mjs",
+    "release": "npm run build && npm test && changeset publish",
+    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
+    "prepublishOnly": "npm run build && npm test",
+    "prepare": "node scripts/prepare.mjs",
+    "prepack": "npm run build",
+    "docs:dev": "cd apps/docs && next dev",
+    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
+    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
+    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
+    "docs:e2e": "playwright test",
+    "report:visual": "node scripts/report-visual-check.mjs",
+    "test:verification-harness": "node --test scripts/verification-harness.test.mjs",
+    "docs:lighthouse": "lhci autorun",
+    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
+    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
+    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
+    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
+    "check:readme-standard": "node scripts/check-readme-standard.mjs",
+    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
+  },
   "keywords": [
     "agentskit",
     "documentation",
@@ -140,45 +188,5 @@
   "bugs": {
     "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
   },
-  "homepage": "https://doc-bridge.agentskit.io/",
-  "scripts": {
-    "prebuild": "node scripts/sync-version.mjs",
-    "build": "tsup",
-    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
-    "test:watch": "vitest",
-    "coverage": "vitest run --coverage",
-    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
-    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
-    "typecheck": "tsc --noEmit",
-    "smoke:packaged": "node scripts/smoke-packaged.mjs",
-    "smoke:docsites": "node scripts/smoke-docsites.mjs",
-    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
-    "smoke:ollama": "node scripts/smoke-ollama.mjs",
-    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
-    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
-    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
-    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
-    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
-    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
-    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
-    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
-    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
-    "coverage:badge": "node scripts/update-coverage-badge.mjs",
-    "changeset": "changeset",
-    "version-packages": "changeset version && node scripts/sync-version.mjs",
-    "release": "npm run build && npm test && changeset publish",
-    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
-    "docs:dev": "cd apps/docs && next dev",
-    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
-    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
-    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
-    "docs:e2e": "playwright test",
-    "docs:lighthouse": "lhci autorun",
-    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
-    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
-    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
-    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
-    "check:readme-standard": "node scripts/check-readme-standard.mjs",
-    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
-  }
-}
+  "homepage": "https://doc-bridge.agentskit.io/"
+}

package/scripts/report-visual-check.mjs

@@ -0,0 +1,250 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { chromium } from '@playwright/test'
+
+const args = process.argv.slice(2)
+const reportPath = resolve(args.find((arg) => !arg.startsWith('--')) ?? '.doc-bridge/report.html')
+const outputFlag = args.indexOf('--output')
+const outputDir = resolve(outputFlag >= 0 ? args[outputFlag + 1] ?? '.doc-bridge/visual-acceptance' : '.doc-bridge/visual-acceptance')
+const humanApproved = args.includes('--human-approved')
+const interactionTimeoutMs = 2500
+const viewports = [[390, 844], [768, 1024], [1440, 900], [1600, 1000], [1920, 1080]]
+const themes = ['light', 'dark']
+const failures = []
+const checks = []
+const networkRequests = []
+
+mkdirSync(outputDir, { recursive: true })
+
+const record = (viewport, theme, result) => {
+  const entry = { viewport: `${viewport[0]}x${viewport[1]}`, theme, ...result }
+  checks.push(entry)
+  for (const failure of result.failures ?? []) failures.push(`${entry.viewport}/${theme}: ${failure}`)
+}
+
+const inspect = async (frame, width, height) => frame.evaluate(({ width: viewportWidth, height: viewportHeight }) => {
+  const controls = [...document.querySelectorAll('#search,#status,#severity,#reset,[data-lens],[data-level]')]
+  const clippedControls = controls.filter((element) => {
+    const rect = element.getBoundingClientRect()
+    return rect.width > 0 && rect.height > 0 && (rect.left < 0 || rect.right > viewportWidth || rect.top < 0 || rect.bottom > viewportHeight)
+  }).map((element) => element.id || element.dataset.lens || element.dataset.level || element.tagName)
+  const workspace = document.querySelector('.workspace')?.getBoundingClientRect()
+  const graph = document.querySelector('#graph')?.getBoundingClientRect()
+  const failures = []
+  if (document.documentElement.scrollWidth - document.documentElement.clientWidth > 1) failures.push('horizontal overflow')
+  if (clippedControls.length) failures.push(`clipped controls: ${clippedControls.join(', ')}`)
+  if (!workspace || workspace.top > viewportHeight * 0.7) failures.push('architecture map starts too far below the first screen')
+  if (!document.querySelector('#graph')) failures.push('architecture graph is missing')
+  if (document.querySelectorAll('[data-lens]').length < 4 || document.querySelectorAll('[data-level]').length < 4) failures.push('required lens or level controls are missing')
+  if (document.querySelectorAll('.finding').length > 40) failures.push('initial findings render grows beyond one bounded page')
+  if (graph && graph.width < Math.min(480, viewportWidth * 0.7)) failures.push('architecture graph is too narrow to inspect')
+
+  const unnamedButtons = [...document.querySelectorAll('button')].filter((button) => {
+    const rect = button.getBoundingClientRect()
+    return rect.width > 0 && rect.height > 0 && !button.textContent.trim() && !button.getAttribute('aria-label') && !button.getAttribute('aria-labelledby')
+  })
+  if (unnamedButtons.length) failures.push(`unnamed visible buttons: ${unnamedButtons.length}`)
+
+  const visibleOverflow = [...document.querySelectorAll('body *')].filter((element) => {
+    const rect = element.getBoundingClientRect()
+    if (!rect.width || !rect.height || element.closest('.map-wrap')) return false
+    const horizontalOverflow = element.scrollWidth > element.clientWidth + 2
+    const containerOverflow = element.children.length > 0 && element.scrollHeight > element.clientHeight + 2
+    return horizontalOverflow || containerOverflow
+  })
+  if (visibleOverflow.length) failures.push(`text/content overflow: ${visibleOverflow.slice(0, 3).map((element) => element.id || element.className || element.tagName).join(', ')}`)
+
+  const parseColor = (value) => {
+    const text = String(value).trim()
+    const hex = text.match(/^#([0-9a-f]{3,8})$/i)?.[1]
+    if (hex) {
+      const expanded = hex.length <= 4 ? [...hex].map((channel) => channel + channel).join('') : hex
+      return [expanded.slice(0, 2), expanded.slice(2, 4), expanded.slice(4, 6)].map((channel) => Number.parseInt(channel, 16) / 255)
+    }
+    const rgb = text.match(/rgba?\(([^)]+)\)/i)?.[1]
+    return rgb ? rgb.split(',').slice(0, 3).map((channel) => Number.parseFloat(channel.trim()) / 255) : null
+  }
+  const luminance = (rgb) => rgb.map((channel) => channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4).reduce((sum, channel, index) => sum + channel * [0.2126, 0.7152, 0.0722][index], 0)
+  const contrast = (foreground, background) => { const a = luminance(foreground); const b = luminance(background); return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05) }
+  const rootStyle = getComputedStyle(document.documentElement)
+  const ink = parseColor(rootStyle.getPropertyValue('--ink'))
+  const muted = parseColor(rootStyle.getPropertyValue('--muted'))
+  const paper = parseColor(rootStyle.getPropertyValue('--paper'))
+  const panel = parseColor(rootStyle.getPropertyValue('--panel'))
+  const contrastFailures = []
+  for (const [name, foreground] of [['ink', ink], ['muted', muted]]) {
+    for (const [backgroundName, background] of [['paper', paper], ['panel', panel]]) {
+      if (foreground && background && contrast(foreground, background) < 4.5) contrastFailures.push(`${name}/${backgroundName}`)
+    }
+  }
+  if (contrastFailures.length) failures.push(`insufficient text contrast: ${contrastFailures.join(', ')}`)
+
+  return {
+    failures,
+    overflow: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+    clippedControls,
+    workspaceTop: workspace?.top ?? null,
+    graphWidth: graph?.width ?? null,
+    initialFindingCount: document.querySelectorAll('.finding').length,
+    findingGroupCount: document.querySelectorAll('.finding-group').length,
+    diagnosticCount: typeof globalThis.__DOC_BRIDGE_DATA__?.diagnosticCount === 'number'
+      ? globalThis.__DOC_BRIDGE_DATA__.diagnosticCount
+      : Number.parseInt(document.querySelector('#finding-count')?.textContent ?? '', 10) || document.querySelectorAll('.finding').length,
+    unnamedButtonCount: unnamedButtons.length,
+    visibleOverflowCount: visibleOverflow.length,
+    contrastFailures,
+  }
+}, { 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
+    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()
+    try {
+      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
+      if (durationMs > 2000) result.failures.push(`${label} took ${durationMs}ms`)
+    } catch (error) {
+      result.failures.push(`${label}: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  for (const [lens, view] of [['architecture', 'architecture'], ['drift', 'insights'], ['risks', 'findings'], ['evidence', 'coverage']]) {
+    await run(`lens ${lens}`, () => frame.locator(`[data-lens="${lens}"]`).click(), async () => {
+      await poll(() => frame.locator('body').getAttribute('data-report-view'), (actual) => actual === view, `lens ${lens}`)
+      if (await frame.locator(`[data-lens="${lens}"]`).getAttribute('aria-selected') !== 'true') throw new Error('aria-selected did not follow the active lens')
+    })
+  }
+
+  await run('finding groups load', async () => {
+    const load = frame.locator('#load-findings')
+    if (await load.count()) await load.click()
+    else if (result.diagnosticCount > 0 && await frame.locator('.finding-group').count() === 0) throw new Error('finding loader is missing while findings are present')
+  }, async () => {
+    if (result.diagnosticCount > 0) {
+      await poll(() => frame.locator('.finding-group').count(), (count) => count > 0, 'finding groups')
+    } else if (await frame.locator('.finding-group').count() !== 0) {
+      throw new Error('finding groups rendered despite zero findings')
+    }
+  })
+
+  await run('map reset', () => frame.locator('[data-lens="architecture"]').click(), async () => {
+    await poll(() => frame.locator('body').getAttribute('data-report-view'), (actual) => actual === 'architecture', 'map reset')
+  })
+
+  if (!(await frame.locator('[data-node]').count())) result.failures.push('architecture graph has no interactive nodes')
+  else {
+    const drillSelectors = [
+      ['package', ['[data-node][aria-label*=" app"]', '[data-node][aria-label*=" domain"]', '[data-node][aria-label*=" group"]', '[data-node]']],
+      ['module', ['[data-node][aria-label*=" package"]', '[data-node][aria-label*=" shared"]']],
+      ['file', ['[data-node][aria-label*=" module"]', '[data-node][aria-label*=" file"]']],
+    ]
+    for (const [expectedLevel, selectors] of drillSelectors) {
+      let selector
+      for (const candidate of selectors) {
+        if (await frame.locator(candidate).count()) {
+          selector = candidate
+          break
+        }
+      }
+      if (!selector) continue
+      await run(`double-click drill-down to ${expectedLevel}`, () => frame.locator(selector).first().dblclick(), async () => {
+        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')
+      })
+    }
+    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 () => {
+      await poll(() => frame.locator('[data-level][aria-pressed="true"]').getAttribute('data-level'), (actual) => actual === 'overview', 'breadcrumb repository')
+    })
+  }
+
+  const map = frame.locator('.map-wrap')
+  const beforeTransform = await frame.locator('#graph').getAttribute('style')
+  await run('map zoom', () => map.dispatchEvent('wheel', { deltaY: -120, deltaX: 0 }), async () => {
+    const afterTransform = await frame.locator('#graph').getAttribute('style')
+    if (!afterTransform || afterTransform === beforeTransform || !afterTransform.includes('scale(')) throw new Error('zoom did not change the graph transform')
+  })
+  await run('map reset keyboard', () => frame.locator('body').dispatchEvent('keydown', { key: '0' }), async () => {
+    const transform = await frame.locator('#graph').getAttribute('style')
+    if (!transform?.includes('scale(1)')) throw new Error('keyboard reset did not restore scale 1')
+  })
+  await run('clear selection', () => frame.locator('#clear-selection').click())
+}
+
+let browser
+try {
+  browser = await chromium.launch()
+  for (const theme of themes) {
+    for (const viewport of viewports) {
+      const page = await browser.newPage()
+      const pageErrors = []
+      const consoleErrors = []
+      const failedRequests = []
+      page.on('pageerror', (error) => pageErrors.push(error.message))
+      page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()) })
+      page.on('requestfailed', (request) => failedRequests.push(`${request.url()} · ${request.failure()?.errorText ?? 'failed'}`))
+      page.on('request', (request) => networkRequests.push(request.url()))
+      let result = { failures: [] }
+      try {
+        await page.setViewportSize({ width: viewport[0], height: viewport[1] })
+        await page.emulateMedia({ colorScheme: theme })
+        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])
+        await exercise(frame, result)
+        result.pageErrors = pageErrors
+        result.consoleErrors = consoleErrors
+        result.failedRequests = failedRequests
+        if (pageErrors.length) result.failures.push(`page errors: ${pageErrors.join(' | ')}`)
+        if (consoleErrors.length) result.failures.push(`console errors: ${consoleErrors.join(' | ')}`)
+        if (failedRequests.length) result.failures.push(`failed requests: ${failedRequests.join(' | ')}`)
+        await page.screenshot({ path: join(outputDir, `${viewport[0]}x${viewport[1]}-${theme}.png`), fullPage: false })
+      } catch (error) {
+        result.failures.push(error instanceof Error ? error.message : String(error))
+      }
+      record(viewport, theme, result)
+      await page.close()
+    }
+  }
+} catch (error) {
+  failures.push(error instanceof Error ? error.message : String(error))
+} finally {
+  await browser?.close()
+}
+
+const status = failures.length || checks.some((check) => check.failures.length) ? 'failed' : humanApproved ? 'passed' : 'pending-human-review'
+const result = {
+  status,
+  reportPath,
+  outputDir,
+  viewports,
+  themes,
+  networkRequests,
+  checks,
+  failures,
+  note: status === 'failed'
+    ? 'Automated visual or interaction evidence failed; human approval is not available for this run.'
+    : humanApproved
+      ? 'Automated checks passed and human approval was explicitly supplied.'
+      : 'Automated checks passed; screenshots require human visual review. Re-run with --human-approved only after review.',
+}
+writeFileSync(join(outputDir, 'result.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8')
+console.log(JSON.stringify(result, null, 2))
+console.log(JSON.stringify({ status }))
+if (status === 'failed') process.exitCode = 1