# Project: Singularity Forge — Purpose-to-Software Compiler

## What This Is

Singularity Forge (SF) is a **purpose-to-software compiler** per [ADR-0000](../docs/adr/0000-purpose-to-software-compiler.md). It takes a stated purpose (a milestone vision) and autonomously plans, executes, validates, and ships the software that fulfills it — through a loop of LLM-driven units (research, plan, execute, validate, complete) operating on a DB-backed state machine.

This project file used to scope the M003 self-healing milestone only; it now covers the whole SF product because the roadmap has expanded beyond M003.

## Core Value

- **Purpose-first**: every milestone, slice, and task ties back to a stated purpose (ADR-0000).
- **Autonomous loop never sits silently stuck**: every halt is communicated to the operator and self-healed where safe (M003).
- **Manifest-driven prompt composition**: every unit's prompt is a verifiable function of its manifest (M004, M005, M006).
- **Reliable in-process dispatch**: inline scope eliminates spawn-based silent failures (M010, in flight).

## Current State (2026-05-17)

### Delivered

- **M001-6377a4** complete — Foundational doctrine (purpose-driven compiler framing, runaway-guard hardening, evidence/recovery surfaces, surface coherence, ACE convergence patterns).
- **M003** complete — Autonomous Self-Healing and Escalation. All 6 slices shipped (S01: HaltWatchdog; S02: durable BLOCKING_NOTICE; S03: halt self-feedback `6a2c61d5e`; S04: remediation dispatcher `bb0c87fda`; S05: auto-defer confidence `c6b8815ad` + `f48a4cc7c`; S06: end-to-end integration verified by the 2026-05-17 dogfood run where the autonomous loop dispatched reassess-roadmap, made 70 tool calls, and exited cleanly with dispatch-stop).
- **M004** complete — Phase 3 migration to composeUnitContext (initial 19/26 builders).
- **M005** complete — V2 migration (remaining builders + ARTIFACT_KEYS formalization + duplication-bug remediation for 5 simple builders).
- **M006** complete — Manifest-Driven Context v2 (final 2 builders migrated; regression test guard pinned in `src/resources/extensions/sf/tests/m006-s02-manifest-drift.test.mjs`).
- **M002**, **M007**, **M008** — cancelled / stub-skipped.

### In-flight (new this session — queued, not delivered)

- **M010** — Unified Dispatch v2: `inline` scope for `full` isolation. Owns R013-R015. 6 slices.
- **M011** — Defective-Complete Milestone Self-Heal. Owns R011-R012. 5 slices.
- **M012** — MessageBus Persistence + Inbox Coherence. Roots the prompt-never-sent bug class. 3 slices.
- **M013** — Multi-Model Routing Intelligence. Tool-failure model demotion. 4 slices.
- **M014** — Project Roadmap & State Reconciliation. DB↔file drift detection + `sf reconcile`. 4 slices.
- **M015** — Operational Tooling: triage + state hygiene CLI commands. 5 slices.

## Architecture / Key Patterns

- **Auto-Loop**: `src/resources/extensions/sf/auto/loop.js` manages iteration and phase dispatch.
- **Dispatch Rules**: `src/resources/extensions/sf/uok/auto-dispatch.js` determines the next action based on milestone/slice state.
- **Swarm Dispatch (current)**: `src/resources/extensions/sf/uok/swarm-dispatch.js` routes through MessageBus + `runAgentTurn`. To be partially replaced by inline scope (M010).
- **Self-Feedback**: `src/resources/extensions/sf/self-feedback.js` provides the registry for anomalous behavior.
- **Notification Store**: `src/resources/extensions/sf/notification-store.js` persists notifications to `.sf/notifications.jsonl` (fail-open, idempotent init).
- **Manifest-Driven Composition**: `src/resources/extensions/sf/unit-context-manifest.js` declares per-unit-type inline + computed artifacts; `composeUnitContext` assembles prompts deterministically.
- **Web UI**: `web/` (Next.js 16) — dashboard, terminal, session manager, settings. Builds and runs (verified 2026-05-17).

## Capability Contract

See [.sf/REQUIREMENTS.md](REQUIREMENTS.md) for the explicit capability contract, requirement status, and coverage mapping. R001-R010 are M003-M005 era contracts (all covered). R011-R015 are queued into M010-M011 (this session).

## Priority Tier Order

