loop-engineering

Loop Engineering

Design a loop with a control-system frame, not as a repeated prompt. This is an operating analogy for measurement, bounded action, verification, and state; it is not a safety proof. Its only valid form is:

goal + state + tools + budget
            |
            v
plan -> act -> observe -> independently verify -> decide
  ^                                               |
  |---------------- continue / stop / escalate ---|

V6 shorthand: every loop must state Trigger -> Execute -> Verify -> State. If any field is vague, do a one-shot task or write a review item instead of starting a loop.

Use scripts/validate_loop_contract.py before starting a loop. Do not bypass a failed contract.

For a concrete pattern, see references/ci-repair-loop-example.md.

Usage Template

Use loop-engineering for this task.

Mode: [goal | interval loop | automation | autoresearch]
Trigger: [manual | cron | webhook | CI | issue | other]
Objective: [measurable outcome]
Scope: [owned files, systems, or outputs]
Evidence: [test, metric, fixture, review, or inspection]
Limits: [iterations, time, tool/token/request budget]
Permission boundary: [allowed writes and approval gates]

Success Metrics

• A valid contract names the metric, independent verifier, finite caps, recovery path, and durable write-back.
• The selected topology is the lowest-complexity topology that can produce independent evidence.
• The final receipt distinguishes verified success, budget stop, stall, and blocked state.
• Scheduled knowledge loops distinguish unattended objective scans from supervised semantic writes.
• The loop mode, trigger, artifact path, work clock, and review budget are explicit before any repeated execution starts.

1. Choose The Execution Mode

Do not call every repeated task a loop. Pick the narrowest mode:

Mode	Use when	Verification
Goal	A bounded task should run until a concrete state is reached.	Test, grader, diff, or artifact acceptance.
Loop	A timeboxed exploration needs periodic observe/steer cycles.	Human steering plus evidence snapshots.
Automation	A schedule, webhook, or external event should trigger a routine.	Logs, receipts, metrics, and anomaly alerts.
AutoResearch	The agent can run many experiments against a cheap objective metric.	Metric leaderboard, sandbox, and reproducible trials.

Reject wide-open loops for taste, product strategy, vague quality, or irreversible external action. Convert them into a one-shot draft, review queue, or supervised goal.

2. Admit Or Reject The Loop

Use a loop only when the work is repeatable, the output can be checked, and each iteration can leave inspectable evidence.

Situation	Default
One reversible edit or answer	Do the task once; do not create a loop.
Objective metric and cheap verification	Use a single-agent loop.
Builder cannot objectively verify its own output	Use maker-checker.
Independent workstreams with explicit file/output ownership	Use manager-workers with an integration gate.
Taste-only, ambiguous, irreversible, or production-changing task	Keep a human approval gate; do not run unattended.

Reject a loop when its only stopping rule is “until satisfied,” “keep improving,” or “run forever.” Convert those requests into a metric, an acceptance fixture, a review queue, or a one-shot draft.

3. Check The Loop Harness

A runnable loop needs five building blocks plus memory:

Building block	Required check
Trigger	Manual start, cron, webhook, PR/CI event, queue threshold, or another agent.
Worktree / isolation	Independent branch, folder, sandbox, DB branch, or explicit shared-state lock.
Skills / rules	Only the task-local procedures needed for this loop.
Tools / connectors	Narrow tool contracts, permissions, failure path, and receipts.
Subagent / verifier	Separate maker/checker when the builder cannot objectively verify.
Memory	Artifact path, loop contract, state ledger, and global work clock/log.

For code loops, verify the codebase is:

• Legible: AGENTS.md, lints, or architecture rules expose forbidden paths and conventions.
• Executable: the agent can run the smallest local command without hidden manual setup.
• Verifiable: tests, E2E, screenshots, static checks, or review tools can catch failure.

If any readiness check fails, first create a one-shot setup task; do not run an autonomous loop.

4. Create The Loop Contract

Create .agent-state/loop-contract.md or an equivalent durable state file before the first action. Use this exact shape:

# Loop Contract

