# Style

- Prefer runtime adapters over ad hoc file parsing when reading SF state. For example, query solver eval history through `sf-db.js` helpers rather than reading `.sf/evals/**/report.json`.
- Make DB-backed tools the pleasant path. If a human-readable file mirrors structured state, prefer a tool that mutates the DB and regenerates the file over hand-editing the projection.
- Keep generated artifacts clearly named, ignored, and reproducible. A committed doc should read like reviewed source, not like a cached run output with host-local paths.
- Use precise boundary names in files and symbols. Avoid stale `mcp` names for native workflow tools; reserve MCP wording for client-side integration with external servers.
- Make migrations one-way and observable. Legacy JSON, JSONL, or Markdown should be imported into SQLite with schema/version checks, then left as ignored fallback or removed when the cutover is complete.
- Prefer product terms that reveal the axis: surface, protocol, output format, run control, permission profile. Do not use `headless`, JSON, or autonomous as catch-all words when a narrower term fits.
