singularity-forge/docs/specs/sf-operating-model.md

SF Operating Model

Working Model Inputs

• Generator: sf-spec-projections@1
• Database: .sf/sf.db (present)
• Guidance: .sf/PRINCIPLES.md (present)
• Guidance: .sf/TASTE.md (present)
• Guidance: .sf/ANTI-GOALS.md (present)
• Optional knowledge: .sf/KNOWLEDGE.md (missing)
• Optional preferences: .sf/PREFERENCES.md (present)
• Source schema version: 45
• DB planning rows: milestones=1, slices=0, tasks=0
• DB spec rows: milestone_specs=1, slice_specs=0, task_specs=0
• Source roots analyzed as implementation evidence: src/resources/extensions/sf/, src/headless*.ts, src/cli.ts, src/help-text.ts, web/, vscode-extension/, packages/

This file is a human export for review, navigation, and git history. Generated docs are allowed to change because Git keeps the human-facing history. If SF needs operational history or future-use knowledge, store it in .sf/DB-backed state instead of relying on this export.

SF has one workflow engine and one database-first working model. TUI, CLI, web, editor integrations, and non-interactive automation must all drive the same flow:

intent -> structured state/evidence -> UOK/policy gates -> execution -> journal/evidence -> projected status

The names below are separate axes. Do not use one as a synonym for another.

Flow

The flow is the product behavior: how SF captures intent, plans work, applies policy, executes tasks, records evidence, and reports status. Flow behavior must not fork by UI surface. If a TUI run and a non-interactive run receive the same state, run control, and permission profile, they should follow the same control model.

Surface

A surface is where a person or program drives or observes the flow.

• TUI surface — interactive terminal UI.
• CLI surface — explicit commands and single-shot prompt entrypoints.
• Web surface — browser UI around the same state and flow.
• Editor surface — IDE/editor integration, usually through an adapter.
• Machine surface — non-interactive runner for CI, scripts, schedulers, and parent processes.

sf headless is the current command name for the machine surface. It means "without the TUI"; it does not mean "JSON", "autonomous", or a separate flow.

Protocol

A protocol is how a surface or adapter talks to SF or to another agent process.

• RPC — SF's current child-process control channel.
• stdio JSON-RPC — process transport used by existing RPC-style adapters.
• ACP — editor/client protocol adapter for agent/editor interoperability.
• HTTP/RPC — possible daemon/web integration protocol.
• Wire — a low-level internal message layer, if introduced, below surfaces and adapters.

Protocols are adapters around the flow. They should translate messages, not invent policy or planning semantics.

Output Format

An output format is only the encoding of a response or event stream.

• text — human-readable progress and results.
• json — one machine-readable result object.
• stream-json / JSONL — event stream for parent processes and monitors.

JSON is not a surface, run control, or permission profile. It is one output format that the machine surface can emit.

Run Control

Run control describes how far SF continues through the flow before stopping for the operator.

• manual — user approves each consequential step.
• assisted — SF proposes and executes bounded steps, with human approval for important or uncertain actions.
• autonomous — SF continues through the flow until policy, evidence, budget, or completion stops it.

auto is not a run-control mode. Use autonomous for continuous run control; use assisted for bounded human-guided progression.

Competitor note: Copilot CLI calls continuous run control autopilot. SF does not use that product name. The SF term is autonomous mode, and it stays separate from permission profiles, surfaces, protocols, and output formats.

UOK kernel records carry runControl as a first-class lifecycle field. Workflow phases such as planning, building, verification, and finalization are separate execution stages, not run-control modes.

Permission Profile

A permission profile describes what SF is allowed to touch when a run-control mode asks it to act.

• restricted — read-mostly or planning-artifact-only permissions.
• normal — default workspace permissions for ordinary project work.
• trusted — wider local permissions for a trusted operator/workspace.
• unrestricted — explicit danger profile; use for logs, policy records, or deliberate bypass flows, not as friendly default product language.

Run control and permission profile are independent. For example, autonomous + restricted can keep going with narrow permissions, while manual + trusted still asks before each consequential step but can perform broader approved actions.

UOK kernel records and execution-policy decisions carry permissionProfile as the trust posture. Permission expansion never implies autonomous continuation.

Work Mode

A work mode describes the kind of work SF is doing. repair is one work mode, not a separate subsystem. It owns self-healing, stale locks, installed-runtime drift, broken state, failed gates, generated/runtime drift, and other cases where SF must repair its own ability to continue safely.

doctor remains a diagnostic engine. It can inspect and report problems, but switching into repair work is a workMode transition.

Task And Scheduler Status

Durable task lifecycle state uses the ORCH-style status machine:

todo -> running -> verifying -> reviewing -> done | blocked | paused | failed | cancelled | retrying

Use todo, not queued, for work that exists but has not started. queued belongs to scheduler state only:

