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>
5.7 KiB
Glossary
Generated: 2026-05-11 | Hand-editable — tracked in git
Project-specific terms only. General software terms not listed.
A
ADR — Architecture Decision Record. Promoted from .sf/DECISIONS.md to docs/adr/. Numbered 0000, 0001, … Immutable once accepted.
Auto-bootstrap context — The set of files (wiki pages, spec files, CODEBASE.md) injected as initial context for an autonomous run that has no active milestone to draw context from. Built by auto-bootstrap-context.js and headless-context.ts.
Autonomous mode — SF running the full UOK dispatch loop without human confirmation per unit. Enabled via sf run --autonomous or the TUI Ctrl+Y (YOLO flag). The controller drives planning → implementation → verification non-stop.
B
Blast radius — The set of systems, users, or data that a task could affect if it produces a wrong output. One of the eight run-control fields used to determine whether a task requires human confirmation.
Build mode — The SF work mode where agent can make file changes. One of two modes (Ask/Build). Toggled via Shift+Tab. YOLO is a flag on top of Build, not a third mode.
C
CODEBASE.md — Auto-generated file map of the repo. Gitignored. Regenerated by SF on each autonomous run start. Lives at .sf/CODEBASE.md.
Coding agent (packages/coding-agent/) — The Pi SDK package that provides tool execution, model sessions, settings, retry logic, and context management. SF wraps this to run agent units.
copy-resources — The npm script (npm run copy-resources) that compiles src/resources/extensions/sf/ TypeScript + copies prompt templates into dist/resources/. Required after any edit to extension source files.
D
DB-first — The project invariant that all structured state lives in SQLite (node:sqlite, .sf/sf.db). No file-based fallbacks for state that belongs in the DB. Never use better-sqlite3.
E
Escalation policy — Tiers of context sources the agent should consult before acting on ambiguity. Tier 1: .sf/ files, wiki. Tier 2: docs/adr/, docs/specs/. Tier 3: source code. Defined in system-context.js.
F
FTS5 — SQLite full-text search extension. Used for semantic memory search and session history search in sf.db. Queries use WHERE search_index MATCH 'term OR synonym' syntax.
H
Headless mode — Machine-surface entry point: sf headless. JSON I/O. Exit codes: 0 = success, 1 = error, 10 = plan needed, 11 = blocked, 12 = budget exhausted. Not synonymous with JSON output or autonomous mode.
M
Milestone — Top-level unit of planned work. Identified as M001, M002, … Stored in sf.db. Rendered as markdown to .sf/milestones/M001/. A milestone contains slices; slices contain tasks.
N
node:sqlite — Node.js built-in SQLite module (Node 26+). The only allowed SQLite interface in this codebase. Never import better-sqlite3 or any native SQLite addon.
P
PDD — Purpose-Driven Development. The eight fields (intent, value, consumer, falsifier, risk, reversibility, blast-radius, cost/compliance) that define what a task is and how to run it safely.
Pi SDK — The underlying agent SDK (packages/coding-agent, packages/ai, packages/agent-core, packages/tui, etc.) that SF is built on.
Promote-only rule — Runtime agent artifacts (.sf/milestones/, .sf/evals/, locks, journals) are gitignored and never committed directly. Durable artifacts are promoted to docs/plans/, docs/adr/, docs/specs/.
Purpose-to-Software Compiler — The foundational product model (ADR-0000): SF captures bounded intent, translates it into PDD fields, applies run-control policy, generates milestone/slice/task contracts, writes failing tests first, implements the smallest satisfying change, then records evidence and continues.
R
Run-control policy — The framework that maps confidence, risk, reversibility, blast radius, cost, compliance, and production impact to a decision on whether to proceed autonomously or ask the human. Part of PDD.
S
sf.db — The canonical SQLite database at .sf/sf.db. Contains milestones, slices, tasks, memories, schedule entries, session logs, FTS5 search indexes. The single source of truth for all structured SF state.
Slice — A scoped, deliverable unit within a milestone. Identified as S01, S02, … Each slice maps to a coherent set of tasks. Stored in sf.db, rendered to .sf/milestones/M001/S01/.
Spec-first TDD — The project doctrine: write a failing test (the spec) before writing implementation code. THE TEST IS THE SPEC. See docs/SPEC_FIRST_TDD.md.
T
Task — The smallest schedulable work unit. Identified as T01, T02, … within a slice. Stored in sf.db. Each task gets its own agent session context and dispatch lifecycle.
Tacit knowledge — Project-specific conventions, patterns, and institutional knowledge stored in .sf/KNOWLEDGE.md. Injected into system context before every SF turn.
U
UOK — Unified Operation Kernel. The deterministic (non-LLM) controller that reads sf.db, selects the next unit, launches a fresh agent session, and records results. Lives in src/resources/extensions/sf/auto/.
W
Wiki (.sf/wiki/) — Human-curated + agent-generated reference pages injected into every SF system context turn. Tracked in git (not gitignored). Hand edits persist across commits and clones. Lowercase filenames (index.md, architecture.md, etc.).
YOLO — A flag on top of Build mode that disables all safety confirmations (no git prompts, no write-gate approvals). Enabled via Ctrl+Y or /mode yolo. Not a third mode — it does not appear as a Shift+Tab stop.