111 lines
4.4 KiB
Markdown
111 lines
4.4 KiB
Markdown
# 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`
|