Capacity-Aware Weekly Planning with Locking

A weekly planner becomes untrustworthy when generation can silently overwrite a plan that the user has already accepted. The implementation separates a reproducible draft from a locked plan and applies capacity rules before persistence.

Generate from constraints, not optimism

The API receives a week start and a capacity between 420 and 1,680 minutes. Deadline items due inside the week are protected. Recurring study candidates are scored, sorted deterministically, and accepted only while the capacity remains. No day receives more than five items.

Each stored item includes its reason as data, not just as UI copy. This keeps the recommendation explainable after the algorithm changes.

{
  "day": "2026-09-09",
  "area": "academic",
  "minutes": 50,
  "reason": "Confirmed assessments and due reviews are handled first."
}

Persist the decision boundary

The plan row stores capacity, planned minutes, deferred count, generation time, status, and lock time. Items reference the plan and receive stable sort positions. Regeneration replaces only the items of an unlocked plan. A locked row returns 409 Conflict, forcing an explicit future change policy rather than accidental overwrite.

Test the whole transition

Unit tests cover week boundaries and capacity selection. A temporary D1 run generated 30 items using 1,035 of 1,050 available minutes, recorded one deferred candidate, locked the plan, and rejected regeneration. The actual local service then generated and locked the current week with the same totals. Future work can add deliberate unlock and revision history; until then, immutability is safer than an ambiguous edit.