Makes an AI coding agent's "done" a verified fact instead of a claim.
Coding agents under pressure will tell you a task is finished when it isn't — they stub a function, skip a failing test, quietly decide a known problem is "out of scope," and you find out days later. Proctor is a supervisor for that moment. It reads what the agent's tools actually did (never what the agent says), and it won't let a session end until the agent's claims are checked against reality.
It's opt-in and invisible until you use it: ordinary chats are never touched. It only engages when you hand a session a contract.
Proctor is the machine-level enforcement engine of the Agent Discipline Layer (ADL) — the behave tier of Frontier Infra, for Claude Code.
- ADL installs in a repo: layered context discipline plus a per-project
/goal→ Warden → signed-proof gate. - Proctor installs on the machine (
~/.claude): it supervises every session — witnessing tool ground truth, gating "done," and handing genuinely human calls to the operator's inbox.
Same contract grammar, same manifest, same proof format — the shared semantics live in ADL's contract & proof spec, which Proctor conforms to (L3 Enforced). The hook wiring here is Claude Code–specific by design; engines for other harnesses conform to the spec, not to this plumbing. Install ADL in the repo, Proctor on the machine — they compose, and either works alone.
Requires Claude Code and python3.
git clone https://github.com/webdevtodayjason/proctor
cd proctor
./install.sh # wires it into ~/.claude, idempotent, backs up your settings
python3 test_gates.py # prints "all green"That's it — Proctor is live. Remove it anytime with ./install.sh --uninstall (your work,
logs, and backups are left untouched).
Setting it up on a new machine with an AI agent? Point the agent at
skills/proctor-setup/SKILL.mdand it will do the above.
1. Write a contract — a goal plus a few checkable acceptance lines, then paste it into a session:
=== LOCKED CONTRACT ===
GOAL: The login endpoint returns 200 for valid creds.
ACCEPTANCE:
- tests pass: `pytest tests/test_login.py -q`
- no stubs left: `! grep -rn "NotImplementedError" src/auth/`
NON-GOALS:
- do not touch `src/legacy/**`
BUDGET: ~1h, ≤3 files.
=== Work only to this contract. ===
2. The agent works. Proctor silently records every failing test, error, and stub the agent produces — regardless of whether the agent mentions them.
3. The agent says "done." Proctor checks. If the claim is false — unclosed problems, unproven acceptance — it blocks and tells the agent exactly what's missing. If a check genuinely needs a human, it hands off to you (out loud). A session can only end clean when the contract's checks actually pass.
The key move: acceptance lines are runnable commands. "Done" stops being a sentence the agent writes and becomes an exit code the harness runs.
- Witness, don't trust self-report. Evidence comes from tool output, never the agent's account.
- Done is an exit code, not a sentence. Prose claims get verified against reality.
- The one who writes the checks isn't the one being checked. Author contracts with one model (or by hand); let another execute them.
- Fail open, yield loud. A safety harness that can brick a session gets uninstalled — so every block is bounded and every give-up is announced, never silent.
| Doc | For |
|---|---|
| docs/how-it-works.md | The mechanism — components, lifecycle, the two gates, data layout |
| docs/using-it.md | Writing contracts, running an agent under one, the operator's side |
| docs/operator-workflow.md | When a contract needs your eyes — the inbox, sign-off, and why it can't be gamed |
| docs/installing.md | Install / reinstall / uninstall, profiles, optional pieces |
| docs/design-notes.md | Why it exists, the incidents that shaped it, open decisions |
skills/proctor-setup/SKILL.md |
Point an AI agent at this to set Proctor up |
Opt-in (no contract → no gating), fails open on any internal error (a bug here can never brick a session), and fully reversible. The optional local-LLM "judge" and the proof-integrity guard are add-ons — the core works without them. See docs/installing.md.