# Configurable Maximize Criteria Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Make the maximize criteria a parameter of `solve()`: a factors dict (E/B/S/C) plus a "product"/"sum" mode, defaulting to the current hardcoded `E²·B·S²` product. **Architecture:** All changes live in `solve.py`. Module-level defaults (`OBJECTIVE_FACTORS`, `OBJECTIVE_MODE`) follow the existing `INITIAL`/`FIXED_CHOICES` pattern; `solve()` resolves `None` args to them (same convention as `resource_constraints`). The hand-chained `AddMultiplicationEquality` objective block is replaced by a generic fold (product mode) or a single linear `Maximize` (sum mode). Phase-1 ceilings are computed only for resources with a nonzero factor. `_report` prints the expression that was actually maximized. **Tech Stack:** Python 3.13, Google OR-Tools CP-SAT (`cp_model`). **Spec:** `docs/superpowers/specs/2026-06-11-configurable-objective-design.md` **Testing:** Per user instruction, no automated tests — the user validates manually. --- ### Task 1: Module-level defaults and validation helper **Files:** - Modify: `solve.py` (PARAMETERS section, after `RESOURCE_CONSTRAINTS` at ~line 68) - [ ] **Step 1: Add the defaults and `_validate_objective`** Insert after the `RESOURCE_CONSTRAINTS = []` line: ```python # Maximize criteria for solve(). Factor = exponent in "product" mode, # weight in "sum" mode. Keys: E, B, S, C; missing keys = 0 (resource # excluded from the objective — it is NOT forced to zero). Negative # factors are allowed only in "sum" mode (a negative exponent would mean # division, which integer CP-SAT cannot express). OBJECTIVE_FACTORS = {"E": 2, "B": 1, "S": 2} OBJECTIVE_MODE = "product" # "product" or "sum" def _validate_objective(factors, mode): if mode not in ("product", "sum"): raise ValueError(f"objective_mode must be 'product' or 'sum', got {mode!r}") unknown = set(factors) - {"E", "B", "S", "C"} if unknown: raise ValueError(f"unknown objective_factors keys: {sorted(unknown)}") for k, v in factors.items(): if not isinstance(v, int) or isinstance(v, bool): raise ValueError(f"objective factor {k}={v!r} must be an int") if mode == "product" and v < 0: raise ValueError( f"objective factor {k}={v} is negative; negative exponents " "are not expressible in product mode" ) if not any(factors.values()): raise ValueError("objective_factors needs at least one nonzero factor") ``` (The `isinstance(v, bool)` check exists because `bool` is a subclass of `int` in Python; `True` as a factor is almost certainly a caller bug.) - [ ] **Step 2: Commit** ```bash git add solve.py git commit -m "feat: add objective factors/mode defaults and validation" ``` --- ### Task 2: Accept and resolve the new `solve()` arguments **Files:** - Modify: `solve.py` — `solve()` signature (~line 981) and top of the function body - [ ] **Step 1: Extend the signature** Add two keyword args to `solve()` (after `resource_constraints=None`): ```python def solve( *, initial=INITIAL, arrivals=ARRIVALS, max_res=MAX_RES, max_vat=MAX_VAT, time_limit=60.0, num_workers=8, verbose=True, fixed_choices=FIXED_CHOICES, resource_constraints=None, objective_factors=None, objective_mode=None, ): ``` - [ ] **Step 2: Resolve defaults and validate, first thing in the body** Insert at the very top of the function body, before the `# ---- build the city list` block, so bad input fails before any model construction: ```python if objective_factors is None: objective_factors = OBJECTIVE_FACTORS if objective_mode is None: objective_mode = OBJECTIVE_MODE _validate_objective(objective_factors, objective_mode) # Normalized copy: every key present, missing keys = 0. obj_factors = {k: objective_factors.get(k, 0) for k in "EBSC"} ``` - [ ] **Step 3: Commit** ```bash git add solve.py git commit -m "feat: solve() accepts objective_factors and objective_mode" ``` --- ### Task 3: Compute Phase-1 ceilings only for resources in the objective **Files:** - Modify: `solve.py` — Phase-1 block (~lines 1536-1554, `def _ceiling` through the three `m.Add(final* <= cap*)` lines) and the verbose ceilings print (~line 1596) - [ ] **Step 1: Replace the fixed capE/capB/capS computation with a caps dict** The existing line `finalE, finalB, finalS = E[NUM_STEPS + 1], ...` stays. Just below it, replace this block: ```python capE = _ceiling(finalE) capB = _ceiling(finalB) capS = _ceiling(finalS) m.Add(finalE <= capE) m.Add(finalB <= capB) m.Add(finalS <= capS) ``` with (keeping `def _ceiling(var):` as is, above it): ```python finals = {"E": finalE, "B": finalB, "S": finalS, "C": C[NUM_STEPS + 1]} # Ceilings only for resources that appear in the objective: each # ceiling solve costs up to 20s, and only objective resources need # bounds (product mode) / benefit from the redundant cap constraint. caps = {} for k, var in finals.items(): if obj_factors[k] != 0: caps[k] = _ceiling(var) m.Add(var <= caps[k]) ``` - [ ] **Step 2: Update the verbose ceilings print** Replace: ```python print(f"(resource ceilings used: E<={capE} B<={capB} S<={capS})") ``` with: ```python caps_str = " ".join(f"{k}<={v}" for k, v in caps.items()) print(f"(resource ceilings used: {caps_str})") ``` - [ ] **Step 3: Commit** ```bash git add solve.py git commit -m "feat: compute resource ceilings only for objective resources" ``` --- ### Task 4: Generic objective builder (product fold / linear sum) **Files:** - Modify: `solve.py` — the "OBJECTIVE IS SET HERE" block (~lines 1556-1578) - [ ] **Step 1: Replace the hardcoded objective block** Delete the whole block from `def Eprod(v):` through `m.Maximize(obj)` (including `Eprod`/`Bprod`/`Sprod` and the `prodEE`/`prodSS`/`prodBB`/`prodEB`/`obj` variables) and replace with: ```python # ====================================================================== # OBJECTIVE IS SET HERE # ====================================================================== if objective_mode == "sum": # Linear: CP-SAT takes weighted sums (negative weights included) # directly, no auxiliary variables needed. m.Maximize(sum(f * finals[k] for k, f in obj_factors.items() if f)) else: # Product: maximize prod(finals[k] ** obj_factors[k]). Expand the # exponents into a flat factor list and fold pairwise, carrying a # running upper bound from the Phase-1 caps. factor_keys = [k for k, f in obj_factors.items() for _ in range(f)] obj = finals[factor_keys[0]] bound = caps[factor_keys[0]] for k in factor_keys[1:]: bound *= caps[k] nxt = m.NewIntVar(0, bound, "") m.AddMultiplicationEquality(nxt, [obj, finals[k]]) obj = nxt m.Maximize(obj) ``` Notes for the implementer: - `factor_keys` for the default `{"E": 2, "B": 1, "S": 2}` is `["E", "E", "B", "S", "S"]`, reproducing the old `E²·B·S²` objective. - A single-factor product (e.g. `{"E": 1}`) skips the loop entirely and maximizes `finalE` directly — that's correct. - Every key in `factor_keys` has a nonzero factor, so `caps[k]` always exists (Task 3 computed caps for exactly those keys). - [ ] **Step 2: Commit** ```bash git add solve.py git commit -m "feat: build objective from factors dict in product or sum mode" ``` --- ### Task 5: Report the actually-maximized objective **Files:** - Modify: `solve.py` — `_report()` signature (~line 1651) and its FINAL print (~lines 1854-1858); the `_report(...)` call inside `solve()` (~line 1597) - [ ] **Step 1: Add objective params to `_report`'s signature** Append two keyword params after `baron_deposits=None`: ```python baron_deposits=None, obj_factors=None, obj_mode=None, ): ``` - [ ] **Step 2: Replace the FINAL print** Replace: ```python fe, fb, fs = solver.Value(finalE), solver.Value(finalB), solver.Value(finalS) print( f"\nFINAL E={fe / 10:.1f} B={fb / 10:.1f} S={fs / 10:.1f} " f"product(scaled) = {fe * fb * fs / 1000} sum = {(fe + fb + fs) / 10:.1f}" ) ``` with: ```python fe, fb, fs = solver.Value(finalE), solver.Value(finalB), solver.Value(finalS) vals = {"E": fe, "B": fb, "S": fs, "C": solver.Value(C[NUM_STEPS + 1])} if obj_factors is None: # Legacy fallback: old hardcoded E*B*S display. obj_str = f"product(scaled) = {fe * fb * fs / 1000}" elif obj_mode == "sum": terms = [ f"{f}{k}" if abs(f) != 1 else (k if f > 0 else f"-{k}") for k, f in obj_factors.items() if f ] expr = " + ".join(terms).replace("+ -", "- ") raw = sum(f * vals[k] for k, f in obj_factors.items()) obj_str = f"objective {expr} = {raw / 10:.1f}" else: expr = "*".join( k if f == 1 else f"{k}^{f}" for k, f in obj_factors.items() if f ) raw, n = 1, 0 for k, f in obj_factors.items(): raw *= vals[k] ** f n += f # Resource values are x10-scaled, so descale by 10^(sum of exponents). obj_str = f"objective {expr} = {raw / 10**n}" print( f"\nFINAL E={fe / 10:.1f} B={fb / 10:.1f} S={fs / 10:.1f} " f"{obj_str} sum = {(fe + fb + fs) / 10:.1f}" ) ``` Display examples: product `{"E": 2, "B": 1, "S": 2}` → `objective E^2*B*S^2 = ...` descaled by `10^5`; sum `{"E": 2, "B": 1, "S": -1}` → `objective 2E + B - S = ...` descaled by 10. - [ ] **Step 3: Pass the objective through from `solve()`** At the `_report(...)` call inside `solve()`, append two keyword arguments after `baron_deposits,`: ```python baron_deposits, obj_factors=obj_factors, obj_mode=objective_mode, ) ``` - [ ] **Step 4: Commit** ```bash git add solve.py git commit -m "feat: report prints the actually maximized objective" ``` --- ### Task 6: Smoke check (user validation) Per user instruction there are no automated tests. A quick way to confirm the default path is byte-for-byte behavior-compatible: - [ ] **Step 1: Syntax check** Run: `uv run python -c "import solve"` Expected: no output, exit 0. - [ ] **Step 2: Hand off to user** The user validates solver behavior themselves (e.g. `uv run python solve.py` should produce the same plan/objective as before the change, now printing `objective E^2*B*S^2 = ...`).