---
name: forge-autonomous-runtime
description: Explains SF autonomous loop, UOK gates, installed-runtime drift, and recovery paths.
user-invocable: false
model-invocable: true
side-effects: none
permission-profile: restricted
triggers:
  - "*"
---

# forge-autonomous-runtime

## Context

SF's autonomous mode is governed by the Unified Operation Kernel (UOK):

1. **State reading** — UOK reads canonical project state from `.sf/sf.db`
2. **Ledger recording** — Each run is recorded in the DB-backed ledger
3. **Projection** — Runtime files under `.sf/runtime/` are generated projections
4. **Dispatch** — UOK determines the next unit of work and creates a fresh agent session
5. **Execution** — LLM executes with focused prompt and pre-inlined context
6. **Reconciliation** — UOK reconciles ledger and projections before next dispatch

## Recovery Paths

- **Crash recovery** — Lock file tracks current unit; next `/autonomous` reads surviving state
- **Stuck detection** — Loop detects stuck iterations and emits `stuck-detected` journal events
- **Health gates** — Pre-dispatch gates check state integrity before execution
- **Parity reports** — Ledger parity ensures no orphaned or missing unit records

## Rules

- Never modify `.sf/sf.db` directly — use UOK APIs
- Never trust `.sf/runtime/` files as authoritative — they are projections
- Always check `runControl` and `permissionProfile` before tool invocation
- Journal events are best-effort; absence is a failure signal