# 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. Uppercase filenames (`INDEX.md`, `ARCHITECTURE.md`, etc.) matching the `.sf/` operational file convention.

**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.
