singularity-forge/docs/design-docs/index.md

# Design Docs

Durable design decisions live here. ADRs (Architecture Decision Records) are numbered sequentially
in `docs/dev/`. Lighter design docs (problem framing, event model decisions) live in this directory.

## Architecture Decision Records (`docs/dev/`)

| ADR | Title | Status |
|-----|-------|--------|
| [ADR-001](../dev/ADR-001-branchless-worktree-architecture.md) | Branchless Worktree Architecture — `.sf/milestones/` tracked, runtime gitignored | Accepted |
| [ADR-003](../dev/ADR-003-pipeline-simplification.md) | Pipeline Simplification — research merged into planning | Accepted |
| [ADR-004](../dev/ADR-004-capability-aware-model-routing.md) | Capability-Aware Model Routing | Accepted |
| [ADR-005](../dev/ADR-005-multi-model-provider-tool-strategy.md) | Multi-Model Provider Tool Strategy | Accepted |
| [ADR-007](../dev/ADR-007-model-catalog-split.md) | Model Catalog Split | Accepted |
| [ADR-008](../dev/ADR-008-sf-tools-over-mcp-for-provider-parity.md) | SF Tools over MCP for Provider Parity | Historical — superseded by ADR-020 boundary |
| [ADR-009](../dev/ADR-009-orchestration-kernel-refactor.md) | Orchestration Kernel Refactor | Accepted |
| [ADR-010](../dev/ADR-010-pi-clean-seam-architecture.md) | Pi Clean Seam Architecture | Accepted |
| [ADR-011](../dev/ADR-011-swarm-chat-and-debate-mode.md) | Swarm Chat and Debate Mode | Proposed |
| [ADR-012](../dev/ADR-012-multi-instance-federation.md) | Multi-Instance Federation | Proposed |
| [ADR-013](../dev/ADR-013-network-and-remote-execution.md) | Network and Remote Execution | Proposed |
| [ADR-014](../dev/ADR-014-singularity-knowledge-and-agent-platform.md) | Singularity Knowledge and Agent Platform | Proposed |
| [ADR-015](../dev/ADR-015-flight-recorder.md) | Flight Recorder | Proposed |
| [ADR-016](../dev/ADR-016-charm-ai-stack-adoption.md) | Charm AI Stack Adoption | Proposed |
| [ADR-017](../dev/ADR-017-charm-tui-client.md) | Charm TUI Client | Proposed |
| [ADR-018](../dev/ADR-018-repo-native-harness-evolution.md) | Repo-Native Harness Evolution | Proposed — staged impl |
| [ADR-019](../dev/ADR-019-workspace-vm-convergence.md) | Workspace VM Convergence — SF↔ACE incremental convergence via microVM execution layer | Proposed |
| [ADR-020](../dev/ADR-020-internal-wire-architecture.md) | Internal Wire Architecture — `singularity-grpc` shared schema repo, gRPC for first-party services, MCP at external-tool boundary only | Proposed |
| [ADR-021](../dev/ADR-021-versioned-documents-and-upgrade-path.md) | Versioned Documents and Upgrade Path — per-file scaffold markers, drift detection, `/sf scaffold sync` | Proposed |

## Design Docs (this directory)

| Doc | Title | Status |
|-----|-------|--------|
| [ADR-TEMPLATE.md](./ADR-TEMPLATE.md) | ADR Template | Reference |
| [core-beliefs.md](./core-beliefs.md) | Core Beliefs | Accepted |
| [notification-event-model.md](./notification-event-model.md) | Notification Event Model | Draft |
fix: stabilize sf auto and subagent routing 2026-04-30 21:55:17 +02:00			`# Design Docs`

