Planning

Planning / Goal Family

The canonical planning abstraction family for turning progress counts into recommendation state.

Route: /docs/planning-goals

The planning layer is a pure evaluation boundary beside scheduler, workflow, and graph helpers.

The canonical repo docs for this layer are:

It owns:

ordered plans and phases
count-based phase snapshots
local-date deadline evaluation
derived recommendation state

A phase resolves to one of four recommendation roles: primary (the track to work on next), catch_up (behind schedule), queued (waiting on an earlier phase), or complete.

It does not own:

learner profiles
grade math
launcher copy
routing URLs
source provenance

Adjacent planning-shaped boundaries stay documented separately:

launcher and goal-coach congruency
count-rollup normalization from sections/objectives/topics
provenance/source honesty above the core evaluator

Core vocabulary

GoalPlan
GoalPhaseDefinition
GoalPhaseSnapshot
GoalPhaseState
GoalPlanEvaluation

For shared UI consumers, @brandon-gottshall/review-game-core/ui now exposes GoalRoadmapCard, which renders ordered GoalPhaseState[] output directly from evaluateGoalPlan(...) without an app-local adapter layer.

Why it exists

Consumer apps like stats-exam-prep-game and math-1111-review-game both need recommendation logic, but they measure progress differently:

stats tracks concepts and exam coverage
Math1111 tracks section completion and unit focus windows

The planning family lets both apps feed progress counts into the same evaluator without forcing the core to understand either product's learner policy.

Canonical semantics

progress is count-based
local dates are day-granular
deadline behavior is explicit
missing snapshots default to zero progress
unknown snapshots are ignored

The kernel is meant to publish recommendation state, not product copy or launcher policy.

See the planning feature page for a worked example and real adapter excerpt.