# Principles

- SQLite is the canonical structured store for initialized SF repos. Treat `.sf/sf.db` as the first place for planning hierarchy, ordering, priority, gates, ledgers, schedules, and validation-sensitive state; a missing DB is bootstrap/recovery, not a parallel normal mode.
- `.sf` is the working model boundary. Keep operational state, project knowledge, preferences, decisions, requirements, roadmap state, and generated projections there first; promote only reviewed plans, specs, and ADRs to `docs/`.
- Generated docs are human-facing exports and reports. They may change because Git keeps their review history; SF-owned operational history belongs in `.sf`/SQLite when SF needs it for future behavior.
- File artifacts may be generated from the DB or imported once from legacy state, but they should not become competing authorities.
- Native SF/pi tools are the product boundary. Integrations may call external MCP servers as clients, but SF-owned capabilities should not be exposed by an SF MCP server.
- Prioritization should be represented as structured state, not filename order or prose position. Prefer explicit priority/order fields in DB-backed roadmap and task records.
- Forge has one flow engine across surfaces. Source placement should name the axis it implements: `src/resources/extensions/sf/` for the SF flow extension, `src/headless*.ts` for the `sf headless` machine surface command path, `src/cli.ts` and `src/help-text.ts` for CLI/session I/O, `web/` for the web surface, `vscode-extension/` for the editor surface, `packages/rpc-client/` for protocol adapters, and `packages/*` for reusable workspace packages.
- Keep run control and permission profile separate in planning state. Run control is manual, assisted, or autonomous. Permission profile is restricted, normal, trusted, or unrestricted.