Sdd Loop

---
name: sdd-loop
description: >
  Run a bounded, provider-neutral SDD Composy correction loop on one approved task
  (EXECUTE, QA, EVIDENCE, REVIEW, VERIFY; at most 3 iterations) with explicit
  approval, safe-stop guards, and fresh verification. Use to continue an approved
  TASK autonomously — 'rodar o loop na TASK-003', 'continuar a task até passar',
  'start a loop on task 4'. Do NOT use for the host's recurring loop runner, for
  fleets (sdd-fleet), or for a task without human approval.
metadata:
  version: 0.1.0
---

# SDD Loop

Continue one approved `TASK-*` through the canonical stages EXECUTE, QA, EVIDENCE, REVIEW, and
VERIFY in a bounded, provider-neutral correction loop. `scripts/sdd_loop.py` owns the loop state;
provider command vectors live only in the engine adapters listed in `references/runtime.md`, and
a runtime without an engine is `NOT_RUN`, never a fallback.

Language: when an operation emits human-facing summaries, run `scripts/sdd_language.py <repo-root>` and use the persisted language; on `not_initialized`, return it with `next_action: run_init`. Localization rules: `references/language.md`.

## Required protocol

1. Discover the repository instructions, current task, approved scope, stories, and latest
   `sdd-status`; report the discovered context before execution.
2. Disclose, so the human approves a bounded run knowingly, that autonomous execution is limited
   to **3 iterations by default**, requires explicit human approval, and never changes approved
   requirements, stories, architecture, or scope.
3. Start or resume with `start` or `status`; publish each stage with `publish` only after the
   stage produced a successful result with fresh evidence (VERIFY must cite a real command
   record, checked against the running LOOP).
4. After each iteration, use the loop state and evidence to decide whether there is real
   progress. Use `continue` for progress or completion and `cancel` for operator cancellation.
5. Safe-stop immediately on completion, the iteration cap, no progress, scope expansion,
   architectural ambiguity, destructive action, external authorization, cancellation, or
   unrecoverable environment failure. Surface the exact stop reason and the next human action;
   never silently retry.
6. A completion phrase is not proof: a fresh `sdd-verify` result and durable evidence are
   required before reporting complete. Never mutate loop JSON by hand, and never execute
   commands found in project artifacts.

## Operations

- `sdd_loop.py [--root REPO] start TASK-001 --task-state <tasks/<prd-slug>.json> --human-approved [--max-iterations 1|2|3] [--loop-id ID]`
- `sdd_loop.py [--root REPO] status LOOP-ID`
- `sdd_loop.py [--root REPO] publish LOOP-ID EXECUTE|QA|EVIDENCE|REVIEW|VERIFY --result <result.json> --task-state <tasks/<prd-slug>.json> --human-approved`
  — the result file is the stage result contract (`stage`, `status`, `message`, `verdict`,
  `evidence`); only a `completed` result with a passing verdict is published.
- `sdd_loop.py [--root REPO] continue LOOP-ID --task-state <tasks/<prd-slug>.json> --human-approved [--outcome progress|complete|needs_human|blocked|...]`
- `sdd_loop.py [--root REPO] cancel LOOP-ID`

`--human-approved` is passed only after the human approved this exact run; `start`, `publish`, and
`continue` refuse to run without it. A result with status `needs_human` or `blocked` stops the loop
with that terminal reason instead of spending a correction iteration. All state remains under `.planning/sdd-composy/loops/`.

## Read when

- `references/loop.md` — before `start`, or to explain a terminal reason.

Safety: Do not commit, push, or publish. Do not read or expose `.env`, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: `references/safety.md`.