When the autonomous planner has multiple eligible candidates to dispatch, prefer lower-numbered tiers. Within a tier, dependency order and risk break ties. Cost-of-iteration is *not* a top-tier driver — SF spending $0.03 to ship a correct slice is fine; what matters is that the slice is correct and the foundations underneath it stay sound.

**Reordered 2026-05-17 after Codex adversarial review** (both diff-scope and full-backlog-vs-ADR-0000). Two structural corrections: (a) self-heal and runtime-regression firewall come *before* new infrastructure, because SF crash-loops on its own bugs (DEFAULT_STALE_TIMEOUT_MS regression burned 2h on 2026-05-17). (b) The purpose/PDD gates (M030/M034/M019/M025/M048) are not "quality polish" — they are the compiler front-end and verifier that ADR-0000 makes load-bearing; they belong in foundation.

| Tier | Theme | Milestones |
|------|-------|------------|
| 1 | Self-heal & regression firewall — must survive own bugs | **M011**, **M038**, **M048** |
| 2 | Compiler front-end & evidence gate (ADR-0000 contract) | **M030**, **M034**, **M019**, **M025** |
| 3 | Dispatch foundation — bus coherence first, then writer | M012, M040 (gated on R016 fix in M012), M010 (with R020 equivalence proof), M041 |
| 4 | Quality / integrity — manifest, doctor, audits | M042, M043, M015 |
| 5 | Performance / scale — *blocked* on tiers 1-3 | M033, M036, M045, M028, M039 (system lane gated on M040+M034) |
| 6 | Cost optimization — purpose-keyed accounting | M020, M046, R040 |
| 7 | Operator UX — surfaces, dashboards | M017, M029 |
| 8 | Extensibility — plugins, federation, exports | M022, M023, M021, M024 |

Rationale:
- **Self-heal first.** R011/R012/R051-R056 + the new R066/M048 firewall need to land before more foundation work because every new foundation bug strands SF in an unrecoverable state until human intervention. M038 lands with or inside M010 as the safety harness for default-on inline dispatch.
- **Purpose gates second.** ADR-0000 sequences the pipeline as PDD → research → run-control → contract → evidence → implementation. Today M030 (purpose trace), M034 (per-R validation), M019 (test-backed completion), M025 (ADR enforcement) sit in Tier 3 — that lets SF keep building a generic agent platform with better dispatch *before* it can prove bounded intent / consumer / contract / falsifier / evidence exist for each unit. Promoted to Tier 2.
- **Dispatch foundation gated.** M040 (DB-via-Bus, R058) cannot land before R016 (bus coherence) is verified — building writer-actor on top of an ack-without-deliver bus converts SQLITE_BUSY into *lost* writes. M010 (inline dispatch) is opt-in until R020 equivalence proof passes.
- **Parallelism deferred.** M033/M036/M039 are pushed to Tier 5 with explicit prereqs: idempotency (M026), writer (M040), rate budget (M045), and purpose gates (M030/M034). Multi-lane work without those gates amplifies corruption, duplicate artifacts, quota failures, and off-purpose spend.
- **Cost stays late.** R040 (purpose-keyed cost) is the right cost lens — "did this $ serve the stated purpose?" — not "how cheap was it?". A cheap-but-incorrect slice is a regression; a correct slice at fair cost compounds.

## Milestone Sequence

- [x] M001-6377a4: Foundational doctrine (5 slices)
- [x] M003: Autonomous Self-Healing — full self-heal loop (S01-S06)
- [x] M004: Phase 3 migration (19 builders)
- [x] M005: V2 migration (remaining builders + duplication-bug remediation)
- [x] M006: Manifest-Driven Context v2 (final builders + regression guard)
- [ ] **M048: Runtime Regression Firewall (R066) — Tier 1**, smoke fixture + last-green ledger + crash-loop quarantine + auto-rollback. Prevents the DEFAULT_STALE_TIMEOUT_MS class of self-inflicted crash-loops.
- [ ] M011: Defective-Complete Milestone Self-Heal (R011-R012) — **Tier 1**
- [ ] M038: Wiggums-style stuck pattern detection — **Tier 1**, lands with or inside M010 as safety harness
- [ ] M010: Unified Dispatch v2 — inline scope (R013-R015), opt-in until R020 equivalence proof — Tier 3
- [ ] M012: MessageBus Persistence + Inbox Coherence (new R016)
- [ ] M013: Multi-Model Routing Intelligence (new R017)
- [ ] M014: Project Roadmap & State Reconciliation (new R018)
- [ ] M015: Operational Tooling — triage + state hygiene (new R019)
