emba-course-solver/openspec/changes/emba-specialization-solver/specs/optimization-engine/spec.md

ADDED Requirements

Requirement: Credit allocation feasibility check

The system SHALL determine whether a target set of specializations can each reach 9 credits given a fixed set of selected courses. The check SHALL use linear programming to find a feasible allocation of credits from courses to specializations, subject to: each course allocates at most 2.5 credits total, only qualifying course-specialization pairs receive credits, and all allocations are non-negative.

Scenario: Feasible allocation exists

• WHEN checking feasibility for {Finance, Corporate Finance} with courses that include Valuation, Corporate Finance, The Financial Services Industry, and Behavioral Finance
• THEN the check returns feasible with an allocation where each target spec has at least 9.0 allocated credits and no course exceeds 2.5 total

Scenario: Infeasible allocation

• WHEN checking feasibility for {Finance, Corporate Finance, Banking} with only 3 qualifying courses across those specs
• THEN the check returns infeasible (7.5 total credits cannot satisfy 27 credits needed)

Requirement: Required course gate enforcement

Before checking LP feasibility for a target set, the system SHALL verify that every specialization in the target set with a required course gate has its required course present in the selected courses. If any required course is missing, the specialization SHALL be excluded from candidates.

Scenario: Required course present

• WHEN Entertainment Media and Technology is in the target set and Entertainment and Media Industries is among selected courses
• THEN EMT passes the required course gate and proceeds to LP feasibility

Scenario: Required course absent

• WHEN Brand Management is in the target set but Brand Strategy is not among selected courses
• THEN Brand Management is excluded from candidates without running the LP

Requirement: Strategy S2 constraint

When Strategy is in the target set, the system SHALL enforce that at most one S2-marked course contributes credits to Strategy. The system SHALL enumerate each possible S2 choice (including no S2 course) and check feasibility for each, returning feasible if any S2 choice produces a feasible allocation.

Scenario: Multiple S2 courses selected

• WHEN the selected courses include Digital Strategy (S2), Private Equity (S2), and Managing Change (S2), and Strategy is in the target set
• THEN the system checks 4 LP variants (one per S2 course contributing + none contributing) and returns the best feasible result

Scenario: No S2 courses selected

• WHEN no S2-marked courses are among the selected courses and Strategy is in the target set
• THEN only S1-marked courses contribute to Strategy and a single LP check is performed

Requirement: Maximize Count optimization mode

In maximize-count mode, the system SHALL find the largest set of achievable specializations. It SHALL enumerate candidate subsets from size 3 down to 0, checking LP feasibility for each. Among all feasible subsets of the maximum size, it SHALL select the subset with the highest priority score, computed as the sum of (15 minus rank position) for each specialization in the subset.

Scenario: Three specializations achievable

• WHEN running maximize-count with courses that can feasibly support 3 specializations
• THEN the result contains exactly 3 achieved specializations and the system has verified no 3-subset with a higher priority score is also feasible

Scenario: Tie-breaking by priority

• WHEN two different 2-specialization subsets are both feasible
• THEN the system selects the subset whose priority score (sum of 15 minus rank for each spec) is higher

Scenario: No specializations achievable

• WHEN no pinned courses are selected (all sets open)
• THEN the result contains 0 achieved specializations from pinned courses alone

Requirement: Priority Order optimization mode

In priority-order mode, the system SHALL process specializations in the user's ranked order. For each specialization, it SHALL check whether adding it to the current achieved set remains LP-feasible. If feasible, the specialization is added; if not, it is skipped. Processing continues through all 14 specializations.

Scenario: Top-ranked specialization guaranteed

• WHEN the #1-ranked specialization is achievable on its own
• THEN it is included in the result, even if including it reduces the total achievable count compared to maximize-count mode

Scenario: Lower-ranked spec skipped when infeasible

• WHEN the #3-ranked specialization cannot be added to the set {#1, #2} without violating credit constraints
• THEN #3 is skipped and the system proceeds to check #4

Requirement: Per-specialization status determination

