docs: Expand ADR 003 with internal state machine documentation

[yewreeka]

Summary

Expand the existing ADR 003 (Inbox Lifecycle Management) with documentation of the internal state machines, rather than creating a duplicate ADR.

What's Added to ADR 003

• Architecture overview diagram showing component relationships (InboxLifecycleManager, MessagingService, state machines, UnusedConversationCache)
• InboxStateMachine state diagram (idle → authorizing → ready → backgrounded → deleting)
• ConversationStateMachine state diagram (uninitialized → creating/validating → joining → ready)
• Edge cases section documenting race condition handling:
  • Re-wake during sleep
  • Duplicate registration prevention
  • Concurrent eviction
  • Stale data cleanup
• Additional related files references

Also Includes

• docs/plans/tech-debt-1.1.0.md - Tech debt tracking for post-1.1.0 release

Context

Between 1.0.6 and 1.1.0 we had 6+ fixes related to inbox lifecycle edge cases. This documentation will help engineers understand the system and reduce future bugs.

Note

Expand ADR 003 to document internal per-inbox and per-conversation state machines in docs/adr/003-inbox-lifecycle-management.md

Add an 'Internal State Machines' section with architecture and state diagrams for InboxStateMachine and ConversationStateMachine, include edge cases with Swift snippets, and update related file links in docs/adr/003-inbox-lifecycle-management.md.

📍Where to Start

Start at the new 'Internal State Machines' section in docs/adr/003-inbox-lifecycle-management.md.

^{Macroscope summarized e6abd98.}

[claude]

Claude finished @yewreeka's task —— View job

---

Code Review

• Read modified ADR file
• Read new tech debt plan file
• Provide review feedback

---

Review Summary

This PR adds valuable documentation with clear, comprehensive state machine diagrams and architectural context. The writing is excellent and the content will significantly help engineers understand the inbox lifecycle system.

Strengths

ADR 003 Expansion:

• State machine diagrams are clear and follow standard notation (idle → authorizing → ready flow)
• Architecture overview diagram effectively shows component relationships
• Edge cases section documents real issues encountered (re-wake during sleep, duplicate registration)
• File references with line numbers make it easy to find implementation details
• Mermaid-style ASCII diagrams work well for markdown rendering

Tech Debt Plan:

• Honest retrospective showing most items were non-issues (2 of 6 required work)
• Evidence-based approach (audit before acting)
• Clear outcome tracking with status indicators
• Good lesson learned section

Suggestions

Minor improvements for ADR 003:

1. State diagram notation (lines 301-329): Consider adding legend for transition conditions:

   ┌─────────┐
   │  idle   │
   └────┬────┘
        │ Event: authorize() or register()
        │ Condition: Has clientId
   

2. Architecture diagram (lines 271-294): Could benefit from showing data flow direction. For example:

   MessagingService ──queries──> InboxActivityRepository
   InboxLifecycleManager ──evicts──> MessagingService
   

3. Edge cases section (lines 366-400): Great content, but could add cross-references to related test files:

   ### Re-wake During Sleep
   
   **Tests:** `InboxLifecycleManagerTests.swift:456-478`
   

4. Line number references: Some references like line 95, 394-417 may drift over time. Consider using method names instead:

   **Location:** `InboxLifecycleManager.wake(clientId:reason:)` and `evictLRUInbox()`
   

Tech Debt Plan:

5. Item 6 (line 135): "Review Agent POC architecture" - Could add more context about what specifically needs review (security model, user permissions, API design, etc.)

Code Quality

Not applicable - documentation-only PR with no source code changes.

Performance

Not applicable - documentation-only PR.

Security

Not applicable - documentation-only PR.

Test Coverage

Not applicable - documentation-only PR. However, the tech debt plan effectively documents that test coverage for inbox state machines is already comprehensive (4,341 lines).

Overall Assessment

Approve with minor suggestions. This is exactly the kind of documentation that prevents future bugs - it captures hard-won knowledge about edge cases and state transitions. The fact that 6+ fixes were required between 1.0.6 and 1.1.0 validates the need for this documentation.

The only improvements needed are minor formatting enhancements that would make the diagrams and references even more maintainable over time.

---

[macroscopeapp]

This PR only adds documentation files (ADR and tech debt plan) with no code changes. Documentation changes don't affect runtime behavior and are safe to approve.

Dismissing my prior approval and re-evaluating approvability for db37987

[macroscopeapp]

This PR only adds documentation files (ADR updates and a tech debt plan). No source code is changed and there is no runtime impact, making it safe to approve.

Dismissing my prior approval and re-evaluating approvability for 4b5f7d9

[macroscopeapp]

This PR only adds documentation (ADR expansion and a tech debt plan). No runtime code is changed, making it safe to approve.

Dismissing my prior approval and re-evaluating approvability for df12c2c

[macroscopeapp]

This PR only adds documentation files (expanding an ADR with state machine diagrams and adding a tech debt planning doc). No code changes, no runtime impact. Safe to approve.

Dismissing my prior approval and re-evaluating approvability for 54da047

[macroscopeapp]

This PR only adds documentation (ADR expansion and a tech debt planning doc). No source code is modified and there's no runtime impact.

Dismissing my prior approval and re-evaluating approvability for 5b594fa

[macroscopeapp]

This PR only adds documentation - expanding an ADR with state machine diagrams and creating a tech debt planning document. No runtime code is changed, making it safe to approve.

Dismissing my prior approval and re-evaluating approvability for e6abd98

[macroscopeapp]

This PR only adds documentation to an existing ADR file (architecture decision record). No runtime code is modified - the changes are ASCII diagrams and explanatory text about internal state machines. Documentation-only changes don't impact runtime behavior and are safe to approve.