# Epic 0 Retrospective — Foundation Migration & Infrastructure Setup

**Date:** 2026-03-13
**Facilitator:** Bob (Scrum Master)
**Epic:** 0 — Foundation Migration & Infrastructure Setup
**Status:** Complete (5/5 stories done)
**First Retrospective:** Yes (no previous retro to reference)

---

## Team Participants

- Bob (Scrum Master) — Facilitator
- John (Product Manager) — Product perspective
- Winston (Architect) — Architecture & decisions
- Amelia (Developer) — Implementation insights
- Quinn (QA Engineer) — Quality perspective
- Saad (Project Lead) — Direction & decisions

---

## Epic Summary & Metrics

**Delivery:**

- Stories Completed: 5/5 (100%)
- Test Suite Growth: ~40 → 93 tests (240 assertions)
- Code Review Findings: 24 total (5 critical/high, resolved)
- Blockers: 0
- Production Incidents: 0

**Stories Delivered:**

| Story | Title | Key Outcome |
|-------|-------|-------------|
| 0.1 | Rename Folders to Declarations in Database | Migration with FK constraints, indexes, rollback support |
| 0.2 | Rename Folders to Declarations in Backend | 40+ files renamed — models, controllers, enums, mail, middleware, routes |
| 0.3 | Rename Folders to Declarations in Frontend | Vue pages, components, Wayfinder routes, user-facing text (FR→"Déclarations") |
| 0.4 | Configure Redis for Cache, Queue & Sessions | Redis service added, triple-duty pattern (cache/queue/sessions), queue:work optimized |
| 0.5 | Foundation Database Migrations & Status Flow | Permissions JSON column, archived_at, DeclarationStatus enum (5 values), DeclarationObserver |

**Infrastructure Changes:**

- PHP 8.2 → 8.4 upgrade in Docker
- Redis service added to compose.yaml
- phpunit.xml configured for SQLite in-memory testing
- queue:listen → queue:work with --tries=3 --timeout=30

---

## What Went Well

1. **Layered migration strategy worked perfectly.** DB → Backend → Frontend ordering gave each story a clean boundary. Each layer could be verified independently before proceeding.

2. **Exceptionally detailed story specs.** File rename mapping tables, code skeletons, migration order-of-operations, and variable rename patterns eliminated guesswork and reduced implementation errors significantly.

3. **Code review caught real bugs.** 24 findings across 5 stories, including 2 critical issues in Story 0.5:
   - ConfirmController was setting status to `termine` instead of `en_cours` (would have broken status flow silently)
   - DeclarationMessageController needed an intermediate `created → en_cours` transition before `en_attente_client`

4. **Test suite more than doubled.** Grew from ~40 to 93 tests covering migration schemas, status flow transitions, auto-archive behavior, Redis connectivity, and declaration CRUD.

5. **Zero blockers throughout the epic.** No external dependencies, no blocking issues, clean execution from start to finish.

---

## What Didn't Go Well

1. **Documentation gap for user-directed changes.** When the project lead directed work outside story acceptance criteria (e.g., cosmetic cleanups), it wasn't clearly attributed in completion notes. This caused false flags during code reviews. Solution: explicitly note user-directed changes with `[User-directed]` tag.

2. **SQLite/MySQL driver differences.** Story 0.1 hit issues with `dropForeign('constraint_name')` syntax not working on SQLite. Had to switch to column array syntax `dropForeign(['column_name'])`. Migration step ordering was also fragile across drivers.

3. **Infrastructure prerequisites bundled into feature stories.** Story 0.1 included PHP 8.2→8.4 upgrade and phpunit.xml DB config changes — necessary for running tests but outside the rename story's scope.

4. **Sprint status tracking not kept current.** Epic 0 still shows `in-progress` in sprint-status.yaml despite all 5 stories being `done`. Status files must be updated when epics complete.

5. **Pre-existing Redis test failures.** 2 RedisConnectivityTest failures in the test environment (queue/session config) create noise in test output. Not introduced by Epic 0 but not resolved either.

---

## Key Insights & Lessons Learned

1. **Detailed story specs pay off massively.** The file rename mapping tables, code skeletons, and order-of-operations documentation in Stories 0.1–0.3 eliminated guesswork. Keep this level of detail for complex stories.

