frontier-infra/proctor/proctor-setup

Proctor setup

Proctor makes an agent's "done" a verified fact instead of a claim. Your job with this skill: get it installed and prove it's live, or repair/remove it. The installer does the work; you drive it and verify. Never hand-edit settings.json — the installer handles that idempotently and backs it up.

1. Locate or clone the repo

The repo is proctor (internal id goal-contract). Find an existing clone first:

for d in ~/code/proctor ~/proctor ~/code/claude-hooks/goal-contract; do
  [ -f "$d/install.py" ] && echo "found: $d" && break
done

If none exists, clone it:

git clone https://github.com/webdevtodayjason/proctor ~/code/proctor

Work from that directory (call it $REPO) for everything below.

2. Install (or repair — it's idempotent)

cd "$REPO"
./install.sh                 # or: ./install.sh --config-dir ~/.claude-<profile>

This symlinks ~/.claude/hooks/goal-contract to the clone, wires the four hooks (witness → PostToolUse; disposition-gate + goal-gate → Stop; arm-contract → UserPromptSubmit), symlinks the authoring skills and /disarm, and seeds judge.config.json. It backs up settings.json first. Re-running is safe — it only adds what's missing.

3. Prove it's live (do not skip)

python3 test_gates.py        # must print "all green"
python3 test_turns.py        # must print "all green"
./install.sh --status        # every hook should read "wired"

Then confirm a hook actually fires end-to-end (wiring can be present but dormant — this catches that):

printf '{"session_id":"proctor-setup-canary","tool_name":"Bash","tool_input":{"command":"pytest"},"tool_response":{"stdout":"=== 1 failed, 1 passed in 0.1s ==="}}' \
  | python3 ~/.claude/hooks/goal-contract/witness.py
test -s ~/.claude/goal-contract/witness/proctor-setup-canary.jsonl \
  && echo "LIVE: witness fired" \
  && python3 -c "import os;os.remove(os.path.expanduser('~/.claude/goal-contract/witness/proctor-setup-canary.jsonl'))"

If the witness log wasn't written, the PostToolUse hook is not loading — check that the entry is in ~/.claude/settings.json (not settings.local.json, which does not load hooks in some builds) and re-run ./install.sh.

4. Optional pieces — report, don't force

• Proof-integrity guard (defense-in-depth) rides on the separate damage-control hooks.

./install.sh --status reports whether its patterns are present. If not, tell the user to merge the block from $REPO/guards/damage-control-patterns.yaml by hand — do not auto-rewrite their damage-control config.

• Judge (signs prose acceptance) needs a local LLM endpoint in judge.config.json. The

core gates work without it; only mention it if the user asks about prose acceptance.

• Voice pages require ~/.config/claude-hooks/voice-attention.py; absent → gates just log.

5. Repair / remove

• Something off: ./install.sh again (idempotent repair), then re-run step 3.
• Remove entirely: ./install.sh --uninstall (leaves witness logs + backups).
• A session is stuck at Stop under a contract: python3 $REPO/disarm.py --list, then

python3 $REPO/disarm.py <session-id> to clear its whole gate set.

What "done" means for this skill

Done = steps 2 and 3 both succeeded: the installer reported the hooks wired, both test suites printed "all green", and the live witness canary fired. Report that plainly (with the command outputs), and note the status of the optional pieces. Do not report success on the install alone — a wired-but-dormant hook is the exact failure this system exists to catch.