# Open Questions & Governance ## Overview This document tracks all design decisions — resolved and remaining — and defines the governance process for the redesign. Resolved decisions are numbered for reference. Remaining questions are prioritized (P1 = must resolve before implementation, P2 = can resolve during implementation). --- ## Resolved Decisions | # | Decision | Resolution | Resolved By | |---|----------|------------|-------------| | 1 | **Winner count per category** | Top N (configurable, default 3). All projects ranked within category. Podium UI for top 3. Cross-category comparison view. | User Q&A | | 2 | **Score model for final winners** | Jury 3 live scores only for final winner determination. All-jury composite rankings available in reports/analytics. Configurable between "Jury 3 only" and "Jury 3 + audience blend" per competition. | User Q&A | | 3 | **Cross-jury visibility** | Fully independent during active evaluation — no cross-jury score visibility. During Live Finals (R7) and Deliberation (R8), prior jury scores/feedback/notes visible to Jury 3 **if admin enables** (`showPriorJuryData` toggle). All cross-jury data available in reports section for internal analytics. | User Q&A | | 4 | **Confirmation model** | Deliberation IS the confirmation — no separate WinnerProposal → jury sign-off → admin approval. Deliberation voting serves as jury agreement. Replaces "all jury agree + admin approval" from original flow spec. | User Q&A | | 5 | **Deliberation modes** | Two admin-configurable modes: SINGLE_WINNER_VOTE (each juror picks one winner) and FULL_RANKING (ordinal 1st, 2nd, 3rd... aggregated via Borda count). | User Q&A | | 6 | **Deliberation scope** | Separate per category (Startup and Concept deliberations are independent sessions). No deliberation for special awards — awards decided by their own jury/judge mechanism. | User Q&A | | 7 | **Tie-breaking** | Multiple methods supported: runoff vote (new vote with tied projects only), admin tie-break (admin decides between tied), admin override (override entire result). All configurable per deliberation session. | User Q&A | | 8 | **Post-deliberation flow** | Admin reviews final deliberation result → locks → ResultLock snapshot created. Unlock requires super-admin with mandatory reason. | User Q&A | | 9 | **Soft-cap buffer** | Default +10 over the soft cap. Configurable per JuryGroup via `softCapBuffer` field. | User Q&A | | 10 | **Startup/concept ratio** | Suggestive bias only (not deterministic). Disclosed to judges. Judges see a note like "You have been assigned primarily Startup projects based on your preference." | User Q&A | | 11 | **Mode A pull-out** | Admin-confirmed (`routingConfirmationMode: ADMIN_CONFIRMED`). Admin must review and approve which projects are pulled from the main pool into the award pool. | User Q&A | | 12 | **File promotion authority** | Team lead and admin can promote mentor workspace files to official submissions. Mentor can promote IF admin enables it per competition. | User Q&A | | 13 | **Invite pre-assignment** | Both modes supported: AssignmentIntent (intent at invite time, honored by algorithm) and direct admin assignment. | User Q&A | | 14 | **Jury absence handling** | Quorum fallback with participant status types: REQUIRED, ABSENT_EXCUSED, REPLACED, REPLACEMENT_ACTIVE. Absent-excused don't count toward quorum. Admin can replace juror or mark as excused. | User Q&A | | 15 | **Result unlock** | Super-admin only, mandatory reason. Creates ResultUnlockEvent with audit trail. | User Q&A | | 16 | **Jury naming** | Custom labels per program. JuryGroup has a `label` field (e.g., "Jury 1", "Selection Panel", "Live Finals Jury"). | User Q&A | | 17 | **Judge onboarding self-service** | Judges CAN adjust their cap and category ratio preference during onboarding. Admin-configurable toggle (`allowOnboardingSelfService`) to enable/disable per JuryGroup. | Flow spec + Q&A | | 18 | **AI ranked shortlist** | AI generates recommended ranked shortlist per category at the end of EVERY evaluation round (Jury 1, Jury 2, and any award evaluation). Admin can always override. | Flow spec + Q&A | | 19 | **Audience vote totals** | Shown to Jury 3 during deliberation phase. Configurable reveal timing (real-time, after jury vote, at deliberation). | Flow spec + Q&A | | 20 | **Assignment intent lifecycle** | Full lifecycle tracking: PENDING → HONORED (algorithm matched) / OVERRIDDEN (admin changed) / EXPIRED (round closed) / CANCELLED (removed). All terminal states immutable. See [04-jury-groups-and-assignment-policy.md](./04-jury-groups-and-assignment-policy.md). | Gap analysis | | 21 | **Submission bundle state** | **REJECTED** — Per-file tracking with SubmissionWindow enforcement is simpler than a formal SubmissionBundle entity. Completeness is derived from slot requirements vs. uploaded files. See Rejected Alternatives below. | Gap analysis | | 22 | **Purpose keys for analytics** | Optional `Round.purposeKey: String?` for analytics grouping (e.g., "jury1_selection", "semifinal_docs"). NOT a new enum — purely semantic. RoundType + label is sufficient for routing; purposeKey is for cross-competition reporting only. | Gap analysis | | 23 | **Enhanced audit with before/after state** | `DecisionAuditLog.details` JSON field already supports before/after state. Convention: include `{ before: {...}, after: {...} }` structure for all override actions. No new DB fields needed — documented as convention. | Gap analysis | --- ## Rejected Alternatives Design concepts from the Codex architecture plan that were evaluated and rejected in favor of simpler approaches: | # | Concept | Source | Rejection Rationale | |---|---------|--------|-------------------| | R1 | **SubmissionBundle entity** | Codex docs | Added complexity without benefit. Per-file tracking with `SubmissionWindow` + slot requirements achieves the same completeness tracking. Deriving bundle state from `required slots - uploaded files` is simpler than maintaining a separate state machine. | | R2 | **FinalConfirmation as separate step** | Codex docs | Merged into Deliberation per Decision #4. Deliberation voting IS the confirmation — a separate WinnerProposal → jury sign-off → admin approval flow added unnecessary ceremony. Admin reviews and locks the deliberation result directly. | | R3 | **Purpose Keys as enum** | Codex docs | Made optional `String?` instead of enum (Decision #22). A fixed enum would require schema migration for each new analytics category. Free-text purposeKey with conventional values is more flexible. | | R4 | **Jury-Stage binding** | Codex docs | JuryGroups are independent entities linked to rounds via `roundId`, not bound to stages. This allows a jury to be reused across competitions and rounds without schema changes. | --- ## Ambiguity Log Design decisions where both approaches were viable. Documenting the trade-off for future reference: | # | Ambiguity | Decision | Trade-Off | |---|-----------|----------|-----------| | A1 | **Cap enforcement: strict vs. flexible** | 3-mode system (HARD/SOFT/NONE) | More complex than binary on/off, but covers all real-world scenarios. SOFT mode with buffer is the common case. | | A2 | **Cross-jury data visibility: always vs. configurable** | Configurable per round via `showPriorJuryData` | Default OFF prevents bias, but some programs want continuity. Toggle gives admin control. | | A3 | **Deliberation mode: single vs. dual** | Both modes supported (SINGLE_WINNER_VOTE / FULL_RANKING) | Two code paths to maintain, but programs have genuinely different needs. Borda count for detailed ranking, simple vote for quick decisions. | | A4 | **Document mutability: immutable vs. admin-replaceable** | Admin can replace with full provenance tracking | Trades simplicity for flexibility. Provenance chain (`replacedById`, audit log) ensures accountability. | --- ## Remaining P1 Questions (Before UI/Router Refactor) These must be resolved before starting Phase 5 (Admin Control Plane + Participant UX): ### P1-1: Mentoring Scope **Question**: Is mentoring available only to finalists, or configurable to include semi-finalists? **Options**: - A) Finalists only (simplest, matches current flow) - B) Configurable via `MentoringConfig.eligibility` enum: FINALISTS_ONLY | SEMIFINALISTS_AND_ABOVE | CONFIGURABLE **Impact**: Affects who sees the "Request Mentor" toggle and when mentor assignment runs. **Current leaning**: The `MentoringConfig` already has an `eligibility` field with options. Implement B for flexibility. --- ### P1-2: Document Mutability After Lock **Question**: Can admins replace locked (read-only) submissions from prior rounds? **Options**: - A) No — once a round's docs are locked, they're immutable for everyone - B) Yes — admin can replace with full provenance (`sourceType: ADMIN_REPLACEMENT`) **Impact**: Affects document lifecycle rules and audit requirements. **Current leaning**: B — admin override everywhere is a guiding principle. Provenance tracking ensures accountability. --- ### P1-3: Audience Reveal Timing **Question**: Are audience vote totals visible to Jury 3 in real time during the live event, or only when deliberation begins? **Options**: - A) Real-time (jury sees audience votes as they come in) - B) After jury vote (jury submits their scores first, then audience results revealed) - C) At deliberation start (audience results shown when deliberation session opens) - D) Configurable via `LiveFinalConfig.audienceRevealTiming` **Impact**: Affects whether audience votes can bias Jury 3 scoring. **Current leaning**: D — make it configurable. Default to C (at deliberation start) to prevent audience bias on jury scores. --- ## Remaining P2 Questions (Can Resolve During Implementation) ### P2-1: Reporting Visibility **Question**: Are per-jury compliance reports (assignment coverage, evaluation completion, etc.) visible to all program admins or super-admin only? **Impact**: Affects report page access control. --- ### P2-2: Override Transparency **Question**: Which override details are visible to jury users? For example, if admin overrides a judge's assignment, does the judge see "Admin assigned this project to you" or just the project appearing? **Impact**: Affects jury dashboard messaging. --- ### P2-3: Notification Triggers **Question**: What exact round transitions trigger applicant email notifications? (e.g., "You've advanced to the semi-finals", "Your submission window is open", "You've been selected as a finalist") **Impact**: Affects notification service configuration. --- ### P2-4: CSV Bulk Invite **Question**: What columns should the CSV bulk invite format include? Current thinking: name, email, role, juryGroupLabel, roundLabel, preAssignmentMode (INTENT | DIRECT), maxProjects, categoryBias. **Impact**: Affects invite import service. --- ## Delivery Governance ### Weekly Architecture Sync - **Who**: Backend lead, frontend lead, product owner, ops - **When**: Weekly, 30 minutes - **Agenda**: Phase progress, blockers, upcoming decisions, contract drift review ### Phase Gate Reviews Each phase completion triggers a review: 1. Deliverables checklist reviewed 2. Release gate criteria verified (see [12-observability-and-release-gates.md](./12-observability-and-release-gates.md)) 3. Test results reviewed 4. Any outstanding P1 questions flagged 5. Sign-off from architecture owner and product owner ### No Silent Contract Drift After Phase 0 (Contract Freeze), any change to the following requires explicit review: | Change Type | Approval Required | |-------------|-------------------| | Prisma model addition or field change | Architecture owner | | Zod config schema modification | Architecture owner | | RoundType enum change | Architecture owner + product owner | | tRPC procedure signature change | Architecture owner | | Assignment policy behavior change | Architecture owner + product owner | | New feature flag addition | Architecture owner | Changes are NOT blocked — they require documentation (what changed, why, impact) and sign-off. ### Evidence Package Template Each phase gate review includes: ``` Phase [X] Evidence Package - Date: YYYY-MM-DD - Phase: [name] - Status: PASS / CONDITIONAL PASS / FAIL Deliverables: - [ ] [deliverable 1] — status, link to PR/commit - [ ] [deliverable 2] — status Test Results: - Unit: X/X passing - Integration: X/X passing - E2E: X/X passing Release Gate: [A/B/C/D/E/F] - [ ] Criterion 1 — status - [ ] Criterion 2 — status Open Items: - [any blockers or deferred items] Sign-off: - Architecture: [name] [date] - Product: [name] [date] ``` --- ## Reference Monaco 2026 Configuration A concrete example showing how the Monaco 2026 competition would be configured in the redesigned system: ```yaml competition: name: "Monaco Ocean Protection Challenge 2026" programId: "monaco-opc-2026" status: DRAFT rounds: - order: 1 label: "Application Window" type: INTAKE config: deadlinePolicy: FLAG # accept late with flag requiredDocSlots: ["executive_summary", "business_plan", "team_profile"] - order: 2 label: "AI Eligibility Screening" type: FILTERING config: aiEnabled: true autoAdvanceEligible: false # admin reviews before advancing - order: 3 label: "Jury 1 — Semi-Finalist Selection" type: EVALUATION juryGroupId: jury-1 config: scoringRubric: { criteria: [...], maxScore: 100 } requireFeedback: true generateAiShortlist: true - order: 4 label: "Semi-Finalist Documents" type: SUBMISSION config: requiredDocSlots: ["updated_business_plan", "financial_projections", "impact_report"] lockPriorRoundDocs: true deadlinePolicy: HARD - order: 5 label: "Jury 2 — Finalist Selection" type: EVALUATION juryGroupId: jury-2 config: scoringRubric: { criteria: [...], maxScore: 100 } requireFeedback: true generateAiShortlist: true showPriorJuryData: false # independent evaluation - order: 6 label: "Finalist Mentoring" type: MENTORING config: eligibility: FINALISTS_ONLY requireMentorRequest: true assignmentMethod: MANUAL allowMentorPromotion: false - order: 7 label: "Live Finals — Jury 3" type: LIVE_FINAL juryGroupId: jury-3 config: audienceVotingEnabled: true audienceRevealTiming: AT_DELIBERATION audienceBlendWeight: 0 # jury only for scoring showPriorJuryData: true # Jury 3 sees prior jury history scoringMode: CRITERIA_BASED presentationOrder: MANUAL - order: 8 label: "Final Deliberation" type: DELIBERATION juryGroupId: jury-3 config: mode: FULL_RANKING showCollectiveRankings: true tieBreakMethod: ADMIN_DECIDES topN: 3 allowAdminOverride: true juryGroups: - label: "Jury 1" defaultCapMode: SOFT defaultMaxProjects: 15 softCapBuffer: 10 allowOnboardingSelfService: true defaultCategoryBias: { STARTUP: 0.5, BUSINESS_CONCEPT: 0.5 } - label: "Jury 2" defaultCapMode: SOFT defaultMaxProjects: 10 softCapBuffer: 10 allowOnboardingSelfService: true - label: "Jury 3 — Live Finals" defaultCapMode: NONE # all finalists reviewed allowOnboardingSelfService: false specialAwards: - name: "Innovation Award" routingMode: STAY_IN_MAIN eligibilityMode: AI_SUGGESTED winnerDecisionMode: JURY_VOTE juryGroupLabel: "Innovation Award Panel" - name: "Ocean Impact Award" routingMode: SEPARATE_POOL pullOutBehavior: KEEP_IN_BOTH routingConfirmationMode: ADMIN_CONFIRMED eligibilityMode: AI_SUGGESTED winnerDecisionMode: SINGLE_JUDGE singleJudgeLabel: "Impact Award Chair" submissionWindows: - label: "Round 1 Application Documents" roundOrder: 1 requirements: - slotKey: "executive_summary" label: "Executive Summary" required: true acceptedTypes: ["application/pdf"] - slotKey: "business_plan" label: "Business Plan" required: true acceptedTypes: ["application/pdf"] - slotKey: "team_profile" label: "Team Profile" required: true acceptedTypes: ["application/pdf"] - label: "Round 2 Semi-Finalist Documents" roundOrder: 4 requirements: - slotKey: "updated_business_plan" label: "Updated Business Plan" required: true - slotKey: "financial_projections" label: "Financial Projections" required: true - slotKey: "impact_report" label: "Environmental Impact Report" required: true ``` This configuration, when loaded into the system, would create the full Monaco 2026 competition with all 8 rounds, 3 main juries, 2 special awards, and 2 submission windows — ready for admin to set dates and invite jury members.