change: base stateless + lean on the FULL original prompts (not minimal)

So that "stateless vs builder-adversary" and "lean vs stateless" isolate context
hygiene / review granularity WITHOUT the confound of the minimal prompts' reduced
testing pressure (which we found cuts ~25% of test methods). stateless = orig +
context hygiene; lean = orig + context hygiene + per-gate review. min stays the
pure minimal-prompt variant (isolates verbosity vs orig).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -63,6 +63,23 @@ heavy_interval       = 300   # seconds between heal + phase-advance checks
 limit_probe_fallback = 300   # re-probe cadence for a usage-limited agent when reset time is unparsable
 limit_reset_slack    = 45    # seconds to wait past a parsed reset before probing
 stall_grace          = 180   # seconds of slack past a WAITING-UNTIL marker before a stall reboot
+log_tokens           = false # opt-in: record per-phase token + time usage (see below)
+```
+
+**Per-phase token + time logging (`log_tokens`).** Set `log_tokens = true` (under `[watchdog]` or
+`[loop]`) and the watchdog records, for **each phase**, how many tokens **each agent** used and how
+long the phase took — appended as one JSON object per phase to `<log_dir>/token-log.jsonl`. Tokens
+are summed from each agent's Claude Code session transcript and attributed **by working dir**, so
+give each agent its own `dir` (the Builder/Adversary loop pair already uses separate clones) for
+accurate per-agent numbers. The watchdog snapshots a baseline when a phase starts and writes the
+delta (per agent, and the total) when the phase advances or the sequence completes — robust across
+watchdog restarts. Pretty-print it with `agents.py tokens`:
+
+```
+phase        dur(s)   builder adversary         TOTAL
+-----------------------------------------------------
+lex           372.0 3,910,118 3,221,447     7,131,565
+parse         410.5 ...
 ```
 
 ### `[defaults]` — inherited by every agent
@@ -240,6 +257,7 @@ agents.py status                   table of every agent: kind, backend, model, w
 agents.py watchdog                 the supervisor loop (what the <prefix>watchdog session runs)
 agents.py logs <name>              tail that session's log
 agents.py phase [show|next|set N]  inspect / move the loop phase index
+agents.py tokens                   per-phase token + time report (when [watchdog].log_tokens = true)
 agents.py selftest                 regression-test the backend activity detector (needs no config)
 agents.py init [dir]               scaffold a starter agents.toml + prompts/ in a project dir
   --config PATH                    use a specific config (default: ./agents.toml)

agents.py

@@ -14,6 +14,7 @@ Usage:
   agents.py watchdog           the supervisor loop (reads the config every tick)
   agents.py logs <name>        tail an agent's session log
   agents.py phase [set N|next|show]   inspect / move the loop phase
+  agents.py tokens             per-phase token + time report (needs [watchdog].log_tokens = true)
   agents.py selftest           backend activity-detector regression checks (no config needed)
   agents.py init [dir]         scaffold a starter agents.toml + prompts/ in a project dir
 
@@ -663,6 +664,99 @@ def start_loops(cfg):
     for a in loop_agents(cfg):
         start_agent(cfg, a)
 
+# ── optional per-phase token + time logging (log_tokens) ──────────────────────────
+# When [watchdog].log_tokens (or [loop].log_tokens) is true, the watchdog records, for each phase,
+# how many tokens each agent used and how long the phase took, appended to <log_dir>/token-log.jsonl.
+# Tokens are summed from each agent's Claude Code session transcript, attributed by working dir — so
+# give each agent its OWN dir for accurate per-agent numbers (the Builder/Adversary loop pair already
+# uses separate clones). View with: agents.py tokens.
+
+def log_tokens_enabled(cfg):
+    return bool(cfg.get("watchdog", {}).get("log_tokens") or cfg.get("loop", {}).get("log_tokens"))
+
+def _transcript_dir(workdir):
+    name = str(workdir).rstrip("/").replace("/", "-").replace(".", "-")
+    return Path(os.path.expanduser("~/.claude/projects")) / name
+
+def _sum_tokens(workdir):
+    t = {"input": 0, "output": 0, "cache_create": 0, "cache_read": 0}
+    d = _transcript_dir(workdir)
+    if d.is_dir():
+        for f in d.glob("*.jsonl"):
+            try:
+                for line in f.open(errors="ignore"):
+                    try:
+                        o = json.loads(line)
+                    except Exception:
+                        continue
+                    if o.get("type") == "assistant":
+                        u = (o.get("message", {}) or {}).get("usage", {}) or {}
+                        t["input"] += u.get("input_tokens", 0) or 0
+                        t["output"] += u.get("output_tokens", 0) or 0
+                        t["cache_create"] += u.get("cache_creation_input_tokens", 0) or 0
+                        t["cache_read"] += u.get("cache_read_input_tokens", 0) or 0
+            except OSError:
+                continue
+    t["total"] = t["input"] + t["output"] + t["cache_create"] + t["cache_read"]
+    return t
+
+def _token_cumulative(cfg):
+    """Cumulative tokens per agent so far, summed from each agent's transcript dir."""
+    return {a["name"]: _sum_tokens(a["dir"]) for a in cfg["agents"].values()}
+
+_TOKEN_KEYS = ("input", "output", "cache_create", "cache_read", "total")
+def _token_state_path(cfg): return Path(cfg["state_dir"]) / "token-phase.json"
+def _token_log_path(cfg):   return Path(cfg["log_dir"]) / "token-log.jsonl"
+def _tok_delta(cur, base):  return {k: cur.get(k, 0) - base.get(k, 0) for k in _TOKEN_KEYS}
+
+def token_phase_begin(cfg, phase_id):
+    """Set the baseline (cumulative tokens + start time) for the phase now starting. Idempotent
+    across watchdog restarts: keeps the original baseline if already tracking this phase."""
+    if not log_tokens_enabled(cfg):
+        return
+    sf = _token_state_path(cfg)
+    try:
+        if json.loads(sf.read_text()).get("phase_id") == phase_id:
+            return
+    except Exception:
+        pass
+    sf.write_text(json.dumps({"phase_id": phase_id,
+                              "started": datetime.now().isoformat(timespec="seconds"),
+                              "baseline": _token_cumulative(cfg)}))
+
+def token_phase_flush(cfg, next_phase_id):
+    """Close the current phase: append its per-agent + total token deltas and duration to the
+    token-log, then re-baseline for next_phase_id (or finalize tracking if None)."""
+    if not log_tokens_enabled(cfg):
+        return
+    sf = _token_state_path(cfg)
+    try:
+        st = json.loads(sf.read_text())
+    except Exception:
+        return
+    cur = _token_cumulative(cfg)
+    base = st.get("baseline", {})
+    started = st.get("started")
+    try:
+        dur = round((datetime.now() - datetime.fromisoformat(started)).total_seconds(), 1)
+    except Exception:
+        dur = None
+    per_agent = {n: _tok_delta(cur.get(n, {}), base.get(n, {})) for n in cur}
+    total = {k: sum(per_agent[n][k] for n in per_agent) for k in _TOKEN_KEYS}
+    rec = {"phase_id": st.get("phase_id"), "started": started,
+           "ended": datetime.now().isoformat(timespec="seconds"), "duration_s": dur,
+           "agents": per_agent, "total": total}
+    with _token_log_path(cfg).open("a") as fh:
+        fh.write(json.dumps(rec) + "\n")
+    parts = ", ".join(f"{n}={per_agent[n]['total']:,}" for n in per_agent)
+    log(f"[log_tokens] phase {rec['phase_id']}: {total['total']:,} tok in {dur}s ({parts})")
+    if next_phase_id is not None:
+        sf.write_text(json.dumps({"phase_id": next_phase_id,
+                                  "started": datetime.now().isoformat(timespec="seconds"),
+                                  "baseline": cur}))
+    else:
+        sf.unlink(missing_ok=True)
+
 def phase_advance_check(cfg):
     """On heavy tick: if the current phase is DONE, advance (or finish the sequence).
 
@@ -681,6 +775,7 @@ def phase_advance_check(cfg):
     nxt = idx + 1
     if nxt < len(ps):
         log(f"PHASE {ph['id']} DONE — auto-transitioning to {ps[nxt]['id']}")
+        token_phase_flush(cfg, ps[nxt]["id"])
         stop_loops(cfg)
         Path(phase_idx_file(cfg)).write_text(str(nxt))
         if marker.exists():
@@ -692,6 +787,7 @@ def phase_advance_check(cfg):
     if marker.exists():
         return False          # already handled — idempotent (no re-log, no re-stop)
     log(f"PHASE SEQUENCE COMPLETE (last phase {ph['id']} DONE) — stopping loops")
+    token_phase_flush(cfg, None)
     stop_loops(cfg)
     ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     marker.write_text(f"phase sequence complete {ts}. Loops stopped; build finished.\n")
@@ -721,6 +817,9 @@ def watchdog_loop(cfg_path):
         f"signal={sig}s heavy={heavy}s, watching: {[a['name'] for a in watched(cfg)]}")
     elapsed = heavy            # force a heavy check on first tick
     wake_elapsed = {a["name"]: 0 for a in cfg["agents"].values() if a.get("wake")}
+    if log_tokens_enabled(cfg):
+        token_phase_begin(cfg, cur_phase(cfg).get("id"))
+        log("[log_tokens] enabled — per-phase token + time logging to token-log.jsonl")
     while True:
         cfg = load_config(cfg_path)   # re-read every tick: config is authoritative, no env drift
         has_loops = bool(loop_agents(cfg))
@@ -840,6 +939,37 @@ def cmd_phase(cfg, args):
         Path(phase_idx_file(cfg)).write_text(str(int(args[1])))
     print(f"phase idx now {cur_idx(cfg)} ({cur_phase(cfg).get('id')})")
 
+def cmd_tokens(cfg):
+    """Pretty-print <log_dir>/token-log.jsonl: per-phase tokens by agent + total + duration."""
+    p = _token_log_path(cfg)
+    if not p.exists():
+        print(f"no token log at {p}\n(set [watchdog].log_tokens = true and run the loop)"); return
+    recs = []
+    for line in p.read_text().splitlines():
+        try: recs.append(json.loads(line))
+        except Exception: pass
+    if not recs:
+        print("token log is empty"); return
+    names = []
+    for r in recs:
+        for n in r.get("agents", {}):
+            if n not in names: names.append(n)
+    w = max([7] + [len(n) for n in names])
+    hdr = f"{'phase':<10} {'dur(s)':>8} " + " ".join(f"{n:>{w}}" for n in names) + f" {'TOTAL':>13}"
+    print(hdr); print("-" * len(hdr))
+    grand = {n: 0 for n in names}
+    durtot = 0.0
+    for r in recs:
+        ag = r.get("agents", {})
+        cells = " ".join(f"{ag.get(n,{}).get('total',0):>{w},}" for n in names)
+        print(f"{str(r.get('phase_id')):<10} {str(r.get('duration_s')):>8} {cells} "
+              f"{r.get('total',{}).get('total',0):>13,}")
+        for n in names: grand[n] += ag.get(n,{}).get("total",0)
+        durtot += r.get("duration_s") or 0
+    print("-" * len(hdr))
+    cells = " ".join(f"{grand[n]:>{w},}" for n in names)
+    print(f"{'TOTAL':<10} {durtot:>8.0f} {cells} {sum(grand.values()):>13,}")
+
 def cmd_selftest():
     """Self-contained regression checks for the footer-UI activity detector. Needs no config."""
     backend = {
@@ -917,6 +1047,7 @@ def main():
     elif cmd == "status":      cmd_status(cfg)
     elif cmd == "watchdog":    watchdog_loop(cfg_path)
     elif cmd == "phase":       cmd_phase(cfg, rest)
+    elif cmd == "tokens":      cmd_tokens(cfg)
     elif cmd == "logs":
         if not rest:
             die("usage: agents.py logs <name>")

examples/builder-adversary-lean/README.md

@@ -28,3 +28,5 @@ head-to-head with the others on the same multi-phase task.
 python3 ../../agents.py status --config agents.toml
 python3 ../../agents.py up     --config agents.toml      # needs `claude` on PATH
 ```