After optimization, the system SHALL assign each specialization one of four statuses: achieved (allocated credits >= 9 and required course present), achievable (not achieved but reachable through courses in open sets), missing_required (enough credits theoretically possible but required course not selected and not available in any open set), or unreachable (maximum potential credits from selected plus open sets < 9).

Scenario: Achieved status

• WHEN a specialization has 9+ allocated credits and its required course (if any) is selected
• THEN its status is achieved

Scenario: Achievable status

• WHEN a specialization is not achieved but qualifying courses exist in open sets that could bring credits to 9+
• THEN its status is achievable

Scenario: Missing required status

• WHEN a specialization's required course is not selected and the set containing it is already pinned to a different course
• THEN its status is missing_required

Scenario: Unreachable status

• WHEN maximum potential credits (selected qualifying courses × 2.5 + open sets with qualifying courses × 2.5) is less than 9
• THEN its status is unreachable

Requirement: Credit allocation output

When the optimization produces achieved specializations, the system SHALL output the full credit allocation: for each selected course, how many credits are allocated to each qualifying specialization. The sum of allocations per course SHALL NOT exceed 2.5. The sum of allocations per achieved specialization SHALL be at least 9.0.

Scenario: Allocation detail

• WHEN viewing results after optimization
• THEN each achieved specialization shows which courses contribute credits and the amount from each, and the total per course across all specializations does not exceed 2.5

Requirement: Upper-bound reachability computation

The system SHALL compute an upper-bound credit potential per specialization by summing 2.5 for each qualifying selected course plus 2.5 for each open set containing a qualifying course. This upper bound SHALL ignore credit sharing and be used only for reachability status determination, not for allocation.

Scenario: Upper bound with open sets

• WHEN a specialization has 2 qualifying pinned courses and 3 open sets with qualifying courses
• THEN the upper-bound potential is 12.5 (5 × 2.5)

Requirement: Decision tree per-choice ceiling computation

For each open set, for each course choice in that set, the system SHALL compute the ceiling outcome: the best achievable result assuming that course is pinned and all other open sets are chosen optimally. The system SHALL enumerate remaining open-set combinations and run the full optimization for each, returning the best result found.

Scenario: Choice enables higher ceiling

• WHEN in Spring Set 2, choosing The Financial Services Industry
• THEN the ceiling computation evaluates all combinations of other open sets and reports the best achievable specialization count and set

Scenario: Early termination at max ceiling

• WHEN a course choice's ceiling reaches 3 specializations (the maximum)
• THEN the system stops enumerating remaining combinations for that choice

Requirement: Decision tree impact ordering

Open sets in the decision tree SHALL be ordered by decision impact, defined as the variance in ceiling outcomes across course choices within the set. Sets where all course choices produce the same ceiling outcome SHALL be ranked lowest. Sets where course choices produce different ceiling outcomes SHALL be ranked highest.

Scenario: High-impact set

• WHEN an open set has 4 courses where one leads to ceiling 3 and the others lead to ceiling 2
• THEN this set is ranked higher than a set where all 4 courses lead to ceiling 3

Scenario: Equal-impact sets

• WHEN two open sets have identical variance in ceiling outcomes
• THEN they are ordered by term chronology (Spring before Summer before Fall)

Requirement: Computation tiering

The system SHALL compute results in three tiers: instant upper-bound reachability on the main thread (runs on every interaction), fast LP optimization on pinned courses only on the main thread, and background decision tree enumeration in a Web Worker (debounced 300ms after user interaction). When 10 or more sets are open, the system SHALL skip background enumeration and show only upper-bound reachability for the decision tree.

Scenario: Instant feedback

• WHEN the user pins a course
• THEN upper-bound reachability and pinned-course optimization results update immediately (within one render cycle)

Scenario: Background tree computation

• WHEN the user has 6 open sets and changes a pin
• THEN the decision tree begins computing in a Web Worker after 300ms of inactivity and updates the UI progressively as each open set's analysis completes

Scenario: Fallback for many open sets

• WHEN 10 or more sets are open
• THEN the decision tree shows upper-bound reachability only, without ceiling computation