# verify-gate-mcp

An MCP server that enforces one rule: the agent that does the work can never mark it complete. Tasks are created with acceptance criteria, claimed done by one agent (with evidence), and can only be verified by a **different** agent. Terminal states are irreversible.

## Why this exists

Three catches from running this gate in production, before open-sourcing it:

1. A devops agent reported a "fix" for a P0 incident. The verify gate found no fix was actually running.
2. A trading gate had a fail-OPEN bug (the system would trade when it should have halted). Verification caught it before any live capital was exposed.
3. Work that is actually done passes clean on the first try. The gate converges; it is a filter, not a wall.

All three came from the same rule: prover and verifier must be different agents, and the gate lives server-side, backed by a SQLite CHECK constraint, not in a prompt. The failure mode this guards against is *honest-but-lazy* agents: an agent marking its own work as verified out of convenience or context-blur.

## Invariants

1. **Criteria at birth**: a task cannot exist without ≥1 non-empty acceptance criterion; there is no add-criteria-later tool.
2. **Prover recorded**: `claim_done` permanently records the claiming agent and evidence.
3. **Prover ≠ verifier**: `verify` hard-rejects when the verifier is the claimer (`E_SELF_VERIFY`), for both verdicts.
4. **Forward-only**: `pending → claimed → (verified | rejected)`. Both end states are terminal; a rejected task's remediation is a new task with `supersedes` set for lineage.

## Install

Requires any MCP-capable agent client; Claude Code is the tested reference client.

From source (npm package coming soon):

```bash
git clone https://github.com/Monkeyattack/verify-gate-mcp.git
cd verify-gate-mcp
npm install && npm run build
node dist/index.js --db ./tasks.db
```

Claude Code / MCP client config:

```json
{
  "mcpServers": {
    "verify-gate": {
      "command": "node",
      "args": ["/path/to/verify-gate-mcp/dist/index.js", "--db", "/shared/tasks.db"],
      "env": { "VG_AGENT_ID": "devops" }
    }
  }
}
```

Multiple agents each run their own stdio server process pointed at the same SQLite file (WAL mode); every state transition is a compare-and-swap inside an `IMMEDIATE` transaction, so concurrent claims have exactly one winner.

## Quickstart: first verified task in under 15 minutes

You need two agent identities. The simplest setup is two Claude Code sessions pointed at the same database file, one launched with `VG_AGENT_ID=devops`, the other with `VG_AGENT_ID=reviewer`.

### Step 1: create a task with checkable criteria

Criteria must be checkable by someone who did not do the work. "Endpoint returns 200" is checkable; "works well" is not. If the verifier cannot decide pass or fail from the criterion alone, rewrite it.

```json
create_task({
  "title": "Add /healthz endpoint to the api service",
  "acceptance_criteria": [
    "GET /healthz on the running service returns HTTP 200",
    "Response body is JSON containing {\"status\": \"ok\"}",
    "npm test passes with the new healthz test included"
  ],
  "created_by": "devops"
})
```

Returns `{ "task_id": "…", "status": "pending", "created_at": "…" }`.

### Step 2: worker claims done, with evidence

The worker (here, `devops`) does the work, then submits evidence: what was done and how each criterion is satisfied. Evidence is a claim to be tested, not a status flag.

```json
claim_done({
  "task_id": "<task_id from step 1>",
  "agent_id": "devops",
  "evidence": "Added healthz route in src/routes/health.ts. curl -i localhost:3000/healthz returns 200 with body {\"status\":\"ok\"}. Added tests/health.test.ts; npm test: 14 passed."
})
```

The task is now `claimed`, and `devops` is permanently recorded as the prover. If `devops` tries to call `verify` on this task, the server returns `E_SELF_VERIFY` and the state does not change. Hand off to the second identity.

### Step 3: a second agent verifies, fail-first

In the `reviewer` session, the verifier independently checks each criterion against the actual system: runs the tests, hits the endpoint, reads the code. It does not take the evidence at its word.

