Teacher Activation Workflow
The Teacher Activation Workflow (WP-TAW) is a 17-step guided state machine that walks a teacher from seeing a bundle recommendation all the way through plan review and exit. It is a pure orchestration layer: it adds no new decision logic, only coordinates the already-built bundle, cluster, and monitoring engines.
The workflow follows the principle stated in V-12: the system proposes, the teacher decides. Every consequential action requires an explicit teacher choice.
The six named UI surfaces
| Surface | Purpose |
|---|---|
| Recommendations Panel | Shows the class’s active bundle recommendations (one per student) derived from the profile engine |
| Smart Grouping Panel | Previews which students can be clustered together (same bundle, anchor skill, scaffold tier, delivery mode) |
| Scaffold Distribution Preview | Shows the Level_1 / Level_2 / Level_3 breakdown across a cluster before the teacher commits |
| Activation Review | Per-member confirmation step; teacher may apply per-member adjustments (OVR_* rules) before finalising |
| Activation Confirmation | Final commit; triggers bulk activation through the existing cluster write path |
| Plan Review & Exit | The ongoing surface the teacher returns to for monitoring status, alert resolution, and plan continuation or exit |
The 17-step state machine (TAW_01..TAW_17)
The single-writer paths (review and exit) acquire an advisory lock per (org, bundleAssignment); distinct assignments never block each other. The bulk-activate path delegates the full transaction to the cluster writer, which holds its own per-(org, class) lock. Each step is executed by delegating to the relevant shipped writer. No new write path is introduced by this module; the five single-write-path lint rules (bundle-assignment, cluster-result, monitoring, and related) remain green.
Step grouping (canonical STEP_STAGE map):
- Review phase (TAW_01..03): load recommendations, check guardrails, surface the recommendation panel.
- Grouping phase (TAW_04..06): compute clusters, present scaffold distribution preview, let teacher adjust membership.
- Activation phase (TAW_07..12): activation review, per-member OVR confirmation, then either a bundle commit (TAW_11 bulk / TAW_12 individual) or a non-bundle routing record (TAW_12). See the two activation outcomes below.
- Monitoring phase (TAW_13..14): plan status read, acute-alert surface.
- Decision phase (TAW_15..17): TAW_15 acute-regression alert resolution, TAW_16 plan-status transition, TAW_17 exit.
Draft persistence
A workflow_draft row (one per (org, teacher, class)) is the only mutable table the workflow
owns. It has a 7-day TTL (soft-expire via last_write_wins upsert). All audit history lives in
teacher_action_log and bundle_assignment_history.triggeringWorkflowStep, never in the draft.
The three guardrail flows
These guardrails are enforced at the workflow boundary and cannot be bypassed by any override code.
| Guardrail | Trigger | System response |
|---|---|---|
| Insufficient Evidence | A student’s recommendation carries do_not_decide_yet | Activation is blocked (409); the student is routed to the “needs more data” bucket and excluded from any cluster |
| Acute Regression | An open acute_regression_alert exists for a student | The teacher must resolve the alert first (/api/workflow/review): dismiss with a context flag, or escalate for a tier-review nomination. The plan status is never auto-changed (GSR-02) |
| DATA_INCOMPLETE | The cluster engine has excluded the student via QA_003 | The student is deferred; activation proceeds for the remaining cluster members |
Override codes and context flags
When a teacher modifies a recommendation, the reason must come from the 9-code OverrideCodeCatalog; no
free text is ever accepted. The applicable scope is enforced at the API level (SCOPE_MISMATCH → 400
when a bundle-exit code is used on a non-exit path, etc.).
Context flags use the closed ContextFlagId dictionary (7 allowed codes: CTX_SESSION_INTERRUPTED,
CTX_TECHNICAL_ISSUE, CTX_AUDIO_PROBLEM, CTX_GROUP_NOT_COMPLETED, CTX_STUDENT_ABSENT,
CTX_NEEDED_REPETITION, CTX_PAPER_CHECK_ADMIN). A context flag is recorded in context_flag_log
only; it is never stored on the alert row itself.
Any deviation from the recommended scaffold tier requires confirmed: true in the request body, or
the server returns 409 CONFIRMATION_REQUIRED.
Two activation outcomes (R12 Tier-D, D-015)
POST /api/workflow/activate now resolves to one of two outcomes depending on the
recommendation’s object type. This replaces the retired NO_BUNDLE_SYSTEM_GUARD
bundle path: non-bundle recommendations no longer create a placeholder assignment.
| Outcome | When | What is written | Response shape |
|---|---|---|---|
kind="activated" | The recommendation is a real INTERVENTION / COMPOSITE bundle (recommended_bundle_id non-null) | One bundle_assignment + scaffold rows | bundleId + activated[], routing: null |
kind="routed" | The recommendation is a non-bundle object (recommended_bundle_id NULL) | No bundle_assignment, no scaffold; the controlled routing/action code is appended to teacher_action_log (actionType='individual_routing', workflowStep TAW_12) | routing: { studentId, objectType, routingOutcome }, bundleId: null, activated: [] |
Both outcomes return HTTP 200. The routed outcome carries only controlled
BundleObjectType + routing/action codes — never free text.
RTI tier
The workflow never writes an RTI tier. Tier escalation/de-escalation is owned by the separate RTI
module. The workflow’s escalation path opens a TeacherReviewRequest nomination only; the formal
TierReviewRequest and applyDecision() write live in the RTI engine.
API endpoints (7)
All routes require teacher authentication and are ClassTeacher-scoped.
| Method | Path | Purpose |
|---|---|---|
GET | /api/workflow/steps | Load the 17 step definitions (version-pinned) |
GET | /api/workflow/recommendations/:classId | Fetch class recommendations (the Recommendations Panel feed) |
GET | /api/workflow/draft/:teacherId/:classId | Resume an in-progress draft |
POST | /api/workflow/save-draft | Persist draft state (7-day TTL upsert) |
POST | /api/workflow/activate | Commit activation — either a bundle assignment (kind="activated") or a non-bundle routing record (kind="routed"); see “Two activation outcomes” above |
POST | /api/workflow/review | Resolve an acute-regression alert (dismiss or escalate) |
POST | /api/workflow/exit | Exit / close the plan |
For full request/response shapes see the API Reference.
Related guides
- Intervention Bundles: how bundles are structured (anchor + supporting threads + asset bridge)
- Smart Clustering: how the 5-key cluster identity is computed
- Progress Monitoring: the monitoring status the Plan Review surface reads
- Language Safety: why context flags replace free-text teacher notes