Verification Contracts

---
name: verification-contracts
description: Task-specific verification contracts generated by governer at task start, enforced by the Stop hook at task end.
triggers:
  - "verification contract"
  - "what do I need to verify"
  - "completion evidence"
  - "how to prove this works"
---

# Verification Contracts — Task-Specific Completion Evidence

## The Problem This Solves

Agents hallucinate completion. They see "no errors" and report "done." The existing evidence gate catches generic runtime claims, but it can't answer: **did you verify the RIGHT thing?**

A curl to `/health` is not evidence that `/api/users/signup` works.
Passing unrelated tests is not evidence that YOUR changes work.
TDD in isolation is not proof of production behavior.

## What a Verification Contract Is

A verification contract is a **specific, falsifiable statement** of what constitutes proof of completion for THIS task. Generated at task start by governer, persisted in the state file, enforced at stop.

```json
{
  "verificationContract": {
    "required": true,
    "generatedAt": "2026-03-14T15:00:00Z",
    "generatedBy": "governer-phase-1.8",
    "taskDecomposition": [
      {
        "intentStatement": "When a paying user visits /settings, given they have an active subscription, then they see a Preferences section with 3 toggles for email, push, and coaching frequency",
        "verificationCommand": "Open localhost:3000/settings with a paying user simulation and verify 3 toggles render",
        "verificationEvidence": null,
        "verified": false
      },
      {
        "intentStatement": "When a toggle is clicked, given the user has an active subscription, then the backend receives a PATCH /api/user/preferences with the correct payload shape and responds 200",
        "verificationCommand": "curl -s -X PATCH localhost:<your-api-port>/api/user/preferences -H 'Cookie: token=...' -d '{\"emailNotifications\":false}' | jq .status",
        "verificationEvidence": null,
        "verified": false
      }
    ]
  }
}
```

## How It Works — Two Gates, One Contract

### START Gate (UserPromptSubmit → Governer Phase 1.8)

1. Human assigns work
2. Agent decomposes into **UX intent statements** — consume `/intent` FIRST for format and rules
   - Every statement MUST be conditional and human-readable: translate code constraints into what the person has done or what state they're in
   - Every condition from the code MUST appear — funnel scope, user state, feature flags, fail-open/fail-closed — but described as the person's experience, not as variable names
   - Variable names are pointers in parentheses, not substitutes for meaning
   - **Zero unconditional statements.** See `/intent` for wrong/right examples.
3. Each intent statement maps to a **verification command** — the specific action that proves the statement is true
4. Agent prints decomposition to the user (human can see interpretation before action)
5. Agent saves decomposition with `alignment-harness compaction scope --intent "..." --certainty N --decomposed "a|b"` (admin can audit interpretation asynchronously)
6. Contract is written with `alignment-harness contract add --intent "When ... then ..." --verify "<command>"`
7. Agent proceeds with work

### END Gate (Stop Hook)

1. Agent claims completion
2. Stop hook reads `verificationContract` from governer state file
3. If contract exists and `required: true`:
   - Include ALL unverified contract items in the blocking message
   - Agent must run verification for each item and show output
   - Only when ALL items have evidence → pass through
4. If no contract → fall through to generic evidence gate (the other agent's work)

## When Contracts Are Required

Governer score determines contract depth:

| Score range | Contract requirement |
|---|---|
| < 20 | No contract — trivial task, generic evidence gate is sufficient |
| 20–59 | Lightweight contract — 1-2 verification items for the primary change |
| 60–79 | Standard contract — verification item per intent statement |
| ≥ 80 | Full contract — verification item per intent statement + regression check on existing behavior |

Category overrides (ALWAYS require contracts regardless of score):
- `payment` / `auth` — always full contract
- `core-coaching` — always standard contract
- Any task where `touchesUserState` gate resolved to `revenue` or `communication` impact tier

## Writing Good Verification Contracts

### The Intent Statement (uses intent-db-add-ux-intent-guide rules)

**BAD** (unconditional — agent will verify the wrong thing):
```
Users see a preferences section on /settings
```

**GOOD** (fully conditional — agent knows exactly what to verify):
```
When a paying user visits /settings, given they have an active Stripe subscription
(subscriptionStatus === 'active'), then they see a Preferences section with 3 toggles.
When a user visits /settings who is NOT a paying subscriber, they do NOT see the
Preferences section (fail-open: non-payers see the page without the section, never an error).
```

### The Verification Command

Must be a **specific, runnable action** — not a description.

**BAD**: "Check that the preferences section works"
**GOOD**: "Open localhost:3000/settings?subscription=active&redirect=/settings in browser, verify 3 toggles render. Then open with subscription=none, verify section is absent."

**BAD**: "Run the tests"
**GOOD**: "npx jest src/components/__tests__/PreferencesSection.test.js — expect 0 failures"

**BAD**: "Verify the API endpoint"
**GOOD**: "curl -s -X PATCH localhost:<your-api-port>/api/user/preferences -H 'Cookie: token=...' -H 'Content-Type: application/json' -d '{\"emailNotifications\":false}' | jq '{status: .status, emailNotifications: .data.emailNotifications}'"

### Template Library (Critical Paths)

For critical path domains, use these verification templates:

**Payment changes**:
```
intentStatement: "When a user with {subscription_state} visits {page}, given {conditions}, then {payment UX outcome}"
verificationCommand: "curl -s localhost:<your-api-port>/api/stripe/{endpoint} -H '...' | jq '{status, plan, subscriptionStatus}'"
regressionCheck: "Verify existing payment flow still works: curl -s localhost:<your-api-port>/api/auth/me -H '...' | jq '.user.subscriptionStatus'"
```

**Auth changes**:
```
intentStatement: "When a {user_type} attempts to {auth_action}, given {auth_conditions}, then {auth_outcome}"
verificationCommand: "curl -s localhost:<your-api-port>/api/auth/{endpoint} -H '...' -d '{...}' | jq '{status, user.email, authenticated}'"
regressionCheck: "Verify existing login flow: Open localhost:3000/login, complete flow, verify redirect to /dashboard"
```

**Coaching changes**:
```
intentStatement: "When a {user_type} sends a message during a coaching session, given {session_conditions}, then {coaching_outcome}"
verificationCommand: "curl -s localhost:<your-api-port>/api/<your-coaching-endpoint> -H '...' -d '{message: \"test\"}' | jq '{status, response}'"
regressionCheck: "Open localhost:3000, start coaching conversation, verify response quality"
```

## Integration with Existing Systems

- **Governer** generates contracts at Phase 1.8 (after scoring, before execution)
- **Stop evidence gate** reads contracts from state file and includes in blocking messages
- **`alignment-harness compaction`** receives the task decomposition for admin audit
- **Intent DB** — contracts can be linked to existing intents via intent IDs from `alignment-harness intent list`
- **TaskCreate** — each intent statement maps to a task

## Rules

1. **Contracts are immutable once generated** — don't modify them during execution. If scope changes, re-run governer to generate new contracts.
2. **Every contract item must have a runnable verification command** — "check the UI" is not runnable. "Open localhost:3000/settings with ?subscription=active" is.
3. **Evidence must match the specific contract** — generic evidence (curl to /health, unrelated test passing) does not satisfy a specific contract item.
4. **The contract is printed to the user** — the human sees exactly what the agent committed to verify. This is the accountability mechanism.
5. **Contracts persist in governer state file** — they survive across turns. The stop hook reads them every time it fires.