2. **Code review catches real bugs, not just style issues.** The 2 critical findings in Story 0.5 would have caused silent data integrity issues. Always run code review.

3. **Layered migration is the right pattern.** DB → Backend → Frontend for cross-stack renames. Each layer had a clean boundary and could be verified independently.

4. **Dual-database testing (MySQL prod + SQLite tests) requires awareness.** Migration syntax must be cross-driver compatible. Always use column array syntax for `dropForeign()`.

5. **Sprint status tracking is a process, not an afterthought.** Status files must stay current — stale status erodes trust in the tracking system.

---

## Action Items

| # | Action | Owner | Priority | Success Criteria |
|---|--------|-------|----------|------------------|
| A1 | Fix sprint-status.yaml: set `epic-0` to `done` | Saad | Immediate | Epic status reads `done` |
| A2 | Establish process: when last story is marked `done`, epic status MUST be updated in same session | Bob (SM) | High | No stale epic statuses going forward |
| A3 | User-directed work outside story ACs should be noted as `[User-directed]` in Completion Notes | Amelia (Dev) | Medium | Reviews don't false-flag user-directed changes |
| A4 | Resolve pre-existing Redis test failures — fix test env config or skip conditionally | Quinn (QA) | Medium | Zero noise in test output |
| A5 | Always use column array syntax for `dropForeign()` in migrations for SQLite/MySQL compatibility | Winston (Arch) | Ongoing | No cross-driver migration failures |

---

## Next Epic Preview — Epic 1: Team Management & Permission System

**Dependencies on Epic 0:**

- `permissions` JSON column on `workspace_user` (Story 0.5) — Epic 1 builds permission UI on top
- Declaration model scopes and status flow — used in role-based access enforcement (Story 1.5)
- Redis infrastructure (Story 0.4) — caching for dashboard in Epic 2

**Stories Planned:** 6 (1.1–1.6)

| Story | Title | Key Focus |
|-------|-------|-----------|
| 1.1 | Permission Configuration & Controller Traits | `HasWorkspaceScope`, `AuthorizesPermissions` traits, `config/permissions.php` |
| 1.2 | Team Management Page — View & Invite Members | Team index page, invite form, workspace-scoped member list |
| 1.3 | Role Assignment & Member Removal | Change role, remove member, activity log |
| 1.4 | Manager Permission Toggle Matrix | Per-manager permission toggles UI |
| 1.5 | Role-Based Access Enforcement Across Views | Workers see only assigned items, Managers/Owners see all |
| 1.6 | Workspace Switching for Multi-Workspace Owners | Switch between owned workspaces |

**Critical Path:** Story 1.1 is a hard dependency for all other stories — traits must be correct before any controller uses them.

**Risks:**

- Story 1.1 is foundational — if wrong, everything downstream breaks
- First time building new Vue pages from scratch (not just renaming) — expect learning curve
- Permission toggle matrix (Story 1.4) has complex UI interactions

**Significant Changes Required:** None — Epic 0 discoveries do not change Epic 1's plan.

---

## Preparation Tasks for Epic 1

**Critical (before epic starts):**

- [ ] Update `epic-0` status to `done` in sprint-status.yaml — Owner: Saad
- [ ] Commit all Epic 0 work (Stories 0.2–0.5 uncommitted) — Owner: Saad

**Parallel (during early stories):**

- [ ] Resolve Redis test environment failures — Owner: Quinn (QA)

**Nice-to-have:**

- [ ] Document SQLite `dropForeign()` pattern in project-context.md

---

## Readiness Assessment

| Area | Status | Notes |
|------|--------|-------|
| Testing & Quality | Ready | 93 tests passing, manual testing confirmed |
| Deployment | Local only | Production deployment is Epic 7 scope |
| Technical Health | Stable | No concerns raised |
| Unresolved Blockers | None | — |
| Stakeholder Acceptance | N/A | Infrastructure epic, no external stakeholders |

**Verdict:** Epic 0 is complete. Team is clear to proceed with Epic 1 after completing critical preparation tasks.

---

## Next Steps

1. Complete critical preparation tasks (update sprint status, commit Epic 0 work)
2. Review action items in next standup
3. Begin Epic 1 — start with Story 1.1 (create story via SM agent)

---

*Retrospective facilitated by Bob (Scrum Master) on 2026-03-13*