eacbbaac82
Final settled design: sha + git ref only, no DB content snapshots at all. The mid-edit case (file observed dirty) loses the ability to reconstruct the intermediate working-tree state, but the change- detection signal is preserved and the operator can commit first if intermediate fidelity matters. Trades a corner-case fidelity loss for a much simpler schema and no DB-vs-disk content duplication. Git remains the only version store; the DB row is a pure "where I left off" pointer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3.3 KiB
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
- UOK reconciles DB-backed ledger + runtime diagnostics → typed state snapshot
- Controller selects next unit (research → plan → implement → verify) from DB state
- Fresh agent context started, task plan injected via
system-context.js - Agent writes artifacts, commits, exits
- 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 contractdocs/adr/0001-sf-state-directory.md—.sf/state modeldocs/adr/0004-capability-aware-routing.md— model routingdocs/adr/0005-multi-model-provider-strategy.md— provider strategy