eb56173fe5
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>
36 lines
2.9 KiB
Markdown
36 lines
2.9 KiB
Markdown
# 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 | Proposed — deferred (usage model mismatch) |
|
|
| [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 |
|