rootnode-academy/docs/ROOT_CAPSTONE_READINESS.md

ROOT Capstone Readiness

Phase 6B §9/§10 — the instructional runway that prepares a student for the existing rootnode-capstone assessment, and the server-side fix that makes its unlock rule actually enforced. This document does not redesign the capstone engine itself (assessments.js, 013_assessments.sql) — see docs/PHASE3B_LEARNING_AND_ASSESSMENT.md for that.

1. The Capstone Readiness module

root-capstone-m02-capstone-readiness (sequenced BEFORE the real capstone module, root-capstone-m01-operate-and-recover, within the root-capstone course) — 4 activities:

1. Lesson — What the Capstone Measures & How the Draw Works. Explains the required-vs-random scenario draw, what "unlocked" means, and what completion records. Never publishes the exact scenario IDs in the current pool or any answer.
2. Lesson — Time Management & Troubleshooting Strategy Under a Clock. Budgeting the 90 minutes, reusing the ROOT 10/ROOT 12 frameworks under pressure, and when to move on from a stuck scenario.
3. Knowledge check — Readiness Check: Are You Actually Ready? A genuine self-assessment (not a graded quiz) against concrete criteria, pointing back to specific ROOT_ modules for any "no" answer.
4. Reflection — What Completion Means. Connects passing the Capstone to a durable, demonstrated skill rather than a completion checkbox.

This module derives its own completion the same way every other lesson-only module does (activity_completions, manual_marker) — it is intentionally NOT a prerequisite the real capstone assessment engine checks before allowing a start (see §3 below for why these two gates are deliberately independent).

2. What was NOT built

No answers, no exact scenario IDs from the current pool, no capstone-specific hint content beyond what the Lab's own progressive hints already provide. No new assessment engine, no second capstone, no readiness "score." This is orientation content, not a shadow exam.

3. Why readiness-module completion and the real unlock gate are independent

The real capstone start (POST /api/assessments/rootnode-capstone/start) is gated by the curriculum path's own unlock_rule — all 6 content stages of rootnode-path.json complete (Foundation, Workloads, Networking, Configuration, Troubleshooting, Real Ops) — computed by computeCurriculumState() (curriculum-rules.js), the exact same function GET /api/capstone already used to display lock state. Whether a student has viewed or completed the Capstone Readiness module has NO bearing on this gate.

This is deliberate, not an oversight: hard-locking the real assessment behind a CONTENT-MODEL module (course_modules/module_activities) would mean the security-critical enforcement boundary lives in two different systems that could drift out of sync — the curriculum-path unlock_rule (Postgres-backed, achievement-derived, already proven) and the course-content prerequisite chain (newer, additive, built for teaching sequencing rather than security enforcement). Keeping them independent means: the readiness module is free to be completed early, late, or skipped by a student who's already prepared some other way, while the real gate remains exactly as strict as docs/PHASE3B_LEARNING_AND_ASSESSMENT.md originally specified.

4. The server-side unlock enforcement fix (Phase 6B §10)

The gap (documented in docs/PHASE6A_ROOT_COURSE_FOUNDATION.md §10): POST /api/assessments/ :definitionId/start (learning-routes.js) checked only that the assessment definition existed and was status = 'active' — it never checked unlock_rule at all. GET /api/capstone correctly computed and displayed lock state, and the student UI never exposed a "start" action while locked, but a direct POST to the start route bypassed the check entirely. Student UI state was the only thing standing between a student and an early capstone attempt.

The fix: the start route now resolves whether the requested definition is the curriculum path's OWN configured capstone (path.stages.find(s => s.type === 'capstone' && s .capstone_assessment_id === definition.assessment_definition_id)), and if so, computes the exact same computeCurriculumState() gate /api/capstone already relies on. A locked gate now returns a clean 403 { error: 'locked', message, blocking_stage_ids } — the same blocking_stage_ids shape /api/capstone already exposes, so a client integrating against this route gets consistent, already-documented error shape rather than a new one. No internal state beyond the stage ids that are actually incomplete is ever returned.

What is NOT gated: any assessment definition the curriculum path does NOT name as its capstone (e.g. rootnode-quick-assessment) is completely unaffected — the check only ever triggers for the one definition the path itself points at via capstone_assessment_id.

What remains valid: no existing assessment_sessions row, no achievement, no enrollment completion record was touched by this fix — it only affects a NEW start attempt going forward. A student who already legitimately completed the capstone before this fix keeps that record exactly as it was.

Regression coverage: platform/test/e2e-phase6b.js proves both directions — a direct start attempt before prerequisites are met is rejected (403 locked), and a legitimately unlocked attempt (all 6 stages genuinely complete) still succeeds and completes normally. A pre-existing gap was also found and fixed in e2e-phase5b.js's own capstone-completion test, which had never included the real-ops stage in its completion loop — it was passing only because the very bug this phase fixes let an incomplete curriculum still start the capstone. See that test file's own comment for detail.