# Phase 2 + Phase 3 — Progress Tracker (2026-07-28 update)

**Companion to:** [2026-07-22-rollout-plan.md](./2026-07-22-rollout-plan.md) (design + sequencing)
**Source plans:** [phase2-analytics](./2026-07-22-phase2-analytics.md) · [phase3-offboarding](./2026-07-22-phase3-offboarding.md)
**Purpose:** Live status of what's actually been built on the feature branches, what's uncommitted, and what's blocking each phase from merging to dev.

> **How to use this doc:** update the status table + per-phase uncommitted-file list at the end of every work session. The next session reads this first instead of re-deriving the state from `git log`.

---

## 0. One-line status (2026-07-28)

| Phase | Owner | Branch | State | Last merge into dev | Pushed to origin? |
|---|---|---|---|---|---|
| **Phase 1** (aux roles + cohorts + assignments) | fchin | `feature/admin-cohorts-2026-07-22` | ✅ Merged (`b75599e`) | b75599e | yes — on `origin/feature/admin-cohorts-2026-07-22` |
| **Phase 2** (analytics dashboard) | Arthur + fchin | `feature/analytics-dashboard-2026-07-22` | ✅ Merged (3 PRs) | b293e84 | **no** — branch has 4 commits ahead of origin |
| **Phase 3** (offboarding workflows) | Craig + fchin | `feature/offboarding-2026-07-22` | ✅ Merged (1 commit, rebased clean) | 43447e2 | **no** — branch has 1 commit ahead of origin |
| Docker rework (side) | fchin | `fix/docker-divergence-2026-07-22` | ✅ Merged | fd1b223 | no |
| Seed modularization (side) | fchin | `refactor/seed-modularization-2026-07-22` | ✅ Merged | 07c8182 | no |

**Local dev is now 14 commits ahead of origin/dev.** All three phases plus the two side branches are merged locally; none are pushed.

> **🚨 Push blocker reminder:** do not promote `dev → main` until at least one of (a) full Playwright pass on the analytics + offboarding E2E specs, (b) manual smoke against the seed for the role-gated analytics tabs. Per AGENTS.md, `main` MUST always be deployable.

---

## 1. Phase 2 — Analytics Dashboard (Arthur + fchin)

**Worktree:** `.worktrees/analytics-dashboard-2026-07-22/`
**Branch tip:** `fded4d7 test(analytics): E2E coverage for /reports dashboard + changelog`
**State:** merged to dev at `b293e84`. Worktree is clean.

### What landed

3 PRs in this order on the branch:
1. `9b73ddb` feat(reports): restructure /api/reports/kpis to nested shape + add streaming /export
2. `e27e947` feat(analytics): full rewrite of /reports UI — 5 tabs, KpiTile, FilterBar, DrilldownModal
3. `fded4d7` test(analytics): E2E coverage for /reports dashboard + changelog

Files touched:
- `server/src/controllers/reports.controller.js` (372-line change: nested KPIs, role-scoped data, new streaming `/export?type=` endpoint)
- `client/src/pages/admin/Reports.tsx` (full rewrite to use new components + nested KPI shape)
- `client/src/components/KpiTile.tsx` (new)
- `client/src/components/FilterBar.tsx` (new)
- `client/src/components/DrilldownModal.tsx` (new)
- `client/src/store/reports.ts` (new Zustand slice)
- `client/e2e/analytics.spec.ts` (new — 197 lines)
- `.harness/changelogs/2026-07-22-analytics-dashboard.md` (new)

### Plan doc cross-walk

All §Approach items landed. Verification recipe in the changelog:
```bash
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:3001/api/reports/kpis | jq .
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://localhost:3001/api/reports/export?type=overview&format=csv" | head -2
cd client && npx playwright test e2e/analytics.spec.ts
```

### Outstanding items for the next session

- [ ] **Verify the analytics E2E spec passes against the seed.** The spec is written and committed but not yet exercised end-to-end. The donor seed has minimal data (just role accounts, no classes / grades / fees), so some assertions may need a richer seed or skip-clauses.
- [ ] **Push the merged branch to origin** so CI / Arthur's teammates can pull it.
- [ ] **Audit / verify the legacy `/api/reports/export/:type` route** — still wired but undocumented. Add a comment or deprecate.

---

## 2. Phase 3 — Offboarding Workflows (Craig + fchin)

**Worktree:** `.worktrees/offboarding-workflow/`
**Branch tip:** `b939637 feat(offboarding): Phase 3 student + staff offboarding workflows` (rebased onto post-Phase-2 dev)
**State:** merged to dev at `43447e2`. Worktree is clean.

### What landed

