5090f1cf4e
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.
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# 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:
|
||
|
||
````markdown
|
||
# 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_visits` always fails the run before the visit
|
||
executes, whatever `on` says.
|
||
- `on` only 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, `approved` on visit three succeeds; `rejected` fails.
|
||
- A target with a lower cap than the reviewer stops the loop first, so the
|
||
reviewer's `on` never fires.
|
||
- `max_visits` accepts 1–5. Every `on` outcome 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 `limits` without `on`) or the target has `limits`.
|
||
|
||
`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.
|