Continuation Protocol - Swift iOS Project

Continuation Protocol - Swift iOS Project

Document ID: GOV-CONT-001
Version: 2.0.0
Created: 2026-01-04
Updated: 2026-01-13
Status: Active
Platform: iOS (Swift/SwiftUI)
Owner: Lead Developer

Related Documents:
- [Master-Checklist](../03-Checklists/Master-Checklist.md) - Task Tracking
- [Entry-Point-Decision](../00-Overview/Entry-Point-Decision.md) - Project Context
- Master Implementation Prompt (`/CLAUDE.md`) - Governance Framework

---

Table of Contents

1. [Overview](#1-overview)
2. [Continuation Anchor System](#2-continuation-anchor-system)
3. [Session Recovery Protocol](#3-session-recovery-protocol)
4. [Source of Truth Registry](#4-source-of-truth-registry)
5. [Checkpoint System](#5-checkpoint-system)
6. [Handoff Procedures](#6-handoff-procedures)
7. [Context Recovery](#7-context-recovery)
8. [Progress Tracking](#8-progress-tracking)

---

1. Overview

1.1 Purpose

This document defines the continuation protocol for the Milk Men iOS project, ensuring work can resume seamlessly across:
- Session boundaries (token limits, natural pauses)
- Developer handoffs (team member changes)
- Time gaps (days or weeks between work sessions)
- Context loss (memory limitations, summarization)

1.2 Continuation Philosophy

The Project Must Be Self-Documenting:
- Any developer (human or AI) can pick up where work left off
- No reliance on memory or conversation history
- All context is written down and accessible
- Progress is always traceable to a specific checkpoint

Deterministic Resumption:
- Reading the continuation anchor should restore full context
- Next action should be unambiguous
- No guesswork or interpretation required

1.3 Key Principles

1. Written > Memory: Never rely on memory; always write down state
2. Snapshots > Deltas: Store complete state, not just changes
3. Explicit > Implicit: Make all context explicit
4. Traceable > Assumed: Every action traces to a source document

---

2. Continuation Anchor System

2.1 Continuation Anchor Format

Definition: A structured summary of current project state that enables instant resumption

Location: Top of this document (updated after each major checkpoint)

Format:

## CONTINUATION ANCHOR

**Last Updated:** [ISO 8601 timestamp]
**Updated By:** [Developer name or AI session ID]

### Current State
- **Phase:** [Phase number and name]
- **Last Completed:** [Last completed task from checklist]
- **Next Active:** [Next pending task from checklist]
- **Active Files:** [Files currently being worked on]

### Confidence Assessment
- **Overall Confidence:** [Low / Medium / High]
- **Open Uncertainties:** [List or "None"]
- **Blocked By:** [Dependencies or "None"]

### Quick Resume
**To resume work:**
1. [First action to take]
2. [Second action to take]
3. [Reference to detailed context if needed]

2.2 Current Continuation Anchor

CONTINUATION ANCHOR

Last Updated: 2026-01-13T12:00:00Z
Updated By: Development Team

### Current State
- Phase: Phase 5 - Routes & Visit Management
- Last Completed: Core services and views implemented
- Next Active: Team management features (Phase 7)
- Active Files:
- `Milk Men/Services/Routes/DynamicRouteService.swift`
- `Milk Men/Views/Routes/RouteListView.swift`

### Confidence Assessment
- Overall Confidence: HIGH
- Open Uncertainties: None
- Blocked By: None

### Quick Resume
To resume work:
1. Review current phase status in Master-Checklist.md
2. Continue implementing next pending feature
3. Run XCTest suite to verify no regressions

---

2.3 When to Update Continuation Anchor

After Every Major Checkpoint:
- Phase completion
- Major deliverable creation
- End of work session
- Before handing off to another developer
- After resolving a blocker

Update Frequency:
- Minimum: End of each day
- Recommended: After each completed checklist item
- Critical: Before long gaps (weekends, holidays)

---

3. Session Recovery Protocol

3.1 Recovery Triggers

When to Execute Recovery Protocol:
- Starting a new work session (after >1 hour gap)
- Resuming after token limit reached
- New developer joining project
- AI session restarted
- After conversation summarization

3.2 Recovery Steps

Step 1: Read Continuation Anchor (30 seconds)

1. Open this document
2. Read "Current State" section
3. Note last completed task
4. Note next active task
5. Check for blockers

Step 2: Verify Source of Truth (1 minute)

1. Open Master-Checklist.md
2. Verify last completed items match continuation anchor
3. Verify next pending item matches continuation anchor
4. If mismatch: Update continuation anchor to match checklist (checklist is source of truth)

Step 3: Load Context (2 minutes)

1. Read next pending task description
2. Read related phase document (if applicable)
3. Review any open uncertainties
4. Identify dependencies

Step 4: Confirm Readiness (30 seconds)

Questions to answer before proceeding:
- Do I understand what needs to be done next? (Yes/No)
- Do I have all required dependencies? (Yes/No)
- Am I confident in the approach? (Low/Medium/High)

If any answer is uncertain, escalate to Decision-Log

Step 5: Begin Work (action)

1. Update todo list to mark next task as "in_progress"
2. Proceed with implementation
3. Update continuation anchor when complete

3.3 Recovery Example

Scenario: AI session restarts mid-Phase 5

Recovery:

1. Read Continuation Anchor:
   - Phase: Phase 5 - Routes & Visit Management
   - Last Completed: RouteService implementation
   - Next Active: Create RouteDetailView

2. Verify Master-Checklist:
   - Task 5.A.01: RouteService (completed)
   - Task 5.B.01: RouteDetailView (in progress)

3. Load Context:
   - Read Phase-05.md section 5.B (Route Views)
   - Review deliverables: RouteDetailView requirements
   - No blockers

4. Confirm Readiness:
   - Understand task: Yes (create detail view with map and stops)
   - Dependencies: RouteService exists (verified)
   - Confidence: High

5. Begin Work:
   - Mark Task 5.B.01 as in_progress
   - Create RouteDetailView.swift

---

4. Source of Truth Registry

4.1 Document Hierarchy

Canonical Documents (Single Source of Truth):

Derived Documents (Reference Only):

4.2 Conflict Resolution

If documents conflict:

1. Checklist vs Continuation Anchor: Checklist wins (checklist is source of truth for tasks)
2. Charter vs Phase Doc: Charter wins (charter defines scope)
3. Glossary vs Code: Glossary wins (code must match definitions)
4. Assumptions vs Reality: Reality wins (update assumptions document)

Example:

Conflict: Continuation anchor says "Phase 5 complete" but checklist shows pending items

Resolution:
1. Checklist is source of truth
2. Update continuation anchor to match checklist
3. Log discrepancy in Decision-Log
4. Continue from checklist state

---

5. Checkpoint System

5.1 Checkpoint Types

Micro Checkpoint (Per Task):
- Trigger: Checklist item completed
- Action: Mark item complete, update todo list
- Duration: <1 minute

Meso Checkpoint (Per Feature):
- Trigger: Feature group completed (e.g., all route views)
- Action: Update phase document status, validate deliverables
- Duration: 5 minutes

Macro Checkpoint (Per Phase):
- Trigger: Phase completed
- Action: Update continuation anchor, phase review, validation against success criteria
- Duration: 30 minutes

5.2 Checkpoint Procedure

Micro Checkpoint:

# 1. Verify task complete
# 2. Update Master-Checklist.md
- [x] Task 5.B.01: RouteDetailView

# 3. Update todo list (via TodoWrite tool)
# 4. Commit to git (if appropriate)
git add "Milk Men/Views/Routes/RouteDetailView.swift"
git commit -m "feat: implement RouteDetailView

- Add MapKit integration for route display
- Add stop markers with visit status
- Add navigation to turn-by-turn directions
- Add pull-to-refresh for route updates

Ref: Phase-05.md, Task 5.B.01"

# 5. Proceed to next task

Meso Checkpoint:

# 1. Validate feature complete
All route views implemented:
- RouteListView
- RouteDetailView
- RouteMapView
- RoutePlanningView

# 2. Run tests
swift test --filter RouteTests

# 3. Update phase document status
Phase-05.md:
- Status: Feature 5.B (Route Views) → COMPLETE

# 4. Update continuation anchor
- Last Completed: Feature 5.B (all route views)
- Next Active: Feature 5.C (Visit views)

Macro Checkpoint:

# 1. Validate phase complete
Phase 5 Checklist:
- 5.A: Route Services
- 5.B: Route Views
- 5.C: Visit Services
- 5.D: Visit Views

# 2. Validate deliverables
All Phase 5 deliverables exist:
- RouteService.swift
- DynamicRouteService.swift
- VisitService.swift
- RouteListView.swift
- RouteDetailView.swift
- VisitCheckinView.swift

# 3. Run comprehensive tests
swift test --filter "Route|Visit"

# 4. Update continuation anchor
Phase: Phase 5 → COMPLETE
Next Phase: Phase 6 (Pipeline)

# 5. Phase review meeting
Attendees: Dev Lead, QA Lead, Product Owner
Agenda:
- Review Phase 5 deliverables
- Demo route features
- Identify any issues
- Sign off on Phase 5 completion
- Plan Phase 6 kickoff

5.3 Checkpoint Artifacts

Every checkpoint produces:
- Updated Master-Checklist.md
- Updated todo list (via TodoWrite)
- Git commit (for code changes)
- Updated continuation anchor (for macro checkpoints)
- Optional: Phase review notes (for macro checkpoints)

---

6. Handoff Procedures

6.1 Developer Handoff

Scenario: Developer A completes work, Developer B continues

Handoff Checklist:

- [ ] Commit all work:

  git status  # Ensure no uncommitted changes
  git add .
  git commit -m "Checkpoint: [description]"
  git push origin [branch]

• [ ] Update Master-Checklist:
• Mark completed tasks
• Note any in-progress tasks (with details)
• Flag any blockers

• [ ] Update Continuation Anchor:
• Set "Last Completed" to final task
• Set "Next Active" to next pending task
• Note any open uncertainties
• Document any blockers

- [ ] Create Handoff Notes:

  # Handoff Notes - [Date]

  **From:** Developer A
  **To:** Developer B

  ## Work Completed
  - [Task 1]
  - [Task 2]

  ## Work In Progress
  - [Task X]: [Status, what's left]

  ## Blockers
  - [Blocker 1]: [Description, who can unblock]

  ## Context Notes
  - [Any non-obvious context Developer B should know]

  ## Next Steps
  1. [First thing Developer B should do]
  2. [Second thing]

• [ ] 30-Minute Knowledge Transfer Call:
• Walk through handoff notes
• Demo work in progress
• Answer questions
• Confirm Developer B understands next steps

6.2 AI-to-AI Handoff

Scenario: AI session ends (token limit), new session begins

Handoff:

# AI Session Handoff

**Previous Session ID:** [session-id]
**New Session ID:** [new session]
**Handoff Time:** 2026-01-13T12:00:00Z

## State Snapshot
- Phase: Phase 5 (Routes & Visits)
- Last Completed: RouteDetailView
- Next Active: VisitCheckinView
- Files Modified This Session:
  - Milk Men/Views/Routes/RouteDetailView.swift (created)
  - Milk Men/Services/Routes/RouteService.swift (updated)

## Recovery Instructions
1. Read this document (Continuation-Protocol.md)
2. Read continuation anchor (above)
3. Complete remaining visit views:
   - VisitCheckinView.swift
   - VisitHistoryView.swift
4. Update Master-Checklist
5. Mark todo as complete

## Context Preserved In
- Master-Checklist.md (authoritative task list)
- Todo list (in-progress tracker)
- This document (continuation anchor)
- Git commits (code changes)

6.3 Team Handoff

Scenario: Entire team changes (consultants → in-house)

Handoff Package:

1. Documentation Bundle:
- All Documentation/Implementation/ files
- README.md with navigation
- Master-Checklist.md with status

2. Codebase Snapshot:
- Git tag: `handoff-YYYY-MM-DD`
- README with setup instructions
- All Xcode schemes configured

3. **Access [sensitive field redacted]
- Supabase project access
- App Store Connect access
- Apple Developer account access
- GitHub repository access

4. Knowledge Transfer Sessions:
- Session 1 (2 hours): Project overview, architecture
- Session 2 (2 hours): Codebase walkthrough
- Session 3 (1 hour): Deployment process
- Session 4 (1 hour): Q&A, next steps

5. Ongoing Support:
- 30-day support period
- Email support (response <24 hours)
- Weekly check-in calls

---

7. Context Recovery

7.1 Context Loss Scenarios

Scenario 1: Conversation Summarized
- Problem: AI context compressed, details lost
- Recovery: Read continuation anchor, Master-Checklist, last 5 git commits
- Time: 5 minutes

Scenario 2: Long Time Gap (Weeks)
- Problem: Forgot project details
- Recovery: Re-read Charter, Entry-Point-Decision, current phase doc
- Time: 30 minutes

Scenario 3: New Team Member
- Problem: Zero project knowledge
- Recovery: Full onboarding (documentation + sessions)
- Time: 8 hours (spread over 1 week)

7.2 Context Recovery Checklist

Quick Recovery (5 minutes):
- [ ] Read continuation anchor
- [ ] Read Master-Checklist (last 10 completed, next 5 pending)
- [ ] Read next task description in detail
- [ ] Check for blockers
- [ ] Begin work

Medium Recovery (30 minutes):
- [ ] Quick recovery steps
- [ ] Read current phase document (Phase-XX.md)
- [ ] Read related algorithm docs (if applicable)
- [ ] Review last 10 git commits
- [ ] Review open issues/PRs (if any)

Deep Recovery (2 hours):
- [ ] Medium recovery steps
- [ ] Read Charter (understand success criteria)
- [ ] Read Entry-Point-Decision (understand project context)
- [ ] Read Glossary (understand terminology)
- [ ] Read Assumptions-Invariants (understand constraints)
- [ ] Review all completed phases
- [ ] Review test results (if Phase 10+)

7.3 Context Refresh Protocol

Before Starting Work Each Day:

# Daily Context Refresh (5 minutes)

## 1. Check Continuation Anchor
- What phase are we in?
- What was last completed?
- What's next?

## 2. Check Master-Checklist
- Verify continuation anchor matches checklist
- Note any changes since yesterday
- Identify any new blockers

## 3. Check Todo List
- What's marked as in_progress?
- Any stale items (need to complete or defer)?

## 4. Check Communication
- Any emails, Slack messages, PRs?
- Any decisions made offline?
- Any blockers unblocked?

## 5. Plan Today's Work
- What will I complete today?
- Any dependencies to resolve?
- Any meetings or reviews?

## 6. Begin Work
- Update todo (mark as in_progress)
- Focus on one task at a time
- Update checklist as tasks complete

---

8. Progress Tracking

8.1 Progress Metrics

Overall Progress:

Total Phases: 11
Completed: [X]
In Progress: [Y]
Not Started: [Z]
Overall Completion: [X/11] = [%]

Current Phase Progress:

Phase [X]: [Name]
Total Tasks: [N]
Completed: [M]
Phase Completion: [M/N] = [%]

8.2 Progress Reporting

Weekly Progress Report:

# Weekly Progress Report - Week [X]

**Date:** [Start] - [End]
**Reporter:** [Name]

## Summary
[One paragraph summary of week's work]

## Completed This Week
- [Task 1]
- [Task 2]
- [Task 3]

## In Progress
- [Task X]: [Status, blockers]

## Planned Next Week
- [Task A]
- [Task B]

## Blockers
- [Blocker 1]: [Description, action needed]

## Metrics
- Tasks Completed: [N]
- Overall Progress: [%]
- On Track: [Yes/No, explanation]

Phase Completion Report:

# Phase Completion Report - Phase [X]

**Phase:** [Name]
**Duration:** [Actual weeks] (Planned: [X] weeks)
**Completed:** [Date]

## Deliverables
All deliverables completed:
- [Deliverable 1]
- [Deliverable 2]

## Success Criteria
All success criteria met:
- [Criterion 1]
- [Criterion 2]

## Challenges
[Any challenges encountered and how resolved]

## Learnings
[What did we learn? What would we do differently?]

## Next Phase
Phase [X+1]: [Name]
Planned Start: [Date]

8.3 Milestone Tracking

Major Milestones:

Milestone Alert System:

If milestone is >1 week late:
1. Assess root cause (scope creep, underestimated, blockers)
2. Re-estimate remaining work
3. Adjust timeline or reduce scope
4. Communicate to stakeholders
5. Document in Decision-Log

---

Appendix A: Continuation Anchor Template

## CONTINUATION ANCHOR

**Last Updated:** [ISO timestamp]
**Updated By:** [Name/Session ID]

### Current State
- **Phase:** [Phase X - Name]
- **Last Completed:** [Task ID and description]
- **Next Active:** [Task ID and description]
- **Active Files:** [List of files being worked on]

### Confidence Assessment
- **Overall Confidence:** [Low / Medium / High]
- **Open Uncertainties:**
  - [Uncertainty 1]
  - [Uncertainty 2]
  - Or "None"
- **Blocked By:**
  - [Blocker 1]
  - [Blocker 2]
  - Or "None"

### Quick Resume
**To resume work:**
1. [Action 1]
2. [Action 2]
3. [Reference to detailed context]

---

Document Version History:

---

This protocol ensures the Milk Men iOS project can be resumed seamlessly at any time, by any developer (human or AI), without context loss.