Craig shipped the entire Phase 3 plan in a single feature commit (the plan doc's 4-PR breakdown is preserved in the changelog for traceability). Rebase onto post-Phase-2 dev was conflict-free.

Files touched (per the commit message + `git show --stat b939637`):
- `server/src/database/migrations/knex/2026072300000010_offboarding.js` (73 lines)
- `server/src/services/OffboardingService.js` (433 lines — the 11-step pipeline)
- `server/src/controllers/offboarding.controller.js` (525 lines — 10 endpoints)
- `server/src/index.js` (controller registered)
- `server/src/services/AuditService.js` (4 lines — accepts passed-in db handle)
- `server/src/services/SyncEngine.js` (2 lines — tablesToSync append)
- `server/tests/offboardingService.test.js` (267 lines — 6 unit tests incl. transaction rollback)
- `client/src/store/offboarding.ts` (181 lines)
- `client/src/pages/admin/Offboarding.tsx` (353 lines)
- `client/src/pages/admin/OffboardingWizard.tsx` (630 lines — 4-step wizard)
- `client/src/pages/admin/Alumni.tsx` (191 lines)
- `client/src/components/OffboardingStepRow.tsx` (90 lines)
- `client/src/components/OverrideModal.tsx` (103 lines)
- `client/src/pages/admin/Users.tsx` (Offboard button)
- `client/src/pages/admin/HRManagement.tsx` (Offboard button)
- `client/src/pages/hr/StaffDirectory.tsx` (Offboard button)
- `client/src/App.tsx` (routes)
- `client/src/components/Nav.tsx` (nav entries)
- `client/e2e/offboarding.spec.ts` (222 lines — 4 e2e specs)
- `.harness/changelogs/2026-07-22-offboarding.md` (71 lines)

### Plan doc cross-walk

All §Approach items landed. Verification recipe per the changelog:
```bash
cd server && npm run db:init  # applies the new offboarding migration
node server/tests/offboardingService.test.js  # unit tests incl. rollback
cd client && npx playwright test e2e/offboarding.spec.ts
```

### Outstanding items for the next session

- [ ] **Verify the offboarding unit tests pass.** `server/tests/offboardingService.test.js` is hand-rolled (no test framework installed). Run it manually.
- [ ] **Verify the offboarding E2E spec passes against the seed.** Requires the donor seed to have at least 1 student and 1 teacher with outstanding fees / payroll to exercise the fee/payroll block flows.
- [ ] **Push the merged branch to origin.**

---

## 3. Cross-cutting work (everyone's affected)

All three phases are now in dev. The cross-cutting-file conflict matrix is resolved. Below is the cumulative state of the shared files:

| File | Phase 1 (b75599e) | Phase 2 (b293e84) | Phase 3 (43447e2) | Side branches |
|---|---|---|---|---|
| `client/src/App.tsx` | +4 cohort routes + ~18 lines of new components | no change | +3 offboarding routes + nav | — |
| `client/src/components/Nav.tsx` | +3 cohort entries | +1 reports entry (already existed) | +2 offboarding entries | — |
| `server/src/index.js` | +cohorts + userRoles controllers | no change | +offboarding controller | — |
| `server/src/services/SyncEngine.js` | +4 cohort tables + user_roles | no change | +2 offboarding tables | — |
| `server/src/database/seeds/demo.js` | not touched | not touched | not touched | modularized by refactor/seed-modularization-2026-07-22 |
| `server/src/controllers/reports.controller.js` | no change | restructure + new export endpoint | no change | — |

No outstanding merge conflicts. The Phase 2 and Phase 3 PRs are both safely in `dev`.

---

## 4. Action queue (fchin, in order)

1. [ ] **Run the analytics E2E spec against a fresh seed.** See Phase 2 outstanding items.
2. [ ] **Run the offboarding unit + E2E specs against a fresh seed.** See Phase 3 outstanding items.
3. [ ] **Address any new TS warnings introduced** by Phase 2 (Reports.tsx rewrite) and Phase 3 (Offboarding*.tsx, Alumni.tsx, etc.). Pre-PR baseline had ~20 pre-existing TS errors; check the delta.
4. [ ] **Push local dev to origin.** 14 commits ahead of `origin/dev`. Includes the docker fix, seed mod, all three phases. Verify with `git log --oneline origin/dev..HEAD` first.
5. [ ] **Promote dev → main** after all 4 tests above pass and `main` is green. Per Git Flow, no direct commits to main; the merge must be a regular `--no-ff` merge.

---

## 5. Quick state-of-play commands

```bash
# What's on local dev but not pushed to origin?
git log --oneline origin/dev..HEAD

# Per-worktree status
for wt in feat-auto-20260722-ed7cf80c analytics-dashboard-2026-07-22 offboarding-workflow tracker-update-2026-07-28; do
  echo "=== $wt ==="
  git -C .worktrees/$wt status -s
done

# Phase 2 commit chain
git -C .worktrees/analytics-dashboard-2026-07-22 log --oneline -5

# Phase 3 commit chain
git -C .worktrees/offboarding-workflow log --oneline -5
```

---

## 6. Changelog of THIS tracker

- 2026-07-27 — first version, written by fchin (orchestrator) at the end of the Phase 1 PR 2+3 merge session. Captures the state immediately after Phase 1 landed on origin/dev.
- 2026-07-28 — second version. All three phases merged to local dev. 14 commits ahead of origin/dev. Phase 2 was 3 PRs (backend, frontend, E2E + changelog); Phase 3 was Craig's single commit rebased cleanly onto post-Phase-2 dev. Outstanding: run the E2E + unit specs against the seed, push to origin, then promote dev → main.