Files
pipelines/internal/author/skill/references/control.md
T
alan 5090f1cf4e Pipelines skill: outcome-first output, aligned review and loop guidance, operator material moved to docs
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.
2026-11-04 17:27:01 +00:00

55 lines
2.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.