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>
2.9 KiB
2.9 KiB
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 | Branchless Worktree Architecture — .sf/milestones/ tracked, runtime gitignored |
Accepted |
| ADR-003 | Pipeline Simplification — research merged into planning | Accepted |
| ADR-004 | Capability-Aware Model Routing | Accepted |
| ADR-005 | Multi-Model Provider Tool Strategy | Accepted |
| ADR-007 | Model Catalog Split | Accepted |
| ADR-008 | SF Tools over MCP for Provider Parity | Proposed — deferred (usage model mismatch) |
| ADR-009 | Orchestration Kernel Refactor | Accepted |
| ADR-010 | Pi Clean Seam Architecture | Accepted |
| ADR-011 | Swarm Chat and Debate Mode | Proposed |
| ADR-012 | Multi-Instance Federation | Proposed |
| ADR-013 | Network and Remote Execution | Proposed |
| ADR-014 | Singularity Knowledge and Agent Platform | Proposed |
| ADR-015 | Flight Recorder | Proposed |
| ADR-016 | Charm AI Stack Adoption | Proposed |
| ADR-017 | Charm TUI Client | Proposed |
| ADR-018 | Repo-Native Harness Evolution | Proposed — staged impl |
| ADR-019 | Workspace VM Convergence — SF↔ACE incremental convergence via microVM execution layer | Proposed |
| ADR-020 | Internal Wire Architecture — singularity-grpc shared schema repo, gRPC for first-party services, MCP at external-tool boundary only |
Proposed |
| ADR-021 | 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 | Reference |
| core-beliefs.md | Core Beliefs | Accepted |
| notification-event-model.md | Notification Event Model | Draft |