Mockup Implementation Plan

QuranFlow Admin Mockup — Implementation Plan

Approach

Build screen-by-screen in dependency order. Each phase produces working, navigable screens committed to git. Complex screens first (they set patterns), simple screens follow fast.

v1 vs v2: Phases 0–13 below describe the completed v1 mockup and are preserved as a historical reference baseline — do not modify them. The v2 redesign (driven by docs/admin-spec-v2/ and decision records in docs/v2-review/) is a parallel build that lives alongside v1 under /v2/* in the same repo (Option C). All v2 routes, pages, and layout components are namespaced under v2/ paths and src/components/v2/ / src/pages/v2/. v2 build phases are documented in the "v2 Build Phases" section below the v1 phases.

Execution Loop

Each phase below is one iteration of this loop.

Standard Loop (every phase)

1. Read spec — Read the spec section(s) listed in the phase. Full paths are provided in each phase header.
2. Plan components — Before writing code, identify what UI elements the screen needs (tables, cards, modals, tabs, etc.) and search for matching shadcn components:
   • bunx --bun shadcn@latest search -q "..." — find components by keyword
   • bunx --bun shadcn@latest docs <component> — read docs/examples for each component you'll use
   • Use Explore subagents in parallel if the phase uses 3+ new components — one agent per component, each returns docs URLs and API patterns. This avoids serial CLI round-trips.
3. Install — Run the phase's install block (shadcn components, dependencies). Add any additional components discovered in step 2.
4. Build — Build the screen(s) listed in the phase. Use TodoWrite to track items when the phase has 4+ build items.
5. Simplify — Run /simplify on the diff. This launches 3 parallel review agents (reuse, quality, efficiency) and fixes any issues found.
6. Verify — Run all checks:
   • bun run build — no type errors
   • bun run lint — no lint violations
   • Code review against spec — re-read the spec section referenced in the phase. Confirm every column, filter, action, and state listed in the spec is present in the code.
   • Smoke test (pattern-setting phases only: 0, 1, 3, 4) — run bun run dev, open in browser, confirm the page renders and basic navigation works.
7. Commit — Use /commit to create a commit for the phase.

Additional steps for pattern-setting phases (0, 1, 3, 4)

These phases establish patterns that every subsequent phase copies. Errors here propagate everywhere.

• Extra review — After simplify, before committing: re-read all shared components and layout files touched in this phase. Check that naming, prop patterns, and file structure are ones you'd want replicated 30+ times. Fix anything you wouldn't want copied.

Additional steps for complex phases (4, 6, 10)

Student Detail (6 tabs), Semester Hub (Close Workflow), and Billing (6 screens with Stripe data) are high-complexity.

• Think through layout — Before building (before step 4), spend time reasoning about tab layout, data flow between tabs, and interaction patterns. No formal document needed — just think through: what data does each tab show, how do tabs share entity context, what cross-links exist, what states need handling. Write brief notes as comments in the page file if helpful.

Parallel execution for repetitive phases (7, 8, 11, 12)

Content (6 list screens), Scheduling (5 screens), Reporting (5 screens), and Admin (5 screens) are independent screens following established patterns.

• Parallelize with subagents — Launch parallel general-purpose subagents, one per independent screen. Each agent receives: (a) the relevant spec section text, (b) the shared component import paths, (c) the mock data file for that domain, and (d) a reference to an existing list screen (e.g., Students List from Phase 3) as the pattern to follow. Agents build screens independently; results are reviewed together in the simplify step.

Where to use subagents

Loop summary

Design Reference

Principles extracted from Stripe's admin UI (Product Catalog, Billing Overview, Invoices) as structural reference — not to copy visually, but to inform layout decisions per-screen.

• Page hierarchy: Title → contextual navigation → filters → content. Consistent across screens, but the type of contextual navigation (tabs, toggles, segmented controls) should be chosen per-screen based on what data and workflows exist.
• Data density: Tables should be dense and scannable. Inline status badges, no card wrappers around tables. Maximize information per row.
• Filter chips: When filters are applied, show them as removable chips below the filter bar (e.g., "Status: Active ×"). Provides clear affordance for what's filtered.
• Metric cards: Dashboard and Payment Overview use metric cards with trend indicators. Keep compact — value + label + trend arrow, not oversized hero numbers.
• Action placement: Primary actions (Add, Export) right-aligned in page header. Secondary actions in dropdown menus.
• Per-screen filtering: Whether a screen uses horizontal status tabs, toggle buttons, or dropdown filters should be decided when building that screen based on: (a) how many statuses exist, (b) how frequently users switch between them, (c) whether counts per status are useful. Don't default to tabs everywhere.

Phase 0: Shell & Routing -- COMPLETE

Goal: App skeleton — sidebar navigation, routing, page header, breadcrumbs. Every future screen slots into this shell.

Spec reference: docs/admin-spec/01-global-patterns.md Sections 1 (Navigation Shell), 2 (Global Search), 3 (Role-Based Access)

Install:

bun add react-router
bunx --bun shadcn@latest add sidebar-07 breadcrumb scroll-area avatar sonner

sidebar-07 provides the "collapses to icons" sidebar pattern. It installs: sidebar, separator, tooltip, input, skeleton, sheet, use-mobile hook. Theme provider already exists (src/components/theme-provider.tsx).

Build:

• src/components/layout/app-shell.tsx — sidebar + main content area using shadcn Sidebar (sidebar-07 pattern)
• src/components/layout/app-sidebar.tsx — 8+1 domain sidebar with icons per spec Section 1.1, collapsible to icon-only
• src/components/layout/page-header.tsx — title, subtitle, primary action button, breadcrumb
• src/components/layout/breadcrumb-nav.tsx — Domain > Screen > Entity pattern
• src/App.tsx — React Router setup with all routes (pages can be placeholder divs initially)
• Global search bar in sidebar (UI only — no search logic yet)
• Dark mode toggle button in sidebar footer

Routes to define (from docs/admin-spec/00-spec-index.md Section 3 navigation tree):

/                                    → Dashboard
/students                            → Students List
/students/:id                        → Student Detail (tabbed)
/submissions                         → Submissions
/promoted-students                   → Promoted Students
/failed-signups                      → Failed Sign Ups
/semesters                           → Semesters List
/semesters/:id                       → Semester Hub (tabbed)
/welcome-package                     → Welcome Package
/email-management                    → Email Management
/tags                                → Tags
/operations                          → Operations
/content/video-lessons               → Video Lessons
/content/resources                   → Resources
/content/recordings                  → Recordings
/content/tutorials                   → Tutorials
/content/mcq-questions               → MCQ Questions
/content/quizzes                     → Quizzes
/scheduling/calendar                 → Calendar View
/scheduling/live-sessions            → Live Sessions
/scheduling/appointments             → Upcoming Appointments
/scheduling/ta-schedules             → TA Schedules
/scheduling/holidays                 → Holidays
/teachers                            → Teaching Assistants List
/teachers/:id                        → TA Detail (tabbed)
/teacher-criteria                    → Teacher Assignment Criteria
/ta-reports                          → TA Reports
/student-groups                      → Student Groups
/billing/overview                    → Payment Overview
/billing/payments                    → Payments
/billing/plans                       → Payment Plans
/billing/coupons                     → Coupons
/billing/family-plans                → Family Plans
/billing/scholarships                → Scholarships & Deferments
/reporting/student-report            → Student Report
/reporting/referrals                 → Referrals
/reporting/specific-reports          → Specific Reports
/reporting/composition               → Student Composition
/reporting/logs                      → Logs
/admin/admins                        → Admins
/admin/settings                      → Settings
/admin/notifications                 → Notifications
/admin/support-links                 → Support Links
/admin/issue-queue                   → Issue Queue

Verify: Clicking every sidebar item navigates to the correct route. Breadcrumbs render. Sidebar highlights the active section. Collapse to icons works. Dark mode toggle switches theme.

Phase 0.5: Data Model & Mock Data -- COMPLETE

Goal: Complete type definitions and all mock data files. Getting data right before building components prevents rework — every screen consumes this data.

Spec reference: All spec docs in docs/admin-spec/ for column/field definitions. Legacy backend docs at /Users/kamran/Downloads/QuranFlowDocumentationFiles/BackendDocumentation/ for data model reality.

Step A — Update src/data/types.ts (already done):

• Added 7 entities: Assessment, Elective, LiveSession, TaSchedule, Subscription, EmailTemplate, AuditLog
• Extended 5 entities: Student (+country, groupId, groupName, electiveId, practiceTier), Semester (+contentAvailabilityDate, launchPartyDateTime, launchPartyZoomLink, isRegistration), Teacher (+gender, profilePicture), FamilyGroup (+stripeCustomerId), Submission (+assessmentId)
• Added enums: GenderScope, EmailCategory

Step B — Create mock data files (build in dependency order):

Cross-referencing: All mock data must be internally consistent. Student.taId references a real Teacher.id. Submission.studentId references a real Student.id. Dashboard alert counts match the actual data (e.g., students with subscriptionStatus "Failed" = Failed Payments tile count).

Data audit (March 2026): A post-completion audit found and fixed several categories of inconsistencies:

• Student status contradictions: Students with Active status but Cancelled/Paused subscriptions were corrected (Khadijah Noor → Inactive, Layla Mahmoud deferment → Completed)
• Submission count gaps: 14 of 20 students had fewer submissions in submissions.ts than their submissionCount field claimed. Added 54 records to bring all students to full coverage (94 total)
• Group member counts: 4 of 8 groups had memberCount values that didn't match the actual students assigned to them
• Scholarship-billing mismatch: Students with 100% scholarships were showing $199 payments. Fixed to $0 with "Scholarship Full" plan name
• Dashboard accuracy: Alert tile counts and comments updated to match actual data after fixes
• Deferment logic: Students on approved deferment are now excluded from "Behind" status in reporting

Key rule: Every student must have a coherent "story" — their status, subscription, submissions, payments, appointments, and issues must all tell the same narrative. See docs/DATA-AUDIT.md for the full student story matrix.

Verify: bun run build passes. Every data file exports typed arrays. Import a few in a scratch component to confirm no circular deps.

Phase 1: Shared Components -- COMPLETE

Goal: Reusable building blocks that every screen needs. Create once, use everywhere.

Spec reference: docs/admin-spec/01-global-patterns.md Sections 4 (Component Patterns)

Install:

bun add @tanstack/react-table
bunx --bun shadcn@latest add table badge card dialog alert-dialog select dropdown-menu checkbox tabs collapsible pagination

Build shared components:

• src/components/shared/data-table.tsx — wraps shadcn Table + TanStack Table. Supports: column sorting (▲/▼), row hover, row click navigation, checkbox bulk selection, pagination ("1-25 of 342"). Per spec Section 4.1.
• src/components/shared/filter-bar.tsx — search input + dropdown filters + active filter chips with × (removable). Per spec Section 4.2.
• src/components/shared/status-badge.tsx — maps all status strings to badge colors per spec Section 4.3. Single component, one source of truth for all status styling.
• src/components/shared/alert-tile.tsx — icon, count, label, trend, color border, clickable. Per spec Section 4.4.
• src/components/shared/metric-card.tsx — label, value, optional trend. Compact layout. Per spec Section 4.5.
• Empty state — uses shadcn's @shadcn/empty component directly (no custom empty-state.tsx needed). Per spec Section 4.8.
• src/components/shared/confirm-dialog.tsx — standard and destructive variants with optional typed confirmation. Per spec Section 4.6.
• src/components/shared/section-header.tsx — title, optional action link, optional count. Per spec Section 4.12.

Verify: Import shared components into a scratch page. Render a DataTable with student mock data. Render StatusBadges for every status type. Render alert tiles. Confirm visual consistency.

Phase 2: Dashboard -- COMPLETE

Goal: The landing page — operational nerve center with alert tiles, phase prompt, quick actions.

Spec reference: docs/admin-spec/02-dashboard.md (all sections)

Build:

• src/pages/dashboard/index.tsx — three-zone layout per spec Section 1.3
• Phase Prompt Bar — full-width, semester-aware, color-coded by phase (Setup=blue, Active=neutral, Close=amber). Per spec Section 1.4. All 4 states implemented (Setup, Active, Close, NoActive).
• Alert Tiles Grid — 2x3 grid using AlertTile component. 6 tiles per spec Section 1.5 (Failed Payments, TAs Behind, Students Behind, Y2 Appointments, App Issues, Semester Progress).
• Quick Actions row — 4 shortcut buttons per spec Section 1.6.
• States: normal (has alerts), all-clear, no-semester. Per spec Section 1.7. Route wired in App.tsx.

Verify: Dashboard renders with mock alert data. Phase prompt shows "Active" state. Tile clicks navigate to target screens. Quick actions navigate. Skeleton state renders on initial load.

Phase 3: Student Management — Students List -- COMPLETE

Goal: The most-used list screen. Sets the pattern for all other list screens.

Spec reference: docs/admin-spec/03-student-management.md Sections 1-2

Build:

• src/pages/student-management/students.tsx — filter bar + data table + pagination
• Columns per spec Section 2.4: Name, Email, Level, Semester, TA, Status, Subscription, Submissions, Last Submission
• Filters: search (name/email), semester dropdown, level dropdown, status dropdown, subscription status dropdown
• Actions: row click → student detail, "Add Student" button (opens modal shell), bulk export, bulk deactivate
• Add Student modal with fields per spec Section 2.5
• All states per spec Section 2.6

Also completed: Refactored all Card-based shared components (MetricCard, AlertTile, PhasePromptBar, QuickAction) to use proper shadcn Card composition (CardHeader/CardTitle/CardAction/CardContent/CardFooter).

Verify: Table renders 20 students. Sorting works on all sortable columns. Filters narrow results. Row click navigates to /students/:id. "Add Student" opens modal. Pagination shows "1-20 of 20".

Phase 4: Student Management — Student Detail Page -- COMPLETE

Goal: The single most important new screen. 6-tab entity page. Sets the entity page pattern for Semester Hub and TA Detail.

Spec reference: docs/admin-spec/03-student-management.md Sections 3.1-3.11

Build:

• src/pages/student-management/student-detail/index.tsx — entity header + 6 tabs
• Entity header: name, email, level badge, semester, TA (clickable → TA Detail), status badge, subscription badge. Per spec Section 3.3.
• Tab: Profile — personal info (incl. country, phone, timezone), enrollment, tags, system info (collapsible) sections. Per spec Section 3.5.
• Tab: Submissions — table with semester filter, summary bar (total/reviewed/under review/avg grade). Per spec Section 3.6.
• Tab: Payments — subscription card (status, plan, next billing), action buttons (Cancel/Pause/Retry contextual), payment history table, special flags (family/scholarship/deferment with links), past due/paused banners. Per spec Section 3.7. Uses static mock Stripe data.
• Tab: Appointments — table with upcoming/past/all filter, status badges, Schedule + Calendar View buttons, TA links. Per spec Section 3.8.
• Tab: Semester History — enrollment history table with level progression, clickable semester links, summary bar, first-semester message. Per spec Section 3.9.
• Tab: Actions — action cards grouped into Academic + Account sections. Promote (disabled when not Pass), Register for Year 2 (Level 4 only), Reset Progress (destructive with typed confirmation), Deactivate (subscription-aware). Inactive state shows only Reactivate + Resend. Per spec Section 3.10.

Verify: Navigate from Students list → Student Detail. All 6 tabs render with data. Tab URL updates (#profile, #submissions, etc.). Entity header stays fixed across tabs. Action confirmations show correct dialog types.

Phase 5: Student Management — Remaining Screens

Spec reference: docs/admin-spec/03-student-management.md Sections 4-7

Build:

• src/pages/student-management/submissions.tsx — dual-view (Assessments / Submissions toggle). Per spec Sections 4.3-4.5.
• src/pages/student-management/promoted-students.tsx — list screen. Per spec Section 5.
• src/pages/student-management/failed-signups.tsx — list screen. Per spec Section 6.

Verify: All three screens render. Student name clicks navigate to Student Detail. Submissions dual-view toggle works.

Phase 6: Semester Management

Goal: Semester Hub with 4 tabs including Setup Checklist and Close Workflow — the two most complex workflow UIs.

Spec reference: docs/admin-spec/04-semester-management.md (all sections)

Install:

bunx --bun shadcn@latest add progress switch accordion

Build:

• src/pages/semester-management/semesters.tsx — semester list with status badges, active indicator
• src/pages/semester-management/semester-hub/index.tsx — entity header + 4 tabs
• Tab: Overview — key metrics, status, dates (incl. contentAvailabilityDate, launchPartyDateTime), configuration summary
• Tab: Setup Checklist — checklist items with completion status, "Configure →" deep links, progress tracking. Non-gated (any order). Deep links pass ?semester={id}&level={id}&from=checklist to content screens.
• Tab: Enrollment — enrollment stats, student list by level, enrollment management
• Tab: Close Workflow — gated 5-step sequential wizard:
  • Step 1: Review EOC — summary table of end-of-cycle assessment results by level. Columns: Student Name, Level, EOC Score, Pass/Fail. Pass threshold: 3.5.
  • Step 2: Confirm Promotions — students who passed, grouped by current level → next level. Level progression: L0→L1→L2→L3→L4→Year 2. Bulk "Confirm All" or individual confirm/override. Year 2 students flagged separately.
  • Step 3: Bulk Payment Setup — SIMPLIFIED: summary of promoted students needing subscription updates (count, plan changes, estimated billing impact). Single "Confirm Payment Setup" button. Note: full billing patterns built in Phase 10; can revisit for richer data after.
  • Step 4: Handle Leavers — students not continuing (failed, didn't re-enroll, cancelled). Linked deactivation action (deactivate + cancel Stripe sub). Uses destructive ConfirmDialog.
  • Step 5: Verify & Close — checklist showing all 4 previous steps complete (green checks). "Close Semester" button (destructive, requires confirmation). On confirm: show success toast.
  • Gating: Steps 2-5 show locked state (gray, non-interactive) until prior step marked complete. Simple boolean state array.
• src/pages/semester-management/welcome-package.tsx — welcome video/PDF management per level
• src/pages/semester-management/email-management.tsx — email template list using EmailTemplate data
• src/pages/semester-management/tags.tsx — tag management (performance, welcome, level tags)
• src/pages/semester-management/operations.tsx — bulk operations (mass email, export, etc.)

Verify: Semester list → Semester Hub navigation. Setup Checklist items show completion. Close Workflow shows gated steps (Step 3 locked until Step 2 complete). "Configure →" links navigate with query params.

Phase 7: Content

Spec reference: docs/admin-spec/05-content.md

Build:

• 6 list screens (Video Lessons, Resources, Recordings, Tutorials, MCQ Questions, Quizzes) — all use DataTable + FilterBar pattern
• Filtering: All screens support semester + level filters EXCEPT Recordings (semester only, no level filter per spec)
• Setup Checklist integration: ?semester={id}&level={id}&from=checklist pre-filters and shows "← Return to Setup Checklist" banner at top of page
• Each screen is lightweight — reuse the list screen pattern from Phase 3

Verify: All 6 screens render. Deep links from Setup Checklist pre-filter correctly. Return banner appears and navigates back. Recordings screen has no level filter.

Phase 8: Scheduling

Spec reference: docs/admin-spec/06-scheduling.md

Build:

• src/pages/scheduling/calendar.tsx — custom Tailwind CSS grid with week/month toggle. No external calendar library. Color-coded events by type. Filter by TA, gender, level, event type.
• src/pages/scheduling/live-sessions.tsx — list screen using LiveSession data. Shows level tags, gender scope, timezone.
• src/pages/scheduling/appointments.tsx — list screen with status derivation using Appointment data
• src/pages/scheduling/ta-schedules.tsx — TA selector + weekly availability grid using TaSchedule data
• src/pages/scheduling/holidays.tsx — list/calendar toggle, merged holiday types

Verify: Calendar shows mock events in week view. Filters narrow visible events. TA Schedules shows availability grid for selected TA. Live Sessions shows gender/level scoping.

Phase 9: Teacher Management

Spec reference: docs/admin-spec/07-teacher-management.md

Build:

• src/pages/teacher-management/teachers.tsx — TA list with avg response time column, gender
• src/pages/teacher-management/teacher-detail/index.tsx — entity header + 4 tabs (Profile, Schedule, Students & Groups, Performance)
• src/pages/teacher-management/assignment-criteria.tsx — rules list + repeat student toggle
• src/pages/teacher-management/ta-reports.tsx — TA performance reports
• src/pages/teacher-management/student-groups.tsx — groups list

Verify: TA list → TA Detail navigation. Performance tab shows metrics with threshold highlighting (>48h = red). Student names on Students & Groups tab link to Student Detail.

Phase 10: Billing & Payments

Spec reference: docs/admin-spec/08-billing-payments.md

Build:

• src/pages/billing/overview.tsx — metrics bar (5 cards) + 6 expandable alert sections using Collapsible (Failed Payments, Past Due, Missing Subscriptions, Expiring Scholarships, Deferment Resume Due, Recently Cancelled). Per spec Sections 2.1-2.8.
• src/pages/billing/payments.tsx — transaction history table. Date range filter uses two <Input type="date" /> fields.
• src/pages/billing/plans.tsx — payment plans table with Stripe sync status column, using PaymentPlan + Subscription data
• src/pages/billing/coupons.tsx — coupons table with redemption counts
• src/pages/billing/family-plans.tsx — family list view + family detail view (two-level navigation). Shows shared stripeCustomerId.
• src/pages/billing/scholarships.tsx — tabbed screen (Scholarships tab with Programs/Students toggle + Deferments tab)

Verify: Payment Overview alert sections expand/collapse. Student name clicks navigate to Student Detail > Payments tab. Family Plans list → detail navigation works.

Phase 11: Reporting

Spec reference: docs/admin-spec/09-reporting.md

Build:

• src/pages/reporting/student-report.tsx — DataTable report
• src/pages/reporting/referrals.tsx — referrals tracking
• src/pages/reporting/specific-reports.tsx — specific report types
• src/pages/reporting/composition.tsx — summary cards + detail table per level. Per spec Section 5. Retention rates shown as static percentages.
• src/pages/reporting/logs.tsx — audit log table using AuditLog data

Verify: Student Composition summary cards render. Level click expands student list. Logs screen shows audit entries.

Phase 12: Admin & System

Spec reference: docs/admin-spec/10-admin-system.md

Build:

• src/pages/admin-system/admins.tsx — admin user list
• src/pages/admin-system/settings.tsx — general settings (placeholder)
• src/pages/admin-system/notifications.tsx — notification send form
• src/pages/admin-system/support-links.tsx — ordered links list with edit modal (no drag-reorder)
• src/pages/admin-system/issue-queue.tsx — issue list with status/priority filters, detail view

Verify: Issue Queue filters work. Status changes via dropdown. All screens accessible from sidebar.

Phase 13: Polish & Cross-Cutting

Goal: Wire up cross-screen navigation, global search, and final consistency pass.

Spec reference: docs/admin-spec/00-spec-index.md Section 6 (Workflows WF1-WF6), docs/admin-spec/01-global-patterns.md Section 2 (Global Search)

Install:

bunx --bun shadcn@latest add command

Build:

• Global search (Cmd+K):
  • Command component inside Dialog (standard shadcn pattern)
  • Searches: students (by name/email), TAs (by name), semesters (by name)
  • Result format: "Name · Level · Semester · Status badge" (students), "Name · Assigned students" (TAs), "Name · Status badge" (semesters)
  • Group by entity type, max 5 results per type
  • Click result → navigate to entity page
• All cross-domain click-throughs verified (Dashboard tile → Payment Overview, Student Detail TA name → TA Detail, etc.)
• "Formerly under [Section]" transition hints on relocated screens
• Loading skeletons on every screen
• Empty states on every screen
• Responsive: sidebar collapses at tablet breakpoint, tiles stack at narrow
• Final visual consistency audit — every table, every badge, every header looks the same

Verify: Full walkthrough of all 6 workflows from docs/admin-spec/00-spec-index.md Section 6 (WF1-WF6). Each workflow's screen sequence navigates correctly end to end.

v2 Build Phases

v2 COMPLETE (2026-04-22) — final commit 42db44c. All numbered phases (v2-0 through v2-5) plus follow-up phases (Apr 22 A/B, Phase C Waves 1+2, Phase D Scheduling, Phase E Communication + Assignment Criteria, Phase F aggregate /simplify, Phase G integration pass, Phase H polish) are shipped. No active phase pointer. Remaining post-v2 work is production scope (see "Deferred Items") and polish followups explicitly punted at Phase H close (see worklog).

The v2 build is a parallel track under /v2/*. v1 phases above remain frozen as a reference baseline; no v2 work touches v1 paths. v2 is specced in docs/admin-spec-v2/ (12 files) with decision records in docs/v2-review/ (ADR-001 through ADR-006; STAKEHOLDER-ANSWERS-2026-04-21.md + STAKEHOLDER-ANSWERS-2026-04-22.md form the canonical resolution layer — read both).

Execution loop: Every v2 phase follows the same loop defined in the "Execution Loop" section at the top of this file (read spec section → plan components → install → build → simplify → build/lint/code-review → commit). Phase-specific gates are noted per phase below.

Topology: v2-0 and v2-1 are lead-executed (pattern-setting). v2-2 fans out to five domain teammates running in isolated git worktrees. v2-3 through v2-5 return to the lead for integration, optional Communication work, and polish.

Phase v2-0: Foundations -- COMPLETE

Date: 2026-04-22. Commit: cbcc43f feat(v2): scaffold /v2 route tree with foundations and 49 page stubs.

Executor: Lead only (no teammates). Scaffolding defines the patterns every later domain agent mirrors, so it cannot be parallelized.

What landed:

• src/components/v2/layout/ — 9 files: nav-config.ts, app-shell.tsx, app-sidebar.tsx, breadcrumb-nav.tsx, page-header.tsx, global-search.tsx, placeholder-page.tsx, entity-tab-shell.tsx, todo-panel.tsx.
• src/pages/v2/ — 49 page stubs across 10 sub-directories (dashboard, student-management, semester-management, content, scheduling, teacher-management, billing, reporting, communication, admin-system).
• src/App.tsx — /v2 route branch added; v1 routes untouched.
• /simplify run; two duplications extracted into V2EntityTabShell and V2TodoPanel.
• bun run build and bun run lint both passing.

Phase v2-1: Low-risk domains (Reporting, Admin & System, Content) -- COMPLETE (exemplar only)

Status (2026-04-22): COMPLETE (scoped-down to exemplar). Lead executed a single exemplar list screen — Reporting > Logs (616e234 feat(v2-reporting): replace Logs stub with v2 exemplar list screen) — to establish the v2 list-screen pattern, then pivoted straight into Phase v2-2 rather than promoting all 16 v2-1 screens. The remaining Reporting / Admin / Content screens originally scoped here were folded into the Phase v2-2 teammate clusters (and several were delivered by those teammates). .agents/v2-domain-spawn-prompt.md and CLAUDE.md pre-work landed in 4642157 chore(v2): prep pre-work for domain teammate fleet.

Goal: Convert the first list-screen stubs into working screens. Establish the v2 list-screen pattern teammates will copy in Phase v2-2.

Executor: Lead only. These domains are deliberately chosen because their screens are mostly list+filter views with minimal cross-domain coupling — ideal for setting a pattern without getting trapped in entity-page complexity.

Spec reference: docs/admin-spec-v2/09-reporting.md, docs/admin-spec-v2/10-admin-system.md, docs/admin-spec-v2/05-content.md.

Build (screens to promote from stub → real):

• Reporting: 5 list screens (Student Report, Referrals, Specific Reports, Student Composition, Logs)
• Admin & System: 5 screens (Admins, Settings, Notifications, Support Links, Issue Queue)
• Content: 6 list screens (Video Lessons, Resources, Recordings, Tutorials, MCQ Questions, Quizzes)

Phase-specific gates (in addition to the standard execution loop):

• Extra review of v2 list-screen pattern before committing — naming, prop shape, filter placement, pagination, deep-link query params. Teammates will copy whatever lands here 30+ times.
• Pre-install any shadcn primitives not already in the repo so Phase v2-2 teammates don't race to add the same component.
• Draft .agents/v2-domain-spawn-prompt.md before Phase v2-2 starts. Template must cover: worktree branch convention, spec section assignment, shared imports (src/components/v2/layout/*, shared v2 components created in v2-1), the Skill-tool invocation of simplify, build/lint gates, and commit discipline.
• Confirm CLAUDE.md covers shadcn critical rules + Card composition rules (so teammates inherit them from cold sessions).

Phase v2-2: Domain teammate fleet -- PARTIAL

Status (2026-04-22): PARTIAL — teammates hit shared Anthropic usage rate limit at ~22 min in. Commit 6b2f5bb feat(v2): partial Phase v2-2 from parallel domain teammates. All 5 teammates were spawned with isolation: "worktree" as planned, all 5 delivered substantial real code before cutoff, none completed their full cluster. Build + lint verified green at merge.

Update (2026-04-22, 8a46270): Lead filled the 4 Semester Hub tab stubs (Overview, Setup Checklist, Enrollment, Onboarding Support) as real screens via 8a46270 feat(v2-semester): fill 4 Semester Hub tab stubs. All 5 Semester Hub tabs now have real content (End Checklist was already real from 6b2f5bb). Build + lint green. Other v2-2 teammate clusters remain partial — see remaining stubs list below.

Shipped screens (real code, route-accessible):

• Semester Mgmt: Semesters list (create/edit/auto-transition dialogs, delete guard), Semester Hub entity page with 5-tab shell + real End Checklist tab. Other 4 hub tabs (overview / setup-checklist / enrollment / onboarding-support) have V2TodoPanel stubs created by lead to satisfy imports.
• Student Mgmt: Students list (Final Status column, per-row + bulk Set Pass/Fail, End Checklist Step 2 deep-link preset), Student Detail with all 7 real tabs (Profile, Submissions, Payments, Appointments, Semester History, Admin Notes, Actions).
• Billing: Coupons, Payments, Plans (grouped: Standard / Family / Scholarships / Discounts per Decision #8).
• Admin & System: Admins, Settings, Support Links, Issue Queue.
• Content: Video Lessons, Resources (multi-level tagging).
• Communication: Automation Emails (unified template library, Preview, Test Send, Sequence View per student). Shared V2RecipientFilter landed here.
• Shared: StatusBadge v2 entries; V2EntityTabShell extended with content + trigger badge + page-header action slot. 9 new data files under src/data/ (admin-notes, assignment-matrix, communication, end-checklist, onboarding-support, one-to-one-usability, payment-setup-queue, setup-checklist, ...).

Remaining stubs (30 screens, route-accessible but V2TodoPanel / PlaceholderPage only):

• Student Mgmt (3): submissions, promoted-students, failed-signups. [x] All 3 shipped — Phase C Wave 1 (f86e2c4, 2026-04-22).
• Teacher Mgmt (5): teachers, teacher-detail (4 tabs), ta-reports, student-groups, assignment-criteria. [x] All 5 shipped — 4 in Phase C Wave 2 (4864d6d, 2026-04-22); Assignment Criteria in Phase E (358e9c2, 2026-04-22) with ADR-002 hybrid matrix + Apr 22 Rotation inversion.
• Content (4): recordings, tutorials, mcq-questions, quizzes. [x] All 4 shipped — Phase C Wave 1 (9048128, 2026-04-22).
• Scheduling (6): calendar-view, live-sessions, appointments, ta-schedules, holidays, one-to-one-usability. [x] All 6 shipped — Phase D (5426a54 + af2c158 extract, 2026-04-22). ?ta=<id> + ?date=<iso> deep-links wired on calendar-view + ta-schedules.
• Reporting (4): student-report, referrals, specific-reports, composition. [x] All 4 shipped — Phase C Wave 2 (66833c4, 2026-04-22). Plus NEW real: Active Semester Enrollment §6, Revenue Breakdown §7. Installment Conversion + Notification Impact remain permanent V2PlaceholderPage per spec §8.3/§9.3. (Logs shipped in v2-1.)
• Billing (3): overview (incl. §2.9 End Checklist Queue), family-plans, scholarships. [x] All 3 shipped — Phase C Wave 2 (521246a, 2026-04-22).
• Communication (5): blast-emails, push-notifications, announcement-board, private-messages, logs. [x] All 5 shipped — Logs in Phase C Wave 1 (4ee528f); remaining 4 in Phase E (6c24bc8 + f04e3ad extract, 2026-04-22).

Additional Semester Mgmt stubs cleared in Phase C Wave 1 (these were filled by lead after the original 30-stub tally was taken, so they were not in the list above but belong in the Wave 1 progress picture):

• Semester Mgmt (3): tags, welcome-package, operations (4-card Operations per ADR-005). [x] All 3 shipped — Phase C Wave 1 (b494819, 2026-04-22).

Phase C Wave 1 completed (2026-04-22) — 11 screens filled across 4 commits (b494819 semester-mgmt tags/welcome-package/operations; 9048128 content recordings/tutorials/mcq/quizzes; f86e2c4 student-mgmt submissions/promoted/failed-signups; 4ee528f communication logs). Post-merge bun run build + bun run lint clean. Remaining stub count drops from 30 → 19 (see Follow-up plan below for the updated tally).

Key learning: 5-teammate fan-out is blocked by a single shared-account usage ceiling, not by per-teammate budget. Parallel isolation does not multiply effective capacity on this account. Follow-up work should use a smaller or sequential topology (see Follow-up plan below).

Goal: Fan out the remaining domain work to five parallel teammates operating in isolated git worktrees. Each teammate owns a cluster, commits on its own branch, and reports back to the lead for merge.

Executor: Five worktree-isolated teammates; lead orchestrates and merges.

Worktree branch convention: v2/<domain-slug> (e.g., v2/student-teacher, v2/semester-hub, v2/content-sched-rep, v2/billing-admin, v2/communication).

Cluster assignments:

Spawn-prompt requirements (see .agents/v2-domain-spawn-prompt.md, drafted in v2-1):

• Teammate must invoke the simplify skill via the Skill tool before reporting done.
• Teammate must run bun run build and bun run lint and both must pass before reporting done.
• Teammate commits on its own worktree branch; commits follow feat(v2-<domain>): ... convention.
• Teammate does NOT merge to main, does NOT touch v1 paths, does NOT trigger the plan-update agent.
• Teammate reports back with: branch name, final commit hash, list of screens completed, list of any cross-domain deep-links it depends on (so lead can resolve in Phase v2-3).

Lead responsibilities during v2-2:

• Review each teammate's branch on return; merge to main in a single merge commit per teammate.
• After each merge, trigger the post-commit plan-update agent (per user memory feedback_update_impl_plan.md).
• Defer cross-domain integration (e.g., End Checklist Step 2 → filtered Students list) to Phase v2-3.

Phase-specific gates:

• Pre-flight check: all shadcn primitives required by spec are already installed (done in v2-1).
• Pre-flight check: .agents/v2-domain-spawn-prompt.md exists and reflects current v2 conventions.
• Per-merge check: bun run build + bun run lint pass on main after each merge.

Phase v2-3: Dashboard + Integration Pass -- COMPLETE (dashboard portion)

Status (2026-04-22): COMPLETE for the Dashboard build itself. Commit 8c1b4f3 feat(v2-dashboard): replace stub with real Dashboard (Phase v2-3). Alert tiles retargeted to /v2 routes, Communication tile added per ADR-003, End phase prompt references End Checklist progress per ADR-001, Quick Actions expanded to 6 (adds Blast Email, Announcement, Private Messages). Executed by lead after teammate cutoff.

The "integration pass" portion (cross-domain deep-link audit, consistency sweep across all 49 screens) is effectively deferred — much of it cannot run until the 30 remaining stubs have real screens to link to. What can be audited today (v2-2 shipped screens + Dashboard) is green; a full integration pass belongs in the follow-up plan after remaining stubs are filled.

Goal: Build the v2 Dashboard (cross-domain tiles that depend on all other domains existing) and resolve cross-domain deep-links and inconsistencies that teammates could not coordinate on.

Executor: Lead only.

Spec reference: docs/admin-spec-v2/02-dashboard.md and cross-links called out in each domain spec.

Build:

• v2 Dashboard — alert tiles, phase prompt, quick actions. Tiles deep-link into teammate-built screens.
• Cross-domain deep-links — e.g., End Checklist Step 2 → Students list filtered to L1–4 with no status; Billing alerts → Student Detail / Payments tab; TA Detail → Student Detail.
• Consistency pass — every v2 table, badge, header, filter bar, pagination control matches the patterns set in v2-1. Fix anything a teammate stylized differently.

Phase-specific gates:

• Verify v2 entity pages' tab lists match spec tab lists (cross-check against 03-student-management.md §3.9, 04-semester-management.md entity spec, 07-teacher-management.md entity spec).
• Walk every Dashboard tile and Quick Action — confirm each navigates to a real v2 screen.
• Walk every spec-defined workflow end-to-end in v2 (the v2 equivalent of v1 WF1–WF6).

Phase v2-4: Communication Domain -- PARTIAL

Status (2026-04-22): PARTIAL — only Automation Emails (1 of 6) shipped by the Comm teammate in Phase v2-2 before cutoff. Remaining 5 screens (blast-emails, push-notifications, announcement-board, private-messages, logs) are still stubs. Reason: teammate fleet hit shared-account rate limit before the full cluster completed.

Goal: Build the new Communication domain (6 screens) — a wholly new cluster in v2 with no v1 analog.

Executor: Either the Comm teammate inside Phase v2-2 (preferred if spec is stable) OR the lead as a dedicated post-v2-3 phase (fallback if Comm spec is still in flux at the time of v2-2 spawn).

Spec reference: docs/admin-spec-v2/11-communication.md (or the equivalent v2 spec filename).

Build: 6 screens per spec. List screens follow the v2-1 pattern; any entity pages follow the v2 entity-page pattern established in Phase v2-2.

Phase-specific gates: Same as Phase v2-2 if executed by the Comm teammate; same as Phase v2-3 if executed by the lead.

Phase v2-5: Polish + Cross-Cutting -- COMPLETE

Status (2026-04-22): COMPLETE — discharged by follow-up Phase H (commits a810217 + d526e1a + 42db44c). The original concern that polish could not start until stubs were real played out exactly — polish ran last, after all feature surfaces were real and after Phase F aggregate /simplify and Phase G integration pass had landed.

Goal: v2 equivalent of v1 Phase 13. Global search, loading skeletons, empty states, responsive behavior, final visual consistency audit.

Executor: Lead only.

Spec reference: docs/admin-spec-v2/01-global-patterns.md and any cross-cutting sections.

Build:

• v2 Global search (Cmd+K) — searches v2 entities across student, TA, semester, and navigation commands. Shipped in a810217.
• Empty states on every v2 screen — hand-rolled empty states swapped for shadcn Empty (assignment-criteria, student-detail) and consistent treatment elsewhere. Shipped in d526e1a.
• Final visual consistency audit — raw palette colors replaced with semantic tokens + StatusBadge across 9 files (billing / scheduling / semester-hub). Shipped in 42db44c.
• Loading skeletons on every v2 screen — consciously deferred; static mock data renders synchronously, no Suspense-shaped boundary to skeleton against.
• Responsive audit — sidebar collapse + tile stacking inherited from v1 shell; table overflow handled per-screen in Phase G. No dedicated pass run.

Phase-specific gates:

• Cmd+K discharge confirmed — Phase H Cmd+K agent walks 4 command groups (students / teachers / semesters / nav).
• /v2 parity with spec coverage table in docs/admin-spec-v2/00-spec-index.md confirmed in Phase G integration pass.
• Explicit deferrals logged in docs/v2-review/_v2-build-worklog.md Phase H section (POLISH 4 button-icon sizing, POLISH 5 fixed-width selects, POLISH 7 revenue-breakdown MetricCard, StatusBadge Stripe-sync states).

v2 Loop summary

Follow-up plan (post-teammate-cutoff)

Context: Phase v2-2's 5-teammate fan-out hit a shared-account Anthropic usage limit at ~22 min; all 5 teammates were cut simultaneously. The plan originally assumed per-teammate budgets were independent; they are not on this account. Do not re-spawn the same 5-teammate fleet — it will hit the same ceiling.

Recommended topology for remaining work:

1. Small batched teammate waves — e.g., 2 teammates at a time, each owning a narrow cluster (Scheduling's 6 screens is a natural single-teammate batch; Teacher Mgmt's 5 screens another). Wait for one wave to complete and merge before spawning the next so usage pressure stays bounded.
2. Sequential lead work — for the simplest stub clusters (Reporting's 4 missing list screens, Billing's 3 remaining screens, the 4 Semester Hub tab stubs), the lead can fill them one at a time faster than spawning + merging teammates. The v2 list-screen pattern and entity-tab pattern are already established.
3. Aggregate simplify — after the remaining 30 stubs are real screens, run /simplify across the full v2 diff (it was skipped across the v2-2 / v2-3 aggregate because teammate budgets were exhausted). Will catch duplication between teammates' independent implementations.
4. Final polish sweep (Phase v2-5) — only once above is done. Covers global search, skeletons, empty states, responsive behavior, full cross-domain deep-link audit, and the end-to-end workflow walkthroughs deferred from v2-3's integration pass.

Remaining stub count: 0 feature stubs after Phase E merge (6c24bc8 + f04e3ad + 358e9c2). Phase E cleared the last 5 feature surfaces (4 Comm + Assignment Criteria). 2 Reporting placeholders (installment-conversion §8.3, notification-impact §9.3) remain permanent V2PlaceholderPage per spec direction — not counted.

Running tally: (30 original) − 11 Wave 1 − 11 Wave 2 − 6 Phase D − 5 Phase E = 0 remaining feature stubs. +2 promoted-to-real Apr-22 Reporting primaries already landed (Active Enrollment, Revenue Breakdown). Stub-fill work for the v2 mockup is now complete.

Cross-cutting phases after Phase E (all COMPLETE as of 2026-04-22):

• Phase F — aggregate /simplify across full v2 diff. COMPLETE — f4a88b3. 3 parallel review agents produced 8+ findings across Phase E + Assignment Criteria; high-ROI subset applied (DateRangeFilter extraction + useMemo + dead-import cleanup). Data-model sharpening companion sweep deferred — flagged as production scope (FamilyMember fields, LiveSession recurrence/status, TaSchedule valid-from/to are data-model-only gaps, not blocking the mockup UX).
• Phase G — integration pass (cross-domain deep-links, workflow walks). COMPLETE — d9f9905. 8 bugs fixed: URL-hash honoring in V2EntityTabShell (10+ deep-links restored), 2 hard-404 route prefixes, query-param honoring on automation-emails + private-messages, end-checklist status-param mismatch, Issue Queue toast → navigate.
• Phase H — polish. COMPLETE — a810217 + d526e1a + 42db44c. Cmd+K with real data + nav commands; shadcn Empty swapped in where hand-rolled empty states existed; overflow / heatmap fixes; raw palette → semantic tokens + StatusBadge across 9 files.

v2 build is COMPLETE at 42db44c. No active phase pointer. Remaining items are explicitly deferred to production scope (see "Deferred Items" below) or consciously punted polish followups (see docs/v2-review/_v2-build-worklog.md Phase H section).

Apr 22 scope amendments (post-STAKEHOLDER-ANSWERS-2026-04-22)

Date: 2026-04-22. Source: Apr 22 working session with Lejla (docs/v2-review/QF-Backend-Review-Apr-22.md). Canonical record: docs/v2-review/STAKEHOLDER-ANSWERS-2026-04-22.md.

The Apr 22 session resolved the three topics deferred from Apr 21 (Reporting, Issue Queue state machine, Repeat Semester). Spec updates landed in a single spec-edit commit. Mockup impact is tracked below and deferred to follow-up build waves — it does NOT enter a new numbered phase; it slots into the existing remaining-stub + polish work.

Spec-only changes (already applied):

• STAKEHOLDER-ANSWERS-2026-04-22.md created. Apr 21 doc cross-linked.
• ADR-002 amended — Repeat-Student "Auto-Assign to previous TA" INVERTED to Repeat-Student Rotation (different TA if possible; falls back to previous TA only when no alternative).
• ADR-006 added — Issue Queue state machine (Open / In Progress / Resolved / Rejected; Delegated sub-state to CS/IT/Teaching; Archive as view; no hard delete).
• 03-student-management.md — added enrollment_type field (Continuing / New / Repeat / Year 2) as a new column + detail field; added per-student "Mark as Repeat-Eligible" action on Actions tab.
• 04-semester-management.md — Step 3 self-service opt-in confirmed; auto-applied semester-scoped enrollment tags documented in Tags section.
• 07-teacher-management.md — §4.4.2 rule renamed + inverted + relogic'd.
• 08-billing-payments.md — new semester_repeat_eligibility table; new §2.10 Repeat Checkout Flow cross-reference.
• 09-reporting.md — Category E banner removed; 2 primary new reports (Active Semester Enrollment, Revenue Breakdown) + 2 nice-to-have stubs (Installment→One-Time, Notification/Email Impact); CSV-only, live+export, no scheduled email.
• 10-admin-system.md — §6 Issue Queue updated per ADR-006.
• 11-communication.md — fail-email self-service wording clarified.
• 01-global-patterns.md — Issue Queue statuses + Enrollment Type statuses added to §4.3.
• 02-dashboard.md — App Issues tile count semantics clarified.
• 00-spec-index.md — Reporting domain updated; Issue Queue resolved.

Mockup work items (deferred to follow-up build waves):

Impact on remaining-stub count: Reporting gains 2 new primary screens + 2 stubs (net +2 real + 2 stubs vs current plan). Students list gains a column (not a new stub). Issue Queue is a modification of existing work (not a new stub). Assignment Criteria is already a placeholder — no net change.

Phase A completed (commit 2ce4422, 2026-04-22) — foundation wave: types + data + nav + routes. Scratch pad at docs/v2-review/_v2-build-worklog.md. Subsequent phases (B: Issue Queue state-machine UI + Students Enrollment Type column/filter + Student Detail badge/action, C6: real Reporting screens, E: Assignment Criteria rename/invert) consume this foundation.

Phase B completed (commit b742208, 2026-04-22) — shipped-screen modifications wave: Issue Queue full state-machine overhaul per ADR-006, Students list Enrollment Type column + filter, Student Detail Enrollment Type badge + Mark-as-Repeat-Eligible action card. Added shadcn toggle + toggle-group UI primitives. Remaining Apr 22 work: C6 (real Active Semester Enrollment + Revenue Breakdown reporting screens — still V2TodoPanel stubs) and E (Assignment Criteria rename/invert — still a stub).

Phase E completed (commits 6c24bc8 + f04e3ad extract + 358e9c2 assignment-criteria, 2026-04-22) — Communication cluster (Blast Emails §3, Push Notifications §4, Announcement Board §5, Private Messages §6) + Assignment Criteria (§4.4 ADR-002 hybrid matrix with Apr 22 Rotation inversion). ADR-002 inversion shipped: "Rotate repeat students to a different TA when possible" toggle (default on) in assignment-criteria.tsx; Precedence Summary orders rotation rule in the precedence stack. ADR-004 no-impersonation honored via "Draft for TA" in Blast Emails §3.5 and Private Messages §6.5.3 (saves pre-draft to TA's queue; production-only TA-facing surface). Scheduling deferred on all compose surfaces per OQ-C3 (Scheduled column/filter kept for forward compat). Shared V2RecipientFilter reused across blast / push / announcement. All Apr 22 mockup work items are now complete.

Phase F completed (commit f4a88b3 refactor(v2): Phase F simplify sweep — extract DateRangeFilter + fixes, 2026-04-22) — aggregate /simplify across the full Phase E + Assignment Criteria diff. 3 parallel review agents (reuse / quality / efficiency) produced 8+ findings; high-ROI subset applied: extracted DateRangeFilter shared component (3 callers), added useMemo to filteredThreads / totalCapacity / projectedTotal hotspots, batched a multi-setSelected call, stripped dead imports + narrative comments. Data-model sharpening companion sweep (the C4/C5/D/E FamilyMember / LiveSession / TaSchedule gaps) was consciously left for production — the gaps do not block mockup UX.

Phase G completed (commit d9f9905 fix(v2): Phase G integration pass — restore deep-links across 8 bugs, 2026-04-22) — cross-domain deep-link audit. 8 bugs identified: 4 blockers + 3 medium + 1 low, all fixed in the single commit. Single highest-leverage fix: V2EntityTabShell now honors the URL hash, which re-activates 10+ #payments / #students-groups deep-links from Dashboard / Billing / Semester Hub. Also fixed 2 hard-404 route prefixes, query-param honoring on automation-emails + private-messages, end-checklist status-param mismatch, and Issue Queue toast → navigate.

Phase H completed (commits a810217 feat(v2): Phase H — wire Cmd+K global search with nav commands + d526e1a polish(v2): Phase H — empty states, overflow, heatmap + 42db44c polish(v2): replace raw palette colors with semantic tokens and StatusBadge, 2026-04-22) — polish + cross-cutting. Cmd+K global search wired against real students / teachers / semesters + navigation commands (v2-5 Cmd+K requirement discharged). Hand-rolled empty states replaced with shadcn Empty (assignment-criteria, student-detail). Private-messages overflow-hidden replaced with min-h-0 + overflow-x-auto (ScrollArea bug). ta-schedules heatmap migrated to semantic primary/15. Raw palette colors (bg-green-X / bg-red-X / text-blue-X) replaced with semantic tokens and StatusBadge across 9 files (billing / scheduling / semester-hub). v2 build COMPLETE at 42db44c.

Explicitly deferred polish followups (not bugs — consciously punted at Phase H close):

• Icons inside Buttons still carry sizing classes on ~15 files (POLISH 4 — low visual impact, skipped).
• Fixed-width SelectTrigger on ~8 sites (POLISH 5 — low impact at admin-scale, skipped).
• revenue-breakdown Projection tiles hand-roll the MetricCard pattern (POLISH 7 — 1 tile, skipped).
• StatusBadge map missing "Not Linked" / "Mismatch" / "Not Found" / "N/A" (Stripe-sync states flagged by the palette sweep, not added).

Deferred Items

Spec-defined features deferred for production implementation. Noted here for completeness:

1. Stripe real-time fetch — Payments tab shows static mock data. No latency simulation, staleness indicators, or customer ID resolution chain. (01-global-patterns.md §5)
2. Recent search persistence — Global search doesn't persist last 5 searches across session. (01-global-patterns.md §2.4)
3. Scroll position on checklist return — Return banner navigates back but doesn't restore scroll position. (04-semester-management.md §3.6)
4. Role-based sidebar — Mockup shows Admin view only. No TA/View-Only/Support Staff toggle. (01-global-patterns.md §3)
5. Webhook simulation — Billing alerts use static data, no webhook event flow. (08-billing-payments.md §9)
6. Retention rate computation — Student Composition shows static percentages, not computed from cross-semester enrollment data. (09-reporting.md §5.4)
7. Support Links drag-reorder — Ordered list with edit modal instead. (10-admin-system.md §5)
8. Setup Checklist dynamic status — Static completion states, not dynamically computed from content counts. (04-semester-management.md §3.6)
9. InfusionSoft/CRM sync — Legacy integration not represented in new admin. (Backend docs)
10. Coupon token system — Individual redeemable tokens. Mockup shows coupon-level data only. (Backend docs)
11. Performance tags — Auto-computed Low/Mid/High Performer tags shown as static badges. (Backend docs)
12. Fresh desk integration — Issue Queue is explicitly scoped to the admin backend only for v2. Fresh desk routing (delegate → email Fresh desk team) is deferred. Per STAKEHOLDER-ANSWERS-2026-04-22 §B. (10-admin-system.md §6)
13. Delegation routing — Issue Queue delegation targets (CS / IT / Teaching Staff) are tag-only in v2. These are NOT backed by RBAC roles and do not route the issue to another system or user. Admin retains ownership + tracking. Full routing is deferred. Per ADR-006. (10-admin-system.md §6)
14. Repeat checkout UI — The student-facing 50%-discount repeat checkout is preserved production behavior, not part of the admin mockup. Admin-side surfaces (Mark as Repeat-Eligible, repeat-eligible list projection) are mocked. Per STAKEHOLDER-ANSWERS-2026-04-22 §C. (08-billing-payments.md §2.10)
15. Full Reporting catalog — Only 2 primary reports (Active Semester Enrollment, Revenue Breakdown) + 2 nice-to-have stubs (Installment→One-Time Conversion §8, Notification/Email Impact §9) specified at Apr 22. The stubs are spec'd with layout TBD; their full design is pending a dedicated reporting working session with Lejla. Remaining uncatalogued report definitions likewise pending that session. (09-reporting.md domain header, §8, §9)
16. Auto-enrollment — Still parked per earlier stakeholder note; revisit post-app-redesign. (STAKEHOLDER-ANSWERS-2026-04-21 §5)

Summary