`README.md`

46 lines
# approval-verifier

Answers one question the yolo-queue can't: **did an approved item actually LAND end-to-end, or did it silently no-op?**

The queue tracks that a task was *processed* (`done/` vs `failed/`), but a memo can be prose-only (recorded, never run), self-gate (bounced by the GATED-GUARD), or land "cancelled." `done/` ≠ effect realized. This tool checks the **real-world effect**.

## Usage
```bash
node verify.mjs --pending            # scan live drafts  ~/.claude/yolo-queue/pending-approval
node verify.mjs --done               # scan processed    ~/.claude/yolo-queue/done
node verify.mjs --memo <file.md>     # one memo
node verify.mjs --pending --json     # machine-readable
node verify.mjs --pending --status LIKELY-NOOP,FAILED   # only the ones that didn't land
```

## Statuses
| Status | Meaning | Confidence |
|---|---|---|
| `LANDED` | explicit VERIFY checks all passed | high |
| `FAILED` / `NO-OP` | explicit VERIFY checks present, some/all failed | high |
| `LIKELY-LANDED` | auto-observed resource state matches the memo's action verb | med |
| `LIKELY-NOOP` | observed state **contradicts** the action (didn't take effect) | med |
| `OBSERVED` | resources found, direction ambiguous — evidence printed | low |
| `UNVERIFIABLE` | no machine-checkable signal — surfaced, never silently "done" | none |

## How it decides (signal priority)
1. **Explicit `VERIFY` block** (authoritative). Put one or more in any memo:
   ```
   <!-- VERIFY: launchctl list | grep -q com.steve.fleet-act -->
   <!-- VERIFY: test -f ~/Projects/_shared/fleet-registry/manifest.json -->
   ```
   or a fenced block:
   ````
   ```verify
   pm2 jlist | jq -e '.[]|select(.name=="wallco-ai")|.pm2_env.status=="stopped"'
   ```
   ````
   Each line is a shell command; **exit 0 = that check passed.**
2. **Auto-inference** (best-effort, no false "done"): launchd labels (`com.steve.*`), pm2 process names, and explicitly-claimed file paths, checked against live state, with the memo's nearby action verb (install/stop/archive/…) used to infer expected direction.
3. None → `UNVERIFIABLE`.

## The convention that makes this powerful
Auto-inference covers the obvious cases, but the durable fix is: **every gated draft should carry a `<!-- VERIFY: … -->` block** stating the one shell test that proves it landed. Then `approve all` becomes a checkable operation — approve a batch, run `verify.mjs`, read `LANDED` vs `LIKELY-NOOP/FAILED`. The fleet-lifecycle cycle spec now instructs the officer to emit these.

A JSONL run ledger is appended to `~/.claude/yolo-queue/.approval-verify-ledger.jsonl`.