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 orchestrator is advisory-locked per (org, teacher, class) and executes each step 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.
Rough step grouping:
- Review phase (TAW_01..04): load recommendations, check guardrails, surface the recommendation panel.
- Grouping phase (TAW_05..08): compute clusters, present scaffold distribution preview, let teacher adjust membership.
- Activation phase (TAW_09..11): activation review, per-member OVR confirmation, bulk activation commit.
- Monitoring phase (TAW_12..15): plan status read, acute-alert surface, alert resolution.
- Decision phase (TAW_16..17): continue / adjust / escalate / 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.
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 (delegates to bulk-activate write path) |
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