Suppose the endpoint works but the test was never committed. The verifier rejects, and notes are required on reject; name the specific gap:

```json
verify({
  "task_id": "<task_id>",
  "verifier_agent_id": "reviewer",
  "verdict": "rejected",
  "notes": "Criteria 1 and 2 pass: GET /healthz returns 200 with {\"status\":\"ok\"}. Criterion 3 fails: tests/health.test.ts does not exist in the repo; npm test runs 13 tests, none cover healthz."
})
```

The task is now `rejected`, and that is terminal. There is no reopen. Remediation is a new task that supersedes the dead one, carrying the lineage:

```json
create_task({
  "title": "Add /healthz endpoint to the api service (remediation)",
  "acceptance_criteria": [
    "GET /healthz on the running service returns HTTP 200",
    "Response body is JSON containing {\"status\": \"ok\"}",
    "npm test passes with the new healthz test included"
  ],
  "created_by": "reviewer",
  "supersedes": "<rejected task_id>"
})
```

The worker fixes the gap (commits the test), claims done on the new task with updated evidence, and the verifier checks again:

```json
verify({
  "task_id": "<new task_id>",
  "verifier_agent_id": "reviewer",
  "verdict": "verified",
  "notes": "All three criteria checked directly: endpoint returns 200 with correct body; tests/health.test.ts present; npm test 15 passed."
})
```

That is the full loop: one rejection, one superseding retry, one verified close. `get_task` on either task shows the full append-only transition history; `supersedes` links the retry back to the rejection.

## Tools

| Tool | Effect |
|------|--------|
| `create_task(title, acceptance_criteria[], created_by, supersedes?)` | New `pending` task |
| `claim_done(task_id, agent_id, evidence)` | `pending → claimed`; records prover + evidence |
| `verify(task_id, verifier_agent_id, verdict, notes?)` | `claimed → verified\|rejected`; verifier must differ from claimer; notes required on reject |
| `get_task(task_id)` | Full record + append-only transition history |
| `list_tasks(status?, claimed_by?, limit?, cursor?)` | Paginated summaries |

Errors are returned as tool results with `isError: true` and a JSON payload `{code, message, current_status?}`; codes include `E_SELF_VERIFY`, `E_WRONG_STATE`, `E_NOT_FOUND`, `E_EMPTY_CRITERIA`, `E_EMPTY_EVIDENCE`, `E_MISSING_NOTES`, `E_INVALID_AGENT_ID`, `E_IDENTITY_MISMATCH`.

## State machine

```
create_task → pending → claim_done(A) → claimed → verify(B≠A) → verified | rejected
                                          │
                                          └ verify(A) → E_SELF_VERIFY (state unchanged)
```

## Identity model (v1)

`agent_id` is caller-declared (normalized: lowercase, trimmed, `^[a-z0-9][a-z0-9._-]{0,63}$`). Optionally, launch with `--agent-id <id>` or `VG_AGENT_ID` to **lock** the connection: any tool call declaring a different agent_id fails with `E_IDENTITY_MISMATCH`. The threat model is honest-but-lazy agents, not adversarial identity forgery; an adversarial agent inside your fleet has already won.

## What this is NOT

- Not an orchestrator. It does not schedule, route, or run agents.
- Not a project-management tool. There are no assignees, priorities, sprints, or due dates.
- Not a task board. `list_tasks` exists so agents can find work, not so humans can manage it.

It does one thing: gate completion behind independent verification. It composes with whatever orchestration, framework, or plumbing you already run; anything that speaks MCP can call it.

## Contributing

```bash
npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build
```

The PR bar is the same rule the tool enforces: every claim in a PR description must itself be verifiable. "Fixed the race in claim_done" needs the test that fails without the fix and passes with it.

## License

MIT. A permissive license fits an integrity primitive: the gate is only useful if anyone can run it anywhere, unmodified or not.