/orbit

Operation Contract

Purpose: load this when creating or auditing loop artifacts. It defines the minimum contract for goal.md, progress.md, done.md, state.env, and the required footer.

Contract version: 1.2.0

Contents

• Contract checklist
• Footer contract
• Resume contract
• Cost tracking
• Contract versioning

Contract Checklist

• goal.md must include:
  • goal statement
  • why it matters
  • 3-6 measurable acceptance criteria — each AC must map to a machine-checkable verify command (the completion oracle). An AC with no command is not measurable; strengthen it via vague-goal-handling.md AC templates before proceeding.
  • at least one explicit external terminator beyond the default iteration cap — declare LOOP_TIMEOUT (wall clock) and/or USD_PER_RUN_CAP (budget). A contract with only MAX_ITERATIONS is under-bounded for unattended runs (SKILL Core Contract: termination MUST be enforced externally by iteration cap / timeout / budget).
  • out-of-scope notes
• progress.md must record per iteration:
  • UTC timestamp
  • iteration number
  • changed files and summary
  • verification commands and outcomes
  • remaining work
  • decision: CONTINUE or DONE
• done.md must include:
  • completion timestamp
  • acceptance checklist with evidence (verify PASS/SKIP and placeholder-clean changed source — verify alone is not DONE evidence; AP-12)
  • rollback note

Contract Validation Gates

Before a contract is accepted (and before generate consumes it), assert:

Footer Contract

Required response footer:

NEXUS_LOOP_STATUS: READY | CONTINUE | DONE
NEXUS_LOOP_SUMMARY: <single-line summary>

Rules:

• NEXUS_LOOP_STATUS must use the exact token.
• Keep the summary concise and operational.
• Missing footer defaults to CONTINUE in conservative mode.

Resume Contract

state.env should preserve:

• NEXT_ITERATION
• LAST_STATUS
• LAST_UPDATED_AT
• ORIGIN_BRANCH when BRANCH_ISOLATION is enabled
• ITER_BRANCH when BRANCH_ISOLATION is enabled
• LOOP_BASE (the pinned starting commit used by completion checks, including without branch isolation)
• any session resume flags
• CONTRACT_VERSION (current: 1.2.0)
• TOTAL_TOKENS (cumulative token usage across iterations)
• TOTAL_API_CALLS (cumulative API call count)
• ESTIMATED_COST_USD (cumulative estimated cost)

Companion loop artifacts (not in state.env, but part of the resumable contract — written/read by the generate runner):

Recovery priority:

1. progress.md timeline
2. runner.log status stamps
3. state.env

Cost Tracking

Each iteration should update cumulative resource metrics in state.env:

Cost Signal: .cost-usd

Cumulative state.env fields above are for resume and reporting. Hard budget enforcement uses the append-only .cost-usd file: executors that know their per-iteration cost append one USD float line per iteration; the runner sums the file and derives ESTIMATED_COST_USD = sum(.cost-usd). Keeping enforcement file-based (not state.env-derived) lets the runner terminate even when an iteration is killed before its state.env write completes.

Budget Alerts and Caps

Soft alerts require COST_TRACKING=true. Hard caps are enforced by the runner whenever the cap is set, independent of COST_TRACKING. For any unattended run, the Terminator-bound validation gate requires ≥ 1 hard cap or LOOP_TIMEOUT.

Cost in Done Report

When COST_TRACKING=true, done.md should include:

## Resource Usage
- Total tokens: {{TOTAL_TOKENS}}
- Total API calls: {{TOTAL_API_CALLS}}
- Estimated cost: ${{ESTIMATED_COST_USD}}
- Iterations: {{actual}} / {{max}}

Contract Versioning

Version Format

Contracts use semantic versioning: MAJOR.MINOR.PATCH

Migration Rules

Version History

Multi-Loop Rules

• Parallel loops: keep separate state.env/progress.md; block overlapping candidate paths.
• Sequential loops: successor goal.md references predecessor output and validates prerequisites independently.
• Loop of loops: consume only inner _STEP_COMPLETE; never write inner loop state directly.

Detail -> reference/patterns.md.