# nexus-gatekeeper

description: "Formalizes Reality Checker as a hard blocking gate in the task pipeline — a task cannot advance past implementation until the gate is cleared. After implementation, spawns the Reality Checker agent and parses its verdict: PASS sets gate_status=passed (downstream agents spawn), NEEDS_WORK or FAIL sets gate_status=failed and halts the pipeline. Writes gate records to task-store.db. In FAIL scenarios with consecutive failures, escalates to the PD or council. Best for teams that want enforcement-grade quality gates without relying on discipline — the gatekeeper makes the workflow self-governing. Also for: tracking recurring quality concerns across tasks and surfacing architectural issues from repeated gate failures."

## Protocol

1. **After implementation:** Spawn Reality Checker agent to assess
2. **Parse verdict:**
   - `PASS` → set `gate_status=passed`
   - `NEEDS_WORK` → set `gate_status=failed`, halt pipeline
   - `FAIL` → set `gate_status=failed`, halt pipeline, escalate
3. **Write gate record** to task store via `task-store` skill
4. **Halt on failed gate:** Do not spawn downstream agents until gate is cleared

## Reality Checker Verdict Reference

- `PASS` — ready to ship, no blocking issues
- `NEEDS_WORK` — significant issues remain, must address before proceeding
- `FAIL` — critical failure, do not continue

## Workflow

```
Implementation Agent
    │
    ▼
Reality Checker Agent
    │
    ├─ PASS → ts-gate passed → spawn downstream agents
    │
    ├─ NEEDS_WORK → ts-gate failed → HALT
    │                    Report to user for remediation
    │
    └─ FAIL → ts-gate failed → HALT
                     Escalate to PD/council
```

## Integration with task-store

The gatekeeper reads from and writes to `~/.claude/task-store.db`:

```bash
# Check gate before spawning
gate=$(sqlite3 ~/.claude/task-store.db \
  "SELECT gate_status FROM tasks WHERE id='$task_id';")
if [ "$gate" = "open" ]; then
  echo "Gate not yet evaluated — run Reality Checker first"
elif [ "$gate" = "failed" ]; then
  echo "BLOCKED — gate failed, see gate_verifier and notes"
else
  echo "Gate passed — safe to advance"
fi
```

## Escalation Path

- Gate `failed` with `NEEDS_WORK`: Report to user with specific issues found
- Gate `failed` with `FAIL`: Escalate to PD or council if multiple consecutive failures
- Gate repeatedly `failed` for the same task: Add to project oversight as recurring quality concern