Skip to content

operator-workflow.md

Latest commit

 

History

History
98 lines (74 loc) · 4.78 KB

operator-workflow.md

File metadata and controls

98 lines (74 loc) · 4.78 KB
Raw

The operator's side — when a contract needs your eyes

Some acceptance criteria a machine can't check: a physical device test, a visual review, a judgment call. When a contract hits those, the session can't self-verify — it needs you. This is how that hand-off works without you re-reading a scroll of worker text or wondering whether the gate got cheated.

The one thing to know

proctor inbox — a short, always-current list of every session waiting on you, and the one command to release each. That's it. When a session needs you, the voice ping says so and points you here; you never have to scan the transcript.

$ proctor inbox
# Proctor — Operator Inbox

**1 session(s) need you:**

## hermes-buddy-esp32s3 — Pocket device ships with working flip-to-silence
✅ SAFE TO SIGN OFF — every machine check passed; only your review remains.
session `ddacf001-...`

Your checklist — do these, then sign off:
  - [ ] Flip the device face-down: silent within ~2s, screen dims
  - [ ] Pull the USB cable: 'connected via tcp' appears in agent.log

▶ Release:  `proctor signoff ddacf001-...`   ·   Abandon:  `/disarm ddacf001-...`

Do the checklist, then:

$ proctor signoff ddacf001-...            # shows it again, read-only
$ proctor signoff ddacf001-... --all      # you did it → sign off

The session releases on its next stop. Done.

Why you can trust it (the anti-cheat)

The whole point is that "did we just cheat the gate?" is always answerable — no:

  • The inbox is built from machine truth, not worker prose. Every line comes from the contract's manifest and the verified proof — the failing/passing checks the machine actually ran. A worker can write a glowing wall of text; it can't change what shows here.
  • Sign-off refuses over a real failure. proctor signoff --all will not sign a session while any machine check is failing. You can only ever vouch for the human_review items — the physical/judgment parts a machine genuinely can't do. Broken code can't be waved through.
  • Sign-off is your act, and it's recorded. It requires a real terminal (a headless worker has no TTY, so it can't sign itself off), and it writes signed_off_by: operator with a timestamp and the exact items you confirmed into the proof. The release is auditable, not a rubber stamp.

The two states you'll see

  • ✅ SAFE TO SIGN OFF — every machine check passed; only your review remains. Do the checklist, --all, done.
  • ⚠ VERIFY — machine checks FAILED — the code itself isn't passing. This is not yours to sign over. Either it goes back to the worker to fix, or you /disarm to abandon the contract. Sign-off is blocked here by design.

If you disagree

  • proctor signoff <sid> --reject "reason" — record a kickback; the worker must address it.
  • /disarm <sid> — retire the gate entirely for that session (the escape hatch). Use when a contract is mis-authored or you just want it out of the way.

Getting alerted across many terminals (Slack + a synced board)

proctor inbox is the local board. When you're running many terminals and can't watch them, turn on two extra rails — both fed from the SAME machine-truth source, so they can't be inflated or faked:

  • A Slack push to your phone. Create an incoming webhook for a channel (e.g. #agent-inbox), then set slack_webhook in ~/.claude/goal-contract/notify.config.json. A new ask posts once (never on every gate stop — it's deduped), states its checklist + release command, and posts a ☑️ Cleared line when you sign off. Failing-check sessions are flagged ⚠ VERIFY so you never rubber-stamp broken work from your phone.
  • A durable per-machine board in your Obsidian vault. Set vault_board_dir to a synced vault folder (e.g. /Users/you/Obsidian Vault/Proctor). Each machine writes its own Operator Inbox - <hostname>.md, so ~N machines never clobber each other — the combined view is the folder. This syncs to your phone as the durable "everything waiting on me" list.

Both rails are best-effort and fail-open: a Slack outage, missing webhook, or empty config is a silent no-op — the local inbox and the voice ping always still work. The webhook URL is a secret; it lives only in that machine-local config (gitignored) and is never printed, logged, or written to any board or message. Voice remains your at-desk layer.

Where it lives

The local inbox is ~/.claude/goal-contract/OPERATOR-INBOX.md; the gates regenerate it (and fan out to Slack + the vault board) whenever a proof needs a human. proctor inbox (or the /inbox slash command) regenerates and prints it on demand. Config: ~/.claude/goal-contract/notify.config.json (seeded by the installer; see notify.config.example.json).