Move product strategy documentation to .product-strategy directory

Organize all product strategy and domain modeling documentation into a dedicated .product-strategy directory for better separation from code. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-12 23:57:11 +01:00
parent 18ea677585
commit 271f5db444
26 changed files with 16521 additions and 0 deletions
--- a/.product-strategy/BACKLOG_QUICK_REFERENCE.md
+++ b/.product-strategy/BACKLOG_QUICK_REFERENCE.md
@@ -0,0 +1,330 @@
+# Aether Backlog: Quick Reference
+
+**Full backlog:** `/BACKLOG.md` (2600+ lines, complete details)
+
+This page is a quick reference for navigating the backlog.
+
+---
+
+## Phase Overview
+
+| Phase | Name | Capabilities | Issues | Dependencies |
+|-------|------|--------------|--------|--------------|
+| 1 | Event Sourcing Foundation | 1, 2, 3 | 17 | None (foundation) |
+| 2 | Local Event Bus | 8 | 9 | Phase 1 |
+| 3 | Cluster Coordination | 5, 6, 7 | 20 | Phase 1 |
+| 4 | Namespace & NATS | 4, 9 | 21 | Phases 1-3 (parallel) |
+
+---
+
+## Issue Count by Context
+
+| Bounded Context | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Total |
+|-----------------|---------|---------|---------|---------|-------|
+| Event Sourcing | 10 | - | - | - | 10 |
+| OCC | 2 | - | - | - | 2 |
+| Event Bus | - | 9 | - | 3 | 12 |
+| Cluster | - | - | 20 | - | 20 |
+| Namespace | - | - | - | 4 | 4 |
+| Documentation | - | - | - | 14 | 14 |
+| **Total** | 12 | 9 | 20 | 21 | 67 |
+
+---
+
+## Phase 1: Event Sourcing Foundation (Issues 1.1-1.12)
+
+### Core Storage (1.1-1.5)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 1.1 | SaveEvent with monotonic version | Command | P0 |
+| 1.2 | Enforce append-only | Rule | P0 |
+| 1.3 | Publish EventStored | Event | P0 |
+| 1.4 | Publish VersionConflict | Event | P0 |
+| 1.5 | GetLatestVersion query | Query | P0 |
+
+### State Rebuild (1.6-1.10)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 1.6 | GetEvents for replay | Query | P0 |
+| 1.7 | Snapshot invalidation policy | Rule | P1 |
+| 1.8 | Publish SnapshotCreated | Event | P1 |
+| 1.9 | GetEventsWithErrors | Query | P1 |
+| 1.10 | SnapshotStore interface | Interface | P0 |
+
+### OCC (1.11-1.12)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 1.11 | Fail-fast on conflict | Rule | P0 |
+| 1.12 | Document retry patterns | Docs | P1 |
+
+---
+
+## Phase 2: Local Event Bus (Issues 2.1-2.9)
+
+### Routing & Filtering (2.1-2.7)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 2.1 | Publish command | Command | P1 |
+| 2.2 | Subscribe with filter | Command | P1 |
+| 2.3 | Enforce exact isolation | Rule | P1 |
+| 2.4 | Document wildcard security | Docs | P1 |
+| 2.5 | Publish SubscriptionCreated | Event | P2 |
+| 2.6 | Publish EventPublished | Event | P2 |
+| 2.7 | GetSubscriptions query | Query | P2 |
+
+### Backpressure (2.8-2.9)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 2.8 | Non-blocking delivery | Rule | P1 |
+| 2.9 | Document backpressure | Docs | P2 |
+
+---
+
+## Phase 3: Cluster Coordination (Issues 3.1-3.17)
+
+### Topology & Leadership (3.1-3.7)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 3.1 | JoinCluster protocol | Command | P1 |
+| 3.2 | LeaderElection | Command | P0 |
+| 3.3 | Single leader invariant | Rule | P0 |
+| 3.4 | Publish LeaderElected | Event | P1 |
+| 3.5 | Publish LeadershipLost | Event | P2 |
+| 3.6 | GetClusterTopology | Query | P1 |
+| 3.7 | GetLeader | Query | P0 |
+
+### Shard Distribution (3.8-3.11)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 3.8 | Consistent hash ring | Command | P1 |
+| 3.9 | Single shard owner invariant | Rule | P0 |
+| 3.10 | Publish ShardAssigned | Event | P2 |
+| 3.11 | GetShardAssignments | Query | P1 |
+
+### Failure & Recovery (3.12-3.17)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 3.12 | Node health checks | Command | P1 |
+| 3.13 | RebalanceShards | Command | P0 |
+| 3.14 | No-orphan invariant | Rule | P0 |
+| 3.15 | Publish NodeFailed | Event | P2 |
+| 3.16 | Publish ShardMigrated | Event | P2 |
+| 3.17 | Document actor migration | Docs | P2 |
+
+---
+
+## Phase 4: Namespace & NATS (Issues 4.1-4.8)
+
+### Namespace Storage (4.1-4.4)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 4.1 | Stream naming | Rule | P1 |
+| 4.2 | Storage isolation | Rule | P0 |
+| 4.3 | Design patterns | Docs | P1 |
+| 4.4 | Format validation | Validation | P2 |
+
+### NATS Delivery (4.5-4.8)
+
+| Issue | Title | Type | Priority |
+|-------|-------|------|----------|
+| 4.5 | NATSEventBus | Command | P1 |
+| 4.6 | Exactly-once delivery | Rule | P1 |
+| 4.7 | Publish EventPublished | Event | P2 |
+| 4.8 | Cross-node subscription | Query | P1 |
+
+---
+
+## Dependency Graph
+
+```
+Phase 1 (Foundation)
+├─ 1.1 (SaveEvent)
+│  ├─ 1.2 (Append-only)
+│  ├─ 1.3 (EventStored event)
+│  ├─ 1.4 (VersionConflict event)
+│  ├─ 1.5 (GetLatestVersion)
+│  ├─ 1.6 (GetEvents)
+│  │  ├─ 1.7 (Snapshot policy)
+│  │  ├─ 1.8 (SnapshotCreated)
+│  │  └─ 1.9 (GetEventsWithErrors)
+│  └─ 1.10 (SnapshotStore)
+├─ 1.11 (Fail-fast)
+│  └─ 1.12 (Retry patterns)
+
+Phase 2 (Event Bus)
+├─ 2.2 (Subscribe)
+│  ├─ 2.1 (Publish)
+│  │  ├─ 2.3 (Exact isolation)
+│  │  ├─ 2.5 (SubscriptionCreated)
+│  │  └─ 2.6 (EventPublished)
+│  └─ 2.7 (GetSubscriptions)
+├─ 2.4 (Wildcard docs)
+├─ 2.8 (Non-blocking)
+│  └─ 2.9 (Backpressure docs)
+
+Phase 3 (Cluster)
+├─ 3.1 (JoinCluster)
+│  ├─ 3.2 (LeaderElection)
+│  │  ├─ 3.3 (Single leader)
+│  │  ├─ 3.4 (LeaderElected event)
+│  │  ├─ 3.5 (LeadershipLost event)
+│  │  └─ 3.7 (GetLeader)
+│  ├─ 3.6 (GetClusterTopology)
+│  ├─ 3.8 (Consistent hash)
+│  │  ├─ 3.9 (Single owner)
+│  │  ├─ 3.10 (ShardAssigned)
+│  │  └─ 3.11 (GetShardAssignments)
+│  ├─ 3.12 (Health checks)
+│  │  ├─ 3.13 (RebalanceShards)
+│  │  │  ├─ 3.14 (No-orphan)
+│  │  │  ├─ 3.15 (NodeFailed)
+│  │  │  └─ 3.16 (ShardMigrated)
+│  │  └─ 3.17 (Migration docs)
+
+Phase 4 (Namespace & NATS)
+├─ 4.1 (Stream naming)
+│  ├─ 4.2 (Storage isolation)
+│  ├─ 4.3 (Design patterns)
+│  └─ 4.4 (Validation)
+├─ 4.5 (NATSEventBus) [depends on 2.1]
+│  ├─ 4.6 (Exactly-once)
+│  ├─ 4.7 (EventPublished)
+│  └─ 4.8 (Cross-node subscription)
+```
+
+---
+
+## Critical Path
+
+**Minimum viable cluster (13 issues):**
+
+1. 1.1 SaveEvent (P0)
+2. 1.5 GetLatestVersion (P0)
+3. 1.6 GetEvents (P0)
+4. 1.10 SnapshotStore (P0)
+5. 1.11 Fail-fast (P0)
+6. 2.1 Publish (P1)
+7. 2.2 Subscribe (P1)
+8. 3.2 LeaderElection (P0)
+9. 3.8 Consistent hash (P1)
+10. 3.12 Health checks (P1)
+11. 3.13 RebalanceShards (P0)
+12. 4.1 Stream naming (P1)
+13. 4.5 NATSEventBus (P1)
+
+**Estimated duration:** 4-6 weeks (aggressive)
+
+---
+
+## Implementation Recommendations
+
+### Start With Phase 1
+- Everything depends on it
+- Core domain logic
+- Enables testing without clustering
+- Parallel: can implement 1.1-1.5 concurrently
+
+### Phase 2 Early
+- Observability (metrics, logging)
+- Tests easier without cluster
+- Validate design before clustering
+
+### Phase 3 in Parallel
+- Can start while Phase 2 incomplete
+- Higher complexity (needs multi-node tests)
+- Consider spike if team unfamiliar with clustering
+
+### Phase 4 Last
+- Namespace: orthogonal (can do anytime)
+- NATS: depends on 2.1 (Publish)
+- Complex (distributed tracing, durability)
+
+---
+
+## Key Files
+
+| Purpose | File |
+|---------|------|
+| Full backlog | `/BACKLOG.md` |
+| Capabilities | `/CAPABILITIES.md` |
+| Domain models | `/DOMAIN_MODEL_*.md` |
+| Bounded contexts | `/BOUNDED_CONTEXT_MAP.md` |
+| This doc | `/BACKLOG_QUICK_REFERENCE.md` |
+
+---
+
+## Using This Backlog
+
+### For Project Managers
+- Use Phase breakdown for milestones
+- Critical path shows minimum scope
+- Dependency graph prevents sequencing errors
+
+### For Engineers
+- Each issue has acceptance criteria
+- DDD guidance explains domain concepts
+- Dependencies prevent blocking work
+- Start with Phase 1 for foundation
+
+### For Architects
+- Capability map shows user value
+- Bounded contexts explain isolation
+- Feature sets show vertical slices
+- Domain models guide implementation
+
+---
+
+## Common Questions
+
+**Q: Can phases be parallelized?**
+A: Partially. Phase 1 must complete first. Phases 2-3 can overlap after Phase 1. Phase 4 can be delayed.
+
+**Q: What if we skip Phase 3 (clustering)?**
+A: Possible. You get event sourcing, local pub/sub, namespaces. But distributed actors won't work. Phase 1 + 2 + 4 is a valid product.
+
+**Q: What's the hardest phase?**
+A: Phase 3 (clustering). Requires multi-node tests, distributed algorithms, failure scenarios. Phase 1 is foundational but not complex.
+
+**Q: Can we deliver value incrementally?**
+A: Yes. After Phase 1: "Event sourcing with OCC". After Phase 2: "Local pub/sub". After Phase 3: "Distributed cluster". After Phase 4: "Multi-tenant NATS".
+
+**Q: Which issues are P0 vs P1?**
+A: P0 = blocking (no alternative); P1 = important (ship without, but limited); P2 = nice-to-have (polish, observability). Focus on P0 first.
+
+---
+
+## Metrics to Track
+
+- **Velocity:** Issues per sprint (size estimates TBD)
+- **Burndown:** Phase completion vs planned
+- **Quality:** Test coverage per phase
+- **Risk:** Dependency blocking (red flag)
+
+---
+
+## Related Skills
+
+- `/issue-writing` - Create Gitea issues from this backlog
+- `/spawn-issues` - Parallelize implementation with worktrees
+- `/product-strategy` - Decompose vision to work (meta-skill used here)
+- `/ddd` - Domain-driven design concepts and patterns
+
+---
+
+## Questions?
+
+Refer to:
+- Full backlog: `/BACKLOG.md`
+- Domain models: `/DOMAIN_MODEL_*.md`
+- Capabilities: `/CAPABILITIES.md`
+- Vision: `/vision.md`
+- Product strategy: `/STRATEGY_CHAIN.md`