singularity-forge/docs/dev/sf-runtime/autonomous-runtime.md

SF 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