singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/ARCHITECTURE.md
Mikael Hugo 500a9d1c1d fix: move unit runtime under uok ownership
2026-05-06 07:02:28 +02:00

4.8 KiB
Raw Blame History

Architecture

Purpose

Singularity Forge (SF) is an autonomous agent orchestration system. It runs long-horizon coding work through the Unified Operation Kernel (UOK): milestones → slices → tasks. Each dispatch unit runs a fresh AI context, writes its output to disk, then terminates. UOK owns lifecycle, recovery, and the DB-backed run ledger; runtime files under .sf/runtime/ are projections for query, UI, and compatibility. A deterministic controller (not an LLM) reads canonical 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 (UOK lifecycle, 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. UOK reconciles the DB-backed ledger, projections, and runtime diagnostics into a typed state snapshot
  2. Controller selects the next dispatch unit (research, plan, implement, verify, etc.) from canonical state
  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. UOK records completion/recovery, updates projections, and 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

  • UOK and the dispatch controller are 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.