update project

docs/release/api-client-migration.md

@@ -0,0 +1,20 @@
+# API Client Migration
+
+For each breaking change, document:
+
+- old endpoint
+- new endpoint
+- old request payload
+- new request payload
+- old response envelope
+- new response envelope
+- new authorization requirements
+- sunset date
+- migration notes
+
+## Example
+
+| Old | New | Notes |
+|---|---|---|
+| `GET /api/payments/file/{filename}` | `GET /api/v2/finance/payments/{payment}/file` | New route is payment-scoped and authorized. |
+| legacy bulk send route | `/api/v2/communication/bulk-sends` | Requires `preview_id` and `confirmation_token`. |

docs/release/feature-flag-rollout-map.md

@@ -0,0 +1,19 @@
+# Feature Flag Rollout Map
+
+Phase 10 requires every risky modular cutover to be flag-controlled by module, school, domain profile, environment, and owner. Flags default safe and must have removal targets where they are temporary.
+
+| Flag | Default | Owner | Rollout Scope | Removal Target |
+|---|---:|---|---|---|
+| `school_context.enabled` | on | Platform | global | permanent |
+| `finance.modular_file_access.enabled` | on | Finance | global, school | 2026-09-30 |
+| `finance.modular_payments.enabled` | off | Finance | school, role | 2026-12-31 |
+| `attendance.modular_scanner.enabled` | off | Attendance | school, route | 2026-12-31 |
+| `students.modular_creation.enabled` | off | Students | school, route | 2026-12-31 |
+| `communication.preview_required.enabled` | on | Communication | global | 2026-09-30 |
+| `communication.modular_send.enabled` | off | Communication | school, channel | 2026-12-31 |
+| `reporting.modular_reports.enabled` | off | Reporting | school, role | 2027-01-31 |
+| `api.v2.enabled` | off | API | school, user role | tbd |
+| `islamic_sunday_school.extension.enabled` | on | Islamic Sunday School | domain profile | permanent |
+| `boundary_enforcement.fail_ci.enabled` | off | Platform | repo/CI | 2026-10-31 |
+
+Rollout order: internal, staging, pilot tenant, Islamic Sunday School production, broader rollout, legacy removal. Do not advance tracks because someone vibes-based the dashboard. That is not a release criterion, it is astrology with logs.

docs/release/incident-response.md

@@ -0,0 +1,31 @@
+# Incident Response Plan
+
+## P0
+
+- cross-school data leak
+- unauthorized payment file access
+- incorrect payment balances at scale
+- bulk communication sent to wrong audience
+- sensitive report export leak
+- scanner outage during active session
+- student data corruption
+
+## P1
+
+- module unavailable
+- report incorrect for subset
+- payment edit failure
+- attendance duplicate spike
+- communication provider failure
+- Islamic extension profile unavailable
+
+## Response Steps
+
+1. Disable feature flag if applicable.
+2. Stop affected queues/jobs.
+3. Preserve logs and audit evidence.
+4. Notify owner/security/support.
+5. Run reconciliation.
+6. Apply rollback or forward fix.
+7. Document root cause.
+8. Add regression test.

docs/release/islamic-sunday-school-production-rollout.md

@@ -0,0 +1,24 @@
+# Islamic Sunday School Production Rollout
+
+Entry criteria:
+
+- `islamic_sunday_school.extension.enabled` configured
+- extension routes profile-gated
+- sensitive profile permissions verified
+- Qur'an, Arabic, Islamic studies, halaqa workflows tested
+- masjid family/community reports validated
+- communication preview tested for Qur'an class guardians
+
+Validation:
+
+- profile row school scope
+- sensitive note access audit
+- extension reports hidden outside Islamic Sunday School profile
+- halaqa attendance uses Attendance read model truth
+- extension communication resolvers cannot return another school's recipients
+
+Exit criteria:
+
+- domain owner signoff
+- no unresolved P0/P1 defects
+- post-rollout reconciliation complete

