ADR-0000: SF Is a Purpose-to-Software Compiler

Status: Accepted Date: 2026-05-06 Source: M012, M015, M019, docs/SPEC_FIRST_TDD.md, .sf/ANTI-GOALS.md

Context

SF has enough moving parts that it can be mistaken for a generic coding agent: a TUI, machine surface, autonomous mode, model routing, memory, Sift, doctor, milestones, slices, workers, and generated project state. That framing is too weak. A generic coding agent can still accept vague intent, write code early, and call the result done because tests or lint happen to pass.

SF's stronger product shape is: take a bounded intent, turn it into a falsifiable purpose contract, research missing context, decide whether autonomous run control is allowed, then generate tests and implementation work from that contract.

The eight PDD fields are the purpose gate:

Purpose
Consumer
Contract
Failure boundary
Evidence
Non-goals
Invariants
Assumptions

Without those fields, SF cannot know whether it is solving the right problem. Without machine-executable evidence or an explicit manual reviewer scenario, SF cannot know whether the contract has been satisfied.

Decision

SF is defined as a purpose-to-software compiler.

The canonical pipeline is:

Capture bounded intent.
Translate intent into PDD fields.
Research missing context and mark unresolved assumptions.
Apply a run-control policy based on confidence, risk, reversibility, blast radius, cost, legal/compliance scope, and production/customer impact.
Generate milestone, slice, task, and artifact contracts from structured state.
Write failing tests or executable evidence before implementation.
Implement the smallest code change that satisfies the contract.
Verify, record evidence, retain useful memory, and continue.

Structured state is authoritative. Markdown is a projection for humans, reviews, reports, and git history. Runtime planning state belongs in .sf/sf.db; durable human-facing exports are promoted into tracked docs/adr/, docs/specs/, and docs/plans/.

TUI, CLI, web, editor integrations, machine automation, workers, and future frontends are different surfaces over the same planner/executor contract. Protocols and output formats must not invent separate planning semantics.

Enforcement

SF must prefer enforcement over recommendation:

Doctor and lint checks reject malformed or incomplete planning artifacts.
Non-trivial milestones, slices, tasks, ADRs, specs, tests, and exported symbols must name their purpose and consumer.
PDD/TDD gates block implementation when purpose, consumer, contract, evidence, or falsifier are missing.
Research claims are cited, linked to repo evidence, or explicitly marked as assumptions.
Run control proceeds only when the configured policy allows it; otherwise SF researches more, parks the work, or asks for a human decision.
Memory stores facts, decisions, failures, and falsifiers that improve future decisions. It must not become unverified lore.
Generated residue, stale projections, duplicate state shapes, and legacy call paths are treated as doctor/cleanup issues, not accepted architecture.

Consequences

Positive:

SF has one clear product contract: convert purpose into verified software.
Product discovery, planning, coding, and verification share the same PDD/TDD gate.
Autonomous behavior becomes policy-driven instead of prompt-driven.
Future UI surfaces can vary without changing the execution semantics.
The system can reject vague work before it becomes code.

Negative:

Upfront planning becomes stricter; some work parks until missing purpose or evidence is supplied.
Doctor, schema validation, and artifact repair become part of the critical path.
More state needs migrations because structured data, not prose, is authoritative.

Non-Goals

SF is not a generic chat agent.
SF is not an open-ended product strategist.
SF is not allowed to write non-trivial implementation code before the purpose gate.
SF does not use markdown planning files as the source of truth when structured state exists.
SF does not route first-party orchestration through MCP or other transport wrappers just because they are available.

4.4 KiB Raw Permalink Blame History