queued -> due -> claimed -> dispatched -> consumed | expired

Parallel workers must stay worktree-isolated and report heartbeat/status into .sf state. Their lifecycle rows use task_status; timed dispatch and reminder rows use task_scheduler.status.

Remote Steering

Remote is a full-session steering surface. It may change workMode, runControl, permissionProfile, and modelMode; it is not only a question delivery channel.

Future Sandbox Profile

sandboxProfile may become a sixth independent axis later. Keep it separate from permissionProfile: sandbox profile controls containment, while permission profile controls what SF may approve.

Naming Rules

• Say flow for the shared planning/execution engine.
• Say surface for TUI, CLI, web, editor, or machine entrypoints.
• Say protocol for ACP, RPC, stdio JSON-RPC, HTTP, or wire messages.
• Say output format for text, json, and stream-json.
• Say run control for manual, assisted, and autonomous.
• Say permission profile for restricted, normal, trusted, and unrestricted.
• Say task status for todo, running, verifying, reviewing, done, blocked, paused, failed, cancelled, and retrying.
• Say scheduler status for queued, due, claimed, dispatched, consumed, and expired.
• Use headless only for the current sf headless command and implementation path. Product docs should explain it as the machine surface.

Working State Contract

SF working state is database-first. An initialized SF repo has .sf/sf.db, and runtime tools use it as the canonical structured store for planning hierarchy, ordering, gates, ledgers, schedules, and validation-sensitive state.

Markdown under .sf/ has two roles:

• working guidance and knowledge that the runtime loads, such as PRINCIPLES.md, TASTE.md, ANTI-GOALS.md, KNOWLEDGE.md, and PREFERENCES.md;
• human-readable projections from DB-owned records, such as rendered decisions, requirements, roadmap, plan, summary, and state files.

Markdown under docs/specs/ is a human export for review, navigation, and git history. Generated docs can change; Git records that human-facing history. If SF needs its own operational history, it should store that in .sf/DB-backed state. Plans should record any surface, protocol, output-format, run-control, or permission-profile impact explicitly when a milestone changes integration behavior.

Source Placement

SF source placement follows the same axis model. New code should extend the owning axis instead of creating parallel trees.

Core Flow

• src/resources/extensions/sf/ owns the SF workflow extension: planning tools, UOK/runtime state, /next commands, prompts, templates, doctors, schedule, and DB-backed state.
• src/resources/extensions/ owns bundled extension packages loaded into the runtime.
• src/resources/agents/, src/resources/skills/, and src/resources/workflows/ own bundled runtime resources, not independent product flows.

Surfaces

• src/cli.ts and src/help-text.ts own CLI/session entrypoint behavior and command help.
• src/headless*.ts owns the existing sf headless machine-surface command path. Keep the command name; describe it as the machine surface in product language.
• web/ owns the browser surface.
• vscode-extension/ owns the editor surface.
• packages/pi-tui/ owns reusable TUI primitives and terminal UI components.

Protocols And Adapters

• packages/rpc-client/ owns reusable RPC client protocol code.
• RPC child-process orchestration stays in the machine-surface path unless promoted into a reusable protocol package.
• ACP, stdio JSON-RPC, HTTP, and future wire layers are protocol/adapters. They should translate messages to the same SF flow, not fork planning semantics.

Workspace Packages

• packages/pi-agent-core/ owns reusable agent-core primitives.
• packages/pi-ai/ owns provider/model integration.
• packages/pi-coding-agent/ owns reusable coding-agent substrate inherited from Pi.
• packages/daemon/ owns daemonized background service code.
• packages/native/ and rust-engine/ own native/Rust performance paths.

State And Projections

• .sf/sf.db is the canonical structured runtime state store for initialized SF repos. Treat a missing or unreadable DB as bootstrap/recovery, not a normal alternate source of truth.
• .sf/DECISIONS.md, .sf/REQUIREMENTS.md, milestone roadmaps, and similar files are rendered working projections when database-backed tools own the data. They are useful to humans and agents but must not compete with DB rows.
• .sf/PRINCIPLES.md, .sf/TASTE.md, .sf/ANTI-GOALS.md, .sf/KNOWLEDGE.md, and .sf/PREFERENCES.md are repo-local working guidance files when present.
• Generated .sf/ runtime files are evidence, projections, or import/recovery artifacts.
• Durable human-facing exports belong in docs/specs/, docs/adr/, or docs/plans/. They are reviewable projections and git-history artifacts, not a second planning database.

Placement Rules

• Do not create a second implementation because a feature appears in another surface. Add an adapter to the same flow.
• Do not name output encodings as surfaces. JSON belongs to output formats.
• Do not name permission expansion as run control. autonomous means the loop continues; trusted or unrestricted means the permission profile widened.
• Do not route human questions because of headless. Questions come from run-control and permission-policy gates; the surface only determines delivery.