RGreview-game-corethe engine behind concept-first review games

Runtime

Workflow Core

Six-phase quiz engine with session, persistence, and deterministic debug contracts.

Route: /docs/workflow-core

The workflow layer drives one quiz turn. The quiz engine runs it through six phases; session and debug helpers are the contracts the engine leans on so consumer shells can persist, restore, and force routes deterministically.

The canonical repo docs for this layer are:

The six-phase quiz engine

Every turn moves through these phases:

  • routing — pick a concept and a question for the learner.
  • question — present the question and wait for the first answer.
  • staged-answer — walk the learner through the stages the question defines (recognize, structure, prove).
  • support — open scaffolding when the learner stalls on a stage.
  • recovery — run a lighter retry after failed support.
  • complete — mark the question finished and hand control back to routing.

The phase names come straight from the QuizEnginePhase union in src/workflow/quiz-engine.ts. Consumer games render whatever UI fits the phase; the core owns the state machine.

Session helpers

workflow/session gives consumer shells:

  • normalized learner IDs
  • session identity records
  • storage-key construction
  • snapshot normalization and reset helpers
  • content-identity comparison for restored question state

Debug helpers

workflow/debug exposes deterministic query contracts — wf=1, seeded routes, fixed concepts, restore flags, and support forcing — so repo-owned browser harnesses can reach any phase without clicking through the whole loop.

Those deterministic routes are important, but they are still regression/debug tools. They do not replace a real low-context WF pass against the visible product path.

See the workflow feature page for the snapshot and debug-route example.

Adjacent showcase pages