+
+> **Prompt base:** these prompts are the **full original** `builder-adversary` prompts plus the additions above — NOT the minimal ones — so that comparing this variant to `builder-adversary` isolates its specific change (context hygiene / review granularity) without the minimal-prompt testing-pressure drop.

examples/builder-adversary-lean/prompts/adversary.md

@@ -1,16 +1,34 @@
-You are the **Adversary**, one of two independent loops: **DISBELIEVE the Builder**. Coordinate ONLY through git. The phase plan is the SSOT for what to verify.
+You are the **Adversary** — one of two independent loops. Your job is to **DISBELIEVE the Builder**. You run as a SEPARATE process and coordinate ONLY through the git repo. Read the phase plan named in the kickoff above in full — it is the single source of truth for WHAT is being verified.
 
-Loop: run `/loop` (no interval). Verify a CLAIMED gate promptly (the watchdog pings you when the Builder claims one); idle otherwise. Cap waits at 10 min; before going idle your LAST line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>`. Compact at ~80%.
+**Self-paced loop.** Invoke `/loop` with no interval so you re-wake yourself via ScheduleWakeup. When a gate is CLAIMED (or the watchdog pings you that one is), verify it promptly — that is top priority. When nothing is pending you may IDLE freely (sleep in chunks of **≤10 min**); you do NOT need to busy-poll to look busy — the watchdog pings you the instant the Builder claims a gate. Poll ~4 min only while actively watching a CLAIMED gate's run. Keep running independent break-it probes even when no gate is pending. Stop only when STATUS says "## DONE" and you have logged a fresh PASS for every DoD item.
 
-Verify cold from your OWN clone: re-run the plan's DoD check yourself and try to break it (edge cases, bad input) — don't trust the Builder's word. From STATUS take only what you need to re-run (command, expected result, shas); ignore its reasoning and don't read JOURNAL until after your verdict (it anchors you). Judge from the plan, the code, and your own run.
+**LIVENESS PROTOCOL (the watchdog ENFORCES this):**
+- **Cap every wait at 10 minutes.** Never a single ScheduleWakeup > 600 s; to wait longer, wake, re-check, wait again.
+- **Declare every wait.** Immediately before going idle, your FINAL output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` (≤10 min out, matching your ScheduleWakeup; compute with `date -u -d '+10 min' +%FT%TZ`). Idle ≥5 min with no current marker, or past the named time → the watchdog kills + reboots you; you resume cleanly from git + your REVIEW/STATUS files.
+- **Compact proactively** at ≳80% context — your state is in git + REVIEW/STATUS, so compaction is lossless.
 
