docs: tighten sf runtime state boundary

.agents/skills/nix-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nix-build
-description: Build any @singularity-forge/* package (or the full stack) via nix develop. Pass a package name like "pi-coding-agent", "native", "mcp-server", or "all" for a full core build.
+description: Build any @singularity-forge/* package (or the full stack) via nix develop. Pass a package name like "pi-coding-agent", "native", "daemon", or "all" for a full core build.
 ---
 
 All build commands in this repo must run inside `nix develop`. Never use bare cargo/rustc.

.gitignore

@@ -75,9 +75,9 @@ TODOS.md
 docs/coherence-audit/
 .plans/
 
-# ── SF project state (per-worktree, never committed) ──
-# Runtime-only patterns are managed per-clone in .git/info/exclude by sf.
-# Tracked artifacts (.sf/milestones/, .sf/PROJECT.md, etc.) live in version control.
+# ── SF project state ──
+# Runtime/generated state stays out of git. Promote reviewed plans/specs/ADRs
+# into docs/; keep only deliberate human-authored .sf guidance tracked.
 
 # ── Native Rust build outputs ──
 native/addon/*.node

AGENTS.md

@@ -195,9 +195,9 @@ Copy `docker/.env.example` to `.env` and fill in API keys. At minimum you need o
 
 ## SF Planning State
 
-`.sf/` is the canonical home for SF agent state. It contains milestone plans, slice plans, task plans, and ephemeral working files under `.sf/milestones/`, `.sf/STATE.md`, `.sf/QUEUE.md`, and related artifacts.
+SQLite (`.sf/sf.db`) is the canonical structured store for SF agent state whenever schema, ordering, priority, joins, or validation matter. Runtime files under `.sf/` are working artifacts, generated projections, evidence, or legacy import inputs.
 
-**Promote-only rule:** Agent state (the `.sf/` directory under `~/.sf/projects/<hash>/`) is transient and gitignored — never committed directly. Project state (`.sf/` tracked in the repo root) contains only human-authored artifacts such as `DECISIONS.md`, `KNOWLEDGE.md`, `REQUIREMENTS.md`, `ROADMAP.md`, and `STATE.md`.
+**Promote-only rule:** Agent runtime state (`.sf/milestones/`, `.sf/evals/`, `.sf/harness/`, locks, journals, and generated manifests) is transient and gitignored — never committed directly. Project `.sf/` files tracked in the repo root are limited to deliberate human-authored guidance such as `PRINCIPLES.md`, `TASTE.md`, `ANTI-GOALS.md`, `DECISIONS.md`, `KNOWLEDGE.md`, `REQUIREMENTS.md`, and `ROADMAP.md`.
 
 Promoted artifacts — milestone summaries, architecture decision records (ADRs), and durable specifications — belong in tracked documentation directories:
 
@@ -212,8 +212,8 @@ Promoted artifacts — milestone summaries, architecture decision records (ADRs)
 
 **Commands:**
 - `sf plan promote <source>` — copy a file from `.sf/` to `docs/plans/`, `docs/adr/`, or `docs/specs/`
-- `sf plan list` — list milestone and slice files in `.sf/`
-- `sf plan diff` — compare `.sf/` state with promoted `docs/` artifacts
+- `sf plan list` — list active milestone and slice records/artifacts
+- `sf plan diff` — compare runtime planning state with promoted `docs/` artifacts
 
 See [`docs/plans/README.md`](docs/plans/README.md), [`docs/adr/README.md`](docs/adr/README.md), and [`docs/specs/README.md`](docs/specs/README.md) for directory-specific conventions.
 

vitest.config.ts

@@ -191,7 +191,7 @@ export default defineConfig({
 		// Cold vitest+esbuild module-graph import takes 16-25s on this repo
 		// (dynamic imports of captures.js and friends). 30s tests-timeout was
 		// racing the import phase, producing spurious 30s failures across
-		// dev-engine, ensure-db-open, workflow-mcp, sf-tools, verification-gate,
+		// dev-engine, ensure-db-open, workflow-tools, sf-tools, verification-gate,
 		// etc. 60s gives the import time to settle without losing real-bug signal.
 		testTimeout: 60_000,
 		hookTimeout: 60_000,