# 06 — Development Plan

Phased build order for the greenfield system. Each phase = one or more focused
Claude Code sessions. Do not start a phase until the previous phase's acceptance
criteria are green (tests passing, checklist ticked, `docs/00-INDEX.md` updated).

## Phase 0 — Foundation (M01) — ~1 week

Laravel 12 install, CI pipeline (Pest + Pint + Larastan on push), base layouts
for the three shells, auth (2FA), RBAC skeleton + full permission matrix seeded,
firm/settings, offices, reference data (courts, practice areas, matter stages),
NumberingService, FirmScope + `BelongsToFirm`, security headers middleware,
activitylog wired, template map documented (`05a-TEMPLATE-MAP.md`).

**Gate**: a logged-in Firm Admin can manage settings/offices/reference data;
cross-firm isolation test passes on a dummy model; route-audit test passes
(every route has a permission).

## Phase 1 — Contacts, Clients & Matters (M02, M03) — ~1.5 weeks

Unified Contacts (people + organizations), Clients, opposing party/counsel
records, conflict-of-interest check, KYC file. Matters: registration, numbering,
team assignment, parties, stages/status, timeline (`matter_events`), matter
detail page with tab shell for all future modules.

**Gate**: can create a client, run a conflict check, register a matter with a
team, and see it on a correctly-scoped list (assigned-only for non-partners).

## Phase 2 — Litigation & Tasks (M04, M05) — ~2 weeks

Hearings with the adjournment chain, witnesses/testimonies, court roster with
clash detection and attendance, **deadline & limitation engine** (built as a
first-class citizen here, not deferred — this is the highest-liability feature
in the whole system), calendar + iCal, task templates/checklists linked to
matters.

**Gate**: recording a hearing outcome with a next date auto-creates the next
hearing; a deadline within its reminder window notifies the right people; roster
clash warning fires correctly; tasks generate from a template on matter creation.

## Phase 3 — Time, Billing & Finance (M06, M07) — ~2.5 weeks

Time entries, fee arrangements, invoice generation from unbilled time/expenses
(VAT/WHT aware), receipts. Double-entry ledger (COA + journals), bank accounts,
**trust/retainer accounting** (deposit/drawdown/refund, overdraw-blocked),
appearance fee claims → approval → payout, aging & profitability calculations.

**Gate**: an invoice generated from time entries balances; a trust drawdown
beyond balance is rejected under concurrent load (tested); an appearance fee
claim cannot be self-approved; ledger always balances (DR=CR) after any
operation (asserted in a dedicated invariant test run against every financial
Action).

## Phase 4 — Documents & Communication (M08, M09) — ~1.5 weeks

Versioned documents (medialibrary), legal typing, confidentiality tiers +
ethical walls, evidence register, template-based document generation, full-text
search. Announcements w/ acknowledgement, internal threads, matter discussions,
notification centre, SMS channel behind a feature flag, daily digest.

**Gate**: confidential document denied to a non-team user (Policy test);
document versions never overwrite; announcement acknowledgement blocks until
actioned; digest email contains only the recipient's own items.

## Phase 5 — Dashboards, Reports & People/Admin (M10, M12) — ~1.5 weeks

Executive dashboard (attention panel first), lawyer "my day" dashboard, matter
health/assessment view, standard report library (case progress, lawyer
performance, court activity, financials, aging, client report — PDF+Excel).
Staff records, leave (optional flag), payroll (optional flag), system admin
(user/role management, backups, audit review, data import wizards).

**Gate**: every dashboard widget query is unit-testable outside the view;
sanitized client report excludes internal remarks/comments (explicit test);
backup restore drill succeeds.

## Phase 6 — Client Portal (M11) — ~1 week

Portal guard/auth, sanitized matter/invoice/document views, secure sharing,
appointment/inquiry requests to staff.

**Gate**: full portal IDOR test suite green; confidential documents cannot be
shared even by mistake (hard-blocked at the Action layer); portal guard never
resolves a staff account under any input.

## Phase 7 — Hardening & Performance Pass — ~1 week

Run the full Security checklist (docs/04-SECURITY.md §10). Load-test the
hearing/invoice list pages with realistic data volumes (10k+ matters); verify
N+1 query prevention is actually enforced; review and tighten Content-Security-
Policy; penetration-test the portal specifically (IDOR, session fixation, CSRF);
confirm all queued jobs have retry/backoff and failure alerting.

**Gate**: security checklist 100% checked; no N+1 warnings in a full click-
through of every list page in staging; portal pen-test findings resolved.

## Phase 8 — UAT, Data Migration & Go-Live — ~1–1.5 weeks

User acceptance testing with real firm staff on staging; import legacy
case/client data via the M12 import wizard with a validation report; production
environment setup (backups scheduled, monitoring/alerting wired, `.env`
reviewed); production backup+restore rehearsal; staff training sessions +
quick-reference guides generated per module; go-live checklist executed;
hypercare week (daily check-ins, fast-turnaround bug fixes).

**Gate**: UAT sign-off from the firm; production restore drill succeeds; zero
Sev-1/Sev-2 bugs open at go-live.

## Cross-cutting: Definition of Done (every module)

- [ ] Migrations reviewed (FKs, indexes, `down()` methods correct)
- [ ] Enums used for all status/type columns (no magic strings)
- [ ] Policies exist for every sensitive model; permission middleware on every route
- [ ] FormRequests validate all input; Actions hold business logic, not controllers
- [ ] Views follow `05-UI-UX.md` patterns using only `05a-TEMPLATE-MAP.md` components
- [ ] Pest feature tests: happy path, permission denial, cross-firm isolation
- [ ] Unit tests for any money/deadline/date logic
- [ ] `php artisan test`, `./vendor/bin/pint`, `./vendor/bin/phpstan analyse` all green
- [ ] Module's acceptance criteria (in its own spec) all checked
- [ ] `docs/00-INDEX.md` status updated

## Git & review workflow

- Trunk-based with short-lived feature branches per module/feature
  (`feat/m04-hearings`), Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`).
- CI on every push: Pest, Pint (fail on diff), Larastan, `composer audit`.
- No direct commits to `main`; every module lands via a reviewed PR referencing
  its spec file and ticking the Definition of Done.
- Tag a release at the end of each Phase (`v0.1-foundation`, `v0.2-matters`, …)
  so rollback points exist through the build.

## Testing strategy summary

| Layer | Tool | Focus |
|---|---|---|
| Unit | Pest | Services (Ledger, Numbering, Reminder), value objects (Money), Actions in isolation |
| Feature | Pest + `RefreshDatabase` | Full HTTP flow per route: happy path, validation errors, permission denial, cross-firm isolation |
| Invariant | Pest | Financial invariants (ledger always balances), deadline engine (reminder windows fire exactly once) |
| Static analysis | Larastan (level 6+) | Type safety, dead code, missing return types |
| Security | Custom route-audit test + manual pen-test (Phase 7) | Every route authorized; portal IDOR |

## Operational appendix: incident/backup basics

- **Data breach runbook** (outline): contain → assess scope → notify Firm Admin
  → preserve logs → notify affected data subjects per NDPR timelines → post-
  mortem. Full runbook fleshed out with the firm before go-live.
- **Backup restore drill**: monthly automated integrity check (Phase 5 gate) +
  one full manual restore rehearsal before go-live (Phase 8 gate).