- Objective: Reduce the selected test suite's failures to zero.
- Mode: Goal.
- Trigger: Manual start from failing CI evidence.
- Scope: `packages/payments/**` and its tests only.
- Non-goals: No API redesign, dependency upgrades, or production deployment.
- Owner: Primary agent; checker owns verification only.
- Inputs: Failing test output and repository guidance files.
- Artifacts path: `.agent-state/payments-artifacts/`.
- State path: `.agent-state/payments-loop.md`.
- Work clock: Read and update `.agent-state/work-clock.md` before and after each iteration.
- Success metric: Selected test command exits 0 with no skipped failures.
- Evidence: `pnpm test --filter payments` output and changed-file diff.
- Verifier: Independent test command plus a checker agent or reviewer.
- Topology: maker-checker.
- Max iterations: 5.
- Time limit: 45 minutes.
- Budget: 20 tool calls; stop before context or cost cap.
- Review budget: Stop if the diff exceeds 1000 changed lines, 10 files, or the human review cap.
- Context policy: Compact state after every iteration; prune stale context when the tool, model, code, or bug changes.
- Stop condition: Success metric passes, or any cap/stall condition fires.
- Write-back: Update `.agent-state/payments-loop.md` and the task log.
- Permission boundary: Local branch writes only; no push, merge, or production action.
- Recovery: Revert the last iteration if tests regress; escalate with evidence after two repeated failures.

For scheduled knowledge-management loops, add:

- Trigger: Cron, automation, webhook, or daily note refresh.
- Execute: Objective scans, queue generation, dashboard refresh, or one supervised KR.
- Verify: Script receipt, lint report, link check, diff, or review receipt.
- State: Daily note, governance dashboard, backlog, log, or skill/SOP candidate.
- Automation boundary: No source-body mutation, concept merge/delete/rename, provenance invention, or semantic rule promotion without review.

Run:

python scripts/validate_loop_contract.py .agent-state/loop-contract.md --strict

Treat a budget cap or stall condition as a controlled stop, not success.

5. Calibrate The Verification Tier

Choose the cheapest verifier that still exercises the failure mode the loop could create. An LLM checker may interpret evidence, but for code, infrastructure, external systems, or durable wiki changes it cannot replace deterministic evidence.

Treat the Model-in-the-Loop / Software-in-the-Loop / Hardware-in-the-Loop vocabulary below as a verifier-fidelity analogy borrowed from embedded-system validation. It does not certify agent-loop safety.

Loop risk	Minimum verifier
Draft, plan, rubric, or contract work	Fixture, checklist, schema, or reviewer inspection.
Local code or document transformation	Real local command, parser, linter, render, diff, or targeted test.
Concurrent repository writes	Isolated branch/worktree plus integration diff and tests.
External connector, scheduled, staging, or production-like loop	Explicit approval, rollback path, audit log, and telemetry or dry-run evidence.

If no telemetry can reveal whether the loop helped, reject the loop or convert it into a one-shot draft with human review.

6. Run The Thin Loop

For each iteration:

1. Read only the contract, current state, last evidence, and minimum task context.
2. Plan one smallest reversible action that can affect the metric.
3. Act inside the contract's file, tool, and permission boundary.
4. Observe tool output, diffs, logs, tests, screenshots, or telemetry.
5. Have the declared verifier evaluate the evidence. The builder cannot be the sole verifier.
6. Record metric delta, changed files, evidence path, budget used, and next decision in state.
7. Stop, continue, or escalate according to the contract.

Keep context lean. Persist state and evidence in files rather than replaying a long chat transcript.

For long-lived loops, use "dreaming" only as a compaction step: summarize repeated failures, decisions, and durable lessons into the state file, project AGENTS.md, or a related skill. Treat old synthetic memory as having a half-life; remove stale context after the underlying tool, model, code, or bug has changed.

7. Select Topology Conservatively

Topology	Use when	Required controls
Single-agent	One owner and an objective check exist.	External test/linter/fixture; finite budget.
Maker-checker	Generation and evaluation need separate judgment.	Checker has a separate prompt or tool evidence and cannot edit before reporting.
Manager-workers	Work decomposes into independent territories.	Per-worker ownership, branch/worktree isolation for concurrent repo writes, integration order, shared-state rule, and final evaluator.

Do not use manager-workers merely to make a task feel more autonomous. Escalate to agent-teams-command when real multi-agent ownership, IPC, or integration work is required. Escalate to harness-engineering when permissions, credentials, scheduling, or production observability are the primary problem.

8. Stop, Recover, Or Escalate

Stop successfully only when the declared verifier accepts the declared evidence. Stop without success when a hard cap fires.

---

Content truncated.