Skip to content

LOOP_CONTRACT.md

Latest commit

 

History

History
108 lines (80 loc) · 4.01 KB

LOOP_CONTRACT.md

File metadata and controls

108 lines (80 loc) · 4.01 KB
Raw

Citadel Loop Contract

Citadel treats a loop as a bounded operating contract, not as "keep prompting until something happens." A loop can be manual, scheduled, Codex-native, daemon-backed, PR-driven, or foreground-only, but it should always expose the same reviewable parts.

Contract Fields

Every loop record should declare:

Field Purpose
id Stable loop identifier.
type Workflow family, such as foreground-loop, daemon, pr-watch, or schedule.
trigger What starts the loop: manual command, schedule, daemon tick, Codex automation, file watch, or PR check.
input Goal or queue the loop consumes.
scope Files, repo area, PR, issue queue, or project boundary the loop may touch.
permissions Filesystem, network, and approval assumptions.
budget Attempt count, spend ceiling, or per-run cost model.
verifier Command, verification profile, or external status that decides whether work is done.
retry Maximum attempts and optional backoff.
stopConditions Shared terminal states that end or pause the loop.
statePath Durable state record under .planning/loops/ or a legacy state file.
reviewArtifact Report, PR, package, or evidence file a human can inspect.
recovery How to continue or roll back if the loop stops midstream.

Shared Stop States

All loop-like workflows should use the same stop vocabulary:

Status Meaning
done Work completed by the loop's declared standard.
verifier-passed The verifier passed and the loop stopped successfully.
verifier-failed The verifier failed and no autonomous repair should continue.
blocked The loop cannot make safe progress without new information.
budget-exhausted The spend, time, session, or attempt budget was reached.
attempt-limit The retry ceiling was reached.
needs-human-review A human decision is required before more work.
unsafe-to-continue The loop stopped before taking a risky action.
no-active-work There is no campaign, PR, queue item, or task left to process.
stopped The user or operator explicitly stopped the loop.

Registry

First-class loop records live in:

.planning/loops/{loop-id}.json

node scripts/loops.js list also reads legacy loop state such as:

  • .planning/daemon.json
  • .planning/codex-automations/*.json

This keeps older workflows visible while new workflows adopt the common contract.

Built-In Templates

Citadel ships these loop templates through core/loops/templates.js:

Template Use
pr-review-repair Monitor a PR, read review/CI feedback, and apply bounded targeted fixes.
issue-triage Periodically classify new issues and write a reviewable summary.
dependency-refresh Check dependency drift and verify safe updates.
docs-drift-check Detect public docs or command drift.
nightly-health Run routine project health checks and summarize blockers.
visual-qa Exercise UI routes and capture inspectable evidence.
security-scan Run bounded security checks and stop for human review.
demo-proof-refresh Refresh operating-loop proof artifacts.

Preview templates with:

node scripts/loops.js templates

Create a plan from a template with:

node scripts/loops.js plan --template docs-drift-check --write

Foreground Loops

Use /loop or node scripts/loop-runner.js for bounded repetition inside the current session:

node scripts/loop-runner.js --action "npm run lint -- --fix" --verify "npm run lint" --max-attempts 3 --write

The verifier controls success. If the verifier passes, the loop stops with verifier-passed. If attempts run out, it stops with attempt-limit.

Design Rule

Do not add a new autonomous or repeated workflow without either:

  1. Writing a loop contract record, or
  2. Explaining why it is not a loop.

The goal is simple: every repeated agent workflow should be inspectable, bounded, reversible, and easy to stop.