Overview

Migration Notes and Adoption Shape

How to map consumer-local mechanisms onto the current core families without pulling rollout choreography into the package docs.

Route: /docs/migration-notes

Use this page as the short migration entrypoint.

The canonical boundary map now lives in docs/core-mechanism-inventory.md.

That inventory is the primary answer to:

• what core already owns
• what a consumer should normalize into those families
• what should stay consumer-local

This page explains the adoption shape around that inventory.

The migration pattern

The package is no longer just absorbing one old stats precursor.

The stable pattern is:

1. identify the mechanism you have in a consumer repo
2. find the matching core family
3. normalize your app-shaped evidence or state into that family
4. keep copy, learner policy, and rollout behavior above core

That applies across the current shared families:

• planning consumes normalized progress counts
• scheduler consumes concept evidence and guided repetition state
• workflow consumes session/debug/turn state
• graph consumes authored structure for projection
• WF doctrine separates deterministic regression from low-context workflow proof

What counts as a good migration

A migration is in good shape when:

• the shared rule becomes more explicit and deterministic
• consumer adapters get thinner instead of more magical
• the core vocabulary gets more stable across games
• the product-specific meaning still lives in the consumer shell

A migration is in bad shape when it pulls any of these into core:

• launcher copy
• learner identity policy
• course grading or exam-window policy
• repo-specific release sequencing
• ad hoc UI state that only one app understands

Planning is still the clearest precursor

The original strong precursor was the vendored stats goal kernel.

That planning migration remains the clearest example of the normalization move:

• app-shaped goal logic -> GoalPlan and GoalPhaseSnapshot
• implicit recommendation heuristics -> explicit recommendation roles
• local dashboard semantics -> a pure evaluator beside scheduler, workflow, and graph

Both current example consumers still adapt their own evidence differently:

• stats-exam-prep-game rolls concept progress into phase snapshots
• math-1111-review-game rolls section progress into phase snapshots

The shared evaluator stays the same because the normalization seam is count-based.

Use the deeper docs by family

• Use Planning / Goal Family when migrating recommendation logic.
• Use Scheduler when migrating concept progression or guided repetition.
• Use Workflow Core when migrating session, persistence, or deterministic debug seams.
• Use docs/core-mechanism-inventory.md when deciding whether something belongs in core at all.

For the planning-adjacent boundary questions that often come up during migration, the canon repo docs are:

• docs/goal-launcher-congruency.md
• docs/planning-rollup-boundary.md
• docs/source-provenance-boundary.md
• docs/saved-plan-seam-evaluation.md

This page is intentionally about adoption shape, not rollout choreography.