---
name: apt:verify-proof
description: "Visual proof-of-work verification — screenshots, HTML report, optional multi-model review (BETA)"
apt-skill-version: {{APT_VERSION}}
stage: verify
intent: ship
when_to_use: "The user wants visual proof of work — screenshots, recorded video, and a browsable HTML proof report — instead of QA scores alone."
user_invocable: true
internal: false
spawns_agent: false
agent_name: null
task_context: require-existing
default_execution_mode: auto
execution_modes:
  - auto
  - step
allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
argument-hint: "apt:verify-proof [--multi-model | --video]"
gates: []
config_keys:
  - verification.open_report
  - verification.report_formats
---

# Proof Verification

Adversarial visual verification with structured evidence capture. Every test requires
an action, evidence, and a verdict. No hallucinated passes.

## When to Use

- After `/apt:execute` completes — verify the implementation actually works
- When the user wants visual proof before approving a change
- When you need to generate a shareable HTML report for stakeholders
- Before creating a PR — attach proof that features work

## When Not to Use

- For quick QA scores without visual evidence — use `/apt:verify` instead
- For code review — use `/apt:review`
- If no UI/visual changes were made — `/apt:verify` is faster

## Driver Architecture

`/apt:verify-proof` is **runtime-agnostic** — the workflow refers to IDL
verbs (`driver.click`, `driver.screenshot`, `driver.navigate`, ...) and
NEVER to concrete MCP tool names (per ID-01). The driver layer at
`packages/framework/drivers/<id>/` maps verbs to transports.

### Auto-detect

The resolver auto-selects the highest-scoring driver per ID-02
(capability_coverage > compatibility > stability > priority > locality).
Preview the selection before running verify-proof:

```bash
apt-tools detect-runtime .
# → { runtime: {is_electron, is_nextjs, ...}, selected_driver_id: "..." }
```

v0.8.6 — the runtime detector now walks `apps/*/package.json` by
default and OR-merges each child's capabilities into the root. The
canonical Aperant monorepo (Electron at `apps/desktop`, Next.js at
`apps/web`) now reports `is_electron: true` AND `is_nextjs: true`
without any config override.

### Per-outcome dispatch (v0.8.6+)

When the spec ships `## User Outcomes` (the verify-proof input
contract — see CLAUDE.md), the workflow runner imports
`resolveDriversForOutcomes()` from the resolver module and picks a
driver PER OUTCOME SURFACE instead of a single per-run driver pick.

```js
import { resolveDriversForOutcomes } from '.aperant/deps/node_modules/@aperant/framework/src/cli/verify-proof/resolver.mjs'

const entries = resolveDriversForOutcomes({
  drivers, runtime,
  outcomes: parsed.outcomes,  // from parseUserOutcomes(spec)
})
// → [{outcome_id: "O1", surface: "electron", driver: {...}}, ...]
// For [electron+web] outcomes, two entries share the same outcome_id.
```

The legacy `apt-tools detect-runtime` still answers the per-run
"which driver would be picked?" question for the override preview.
For the per-outcome dispatch (the new contract), import
`resolveDriversForOutcomes` directly.

### Override

Force a specific driver chain in `.aperant/config.json`:

```json
{ "verification": { "runtimes": ["electron", "cli"] } }
```

v0.8.6 — `verification.monorepo_globs` is the new opt-out for the
monorepo walk. The walk now runs by default — adopters whose
monorepo lives at a non-canonical prefix
(`packages/apps/*`, `services/*`) override via
`verification.monorepo_globs: ["packages/apps/*"]`; set to `[]` to
disable the walk entirely (root-only behaviour, backwards compat).
The `verification.runtimes[]` override stays the final escape hatch
and is now usually unnecessary because the walk runs by default.

### Bundled drivers (4)

- **browser** (priority=100, ga) — Next.js / vanilla web frontends.
- **electron** (priority=90, ga) — Electron desktop apps.
- **cli** (priority=60, ga) — headless CI, output-shape assertions.
- **api** (priority=50, ga) — HTTP / JSON-API regression tests.

### Driver authors

Third-party driver authors should run `apt-tools driver doctor .` before
publishing to validate manifest schema + IDL conformance:

```bash
apt-tools driver doctor .
# → { drivers: [{driverId, manifest_valid, idl_conformant, ...}], summary: {...} }
```

IDL types, error taxonomy, and conformance kit live inside the framework
itself under `packages/framework/src/driver-sdk/` — see that directory's
public-api-lock test for the surface contract.

## Execution

Execute the verify-proof workflow end-to-end using IDL verbs (the driver
maps verbs to its transport — MCP server, local command, HTTP):

<execution_context>
@packages/framework/workflows/verify-proof.md
@packages/framework/context/installed/verification.md
@packages/framework/templates/proof-verification.md
</execution_context>

<process>
Follow the verify-proof workflow from @packages/framework/workflows/verify-proof.md.

**Critical:** Read the verification context (@packages/framework/context/installed/verification.md) FIRST
to adopt the adversarial QA mindset. You are not a helpful assistant during verification —
you are trying to break things and prove they work.

Respect ALL workflow gates:
1. Pre-check gate — all subtasks completed
2. Design-lint gate (C11) — for every UI-touching task, run `apt-tools design-lint` against the implementation's generated HTML + `{task_dir}/mockups/mockup_final.html` (when present). The DESIGN.md contract's `antiPatterns` block is the authority. Violations MUST be surfaced in the VERIFICATION.md report as a distinct section; they are NOT blocking by themselves but they contribute to the visual-quality score.
3. Test generation gate — ALL tests written before execution
4. Test execution gate — ALL tests executed before scoring
5. Evidence gate — every test has evidence AND analysis
6. Scoring gate — scores derived from evidence, not assumed

Use the proof-verification template (@packages/framework/templates/proof-verification.md)
for the VERIFICATION.md output format.

**Design-lint invocation** (when the task touched UI):

```bash
node packages/framework/bin/apt-tools.mjs design-lint \
  --design-file DESIGN.md \
  {task_dir}/mockups/mockup_final.html \
  <implementation-rendered-html-files>
```

Include the command's full JSON output verbatim in the report's `## Design-Lint` section. When violations exist, include each rule's `why` + `rewrite` so the reviewer sees the fix path without following a link.
</process>

## References

For multi-model verification details:
- `references/multi-model-verification.md` — Gemini, Codex, Claude verdicts and quorum
- `references/multi-model-setup.md` — API keys, model presets, benchmarks
- `references/proof-capture.md` — Evidence capture best practices

## Config

Settings live in the MERGED Aperant config (shared `.aperant/config.json` + per-device `.aperant/config.local.json`; local wins). Run `/apt:setup` to configure. Read via `apt-tools config read .` or the framework's `loadMergedProjectConfig()` — NEVER raw `JSON.parse(readFileSync('.aperant/config.json'))`, which misses per-device overrides.

- `verification.evidence_capture` — shared. capture screenshots + terminal output (default: true)
- `verification.open_report` — **per-device (config.local.json)** per AUDIT-001. open HTML in browser when done (default: true)
- `multi_model.enabled` — shared. run multi-model verification (default: false)
- `multi_model.cross_verification.tools` — **per-device (config.local.json)** per AUDIT-001. which CLIs to cross-verify with.
- `multi_model.gemini.model` — shared. Gemini preset: default/thorough/fast
