singularity-forge/.sf/PRINCIPLES.md

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.