singularity-forge/ARCHITECTURE.md

Architecture

Purpose

Singularity Forge (SF) is an autonomous agent orchestration system. It runs long-horizon coding work as a state machine: milestones → slices → tasks. Each dispatch unit runs a fresh AI context, writes its output to disk, then terminates. A deterministic controller (not an LLM) reads disk state and decides what to dispatch next. The user is the end-gate — autonomous mode delivers work to human review, it does not merge to production unattended.

Codemap

Path	Purpose
src/loader.ts	Entry point — initializes resources, registers extension
src/headless.ts	Non-interactive (headless) mode driver — exit codes 0/1/10/11/12
src/headless-events.ts	Transcript event parsing and notification routing
src/extension-registry.ts	Registers SF as a Pi coding-agent extension
src/resources/extensions/sf/	All SF extension source (TypeScript)
src/resources/extensions/sf/auto/	Autonomous workflow orchestrator (state machine, dispatch, planning)
src/resources/extensions/sf/bootstrap/	Context injection, system prompt assembly
src/resources/extensions/sf/prompts/	Prompt templates (.md, loaded by prompt-loader.ts)
src/resources/extensions/sf/tests/	Unit and integration tests
dist/resources/extensions/sf/	Compiled JS (rebuilt by npm run copy-resources)
~/.sf/agent/extensions/sf/	Installed copy (synced from dist on startup)
docs/	Durable product, design, plan, reliability, and security context
harness/	Specs (behavior contracts), evals (model-output tests), graders

State layout (.sf/)

.sf/ can be a symlink (external state, ~/.sf/projects/<hash>/) or a local directory (tracking-enabled per ADR-001).

Tracked in git (travel with the branch, per ADR-001):

.sf/milestones/     — roadmaps, plans, summaries, task plans
.sf/PROJECT.md      — project overview
.sf/DECISIONS.md    — architectural decisions register
.sf/REQUIREMENTS.md — requirements register
.sf/QUEUE.md        — work queue / backlog
.sf/KNOWLEDGE.md    — project-specific rules for agents

Gitignored (runtime/ephemeral — managed by ensureGitInfoExclude() in .git/info/exclude):

.sf/activity/       — JSONL session dumps
.sf/audit/          — audit trail entries
.sf/exec/           — in-flight execution state
.sf/forensics/      — crash forensics
.sf/journal/        — SF journal entries
.sf/model-benchmarks/ — model benchmark results
.sf/parallel/       — parallel dispatch coordination
.sf/reports/        — generated reports
.sf/runtime/        — dispatch records, timeout tracking
.sf/worktrees/      — git worktree working directories
.sf/auto.lock       — crash detection sentinel
.sf/metrics.json    — token/cost accumulator
.sf/sf.db*          — SQLite cache (rebuilt from markdown by importers)
.sf/STATE.md        — derived state cache
.sf/notifications.jsonl, .sf/routing-history.json, .sf/self-feedback.jsonl, .sf/repo-meta.json

The symlink case uses a blanket .sf gitignore pattern (git cannot traverse symlinks). The directory case uses granular patterns so planning artifacts remain trackable.

Key flows

Autonomous dispatch loop (src/resources/extensions/sf/auto/):

1. deriveState() reads disk and produces a typed state snapshot
2. Controller selects the next dispatch unit (research, plan, implement, verify, etc.)
3. A fresh agent context is started with the task plan injected via system-context.ts
4. Agent writes artifacts to disk, commits, exits
5. Loop repeats until milestone completes or a gate fails

System context assembly (bootstrap/system-context.ts): PREFERENCES.md → KNOWLEDGE.md → ARCHITECTURE.md → CODEBASE.md → code intelligence → memories → worktree/VCS blocks

Write gate (bootstrap/write-gate.ts): All file writes in autonomous mode pass through a gate. Protected files (CLAUDE.md, CODEBASE.md, certain spec files) require explicit override.

Invariants

• The state machine (controller) is pure TypeScript — no LLM decisions in the dispatch loop itself.
• Each dispatch unit runs in a fresh context — no cross-turn state accumulation.
• Planning artifacts are tracked in git; runtime artifacts are never committed.
• SF_RUNTIME_PATTERNS in gitignore.ts is the canonical source of truth for runtime paths. git-service.ts (RUNTIME_EXCLUSION_PATHS) and worktree-manager.ts (SKIP_* arrays) must stay synchronized with it.
• The user is the end-gate. SF delivers for review, not to production.