singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
singularity-forge/docs
History
Mikael Hugo d2ff4e84ba land 6 parallel codex/sonnet rescue outputs 
- R016 swarm bus deliver verify (uok/swarm-dispatch.js + test): _busDispatch now
  force-refreshes target inbox and verifies messageId visibility before returning
  ok:true; ack-without-deliver class closed.
- R082 drift detection UokGate (uok/drift-detection-gate.js + test): single-task
  + sweep scope; 3 drift classes (artifact-missing, prose-status mismatch,
  broken-import); follows ADR-0075 id/type/execute -> GateResult contract.
- R087 PDD typed contracts (engine-types.js + test): ADR-0000 8 PDD fields +
  7-dim run-control policy + ADR-0075 GateResult typedefs and validators.
- R090 planning-execute lane split (auto/unit-lanes.js + auto/loop.js + 2 tests):
  lane classifier + capacity-aware tick dispatcher; SF_LANES=0 fallback is
  byte-equivalent to pre-R090.
- R053 + R054 Wiggums detectors (detectors/repeated-feedback-kind.js +
  detectors/artifact-flap.js + 2 tests); R055 stale-lock + R056 periodic-runner
  source landed without tests (gap filed as self-feedback).
- M053 per-repo supervisor design + skeleton (supervisor/repo-supervisor.js +
  test + design doc): RepoSupervisor class, zero module-global state, tick
  stub, failure isolation; M056 trust-boundary called out as follow-up.

85/85 tests green across the 8 new test files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 13:44:42 +02:00
..
adr fix(auto): split autonomous solver from executor per ADR-0079 2026-05-12 23:55:02 +02:00
design-docs docs: align sf purpose doctrine and docs 2026-05-06 00:38:36 +02:00
dev land 6 parallel codex/sonnet rescue outputs 2026-05-17 13:44:42 +02:00
exec-plans docs: align runtime state and mcp boundaries 2026-05-07 03:09:55 +02:00
generated feat: implement 3 quick wins for SF self-evolution 2026-05-06 22:01:37 +02:00
plans sf snapshot: uncommitted changes after 187m inactivity 2026-05-17 12:04:55 +02:00
product feat: Created draft mapping of SF patterns to ACE reference draft 2026-05-13 02:01:41 +02:00
product-specs feat: implement 3 quick wins for SF self-evolution 2026-05-06 22:01:37 +02:00
records sf snapshot: uncommitted changes after 202m inactivity 2026-05-08 13:31:08 +02:00
references feat: implement 3 quick wins for SF self-evolution 2026-05-06 22:01:37 +02:00
specs docs(specs): add sf-prompt-modularization.md operator guide 2026-05-15 19:47:20 +02:00
user-docs refactor: make bundled agents internal 2026-05-14 19:54:56 +02:00
DESIGN.md feat: implement ADR-001 gitignore split and fill placeholder docs 2026-05-01 22:32:28 +02:00
ENV.md fix(env): align SF_PERMISSION_LEVEL enum with permission-profile values 2026-05-14 21:11:36 +02:00
FRONTEND.md feat: implement 3 quick wins for SF self-evolution 2026-05-06 22:01:37 +02:00
PLANS.md docs: align sf purpose doctrine and docs 2026-05-06 00:38:36 +02:00
PRODUCT_SENSE.md docs: align sf purpose doctrine and docs 2026-05-06 00:38:36 +02:00
QUALITY_SCORE.md sf snapshot: uncommitted changes after 93m inactivity 2026-05-06 11:37:27 +02:00
README.md sf snapshot: uncommitted changes after 49m inactivity 2026-05-08 01:07:24 +02:00
RECORDS_KEEPER.md fix(self-feedback): 3 sf-internal defects resolved 2026-05-17 00:55:56 +02:00
RELIABILITY.md sf snapshot: uncommitted changes after 110m inactivity 2026-05-08 00:17:47 +02:00
SECURITY.md docs: align sf purpose doctrine and docs 2026-05-06 00:38:36 +02:00
SPEC_FIRST_TDD.md feat(sf): align node sqlite uok runtime 2026-05-08 03:01:20 +02:00
TEST-COVERAGE-PLAN.md Update test coverage plan: Phase 3 complete 2026-05-07 01:01:47 +02:00

README.md

SF Documentation

Welcome to the SF documentation. SF is a purpose-to-software compiler: it turns bounded intent into PDD contracts, researches missing context, writes failing tests or executable evidence first, implements the smallest satisfying change, and records verification. See ADR-0000 and Spec-First TDD before changing product behavior.

This index covers everything from getting started to advanced configuration, autonomous mode internals, and extending SF with the Pi SDK.

User Documentation

Guides for installing, configuring, and using SF day-to-day. Located in user-docs/.

Guide Description
Getting Started Installation, first run, and basic usage
Autonomous Mode How autonomous execution works — the state machine, crash recovery, and steering
Commands Reference All commands, keyboard shortcuts, and CLI flags
Remote Questions Discord and Slack delivery for run-control-gated questions
Configuration Preferences, model selection, git settings, and token profiles
Provider Setup Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers
Custom Models Advanced model configuration — models.json schema, compat flags, overrides
Token Optimization Token profiles, context compression, complexity routing, and adaptive learning (v2.17)
Dynamic Model Routing Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19)
Captures & Triage Fire-and-forget thought capture during autonomous mode with automated triage (v2.19)
Workflow Visualizer Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19)
Cost Management Budget ceilings, cost tracking, projections, and enforcement modes
Git Strategy Worktree isolation, branching model, and merge behavior
Parallel Orchestration Run multiple milestones simultaneously with worker isolation and coordination
Working in Teams Unique milestone IDs, .gitignore setup, and shared planning artifacts
Skills Bundled skills, skill discovery, and custom skill authoring
Migration from v1 Migrating .planning directories from the original SF
Troubleshooting Common issues, /sf doctor (real-time visibility v2.40), /sf forensics (full debugger v2.40), and recovery procedures
Web Interface Browser-based project management with sf --web (v2.41)
VS Code Extension Chat participant, sidebar dashboard, and RPC integration for VS Code

Architecture & Internals

Design documents, ADRs, and internal references. Located in dev/.

Guide Description
ADR-0000: Purpose-to-Software Compiler Foundational architecture decision for SF's product contract
Spec-First TDD Purpose gate, PDD fields, and test-first change method
Architecture Overview System design, extension model, state-on-disk, and dispatch pipeline
Native Engine Rust N-API modules for performance-critical operations
ADR-001: Branchless Worktree Architecture Decision record for the v2.14 git architecture
ADR-003: Pipeline Simplification Research merged into planning, mechanical completion (v2.30)
ADR-004: Capability-Aware Model Routing Extend routing from tier/cost selection to task-capability matching
ADR-007: Model Catalog Split Separate model metadata from routing logic for extensibility
Context Optimization Opportunities Analysis of context window usage and optimization strategies
File System Map Complete file system reference
CI/CD Pipeline Continuous integration and deployment pipeline
Frontier Techniques Advanced techniques and research
PRD: Branchless Worktree Product requirements for branchless worktree architecture

Pi SDK Documentation

Guides for the underlying Pi SDK that SF is built on. Located in dev/.

Guide Description
What is Pi Core concepts — modes, agent loop, sessions, tools, providers
Extending Pi Building extensions — tools, commands, UI, events, state
Context & Hooks Context pipeline, hook reference, inter-extension communication
Pi UI / TUI Terminal UI components, theming, keyboard input, rendering

Research

Guide Description
Building Coding Agents Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs
Proposals Feature proposals and workflow definitions