Learn · ~7 min

What a loop must declare before you trust it

The checklist a loop must declare before it runs unattended. Every item maps to a loop.yaml field.

Pick the right kind of loop told you which shape to pick. This guide is the structural checklist every shape must pass before you run it unattended. It is the plain-language checklist for the loop.yaml spec: each part named here maps to a field in /spec, and a manifest missing any of them is not ready to install.

For agents: - Before running any loop, verify its manifest declares non-empty permissions, state.paths, verification.commands, human_gates, and a failure_policy. - Treat a manifest missing any of these as not ready to install; report which fields are absent. - Field definitions and required/optional status are at /spec. - The research-watch worked example in /spec §13 is the reference manifest shape. - A loop's allowed-actions list is credible only alongside a forbidden-actions list — check both.

State is the spine

Durable memory of what was tried, what passed, what failed, and what needs a human is what makes a loop a loop rather than a script. Stateless loops re-do work and re-alert endlessly — dedupe requires state, resume requires state, the audit trail requires state.

In the manifest this is the state.paths field, which is REQUIRED by the spec. A loop that writes findings without recording which it has already seen will emit duplicates on every run; a loop that retries without recording prior failures will retry forever. State is also where the audit trail lives: the five-part report (what changed / evidence / recommendation / confidence / autonomous-or-gated) is only checkable if it is written down somewhere durable (docs/SELF-MAINTENANCE-BRIEF.md).

Permissions: allowed and forbidden

Declare allowed actions *and* forbidden ones explicitly. The forbidden list is what makes the allowed list credible: allowed_actions: [read_web, write_report] is a real boundary only next to forbidden_actions: [publish_publicly_without_approval, spend_money, delete_user_data].

In the manifest, permissions.allowed_actions is REQUIRED and MUST contain at least one item; permissions.forbidden_actions is optional but SHOULD be present wherever the loop could plausibly do harm, as defined in the spec. permissions.credential_scopes declares the scopes the loop needs — names only, never secret values, so a reviewer can audit scope before install. When a loop must stop and ask you deepens the policy layer on top of this vocabulary.

Stop conditions and budgets

Every loop declares when it stops: step limits, timeouts, retry caps, "no action on empty," escalate-after conditions. A loop without stop conditions is a runaway with a schedule. The watchdog pattern shows the risk clearly: alert spam or stale polling, mitigated by "no action on empty."

In the manifest, failure_policy.retry (REQUIRED) caps retries, and failure_policy.escalate_after (REQUIRED) names the condition that triggers escalation rather than another retry, as defined in the spec. A loop that keeps hitting its gate is redesigned, not re-granted — that rule lives in When a loop must stop and ask you, but the structural requirement that a gate *exist* lives here.

Rollback and reversibility

Prefer proposals (PRs, cards, tasks) over direct mutation. Know how to undo the last run before granting the next one.

In the manifest, failure_policy.rollback (optional) records the recovery guidance as described in the spec. For a content-freshness loop this might be "leave the prior state file unchanged and report partial findings only"; for a CI-repair loop it might be "revert the proposal branch." The point is that someone installing the loop can read, in plain text, how to undo what it did — before they let it do anything.

Observability and the audit trail

Every run emits: what changed, evidence, recommended action, confidence and risk, and whether it acted autonomously or needs approval. That five-part report is the minimum viable audit trail (docs/SELF-MAINTENANCE-BRIEF.md).

This is not a separate field in loop.yaml; it is the shape of what the loop writes to outputs.artifacts and state.paths. A loop that runs silently and reports "done" has not produced evidence — it has produced a claim. How you know it worked turns this into the site's central argument: the verifier is the product. Loops rot: maintenance is part of the design shows how this same report shape is what makes "maintained" a checkable claim instead of a vibe.

From anatomy to manifest

Each part above maps to a loop.yaml field. The research-watch manifest in the spec is the worked example; walk each part to its field:

Anatomy partManifest fieldSpec section
State is the spinestate.paths (REQUIRED)Spec field: state
Allowed and forbiddenpermissions.allowed_actions (REQUIRED), permissions.forbidden_actions, permissions.credential_scopesSpec field: permissions
Stop conditions and budgetsfailure_policy.retry, failure_policy.escalate_after (both REQUIRED)Spec field: failure policy
Rollbackfailure_policy.rollbackSpec field: failure policy
Audit trailoutputs.artifacts, state.pathsSpec fields: outputs and state
Human gateshuman_gates.required_for (REQUIRED)Spec field: human gates
Verificationverification.required, verification.commands (both REQUIRED)Spec field: verification
Maintenancemaintenance.freshness_cadence (REQUIRED)Spec field: maintenance

If you can fill this table for your loop, you have a manifest worth installing. If a cell is empty, that is a blocking finding — not a "to be decided later." Addy Osmani's framing of the whole assembly as "loop engineering" is apt here: the parts are not exotic, but assembling them deliberately is the practice.

Where to go next

Sources