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.