feat(voyage): document recovery/retry iteration caps in trekexecute

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

commands/trekexecute.md

@@ -1298,6 +1298,38 @@ Status: partial (recovery_depth=2, escalated to user)
 
 Do NOT dispatch a third recovery. Report to the user.
 
+### Iteration caps + global recovery/retry budget
+
+Every recovery/retry loop in this executor has a documented numeric bound.
+These are **three distinct axes** — not one nested counter — plus a separate
+child turn cap:
+
+- **Per-step retry cap** — `attempts ≤ 3` (initial + **maximum 2 retries**;
+  Hard Rule 5 / Sub-step E). Bounds the retries of a *single* step.
+- **Per-session recovery cap** — `recovery_depth < 2` (Phase 7.6 hard cap).
+  Bounds how deep recovery *dispatch* nests.
+- **Global recovery/retry budget** — a new env-overridable constant
+  `TREKEXECUTE_MAX_RECOVERY_ITERATIONS` (default **25**) — the aggregate ceiling
+  on the **total count of recovery + retry iterations across the whole
+  execution**. This is the case the two caps above do NOT bound: many steps each
+  retrying up to 3× can sum unbounded. It primarily backstops the **retry
+  aggregate** (recovery dispatch is already hard-capped at 2). Surfaced and
+  enforced via the `iterations_remaining` counter (Phase 3 schema; decremented
+  on every recovery/retry iteration; reconciled at the Phase 7.5 completion
+  gate).
+- **Child turn cap** — `--max-turns` (`TREKEXECUTE_MAX_TURNS`, default 50)
+  bounds model turns inside a single `-p` child; a *different* axis from the
+  three above.
+
+Default **25** is an independent value from the cap research (practitioner range
+10–50; OWASP Agentic ASI08 financial-DoS), tuned down from the research ~50
+starting point for a tighter backstop. It is **not** a reconciliation with
+`--max-turns` (50) — the axes are incomparable. Operators may override:
+`TREKEXECUTE_MAX_RECOVERY_ITERATIONS=10 /trekexecute --project ...`. The
+`effort=='low'` single-foreground-loop path and the wave path are both subject to
+this aggregate ceiling; it is an execution-spec ceiling (enforced via the
+`iterations_remaining` counter), not a code-loop edit.
+
 ## Phase 8 — Final report
 
 Always produce a final report.
@@ -1698,3 +1730,10 @@ code-path.
     cleanup proceeds regardless. Rationale: this converts an unrecoverable
     failure (worktree removed, branch deleted, work lost) into a recoverable
     one (push succeeded, branch preserved on remote). Source: research/02 R3.
+
+20. **Three distinct iteration axes.** Per-step `attempts` (≤3), per-session
+    `recovery_depth` (<2), and the global `TREKEXECUTE_MAX_RECOVERY_ITERATIONS`
+    budget (default 25 — aggregate recovery+retry backstop) are independent
+    bounds, not one nested counter; child `--max-turns` (50) is a fourth,
+    separate axis. Every recovery/retry loop is bounded by at least one of them.
+    See "Iteration caps + global recovery/retry budget".