MOPC-App/docs/codex-architecture-redesign-docs/06-implementation-roadmap-and-migration-plan.md

# 06. Implementation Roadmap And Migration Plan

## 1) Delivery Strategy
Use an incremental, low-risk migration with compatibility layers.

Execution mode:
- Additive schema first
- Dual-read where required
- Single-write to new contracts once validated
- Feature flags for runtime switches
- Rollback-safe at every phase gate

## 2) Phase Plan

## Phase 0: Contract Freeze And Blueprint Sign-Off

### Deliverables
- Approved Monaco flow contract (stage purpose keys, jury model, assignment semantics)
- Locked ADRs for major design choices
- Finalized open question decisions from `08-open-questions-for-flow-owners.md`

### Exit Criteria
- No unresolved P0 architecture questions
- Product + operations + engineering agreement on control-plane UX behavior

## Phase 1: Schema Foundation (Additive)

### Scope
- Add `stagePurposeKey`
- Add jury models (`Jury`, `JuryMembership`, `JuryStageBinding`)
- Add assignment policy models (`AssignmentPolicy`, `JudgePolicyOverride`, `AssignmentIntent`, `AssignmentException`)
- Add submission round models (`SubmissionRound`, bundle state fields)
- Add mentoring workspace + promotion models
- Add final confirmation models

### Data Migration Tasks
1. Backfill stage purpose keys from known stage names/slugs/types.
2. Create purpose-bound main juries for active Monaco programs with editable custom labels.
3. Create baseline assignment policies from existing stage config values.
4. Materialize current intake requirements into typed submission round artifacts.

### Exit Criteria
- All migrations run cleanly in staging
- Backfill report has zero unknown stage purpose for Monaco pipelines
- Referential integrity validated

## Phase 2: Policy Engine And Context Resolver

### Scope
- Build centralized `competitionContextResolver`
- Build centralized `policyResolver`
- Refactor assignment/filtering/live access paths to consume resolver

### Key Deliverables
- `resolveContext(program/stage/project/user)` service
- `resolveAssignmentPolicy(stageId, juryId, userId)`
- policy-aware access checks for docs/evaluations/live controls

### Exit Criteria
- No core router uses legacy ad hoc logic for stage/jury policy checks
- Policy resolution explainability endpoint available (admin debug)

## Phase 3: Invite/Member/Onboarding Integration (Critical)

### Scope
- Refactor admin member invite flow to create jury memberships plus dual pre-assignment modes (intent mode and direct policy-validated assignment mode)
- Align team invite flow with unified invitation context metadata
- Update accept-invite routing to membership-aware onboarding

### Key Deliverables
- `/admin/members/invite` UX and backend contract update
- `user.bulkCreate` migration to support both assignment intent creation and direct policy-validated assignments
- onboarding path resolver by role + memberships, including clear bias-disclosure text for jury onboarding

### Exit Criteria
- Invite-created users can be traced from invite -> membership -> assignment materialization
- No orphan invitation states
- Regression tests pass for admin invite + team invite + accept invite

## Phase 4: Submission Bundle Lifecycle + Document Locking

### Scope
- Introduce submission rounds and bundle states in runtime
- Enforce edit/read-only behavior by round and stage purpose
- Support provenance-aware promotion from mentor workspace

### Exit Criteria
- Applicants can only edit current round slots
- Judges can see current + prior bundles by policy
- Promotion events produce immutable trace

## Phase 5: Assignment Engine Hardening For Monaco Semantics

### Scope
- Implement strict hard/soft cap behavior with buffer
- Implement startup/concept weighting as soft-bias preference per judge (non-deterministic)
- Implement deterministic unassigned queue and manual fallback

### Exit Criteria
- Policy compliance report proves no hard-cap violations
- Soft-cap overflow behavior matches configured buffer rules
- Ratio/bias behavior is explainable and visibly disclosed as suggestive in onboarding and admin UI
- Manual queue receives all residual items with reasons

## Phase 6: Awards + Mentoring + Finals + Confirmation

### Scope
- Add award participation mode semantics, admin-confirmed pull-out flow, and single-judge award decision mode
- Complete mentor workspace file/comment/promotion behavior
- Link live finals to final confirmation workflow and result lock/unlock governance

### Exit Criteria
- Mode A/B award behavior validated in staging scenarios, including admin-confirmed pull-out
- Final confirmation requires configured jury agreement with quorum fallback + admin approval (or configured single-judge award path), with admin override support and audit trail
- Result lock snapshot generated and immutable until explicit super-admin unlock workflow is used

## Phase 7: UX Consolidation And Operator Experience

### Scope
- Simplify admin pipeline editors with purpose-aware controls
- Remove/disable ambiguous config controls
- Add context-rich dashboards and compliance panels

### Exit Criteria
- Operators can configure full Monaco flow without advanced/manual JSON edits
- Support docs and admin runbooks updated

## Phase 8: Cutover And Decommission Legacy Paths

### Scope
- Enable new contracts by default
- Deprecate legacy code paths and config fallback branches
- cleanup migration of deprecated fields where safe

### Exit Criteria
- Production traffic fully on new architecture
- Legacy path usage dashboards show zero critical usage
- post-cutover audit and incident-free burn-in period complete

## 3) Workstream Breakdown

## 3.1 Backend Workstream
- Schema/migrations
- Policy resolver
- Router refactors
- Event/audit normalization

## 3.2 Frontend Workstream
- Admin pipeline UX
- Member invite and onboarding flows
- Applicant/jury/mentor stage-aware views
- finals control + confirmation UI

## 3.3 Data/Operations Workstream
- Backfills and integrity checks
- Job monitoring and reconciliation scripts
- release runbooks and rollback procedures

## 3.4 QA Workstream
- End-to-end test scenarios for full Monaco flow
- policy compliance assertions
- performance and reliability testing

## 4) Migration Sequencing Rules
1. No destructive migration before dual-read period completes.
2. Every new write path must emit old + new audit evidence during transition.
3. Use idempotent backfills with resumable checkpoints.
4. Keep feature toggles per major subsystem (invite policy, assignment policy, docs, confirmation).

## 5) Rollback Strategy

### 5.1 Technical Rollback
- Feature flag rollback first
- Keep old write handlers until two stable releases after cutover
- Avoid schema drops until rollback window closes

### 5.2 Operational Rollback
- Predefined rollback runbook for each phase
- operator checklist for reverting admin workflows
- communication templates for judges/admins if rollback impacts active stages

## 6) Delivery Governance
- Weekly architecture sync (backend/frontend/product/ops)
- Phase gate reviews with evidence packages
- Strict “no silent contract drift” policy for late-stage changes

## 7) Suggested Initial Milestones (Order)
1. Approve purpose keys + jury model + assignment semantics.
2. Implement schema foundation and context resolver.
3. Integrate invite/onboarding/team flows.
4. Enforce round bundle lifecycle.
5. Harden assignment policy behavior.
6. Complete awards/mentoring/finals/confirmation chain.