Design doc for moving SF's milestone planning state from
markdown-as-source-of-truth to DB-as-source-of-truth, with markdown
becoming a render target.
463 lines, ~4500 words. Includes:
- Survey of all markdown artifacts under .sf/milestones/M*/ and
who writes/reads each today (drift authoritative-ness is
ambiguous in most cases)
- MVP picks *-VALIDATION.md as first artifact to migrate — three
read-site fixes, no schema change, the doctor's
db_projection_validation_drift check retires immediately
- Hybrid editing UX (option c): CONTEXT-DRAFT and in-progress PLAN
stay LLM-writable markdown; tool-call-bounded artifacts
(validate_milestone, complete_slice, etc.) become DB-first with
generated <!-- generated --> headers
- 5-phase rollout plan
- Open question flagged: git atomicity for milestone-level
syncMilestoneLevelFiles calls — needs explicit tracing before
Phase 4/5
No source-code changes. Implementation comes later.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Design doc for collapsing the five parallel agent-dispatch sites
(defaultAgentRunner, runHeadlessPrompt, runSingleAgent, runUnitViaSwarm,
slice-parallel-orchestrator) onto one runtime with three orthogonal
axes — persistence, isolation, routing.
590 lines, ~5200 words. Includes:
- Problem statement with five concrete pain points from this session's
swarm convergence rounds (spawn hangs, inbox cache, checkpoint
synthesis, ledger isolation, etc.)
- Worked-out TypeScript interface
- Mapping of each existing site to runtime options (table)
- 8-step migration plan in blast-radius order (~4-5 days focused work)
- Open questions
No source-code changes. Implementation comes later.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Final rebrand: rename remaining Rust source file to complete the gsd → forge
transition. All parser references already use forge_parser after earlier commits.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split flat docs/ into user-docs/ (guides, config, troubleshooting) and
dev/ (ADRs, architecture, extension guides, proposals). Updated
docs/README.md index to reflect new paths.
