# Architecture

*Generated: 2026-05-11 | Source: ARCHITECTURE.md, docs/adr/*

## Overview

SF is a Purpose-to-Software Compiler (ADR-0000). It runs long-horizon coding work through the **Unified Operation Kernel (UOK)**: milestones → slices → tasks. A deterministic controller (not an LLM) reads canonical DB state and decides what to dispatch next. Each dispatch unit gets a fresh AI context.

**Key invariant:** `sf.db` (SQLite via `node:sqlite`) is the single source of truth for all structured state. Markdown files are rendered projections or human-editable inputs, not authoritative sources.

## Subsystems at a Glance

| Subsystem | Path | Purpose |
|-----------|------|---------|
| CLI entry | `src/loader.ts` | Initializes resources, registers extension |
| Headless driver | `src/headless.ts` | Non-interactive mode, exit codes 0/1/10/11/12 |
| SF extension | `src/resources/extensions/sf/` | All SF autonomous flow logic |
| UOK orchestrator | `src/resources/extensions/sf/auto/` | Dispatch loop, lifecycle, planning |
| Context injection | `src/resources/extensions/sf/bootstrap/` | System prompt assembly |
| Prompt templates | `src/resources/extensions/sf/prompts/` | `.md` templates loaded at runtime |
| Agent core | `packages/coding-agent/` | Tools (bash, grep, read…), models, sessions, settings |
| LLM providers | `packages/ai/` | Anthropic, OpenAI, Google, Moonshot, etc. |
| Terminal UI | `packages/tui/` | Ink-based TUI |
| Daemon | `packages/daemon/` | Background process |
| RPC client | `packages/rpc-client/` | RPC adapter |
| Native addon | `packages/native/` | Rust N-API bindings (grep, glob, ps, highlight, ast, diff) |

## Autonomous Dispatch Loop

1. UOK reconciles DB-backed ledger + runtime diagnostics → typed state snapshot
2. Controller selects next unit (research → plan → implement → verify) from DB state
3. Fresh agent context started, task plan injected via `system-context.js`
4. Agent writes artifacts, commits, exits
5. UOK records completion/recovery, updates projections, repeats

## System Context Assembly (per turn)

`system-context.js` `buildBeforeAgentStartResult` assembles blocks in order:

```
escalation-policy → system.md → preferences → knowledge (DB) → ARCHITECTURE.md 
→ tacit-knowledge → wiki (.sf/wiki/) → CODEBASE.md → code-intelligence 
→ memories (DB) → new-skills → self-feedback → worktree/VCS → model identity
```

## State Layout

**Tracked in git:**
- `.sf/milestones/` — plans, summaries (rendered projections)
- `.sf/PROJECT.md`, `.sf/REQUIREMENTS.md`, `.sf/DECISIONS.md`, etc.

**Gitignored (runtime):**
- `.sf/sf.db*` — canonical SQLite state
- `.sf/wiki/` — generated + hand-curated wiki (this directory; **tracked in git**)
- `.sf/CODEBASE.md` — generated file map
- `.sf/runtime/`, `.sf/activity/`, `.sf/worktrees/`, etc.

## Tools in bash tool

Bash tool has a 120s default timeout (prevents autonomous mode hangs). Override via `settings.json → bash.defaultTimeoutSeconds`. Prefer dedicated tools: `grep`, `find`, `ls`, `read` over bash for file operations.

## ADRs

- `docs/adr/0000-purpose-to-software-compiler.md` — foundational product contract
- `docs/adr/0001-sf-state-directory.md` — `.sf/` state model
- `docs/adr/0004-capability-aware-routing.md` — model routing
- `docs/adr/0005-multi-model-provider-strategy.md` — provider strategy
