## PROOF EVIDENCE CAPTURE

Guidelines for capturing visual proof during /apt:verify-proof verification.

### Evidence Capture Strategy

**Priority order for each feature:**

1. **Screenshots** — Always capture. Every verification step that touches UI should have a before/after screenshot.
2. **Terminal output** — Capture for all automated checks (tests, typecheck, lint) and code-only verification steps.
3. **Assertions** — Record the expected vs actual for each verification step.

### Screenshot Best Practices

**Timing:** Take screenshots AFTER the action completes and the UI has settled. Wait for:
- Animations to complete
- Loading spinners to resolve
- Network requests to finish (check for skeleton loaders)

**Naming convention:** `{featureId}-step-{n}-{action}` (e.g., `login-flow-step-2-fill-email`)

**What to capture:**
- Initial state before interaction
- State after each significant interaction
- Final state showing the completed feature
- Error states (if testing error handling)

### Terminal Output Best Practices

**Truncation:** Cap terminal output at 200 lines per check. This keeps the HTML report manageable while preserving meaningful output.

**What to capture:**
- Full test runner output (shows pass/fail per test)
- Type checker errors (if any)
- Lint warnings (if any)
- Custom verification command output

### Building ProofEntry Objects

Each piece of evidence becomes a `ProofEntry`:

```json
{
  "id": "unique-id",
  "featureId": "feature-id-from-testable-features",
  "label": "Human-readable description of what was checked",
  "type": "screenshot|terminal|log|assertion",
  "timestamp": "2026-04-10T12:00:00Z",
  "step": 1,
  "result": "pass|fail|skip|error",
  "description": "What was expected to happen",
  "imageData": "base64-encoded-png (for screenshots only)",
  "terminalOutput": "captured stdout/stderr (for terminal only)",
  "assertion": {
    "expression": "document.querySelector('.dashboard')",
    "expected": "not null",
    "actual": "HTMLDivElement"
  },
  "duration": 1200
}
```

### Handling Missing MCP Tools

If an MCP tool is not available for a feature:
- Mark the feature as `"skip"` (not `"fail"`)
- Add a note: "MCP server {name} not available — visual verification skipped"
- Still run any code-based verification steps
- The proof report will show skipped features in gray

### Multi-Model Evidence Handoff

When `--quorum` is used, evidence files are shared with other models:
- Screenshots are saved to disk (not just base64) so Gemini/Codex can read them
- Terminal output is written to temporary files for model consumption
- Each model receives the same evidence set for independent analysis
