# SF project context

## What SF is

SF is a **purpose-to-software compiler**: it captures bounded intent, translates it into PDD fields, researches missing context, applies run-control policy, generates milestone/slice/task contracts, writes failing tests, implements the smallest satisfying code change, and records evidence.

Foundational contract: `docs/adr/0000-purpose-to-software-compiler.md`.

## Modes

SF has exactly **two work modes**: Ask and Build.
`Shift+Tab` cycles between them.
**YOLO** (`Ctrl+Y` / `/mode yolo`) is a flag layered on top of Build — not a third mode.

## State and planning

- `.sf/sf.db` is the canonical structured store (SQLite, `node:sqlite`).
- Runtime planning artifacts (`.sf/milestones/`, `.sf/evals/`, locks, journals) are transient and gitignored — never committed.
- Promoted artifacts go to `docs/plans/`, `docs/adr/`, `docs/specs/`.
- Naming: milestone IDs `M001…`, slice IDs `S01…`, task IDs `T01…`.

## Build and test

```bash
npm run build          # full build
npm run build:core     # packages + tsc + resources only
npm run test:unit      # Vitest unit tests
npm run test:integration
npm run copy-resources # recompile src/resources/extensions after editing .ts files
```

## Key source locations

| Path | Purpose |
|------|---------|
| `src/resources/extensions/sf/` | SF flow extension (TypeScript source) |
| `packages/` | Seven npm workspace packages |
| `web/` | Next.js browser surface |
| `src/headless*.ts` | `sf headless` machine-surface command |
| `vscode-extension/` | Editor surface |
