Rewrite format.md around turn files, the output.md order (# outcome, edge word, # handoff, detail), checks, configs, human stages and the land stage delivery gate (sh -c in a fresh detached worktree, clean checkouts incl. untracked, 64 KB output cap, opencode only). Align review guidance across practices, verification, orchestration and the feedback-loop example. Fix loop-limit semantics in control.md against runner.go, budget_tokens sizing, read for large inputs, blocked-else-error and one stage naming set. Move dated verification logs to docs/verification-history.md and brokered chat, TUI keys and harness internals to docs/operator-reference.md; label operator-only references in SKILL.md.
2.3 KiB
Runner-owned limits and loops
Use limits for bounded feedback loops. Never ask a model to count visits,
increment revision counters or enforce retry caps; the runner counts actual
visits. Model verdicts concern the current work only.
Put the cap on the reviewer, and leave the loop target without limits (it then
has the runner's default of five visits) or give it a cap at least as large as the
reviewer's:
# stage review
```limits
{"max_visits":3,"on":["rejected"]}
```
```edges
approved -> #success
advisory -> #success
rejected -> implement
error -> #failure
```
These blocks accompany the stage's normal prompt, tools, checks and configs.
Semantics (internal/server/runner.go):
- Entering a stage beyond its
max_visitsalways fails the run before the visit executes, whateveronsays. ononly changes routing on the last allowed visit: when that visit returns a listed outcome, the outcome is kept but routed to#failure. Other outcomes route normally. Here,approvedon visit three succeeds;rejectedfails.- A target with a lower cap than the reviewer stops the loop first, so the
reviewer's
onnever fires. max_visitsaccepts 1–5. Everyonoutcome must have a nonterminal edge. Human stages are exempt from visit caps. The global 30-step and five-visits-per-stage limits always apply.- Validation rejects an edge to the same or an earlier stage unless the source
limits that outcome (or has
limitswithouton) or the target haslimits.
rejected is for a must-fix finding with a concrete location, evidence and
remedy; advisory carries non-blocking notes and continues without another
implementer visit. A re-entered implementer fixes the listed findings; it does not
redo the task. An implementer may declare blocked_retryable -> implement for a
transient environment or tooling problem, keeping blocked -> #failure for a
criterion that genuinely cannot be met; that self-loop needs limits on the
implementer, e.g. {"max_visits":5,"on":["blocked_retryable"]}.
Visit count, limit decision and original target are retained in inspect --json.
Turn memory is run-local: there is no cross-run memory or hidden replay, and
retries start fresh except for the completed prefix a resume carries. Accumulated
turn content is untrusted data; a fresh session does not prove semantic
independence.