feat: implement ADR-001 gitignore split and fill placeholder docs Gitignore (core change): - Remove stale blanket .sf/ entries from .gitignore (migrated to .git/info/exclude on 2026-04-29, never cleaned up) - gitignore.ts: split SF_RUNTIME_EXCLUSION_PATTERNS into two modes — SF_SYMLINK_EXCLUSION_PATTERNS (blanket .sf for symlink repos where git cannot traverse the symlink) and SF_RUNTIME_EXCLUSION_PATTERNS (granular runtime-only patterns for directory repos, enabling .sf/milestones/ and other durable planning artifacts to be tracked) - ensureGitInfoExclude() now detects symlink vs directory and writes the correct patterns, handling transitions between modes cleanly - ADR-001 status: Proposed → Accepted Docs: - Fill 11 placeholder scaffold docs with real SF-specific content: PLANS, DESIGN, PRODUCT_SENSE, QUALITY_SCORE, RELIABILITY, SECURITY, design-docs/index.md, exec-plans/active, exec-plans/completed, exec-plans/tech-debt-tracker, records/index - Add records note: docs/records/2026-05-01-repo-vcs-and-notifications.md - ADR-008 status: Accepted → Proposed (deferred — not applicable to current usage model where Claude Code assists externally, not as a Pi provider inside SF's dispatch loop) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 22:32:28 +02:00			`Durable design decisions live here. ADRs (Architecture Decision Records) are numbered sequentially`
			in `docs/dev/`. Lighter design docs (problem framing, event model decisions) live in this directory.

			## Architecture Decision Records (`docs/dev/`)

			`\| ADR \| Title \| Status \|`
			`\|-----\|-------\|--------\|`
			\| [ADR-001](../dev/ADR-001-branchless-worktree-architecture.md) \| Branchless Worktree Architecture — `.sf/milestones/` tracked, runtime gitignored \| Accepted \|
			`\| [ADR-003](../dev/ADR-003-pipeline-simplification.md) \| Pipeline Simplification — research merged into planning \| Accepted \|`
			`\| [ADR-004](../dev/ADR-004-capability-aware-model-routing.md) \| Capability-Aware Model Routing \| Accepted \|`
			`\| [ADR-005](../dev/ADR-005-multi-model-provider-tool-strategy.md) \| Multi-Model Provider Tool Strategy \| Accepted \|`
			`\| [ADR-007](../dev/ADR-007-model-catalog-split.md) \| Model Catalog Split \| Accepted \|`
docs: align sf purpose doctrine and docs 2026-05-06 00:38:36 +02:00			`\| [ADR-008](../dev/ADR-008-sf-tools-over-mcp-for-provider-parity.md) \| SF Tools over MCP for Provider Parity \| Historical — superseded by ADR-020 boundary \|`
feat: implement ADR-001 gitignore split and fill placeholder docs Gitignore (core change): - Remove stale blanket .sf/ entries from .gitignore (migrated to .git/info/exclude on 2026-04-29, never cleaned up) - gitignore.ts: split SF_RUNTIME_EXCLUSION_PATTERNS into two modes — SF_SYMLINK_EXCLUSION_PATTERNS (blanket .sf for symlink repos where git cannot traverse the symlink) and SF_RUNTIME_EXCLUSION_PATTERNS (granular runtime-only patterns for directory repos, enabling .sf/milestones/ and other durable planning artifacts to be tracked) - ensureGitInfoExclude() now detects symlink vs directory and writes the correct patterns, handling transitions between modes cleanly - ADR-001 status: Proposed → Accepted Docs: - Fill 11 placeholder scaffold docs with real SF-specific content: PLANS, DESIGN, PRODUCT_SENSE, QUALITY_SCORE, RELIABILITY, SECURITY, design-docs/index.md, exec-plans/active, exec-plans/completed, exec-plans/tech-debt-tracker, records/index - Add records note: docs/records/2026-05-01-repo-vcs-and-notifications.md - ADR-008 status: Accepted → Proposed (deferred — not applicable to current usage model where Claude Code assists externally, not as a Pi provider inside SF's dispatch loop) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 22:32:28 +02:00			`\| [ADR-009](../dev/ADR-009-orchestration-kernel-refactor.md) \| Orchestration Kernel Refactor \| Accepted \|`
			`\| [ADR-010](../dev/ADR-010-pi-clean-seam-architecture.md) \| Pi Clean Seam Architecture \| Accepted \|`
			`\| [ADR-011](../dev/ADR-011-swarm-chat-and-debate-mode.md) \| Swarm Chat and Debate Mode \| Proposed \|`
			`\| [ADR-012](../dev/ADR-012-multi-instance-federation.md) \| Multi-Instance Federation \| Proposed \|`
			`\| [ADR-013](../dev/ADR-013-network-and-remote-execution.md) \| Network and Remote Execution \| Proposed \|`
			`\| [ADR-014](../dev/ADR-014-singularity-knowledge-and-agent-platform.md) \| Singularity Knowledge and Agent Platform \| Proposed \|`
			`\| [ADR-015](../dev/ADR-015-flight-recorder.md) \| Flight Recorder \| Proposed \|`
			`\| [ADR-016](../dev/ADR-016-charm-ai-stack-adoption.md) \| Charm AI Stack Adoption \| Proposed \|`
			`\| [ADR-017](../dev/ADR-017-charm-tui-client.md) \| Charm TUI Client \| Proposed \|`
			`\| [ADR-018](../dev/ADR-018-repo-native-harness-evolution.md) \| Repo-Native Harness Evolution \| Proposed — staged impl \|`
docs: add ADR-019 workspace VM convergence architecture Captures the SF↔ACE incremental convergence strategy: workspace VMs (Firecracker) as the unified execution isolation primitive, the three-layer architecture (orchestration/knowledge/execution), the 6-phase convergence path, and ADR-014 Phase 4 cancellation (persistent-agent runtime reassigned to ACE). Cross-references the matching ACE document at docs/architecture/sf-ace-convergence.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 23:21:23 +02:00			`\| [ADR-019](../dev/ADR-019-workspace-vm-convergence.md) \| Workspace VM Convergence — SF↔ACE incremental convergence via microVM execution layer \| Proposed \|`
feat: SF strengthening + ADR-020 wire architecture (Phases 1-2) Phase 1 — close SF-side polish gaps: - codebase-generator: distinguish uv/poetry/pdm in Python stack-signals; surface configured tooling (ruff/mypy/pyright) when config files exist - doctor-environment: new checkPythonEnvironment — detects uv/poetry/pdm via lockfile, verifies binary on PATH, warns with install hint when missing - doctor-environment: new checkSiftAvailable — recommends sift install for repos > 5000 source files when not on PATH - tech-debt-tracker: documented future memory-as-sub-extension extraction (defer until real backend-swap requirement) Phase 2 — internal wire architecture: - ADR-020: singularity-grpc as shared schema repo; gRPC + typed clients for first-party services; MCP façade only at external-tool boundary - ADR-019: trimmed MCP scope section to a 3-line summary linking to ADR-020 to avoid the wire-format table living in two places - design-docs/index.md: ADR-020 added to ADR table These changes make SF stronger for autonomous work on Python repos (particularly ace-coder) and capture the internal wire architecture decision as a durable ADR before any singularity-grpc code lands. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-02 00:03:34 +02:00			\| [ADR-020](../dev/ADR-020-internal-wire-architecture.md) \| Internal Wire Architecture — `singularity-grpc` shared schema repo, gRPC for first-party services, MCP at external-tool boundary only \| Proposed \|
ADR-021: versioned documents + automatic upgrade via records-keeper Generalizes the preferences-template-upgrade pattern to all scaffold-managed documents with three states (pending/editing/completed), HTML-comment markers on Markdown files, frontmatter on PREFERENCES.md, and a content-hash archive for migrating legacy projects. Operation is automatic-first, not command-driven: - Synchronous on every SF startup (cheap path: missing + upgradable + legacy) - Asynchronous after milestone completion: scaffold-keeper subagent runs the existing records-keeper skill, treating code as the source of truth and re-deriving doc content from source when drift is detected - Surfaces results via the structured-notification model (kind:approval_request) only when human review is warranted; silent runs produce no notification - Manual /sf scaffold sync exists as an escape hatch for dry-run + forced refresh, not as the primary interface Five implementation phases (A-E), each independently shippable. Phase A unlocks the architectural property; Phase D is what makes records-keeper autonomous for code-derived docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-02 00:18:16 +02:00			\| [ADR-021](../dev/ADR-021-versioned-documents-and-upgrade-path.md) \| Versioned Documents and Upgrade Path — per-file scaffold markers, drift detection, `/sf scaffold sync` \| Proposed \|
feat: implement ADR-001 gitignore split and fill placeholder docs Gitignore (core change): - Remove stale blanket .sf/ entries from .gitignore (migrated to .git/info/exclude on 2026-04-29, never cleaned up) - gitignore.ts: split SF_RUNTIME_EXCLUSION_PATTERNS into two modes — SF_SYMLINK_EXCLUSION_PATTERNS (blanket .sf for symlink repos where git cannot traverse the symlink) and SF_RUNTIME_EXCLUSION_PATTERNS (granular runtime-only patterns for directory repos, enabling .sf/milestones/ and other durable planning artifacts to be tracked) - ensureGitInfoExclude() now detects symlink vs directory and writes the correct patterns, handling transitions between modes cleanly - ADR-001 status: Proposed → Accepted Docs: - Fill 11 placeholder scaffold docs with real SF-specific content: PLANS, DESIGN, PRODUCT_SENSE, QUALITY_SCORE, RELIABILITY, SECURITY, design-docs/index.md, exec-plans/active, exec-plans/completed, exec-plans/tech-debt-tracker, records/index - Add records note: docs/records/2026-05-01-repo-vcs-and-notifications.md - ADR-008 status: Accepted → Proposed (deferred — not applicable to current usage model where Claude Code assists externally, not as a Pi provider inside SF's dispatch loop) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 22:32:28 +02:00
			`## Design Docs (this directory)`

			`\| Doc \| Title \| Status \|`
			`\|-----\|-------\|--------\|`
feat: harness scaffold, runtime pattern sync, and ARCHITECTURE injection - Add harness/ directory to SF repo (specs/, evals/, graders/ with AGENTS.md) and seed harness/specs/bootstrap.md (agent-legibility verification) - Extend agentic-docs-scaffold.ts: new repos get harness/ + ADR-TEMPLATE.md and just adr / just spec / just harness-spec recipes via justfile - Sync SF_RUNTIME_PATTERNS (gitignore.ts canonical) → git-service.ts and worktree-manager.ts: add audit/, exec/, model-benchmarks/, reports/, notifications.jsonl, routing-history.json, self-feedback.jsonl, repo-meta.json, and milestone continue-marker patterns - Inject ARCHITECTURE.md into system prompt via loadArchitectureBlock() in system-context.ts (capped at 8 000 chars, after KNOWLEDGE block) - Write real ARCHITECTURE.md for this repo (system map, .sf/ layout, key flows) - Add ADR-TEMPLATE.md to docs/design-docs/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 22:46:28 +02:00			`\| [ADR-TEMPLATE.md](./ADR-TEMPLATE.md) \| ADR Template \| Reference \|`
feat: implement ADR-001 gitignore split and fill placeholder docs Gitignore (core change): - Remove stale blanket .sf/ entries from .gitignore (migrated to .git/info/exclude on 2026-04-29, never cleaned up) - gitignore.ts: split SF_RUNTIME_EXCLUSION_PATTERNS into two modes — SF_SYMLINK_EXCLUSION_PATTERNS (blanket .sf for symlink repos where git cannot traverse the symlink) and SF_RUNTIME_EXCLUSION_PATTERNS (granular runtime-only patterns for directory repos, enabling .sf/milestones/ and other durable planning artifacts to be tracked) - ensureGitInfoExclude() now detects symlink vs directory and writes the correct patterns, handling transitions between modes cleanly - ADR-001 status: Proposed → Accepted Docs: - Fill 11 placeholder scaffold docs with real SF-specific content: PLANS, DESIGN, PRODUCT_SENSE, QUALITY_SCORE, RELIABILITY, SECURITY, design-docs/index.md, exec-plans/active, exec-plans/completed, exec-plans/tech-debt-tracker, records/index - Add records note: docs/records/2026-05-01-repo-vcs-and-notifications.md - ADR-008 status: Accepted → Proposed (deferred — not applicable to current usage model where Claude Code assists externally, not as a Pi provider inside SF's dispatch loop) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-05-01 22:32:28 +02:00			`\| [core-beliefs.md](./core-beliefs.md) \| Core Beliefs \| Accepted \|`
			`\| [notification-event-model.md](./notification-event-model.md) \| Notification Event Model \| Draft \|`