# 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:

1. Capture bounded intent.
2. Translate intent into PDD fields.
3. Research missing context and mark unresolved assumptions.
4. Apply a run-control policy based on confidence, risk, reversibility, blast radius,
   cost, legal/compliance scope, and production/customer impact.
5. Generate milestone, slice, task, and artifact contracts from structured state.
6. Write failing tests or executable evidence before implementation.
7. Implement the smallest code change that satisfies the contract.
8. 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.

## See Also

- `docs/SPEC_FIRST_TDD.md`
- `.sf/ANTI-GOALS.md`
- `docs/adr/0001-promote-only-sf-state.md`
- `.sf/milestones/M012/M012-ROADMAP.md`
- `.sf/milestones/M015/M015-ROADMAP.md`
- `.sf/milestones/M019/M019-ROADMAP.md`