docs/release/legacy-removal-plan.md

@@ -0,0 +1,22 @@
+# Legacy Removal Plan
+
+Removal order:
+
+1. Disable legacy route behind flag.
+2. Monitor usage.
+3. Add deprecation warning/header.
+4. Notify clients/admins where needed.
+5. Remove route.
+6. Remove adapter controller.
+7. Remove legacy service method.
+8. Remove old tests.
+9. Remove old schema only after data retention review.
+
+Unsafe legacy routes to prioritize:
+
+- filename-based payment file route
+- blind bulk send route
+- unsafe student identifier generation path
+- legacy scanner mutation path
+
+Security defects outrank compatibility. The support team can survive complaints. They cannot unsend leaked data.

docs/release/migration-validation.md

@@ -0,0 +1,31 @@
+# Migration Validation
+
+Run:
+
+```bash
+php artisan app:release-migration-validate
+```
+
+Required validation areas:
+
+## Finance
+
+Validate invoice count, payment count, payment sums, outstanding balances, refund/reversal counts, payment file count, and finance audit count.
+
+## Attendance
+
+Validate attendance session count, record count, scan log count, duplicate scan behavior, student/staff separation, and manual override audits.
+
+## Students
+
+Validate student count by school, guardian links, enrollment rows, assignment rows, identifier uniqueness, and Islamic Sunday School extension profile linkage.
+
+## Communication
+
+Validate recipient previews, dedupe counts, preference exclusions, message logs, delivery attempts, and provider callback mapping.
+
+## Reporting
+
+Validate report registry entries, export audit logs, report snapshots, Islamic reports, and scheduled report recipient authorization.
+
+All validation output is written to `storage/app/generated/release-validation/validation-summary.json`.

docs/release/monitoring-dashboards.md

@@ -0,0 +1,40 @@
+# Monitoring Dashboards and Alerts
+
+## Platform
+
+Track request count, error rate, latency, context resolution failures, wrong-school attempts, authorization failures, and feature flag state by school.
+
+## Finance Alerts
+
+- balance mismatch detected
+- payment mutation without audit log
+- wrong-school payment file attempt
+- finance exception spike
+
+## Attendance Alerts
+
+- scanner error spike
+- duplicate scan spike
+- badge not found spike
+- attendance mutation without audit
+
+## Students Alerts
+
+- identifier collision spike
+- student creation failure spike
+- wrong-school guardian link attempt
+
+## Communication Alerts
+
+- bulk send without preview attempt
+- provider failure spike
+- retry storm
+- wrong-school recipient attempt
+
+## Reporting Alerts
+
+- sensitive export by unauthorized actor
+- report export without audit
+- scheduled report failure spike
+
+Wire this document to your observability platform. Markdown cannot page anyone, which is merciful but useless.

docs/release/performance-readiness.md

@@ -0,0 +1,23 @@
+# Performance Readiness Review
+
+Baseline before rollout:
+
+- SchoolContext resolution overhead
+- student list response time
+- scanner process latency
+- payment record/edit latency
+- recipient preview generation time
+- bulk send queueing time
+- report run time
+- export generation time
+
+Known risks:
+
+- unscoped queries
+- N+1 resources
+- large recipient previews
+- large exports
+- scanner latency during active check-in
+- extension table joins in reports
+
+Correctness wins first. Fast wrong answers are still wrong, just with better posture.

docs/release/pilot-rollout-plan.md

@@ -0,0 +1,26 @@
+# Pilot Rollout Plan
+
+Pilot entry criteria:
+
+- feature flags configured
+- staging validation passed
+- shadow comparisons reviewed
+- monitoring dashboard ready
+- rollback rehearsed
+- support briefed
+
+Pilot sequence:
+
+1. Enable read-only SchoolContext enforcement.
+2. Enable hardened payment file access.
+3. Enable communication preview requirement.
+4. Enable student identifier modular path.
+5. Enable one high-risk mutation path at a time.
+6. Review daily metrics and support tickets.
+
+Pilot exit criteria:
+
+- no unresolved P0/P1 defects
+- reconciliation passes
+- support playbook validated
+- owner signoff recorded