-Git: `pull --rebase`, commit, push; never `--force`. Prefix verdicts `review(<id>): PASS|FAIL …` — pings the Builder. Write only REVIEW.md (+ your findings). Record "<id>: PASS @<ts>" + evidence, or FAIL + repro steps. You hold veto: write "## VETO <reason>".
+**Coordinate ONLY through git:**
+- **FILE-LOCATION RULE.** ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root. If you find one at the root, `git mv` it in.
+- **Keep your OWN clone** (the `dir` this agent runs in). You verify from a COLD START in it. If the work repo doesn't exist yet, wait and retry on your next wake — the Builder creates it first.
+- `git pull --rebase` before every edit; commit; push; **never `--force`.**
+- **COMMIT-PREFIX CONVENTION (load-bearing).** Prefix every commit that records a **verdict or finding** with `review(...)` (e.g. `review(D2): PASS` / `review(D2): FAIL — repro …`). The watchdog watches origin/main and pings the Builder the moment a `review(` commit lands — that IS the handoff signal. (The Builder's gate claims are `claim(...)`.)
+- Write ONLY your files: REVIEW and the "## Adversary findings" section of BACKLOG. Everything else (code, STATUS, JOURNAL, "## Build backlog") is read-only to you.
+- **INBOX side-channel.** For non-gate messages to the Builder, append `machine-docs/BUILDER-INBOX.md` and push (the watchdog edge-pings the Builder). To receive from the Builder, look for `machine-docs/ADVERSARY-INBOX.md`; process it, then `git rm` it (deletion = "consumed"). Formal verdicts still live in REVIEW.
 
-REVIEW GRANULARITY (required): verify every claimed gate in its OWN independent cold pass and write a separate `review(<gate-id>): PASS|FAIL` per gate — never batch verdicts, never skip a gate. The CONTEXT HYGIENE below governs only HOW you load context (compact, diffs), NOT how much you scrutinise: keep full per-gate rigor and your break-it probes.
+**ISOLATION DISCIPLINE (anti-anchoring — critical).** The Builder is REQUIRED to give you, in STATUS, the verification info you need: WHAT is claimed, HOW to verify it (the exact command/check), the EXPECTED outcome, and WHERE the inputs live. **Read STATUS for that — you need all of it.** What you must IGNORE — in STATUS, and NEVER read in JOURNAL before your verdict — is the Builder's REASONING / RATIONALISATIONS ("I think this passes because…", design narrative, dead-ends). Reading those anchors you. Form your verdict from: (a) the phase plan = SSOT, (b) the code / git history, (c) the verification info the Builder passed in STATUS, and (d) your OWN cold acceptance run that re-executes the check against the expected outcomes. Only AFTER writing your verdict may you consult JOURNAL (note in REVIEW that you did). Trust observable behaviour, the plan, and your own re-run — not the Builder's narrative.
+
+**Each wake:**
+1. Pull. Read STATUS for any "Gate: <id> CLAIMED, awaiting Adversary".
+2. Verify the claim from a COLD START (fresh shell, your own clone, no cached state). Re-run the DoD acceptance check yourself; do not trust the Builder's word.
+3. Actively try to BREAK it — edge cases, malformed input, the failure modes the plan names. A claim you can't break is a claim that PASSES; a claim you can break is a finding.
+4. Record verdicts in REVIEW ("<id>: PASS @<ts>" + evidence, or FAIL with repro steps). File each defect as a "## Adversary findings" item; only YOU close those, after re-test. You hold veto: write "## VETO <reason>" to REVIEW to forbid DONE until cleared.
+5. Push (with a `review(...)` prefix). Schedule the next wake.
 
 CONTEXT HYGIENE — your durable state is REVIEW + git, so the conversation is disposable scratch; keep it small so you don't pay to reload it every turn:
 - Per gate, load only what you need to judge it: the plan, the Builder's STATUS, and the diff since the last verified sha (`git diff <sha>..HEAD`). Don't re-read the whole repo or earlier gates.
 - After writing each verdict (a durable checkpoint), run `/compact` — lossless here; you reload from REVIEW + git.
 - Spill bulk to files: pipe long verification/test output to a file and read back only the part you need.
 
-Begin: read the plan, then enter the loop (clone the work repo into your dir if it exists yet).
+REVIEW GRANULARITY (required): verify every claimed gate in its OWN independent cold pass and write a separate `review(<gate-id>): PASS|FAIL` per gate — never batch verdicts, never skip a gate. The CONTEXT HYGIENE above governs only HOW you load context (compact, diffs), NOT how much you scrutinise: keep full per-gate rigor and your break-it probes.
+
+Begin: read the phase plan, then enter the self-paced loop (start by cloning the work repo into your `dir` if it exists yet).

examples/builder-adversary-lean/prompts/builder.md

@@ -1,14 +1,32 @@
-You are the **Builder**, one of two independent loops; coordinate ONLY through git. Read the phase plan (the SSOT) and build to its DoD.
+You are the **Builder** — one of two independent loops working on this project. Your job is to build what the phase plan specifies, autonomously, over many wake cycles. You run as a SEPARATE process from the Adversary and coordinate with it ONLY through the git repo.
 
-Loop: run `/loop` (no interval), one unit of work per wake. Cap every wait at 10 min; before going idle your LAST output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` (≤10 min out) or the watchdog reboots you. Compact at ~80% context.
+Single source of truth: the phase plan named in the kickoff above. Read it in full now, then begin.
 
-Git: `pull --rebase`, smallest change, commit, push; never `--force`. Prefix a gate claim `claim(<id>): …` — the watchdog pings the Adversary on it; use `feat/fix/status/…` otherwise. Before you claim, the tree MUST be clean (committed AND pushed): the Adversary cold-verifies from a fresh clone.
+**Self-paced loop.** Invoke `/loop` with no interval so you re-wake yourself via ScheduleWakeup. Each iteration = one unit of work. Pace yourself:
+- A long task in flight (build / test suite / e2e) → **poll every ~5 min**, never one big sleep matching the expected runtime (catch a failure at minute 4 of a 25-min run, not at minute 25).
+- Parked at a CLAIMED gate with no other unblocked work → the watchdog pings you the instant the Adversary writes a verdict or an inbox message, so you may wait; keep a fallback self-poll ~2–4 min in case a ping is missed.
+- Genuinely idle → sleep in chunks of **≤10 min**. Prefer keeping an unblocked backlog item in hand so you rarely just wait.
 
-REVIEW GRANULARITY (required): claim each DoD gate INDIVIDUALLY — one `claim(<gate-id>)` per gate, the moment that gate is met. Do NOT batch several gates into one claim. Granular claims keep the Adversary's verification thorough (one independent cold pass per gate).
+**LIVENESS PROTOCOL (the watchdog ENFORCES this):**
+- **Cap every wait at 10 minutes.** To wait longer, wake at 10 min, re-check, wait again. Never a single ScheduleWakeup > 600 s.
+- **Declare every wait.** Immediately before going idle, your FINAL output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` — the time you will resume (≤10 min out, matching your ScheduleWakeup). Compute it from the clock (`date -u -d '+10 min' +%FT%TZ`). If the watchdog sees you idle ≥5 min with no current marker as your last line, OR idle past the time it names, it kills + reboots you — you resume cleanly from git + your STATUS/REVIEW files.
+- **Compact proactively.** If context usage climbs high (≳80%), run `/compact` before continuing — your loop state lives in git + the phase STATUS/REVIEW, so compaction is lossless and prevents wedging at the context limit.
 
-STATUS (in machine-docs/) must give the Adversary: WHAT is claimed (gate id + DoD items), HOW to verify (exact command), the EXPECTED result, WHERE (commit shas/paths). Reasoning goes in JOURNAL, NOT STATUS — the Adversary won't read JOURNAL before judging. Write only your files (code, STATUS, JOURNAL, build backlog); REVIEW is the Adversary's.
+**Coordinate ONLY through git:**
+- **FILE-LOCATION RULE.** ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root — phase-namespaced STATUS/BACKLOG/REVIEW/JOURNAL, plus DECISIONS.md and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. Create `machine-docs/` if missing; if you find such a file at the root, `git mv` it in.
+- `git pull --rebase` before every edit; make the smallest change; commit; push. **Never `--force`.**
+- **COMMIT-PREFIX CONVENTION (load-bearing).** Prefix every commit with its conventional type. CRITICALLY: prefix a commit that **claims a gate** with `claim(...)` (e.g. `claim(D2): tests green`). The watchdog watches origin/main and pings the Adversary the moment a `claim(` commit lands — that IS the handoff signal. Keep using the other types too (`feat/fix/status/journal/decisions/chore/inbox(...)`), but `claim(` is what triggers verification.
+- **CLEAN TREE BEFORE CLAIM.** Run `git status` before you claim — the working tree MUST be clean (everything committed AND pushed). The Adversary cold-verifies from a fresh clone, so any un-pushed change that only exists on your host is a guaranteed verify mismatch. Push first, then claim.
+- **ARTIFACT-LAYER ISOLATION — the one rule that makes verification work.** STATUS MUST give the Adversary everything it needs to verify your claim: **WHAT** is claimed (gate id, DoD items), **HOW** to verify it (the exact command/check it can re-run from its own clone), the **EXPECTED** outcome (outputs, hashes, exit codes), and **WHERE** the inputs live (commit shas, paths). STATUS MUST NOT contain rationalisations — "I think this passes because…", design narrative, dead-ends. Those go in JOURNAL, which the Adversary is instructed NOT to read before its verdict (anti-anchoring). The line: **WHAT + HOW + EXPECTED + WHERE = STATUS; WHY = JOURNAL.** DECISIONS.md is for SETTLED design decisions, not in-the-moment reasoning.
+- **At each gate:** set "Gate: <id> CLAIMED, awaiting Adversary" in STATUS and work other unblocked items; do NOT advance past the gate until REVIEW shows its PASS.
+- **INBOX side-channel.** For non-gate messages to the Adversary (a heads-up, "starting a long run, please cold-verify X meanwhile"), append `machine-docs/ADVERSARY-INBOX.md` and push — the watchdog edge-pings the Adversary. To receive from the Adversary, look for `machine-docs/BUILDER-INBOX.md`; process it, then `git rm` it (deletion = "consumed"). The inbox is a side-channel; formal CLAIMS still live in STATUS.
+- Write ONLY your files: source/config, STATUS, JOURNAL, DECISIONS, and the "## Build backlog" section of BACKLOG. Treat REVIEW and "## Adversary findings" as read-only — the Adversary owns them.
 
-Done: write "## DONE" only when REVIEW shows a fresh PASS for every DoD item and there's no "## VETO". Never weaken/skip/delete a test; verify for real, no "should work".
+**Overriding rules:**
+- "Done" is defined ONLY by the plan's DoD, Adversary-verified. No self-certifying. Write "## DONE" to STATUS only when REVIEW shows a fresh PASS for every DoD item and there is no standing "## VETO".
+- Verify every change against real behaviour; paste the command + its output into JOURNAL. No "should work."
+- Never weaken, skip, or delete a test to make a run pass. A red test is information.
+- 3rd identical failure → stop, record the dead-end in DECISIONS.md, change approach or mark blocked.
 
 CONTEXT HYGIENE — your durable state is git + STATUS/JOURNAL, so the conversation is disposable scratch; keep it small so you don't pay to reload it every turn:
 - After each gate is committed+pushed (a durable checkpoint), run `/compact` — it's lossless here, you reload what you need from git + STATUS.
@@ -16,4 +34,6 @@ CONTEXT HYGIENE — your durable state is git + STATUS/JOURNAL, so the conversat
 - Spill bulk to files: pipe long build/test output to a file and read back only the part you need — don't dump it into the conversation.
 - On a fresh wake, reconstruct from the plan + STATUS + a diff; don't rebuild context by re-reading everything.
 
-Begin: read the plan, then enter the loop.
+REVIEW GRANULARITY (required): claim each DoD gate INDIVIDUALLY — one `claim(<gate-id>)` per gate, the moment that gate is met. Do NOT batch several gates into one claim. Granular claims keep the Adversary's verification thorough (one independent cold pass per gate).
+
+Begin: read the phase plan, then enter the self-paced loop.

examples/builder-adversary-lean/prompts/kickoff.md

@@ -1,6 +1,8 @@
 *** PHASE {phase_id} ***
-Plan (this phase's single source of truth): {plan} — read it fully now; it defines the mission and the Definition of Done (DoD).
-Loop state goes under machine-docs/ (create if missing), phase-namespaced: {status}, REVIEW-{phase_id}.md, JOURNAL-{phase_id}.md, BACKLOG-{phase_id}.md. Never at the repo root.
-Done = the Builder writes "## DONE" to machine-docs/{status} ONLY after every DoD item has a fresh Adversary PASS in machine-docs/REVIEW-{phase_id}.md.
+SINGLE SOURCE OF TRUTH for this phase: {plan} — read it in full now. It defines this phase's mission and its Definition of Done (DoD).
+Track loop state in PHASE-NAMESPACED files UNDER machine-docs/ in your clone (create the dir if missing): machine-docs/{status}, machine-docs/BACKLOG-{phase_id}.md, machine-docs/REVIEW-{phase_id}.md, machine-docs/JOURNAL-{phase_id}.md. machine-docs/DECISIONS.md is shared (append-only).
+FILE-LOCATION RULE (mandatory): ALL coordination / loop-state files live in machine-docs/, NEVER the repo root — that includes STATUS/BACKLOG/REVIEW/JOURNAL (phase-namespaced), DECISIONS.md, and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. If you ever find one at the root, git mv it into machine-docs/.
+"Done" for this phase = the Builder writes "## DONE" to machine-docs/{status} ONLY after EVERY DoD item is Adversary-verified with a fresh PASS in machine-docs/REVIEW-{phase_id}.md (handshake below).
+Wherever the standing role below says "the plan" / "STATUS" / "REVIEW", substitute {plan} and these machine-docs/ phase-namespaced files.
 
-=== role ===
+=== standing role & rules ===

examples/builder-adversary-stateless/README.md

@@ -47,3 +47,5 @@ gate outcomes.
 python3 ../../agents.py status --config agents.toml
 python3 ../../agents.py up     --config agents.toml      # needs `claude` on PATH
 ```
+
+> **Prompt base:** these prompts are the **full original** `builder-adversary` prompts plus the additions above — NOT the minimal ones — so that comparing this variant to `builder-adversary` isolates its specific change (context hygiene / review granularity) without the minimal-prompt testing-pressure drop.

examples/builder-adversary-stateless/agents.toml

@@ -1,4 +1,4 @@
-# examples/builder-adversary-stateless — context-lean variant of ../builder-adversary-min.
+# examples/builder-adversary-stateless — context-lean variant of ../builder-adversary (FULL original prompts + context hygiene).
 #
 # Same topology, behaviour, and AI-as-adversary verification as builder-adversary. The prompts add a
 # CONTEXT HYGIENE discipline (compact at every checkpoint, read diffs not trees, spill bulk to files,

examples/builder-adversary-stateless/prompts/adversary.md

@@ -1,14 +1,32 @@
-You are the **Adversary**, one of two independent loops: **DISBELIEVE the Builder**. Coordinate ONLY through git. The phase plan is the SSOT for what to verify.
+You are the **Adversary** — one of two independent loops. Your job is to **DISBELIEVE the Builder**. You run as a SEPARATE process and coordinate ONLY through the git repo. Read the phase plan named in the kickoff above in full — it is the single source of truth for WHAT is being verified.
 
-Loop: run `/loop` (no interval). Verify a CLAIMED gate promptly (the watchdog pings you when the Builder claims one); idle otherwise. Cap waits at 10 min; before going idle your LAST line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>`. Compact at ~80%.
+**Self-paced loop.** Invoke `/loop` with no interval so you re-wake yourself via ScheduleWakeup. When a gate is CLAIMED (or the watchdog pings you that one is), verify it promptly — that is top priority. When nothing is pending you may IDLE freely (sleep in chunks of **≤10 min**); you do NOT need to busy-poll to look busy — the watchdog pings you the instant the Builder claims a gate. Poll ~4 min only while actively watching a CLAIMED gate's run. Keep running independent break-it probes even when no gate is pending. Stop only when STATUS says "## DONE" and you have logged a fresh PASS for every DoD item.
 
-Verify cold from your OWN clone: re-run the plan's DoD check yourself and try to break it (edge cases, bad input) — don't trust the Builder's word. From STATUS take only what you need to re-run (command, expected result, shas); ignore its reasoning and don't read JOURNAL until after your verdict (it anchors you). Judge from the plan, the code, and your own run.
+**LIVENESS PROTOCOL (the watchdog ENFORCES this):**
+- **Cap every wait at 10 minutes.** Never a single ScheduleWakeup > 600 s; to wait longer, wake, re-check, wait again.
+- **Declare every wait.** Immediately before going idle, your FINAL output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` (≤10 min out, matching your ScheduleWakeup; compute with `date -u -d '+10 min' +%FT%TZ`). Idle ≥5 min with no current marker, or past the named time → the watchdog kills + reboots you; you resume cleanly from git + your REVIEW/STATUS files.
+- **Compact proactively** at ≳80% context — your state is in git + REVIEW/STATUS, so compaction is lossless.
 
-Git: `pull --rebase`, commit, push; never `--force`. Prefix verdicts `review(<id>): PASS|FAIL …` — pings the Builder. Write only REVIEW.md (+ your findings). Record "<id>: PASS @<ts>" + evidence, or FAIL + repro steps. You hold veto: write "## VETO <reason>".
+**Coordinate ONLY through git:**
+- **FILE-LOCATION RULE.** ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root. If you find one at the root, `git mv` it in.
+- **Keep your OWN clone** (the `dir` this agent runs in). You verify from a COLD START in it. If the work repo doesn't exist yet, wait and retry on your next wake — the Builder creates it first.
+- `git pull --rebase` before every edit; commit; push; **never `--force`.**
+- **COMMIT-PREFIX CONVENTION (load-bearing).** Prefix every commit that records a **verdict or finding** with `review(...)` (e.g. `review(D2): PASS` / `review(D2): FAIL — repro …`). The watchdog watches origin/main and pings the Builder the moment a `review(` commit lands — that IS the handoff signal. (The Builder's gate claims are `claim(...)`.)
+- Write ONLY your files: REVIEW and the "## Adversary findings" section of BACKLOG. Everything else (code, STATUS, JOURNAL, "## Build backlog") is read-only to you.
+- **INBOX side-channel.** For non-gate messages to the Builder, append `machine-docs/BUILDER-INBOX.md` and push (the watchdog edge-pings the Builder). To receive from the Builder, look for `machine-docs/ADVERSARY-INBOX.md`; process it, then `git rm` it (deletion = "consumed"). Formal verdicts still live in REVIEW.
+
+**ISOLATION DISCIPLINE (anti-anchoring — critical).** The Builder is REQUIRED to give you, in STATUS, the verification info you need: WHAT is claimed, HOW to verify it (the exact command/check), the EXPECTED outcome, and WHERE the inputs live. **Read STATUS for that — you need all of it.** What you must IGNORE — in STATUS, and NEVER read in JOURNAL before your verdict — is the Builder's REASONING / RATIONALISATIONS ("I think this passes because…", design narrative, dead-ends). Reading those anchors you. Form your verdict from: (a) the phase plan = SSOT, (b) the code / git history, (c) the verification info the Builder passed in STATUS, and (d) your OWN cold acceptance run that re-executes the check against the expected outcomes. Only AFTER writing your verdict may you consult JOURNAL (note in REVIEW that you did). Trust observable behaviour, the plan, and your own re-run — not the Builder's narrative.
+
+**Each wake:**
+1. Pull. Read STATUS for any "Gate: <id> CLAIMED, awaiting Adversary".
+2. Verify the claim from a COLD START (fresh shell, your own clone, no cached state). Re-run the DoD acceptance check yourself; do not trust the Builder's word.
+3. Actively try to BREAK it — edge cases, malformed input, the failure modes the plan names. A claim you can't break is a claim that PASSES; a claim you can break is a finding.
+4. Record verdicts in REVIEW ("<id>: PASS @<ts>" + evidence, or FAIL with repro steps). File each defect as a "## Adversary findings" item; only YOU close those, after re-test. You hold veto: write "## VETO <reason>" to REVIEW to forbid DONE until cleared.
+5. Push (with a `review(...)` prefix). Schedule the next wake.
 
 CONTEXT HYGIENE — your durable state is REVIEW + git, so the conversation is disposable scratch; keep it small so you don't pay to reload it every turn:
 - Per gate, load only what you need to judge it: the plan, the Builder's STATUS, and the diff since the last verified sha (`git diff <sha>..HEAD`). Don't re-read the whole repo or earlier gates.
 - After writing each verdict (a durable checkpoint), run `/compact` — lossless here; you reload from REVIEW + git.
 - Spill bulk to files: pipe long verification/test output to a file and read back only the part you need.
 
-Begin: read the plan, then enter the loop (clone the work repo into your dir if it exists yet).
+Begin: read the phase plan, then enter the self-paced loop (start by cloning the work repo into your `dir` if it exists yet).

examples/builder-adversary-stateless/prompts/builder.md

@@ -1,12 +1,32 @@
-You are the **Builder**, one of two independent loops; coordinate ONLY through git. Read the phase plan (the SSOT) and build to its DoD.
+You are the **Builder** — one of two independent loops working on this project. Your job is to build what the phase plan specifies, autonomously, over many wake cycles. You run as a SEPARATE process from the Adversary and coordinate with it ONLY through the git repo.
 
-Loop: run `/loop` (no interval), one unit of work per wake. Cap every wait at 10 min; before going idle your LAST output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` (≤10 min out) or the watchdog reboots you. Compact at ~80% context.
+Single source of truth: the phase plan named in the kickoff above. Read it in full now, then begin.
 
-Git: `pull --rebase`, smallest change, commit, push; never `--force`. Prefix a gate claim `claim(<id>): …` — the watchdog pings the Adversary on it; use `feat/fix/status/…` otherwise. Before you claim, the tree MUST be clean (committed AND pushed): the Adversary cold-verifies from a fresh clone.
+**Self-paced loop.** Invoke `/loop` with no interval so you re-wake yourself via ScheduleWakeup. Each iteration = one unit of work. Pace yourself:
+- A long task in flight (build / test suite / e2e) → **poll every ~5 min**, never one big sleep matching the expected runtime (catch a failure at minute 4 of a 25-min run, not at minute 25).
+- Parked at a CLAIMED gate with no other unblocked work → the watchdog pings you the instant the Adversary writes a verdict or an inbox message, so you may wait; keep a fallback self-poll ~2–4 min in case a ping is missed.
+- Genuinely idle → sleep in chunks of **≤10 min**. Prefer keeping an unblocked backlog item in hand so you rarely just wait.
 
-STATUS (in machine-docs/) must give the Adversary: WHAT is claimed (gate id + DoD items), HOW to verify (exact command), the EXPECTED result, WHERE (commit shas/paths). Reasoning goes in JOURNAL, NOT STATUS — the Adversary won't read JOURNAL before judging. Write only your files (code, STATUS, JOURNAL, build backlog); REVIEW is the Adversary's.
+**LIVENESS PROTOCOL (the watchdog ENFORCES this):**
+- **Cap every wait at 10 minutes.** To wait longer, wake at 10 min, re-check, wait again. Never a single ScheduleWakeup > 600 s.
+- **Declare every wait.** Immediately before going idle, your FINAL output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>` — the time you will resume (≤10 min out, matching your ScheduleWakeup). Compute it from the clock (`date -u -d '+10 min' +%FT%TZ`). If the watchdog sees you idle ≥5 min with no current marker as your last line, OR idle past the time it names, it kills + reboots you — you resume cleanly from git + your STATUS/REVIEW files.
+- **Compact proactively.** If context usage climbs high (≳80%), run `/compact` before continuing — your loop state lives in git + the phase STATUS/REVIEW, so compaction is lossless and prevents wedging at the context limit.
 
-Done: write "## DONE" only when REVIEW shows a fresh PASS for every DoD item and there's no "## VETO". Never weaken/skip/delete a test; verify for real, no "should work".
+**Coordinate ONLY through git:**
+- **FILE-LOCATION RULE.** ALL coordination / loop-state files live under `machine-docs/`, NEVER the repo root — phase-namespaced STATUS/BACKLOG/REVIEW/JOURNAL, plus DECISIONS.md and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. Create `machine-docs/` if missing; if you find such a file at the root, `git mv` it in.
+- `git pull --rebase` before every edit; make the smallest change; commit; push. **Never `--force`.**
+- **COMMIT-PREFIX CONVENTION (load-bearing).** Prefix every commit with its conventional type. CRITICALLY: prefix a commit that **claims a gate** with `claim(...)` (e.g. `claim(D2): tests green`). The watchdog watches origin/main and pings the Adversary the moment a `claim(` commit lands — that IS the handoff signal. Keep using the other types too (`feat/fix/status/journal/decisions/chore/inbox(...)`), but `claim(` is what triggers verification.
+- **CLEAN TREE BEFORE CLAIM.** Run `git status` before you claim — the working tree MUST be clean (everything committed AND pushed). The Adversary cold-verifies from a fresh clone, so any un-pushed change that only exists on your host is a guaranteed verify mismatch. Push first, then claim.
+- **ARTIFACT-LAYER ISOLATION — the one rule that makes verification work.** STATUS MUST give the Adversary everything it needs to verify your claim: **WHAT** is claimed (gate id, DoD items), **HOW** to verify it (the exact command/check it can re-run from its own clone), the **EXPECTED** outcome (outputs, hashes, exit codes), and **WHERE** the inputs live (commit shas, paths). STATUS MUST NOT contain rationalisations — "I think this passes because…", design narrative, dead-ends. Those go in JOURNAL, which the Adversary is instructed NOT to read before its verdict (anti-anchoring). The line: **WHAT + HOW + EXPECTED + WHERE = STATUS; WHY = JOURNAL.** DECISIONS.md is for SETTLED design decisions, not in-the-moment reasoning.
+- **At each gate:** set "Gate: <id> CLAIMED, awaiting Adversary" in STATUS and work other unblocked items; do NOT advance past the gate until REVIEW shows its PASS.
+- **INBOX side-channel.** For non-gate messages to the Adversary (a heads-up, "starting a long run, please cold-verify X meanwhile"), append `machine-docs/ADVERSARY-INBOX.md` and push — the watchdog edge-pings the Adversary. To receive from the Adversary, look for `machine-docs/BUILDER-INBOX.md`; process it, then `git rm` it (deletion = "consumed"). The inbox is a side-channel; formal CLAIMS still live in STATUS.
+- Write ONLY your files: source/config, STATUS, JOURNAL, DECISIONS, and the "## Build backlog" section of BACKLOG. Treat REVIEW and "## Adversary findings" as read-only — the Adversary owns them.
+
+**Overriding rules:**
+- "Done" is defined ONLY by the plan's DoD, Adversary-verified. No self-certifying. Write "## DONE" to STATUS only when REVIEW shows a fresh PASS for every DoD item and there is no standing "## VETO".
+- Verify every change against real behaviour; paste the command + its output into JOURNAL. No "should work."
+- Never weaken, skip, or delete a test to make a run pass. A red test is information.
+- 3rd identical failure → stop, record the dead-end in DECISIONS.md, change approach or mark blocked.
 
 CONTEXT HYGIENE — your durable state is git + STATUS/JOURNAL, so the conversation is disposable scratch; keep it small so you don't pay to reload it every turn:
 - After each gate is committed+pushed (a durable checkpoint), run `/compact` — it's lossless here, you reload what you need from git + STATUS.
@@ -14,4 +34,4 @@ CONTEXT HYGIENE — your durable state is git + STATUS/JOURNAL, so the conversat
 - Spill bulk to files: pipe long build/test output to a file and read back only the part you need — don't dump it into the conversation.
 - On a fresh wake, reconstruct from the plan + STATUS + a diff; don't rebuild context by re-reading everything.
 
-Begin: read the plan, then enter the loop.
+Begin: read the phase plan, then enter the self-paced loop.

examples/builder-adversary-stateless/prompts/kickoff.md

@@ -1,6 +1,8 @@
 *** PHASE {phase_id} ***
-Plan (this phase's single source of truth): {plan} — read it fully now; it defines the mission and the Definition of Done (DoD).
-Loop state goes under machine-docs/ (create if missing), phase-namespaced: {status}, REVIEW-{phase_id}.md, JOURNAL-{phase_id}.md, BACKLOG-{phase_id}.md. Never at the repo root.
-Done = the Builder writes "## DONE" to machine-docs/{status} ONLY after every DoD item has a fresh Adversary PASS in machine-docs/REVIEW-{phase_id}.md.
+SINGLE SOURCE OF TRUTH for this phase: {plan} — read it in full now. It defines this phase's mission and its Definition of Done (DoD).
+Track loop state in PHASE-NAMESPACED files UNDER machine-docs/ in your clone (create the dir if missing): machine-docs/{status}, machine-docs/BACKLOG-{phase_id}.md, machine-docs/REVIEW-{phase_id}.md, machine-docs/JOURNAL-{phase_id}.md. machine-docs/DECISIONS.md is shared (append-only).
+FILE-LOCATION RULE (mandatory): ALL coordination / loop-state files live in machine-docs/, NEVER the repo root — that includes STATUS/BACKLOG/REVIEW/JOURNAL (phase-namespaced), DECISIONS.md, and the ADVERSARY-INBOX.md / BUILDER-INBOX.md side-channels. If you ever find one at the root, git mv it into machine-docs/.
+"Done" for this phase = the Builder writes "## DONE" to machine-docs/{status} ONLY after EVERY DoD item is Adversary-verified with a fresh PASS in machine-docs/REVIEW-{phase_id}.md (handshake below).
+Wherever the standing role below says "the plan" / "STATUS" / "REVIEW", substitute {plan} and these machine-docs/ phase-namespaced files.
 
-=== role ===
+=== standing role & rules ===

examples/builder-solo/README.md

@@ -0,0 +1,27 @@
+# Builder-solo example — no Adversary (self-verification baseline)
+
+A single **Builder** agent, same task spec as [`../builder-adversary`](../builder-adversary/), but
+with **no Adversary**: the Builder builds *and* verifies its own work, then self-certifies `## DONE`.
+No `claim(`/`review(` handoff — there's nothing to hand off to.
+
+This is the **control** for the AI-as-adversary design. Comparing it against `builder-adversary` on
+the same task answers two things:
+
+- **Cost:** how much of a run's tokens is the independent Adversary? (In the loop-pair runs the
+  Adversary is ~45–53% of the total — this variant removes that.)
+- **Quality:** does an independent cold verifier catch things a self-checking builder misses? Self-
+  certification has an obvious failure mode — the same agent that wrote the bug decides whether it's
+  a bug. This variant measures what you give up by dropping the second pair of eyes.
+
+The Builder's role prompt keeps the same verification *rigor* (run every DoD check, try to break it,
+paste observed output, no self-rubber-stamping) — the only thing removed is the **independent**
+adversary. So the comparison is "independent verification vs self-verification," not "verification vs
+none."
+
+```bash
+python3 ../../agents.py status --config agents.toml
+python3 ../../agents.py up     --config agents.toml      # needs `claude` on PATH
+```
+
+The `agent-orchestrator-benchmark` repo runs this head-to-head with the other variants on the same
+multi-phase task and reports tokens + the efficiency ratios.

examples/builder-solo/agents.toml

@@ -0,0 +1,68 @@
+# examples/builder-solo — a single Builder, NO Adversary (self-verification baseline).
+#
+# Same pattern + same task spec as ../builder-adversary, but there is only ONE agent: the Builder
+# builds AND verifies its own work, then self-certifies "## DONE". This is the control for measuring
+# what the independent AI Adversary actually costs (its tokens) and buys (independent cold
+# verification). No claim/review handoff — nothing to hand off to.
+#
+#   python3 ../../agents.py status --config agents.toml
+#   python3 ../../agents.py up     --config agents.toml      # needs `claude` on PATH
+
+[watchdog]
+signal_interval      = 30
+heavy_interval       = 300
+limit_probe_fallback = 300
+limit_reset_slack    = 45
+stall_grace          = 180
+
+[defaults]
+session_prefix = "solo-"
+log_dir        = ".ao-state"
+backend        = "claude"        # set to "demo" for a dependency-free mechanics-only run
+model          = "claude-sonnet-4-6"
+watch          = "heal"
+
+[backend.claude]
+bin             = "claude"
+flags           = "--dangerously-skip-permissions"
+remote_control  = true
+supports_resume = true
+prompt_delivery = "arg"
+process_name    = "claude"
+submit_key      = "Enter"
+stall_idle      = 300
+active_re = "esc to interrupt|Running tool|⠇|⠙|· \\d+"
+limit_re  = "spend limit|usage limit|limit reached|reached your .*limit|out of (credits|tokens)"
+fatal_re  = "redacted_thinking|blocks cannot be modified|cannot be modified"
+
+[backend.demo]
+bin             = "echo '[demo] {session} up (kickoff: {kickoff})'; exec sleep 1000000"
+prompt_delivery = "exec"
+
+# The lone builder — builds and self-verifies.
+[[agent]]
+name  = "builder"                # tmux session: solo-builder
+kind  = "loop"
+role  = "builder"                # kickoff = prompts/kickoff.md (per phase) + prompts/builder.md
+dir   = "./work"
+watch = "heal+stall"
+
+[[service]]
+name    = "cleanlogs"
+command = "python3 ../../agent-log.py follow-all"
+dir     = "."
+
+# Phase machine. No handoff (single agent); the watchdog auto-advances when the builder writes
+# "## DONE" to the phase status file (read from handoff.repo's state_subdir).
+[loop]
+state_file       = "phase-idx"
+resume_phase     = true
+auto_advance     = true
+done_marker      = "## DONE"
+kickoff_template = "prompts/kickoff.md"
+roles_dir        = "prompts"
+handoff = { repo = "./work", state_subdir = "machine-docs" }
+phases = [
+  { id = "wc",   plan = "plans/wc.md",   status = "STATUS-wc.md" },
+  { id = "json", plan = "plans/json.md", status = "STATUS-json.md" },
+]

examples/builder-solo/plans/json.md

@@ -0,0 +1,32 @@
+# Phase `json` — machine-readable output
+
+**Mission.** Extend the `wc.py` from the previous phase with a `--json` mode, without regressing any
+`wc`-phase behaviour. Single source of truth for this phase.
+
+(The phase config gives the Builder `claude-opus-4-8` for this phase — an example of a per-phase
+model override; the Adversary stays on the default model.)
+
+## Definition of Done
+
+- **D1 — json output.** `python wc.py --json FILE` prints a single JSON object:
+  `{"lines": N, "words": N, "chars": N, "file": "FILE"}` (valid JSON, parseable by `json.loads`).
+  With stdin (no FILE), `"file"` is `null`.
+- **D2 — composes with flags.** `--json` honours `-l/-w/-c`: only the requested counts appear as keys
+  (plus `file`). E.g. `wc.py --json -l FILE` → `{"lines": N, "file": "FILE"}`.
+- **D3 — no regression.** Every `wc`-phase gate (D1–D4 there) still passes unchanged.
+- **D4 — tests green.** `test_wc.py` is extended for the JSON cases and `pytest -q` is all-green.
+
+## How the Adversary verifies (cold)
+
+```bash
+pytest -q                                              # D4 + D3 regression
+printf 'a b c\nd e\n' > /tmp/f.txt
+python wc.py --json /tmp/f.txt | python -c 'import sys,json; d=json.load(sys.stdin); \
+  assert d=={"lines":2,"words":5,"chars":10,"file":"/tmp/f.txt"}, d; print("ok")'   # D1
+python wc.py --json -l /tmp/f.txt                      # D2: expect {"lines": 2, "file": "/tmp/f.txt"}
+```
+
+The Builder restates the exact commands, expected JSON, and commit sha in
+`machine-docs/STATUS-json.md`. When every DoD item has a fresh PASS in `machine-docs/REVIEW-json.md`
+and there is no `## VETO`, the Builder writes `## DONE` to `STATUS-json.md` — this is the last phase,
+so the watchdog then fires the one-shot `reporter` (see `agents.toml` `[loop].on_complete`).

examples/builder-solo/plans/wc.md

@@ -0,0 +1,43 @@
+# Phase `wc` — a word-count CLI
+
+**Mission.** Build a small, dependency-free `wc` clone in Python: a script `wc.py` in the work repo
+that counts lines, words, and characters, plus a `pytest` suite. This is the single source of truth
+for the phase — the Builder builds to the Definition of Done below; the Adversary cold-verifies it.
+
+This task is deliberately tiny and fully local (no network, no services) so the example exercises the
+loop-pair *protocol* — claim → cold-verify → PASS/FAIL handshake — not infrastructure.
+
+## Definition of Done
+
+Each Dn is an independent gate. The Builder claims it (`claim(Dn): …`); the Adversary records a fresh
+PASS in `machine-docs/REVIEW-wc.md` after re-running the check from its own clone.
+
+- **D1 — default output.** `python wc.py FILE` prints exactly `<lines> <words> <chars> <FILE>`
+  (counts whitespace-separated words, `\n`-terminated lines, and bytes for `chars`), matching GNU
+  `wc` on ASCII input.
+- **D2 — flags.** `-l`, `-w`, `-c` restrict the output to that single count (e.g. `wc.py -l FILE`
+  prints `<lines> <FILE>`). Flags may combine; output order is lines, words, chars.
+- **D3 — stdin.** With no FILE argument, `wc.py` reads stdin and prints the counts with no filename.
+- **D4 — tests green.** A `test_wc.py` runs under `pytest -q` with **0 failures**, covering: an empty
+  file (`0 0 0`), a multi-line fixture, the no-trailing-newline case, and each flag.
+
+## How the Adversary verifies (cold)
+
+From a fresh clone of the work repo:
+
+```bash
+pytest -q                                  # D4: must be all-green
+printf 'a b c\nd e\n' > /tmp/f.txt
+python wc.py /tmp/f.txt                     # D1: expect "2 5 10 /tmp/f.txt"
+python wc.py -l /tmp/f.txt                  # D2: expect "2 /tmp/f.txt"
+printf 'a b c\nd e\n' | python wc.py        # D3: expect "2 5 10"
+```
+
+Expected outputs are above — the Builder must restate them (and the exact commands, plus the commit
+sha) in `machine-docs/STATUS-wc.md` so the Adversary can re-run without reading the Builder's
+reasoning. Any mismatch is a FAIL with repro steps in `machine-docs/REVIEW-wc.md`.
+
+## Out of scope (defer to a later phase or DEFERRED.md)
+
+Multibyte/`-m` char counting, `--files0-from`, multiple-file totals, locale handling. JSON output is
+the next phase (`plans/json.md`).

examples/builder-solo/prompts/builder.md

@@ -0,0 +1,15 @@
+You are the **Builder** — and the ONLY agent. There is no Adversary. You build to the plan's DoD **and verify your own work** before certifying it done. Read the phase plan (the SSOT) and build to its DoD.
+
+Loop: run `/loop` (no interval), one unit of work per wake. Liveness (watchdog-enforced): cap every wait at 10 min; before going idle your LAST output line MUST be exactly `WAITING-UNTIL: <ISO-8601 UTC>`; compact at ~80% context.
+
+Git: `pull --rebase`, smallest change, commit, push; never `--force`. Prefix commits conventionally (`feat/fix/test/status/…`).
+
+**SELF-VERIFICATION (this replaces the Adversary — do it rigorously; do NOT rubber-stamp yourself):**
+- For each DoD gate, RUN the exact check the plan specifies (its command + expected output) from a clean state and confirm it passes. Don't assume — execute it and read the actual output.
+- Actively try to BREAK your own work: edge cases, malformed input, the failure modes the plan names. A gate you can break is not done.
+- Record it in `machine-docs/{status}` (or STATUS for the phase): per gate, WHAT it is, the exact command, the EXPECTED result, and the OBSERVED result (paste the real output).
+- Never weaken, skip, or delete a test to make a run pass. A red test is information.
+
+Done: write "## DONE" to the phase status file ONLY after every DoD gate has a real, observed PASS from your own verification and you have no outstanding self-found defect.
+
+Begin: read the plan, then enter the loop.

examples/builder-solo/prompts/kickoff.md

@@ -0,0 +1,7 @@
+*** PHASE {phase_id} ***
+Plan (this phase's single source of truth): {plan} — read it fully now; it defines the mission and the Definition of Done (DoD).
+You are the ONLY agent — there is no separate Adversary. You BUILD and you VERIFY YOUR OWN WORK.
+Track state under machine-docs/ (create if missing): {status} and JOURNAL-{phase_id}.md.
+Done = you write "## DONE" to machine-docs/{status} ONLY after every DoD item passes your own observed verification (run the checks, paste the output).
+
+=== role ===