harness-doctor

/harness-doctor

Runs 5 deterministic checks and reports [ PASS ], [ WARN ], or [ FAIL ] per item.

Instructions

You are running the hplan installation health check.

Execute all 5 checks in sequence. Do not skip any check. Collect all results, then output the summary block.

---

Check 1 — Claude Code Hook Registration

cat .claude/settings.json 2>/dev/null || cat ~/.claude/settings.json 2>/dev/null

• PASS: Output contains gate_guard.py under PreToolUse hooks
• WARN: settings.json not found — hook may not be registered
• FAIL: File found but gate_guard.py not in PreToolUse

Remedy if WARN/FAIL: add the hook path to .claude/settings.json under hooks.PreToolUse.

---

Check 2 — gate_guard.py Execution

echo '{"tool_input": {"file_path": "docs/PRD.md"}}' \
  | python3 hplan/hooks/gate_guard.py
echo "exit=$?"

• PASS: exit=2 — gate_guard blocked the write as expected (no checkpoint present)
• WARN: exit=0 — gate_guard ran but did not block (checkpoint may already exist)
• FAIL: Any Python error or hplan/hooks/gate_guard.py not found

Note: exit=2 is the correct behavior here. The hook is designed to block writes to protected files until harness/build-gate/checkpoint.json shows status: "approved".

---

Check 3 — Checkpoint State

python3 -c "
import json, pathlib, sys
cp = pathlib.Path('harness/build-gate/checkpoint.json')
if not cp.exists():
    print('MISSING')
    sys.exit(0)
try:
    d = json.loads(cp.read_text())
    print(d.get('status', 'NO_STATUS'))
except Exception as e:
    print(f'PARSE_ERROR: {e}')
"

• PASS (approved): Project has passed the Build Gate — writes to PRD/spec files are unblocked
• PASS (MISSING): No checkpoint yet — normal for a project that hasn't run /harness-build yet
• WARN (CONDITIONAL_GO / other status): Gate was run but not fully approved
• FAIL (PARSE_ERROR): checkpoint.json is malformed — delete it and re-run /harness-build