docs/release/post-release-review-template.md

@@ -0,0 +1,34 @@
+# Post-Release Review Template
+
+## Release
+
+- Module:
+- Date:
+- Schools/Tenants:
+- Flags enabled:
+
+## Metrics
+
+- Incidents:
+- Support tickets:
+- Error rate:
+- Latency:
+- Reconciliation status:
+- Audit completeness:
+
+## Findings
+
+- What worked:
+- What failed:
+- Missed tests:
+- Missed docs:
+- Performance issues:
+- Security findings:
+
+## Follow-Up
+
+- Regression tests to add:
+- Docs to correct:
+- Legacy paths to remove:
+- Flags to retire:
+- Owners:

docs/release/production-readiness-review.md

@@ -0,0 +1,25 @@
+# Production Readiness Review
+
+Required attendees:
+
+- platform owner
+- module owner
+- security reviewer
+- QA/test owner
+- support owner
+- Islamic Sunday School domain owner, if extension affected
+- finance owner, if finance affected
+
+Checklist:
+
+- [ ] tests pass
+- [ ] architecture checks pass
+- [ ] migration validation passes
+- [ ] shadow comparison mismatches reviewed
+- [ ] rollback plan approved
+- [ ] monitoring ready
+- [ ] support docs ready
+- [ ] UAT signoff complete
+- [ ] owner approval recorded
+- [ ] feature flags configured and auditable
+- [ ] legacy unsafe routes disabled or scheduled

docs/release/rollback-playbooks.md

@@ -0,0 +1,44 @@
+# Rollback Playbooks
+
+Rollback should prefer feature flags over destructive database rollback.
+
+## Finance
+
+1. Disable `finance.modular_payments.enabled` or `finance.modular_file_access.enabled`.
+2. Preserve audit/idempotency logs.
+3. Run finance reconciliation.
+4. Review payment/invoice deltas with finance owner.
+5. Apply forward-fix migration if production writes occurred.
+
+## Attendance
+
+1. Disable attendance scanner/manual override flags.
+2. Preserve scan logs.
+3. Run duplicate/missing attendance reconciliation.
+4. Notify operations if scanner behavior changed.
+
+## Students
+
+1. Disable modular creation/enrollment flags.
+2. Run student/guardian/enrollment count validation.
+3. Check identifier uniqueness and collision logs.
+4. Repair only through audited scripts.
+
+## Communication
+
+1. Disable modular send flag.
+2. Stop scheduled send queues if needed.
+3. Check idempotency and message logs before retrying anything.
+4. Verify no duplicate sends are pending.
+
+## Reporting
+
+1. Disable modular report flag.
+2. Disable scheduled reports if sensitive exports are affected.
+3. Preserve report snapshot/export audit logs.
+
+## Islamic Sunday School Extension
+
+1. Disable extension flag only if extension workflows are unsafe.
+2. Preserve sensitive access audit logs.
+3. Validate profile/report access permissions before re-enable.

docs/release/security-readiness.md

@@ -0,0 +1,15 @@
+# Security Readiness Review
+
+Required checks before production rollout:
+
+- Cross-school access tests pass.
+- Wrong-role access tests pass.
+- Payment file access is payment-scoped and authorized.
+- Bulk communication requires preview and confirmation token.
+- Report export requires explicit export permission.
+- Extension routes require `islamic_sunday_school` domain profile.
+- Sensitive Islamic Sunday School profile fields require explicit permission.
+- Provider callbacks are signature-verified where applicable.
+- Risky endpoints have rate limits.
+
+High-risk extension data includes imam/admin sensitive notes, Qur'an/Arabic/Islamic studies placement details, scholarship/sadaqah support indicators, family/community profile notes, and guardian contact information.

docs/release/shadow-comparison-plan.md

@@ -0,0 +1,19 @@
+# Shadow Comparison Plan
+
+Run:
+
+```bash
+php artisan app:release-shadow-compare
+```
+
+Shadow mode compares legacy output to modular output without double-writing or double-sending. This matters because duplicating payments, attendance records, or family messages in the name of testing is the kind of innovation nobody asked for.
+
+## Required Comparisons
+
+- Finance: legacy balance vs modular BalanceCalculator/read model.
+- Attendance: legacy scanner result vs modular ScannerService result.
+- Students: legacy creation payload vs modular DTO/identifier strategy.
+- Communication: legacy recipient query vs modular preview/dedupe/preferences.
+- Reporting: legacy report output vs modular read-model-backed report.
+
+Mismatch reports must include school, scenario, legacy value, modular value, severity, and owner.

docs/release/support-playbooks.md

@@ -0,0 +1,29 @@
+# Support Playbooks
+
+## Payment Balance Discrepancy
+
+Collect school, invoice, payment IDs, actor, timestamp, idempotency key, audit entries, and reconciliation output. Disable modular payment flag only if discrepancy is systemic.
+
+## Scanner Not Recognizing Badge
+
+Collect badge value hash, station, school, timestamp, scanner response, badge lookup result, and attendance audit logs. Check duplicate window and school scope.
+
+## Duplicate Scan Complaint
+
+Check idempotency records, scan logs, duplicate_of links, and attendance record first_seen/last_seen values.
+
+## Guardian Cannot See Student
+
+Check guardian/student relationship, school scope, permissions, relationship visibility, and resource masking.
+
+## Bulk Message Sent to Unexpected Recipients
+
+Collect preview ID, confirmation token, recipient snapshot, dedupe output, exclusions, and message logs. Do not retry until idempotency and delivery logs are reviewed.
+
+## Report Export Missing Data
+
+Check report filters, column permissions, read model freshness, snapshot ID, export audit, and sensitive column policy.
+
+## Islamic Profile Field Missing or Unauthorized
+
+Check domain profile, extension flag, permission, sensitive field policy, and audit access record.

docs/release/training-guides.md

@@ -0,0 +1,14 @@
+# Training Guides Index
+
+Create role-specific guides before pilot rollout:
+
+- Admin quick guide
+- Finance quick guide
+- Attendance/scanner quick guide
+- Student lifecycle quick guide
+- Communication preview/send guide
+- Reporting/export guide
+- Islamic Sunday School extension guide
+- Support escalation guide
+
+Each guide should include before/after behavior, screenshots from the real app, permission notes, and escalation path. Do not hand users an architecture diagram and call it training. That is how resentment gets versioned.

docs/release/uat-scenarios.md

@@ -0,0 +1,48 @@
+# UAT Scenarios
+
+## Admin
+
+- Create student.
+- Link guardian.
+- Enroll student.
+- Assign class/group.
+- Record payment.
+- Download payment file.
+- Send bulk communication with preview.
+- Export student roster.
+
+## Teacher / Staff
+
+- View assigned students.
+- Record attendance.
+- Scan check-in/check-out.
+- Manual override if permitted.
+- View attendance summary.
+- Send class communication if permitted.
+
+## Finance User
+
+- Record payment.
+- Edit payment with reason.
+- Reverse/refund payment.
+- View invoice balance.
+- Export outstanding balance report.
+
+## Islamic Sunday School
+
+- Create Islamic Sunday School student profile.
+- Assign Qur'an level.
+- Assign Arabic level.
+- Assign Islamic studies track.
+- Assign halaqa/group.
+- Record Sunday program attendance.
+- View Qur'an progress report.
+- Message Qur'an class guardians with preview.
+- Export masjid family/community summary with permissions.
+
+## Guardian / Parent
+
+- View own student profile.
+- View allowed attendance and finance details.
+- Receive communication.
+- Fail to see unrelated students and sensitive notes.