docs: prepare M01 learner-validation evidence gate

.github/workflows/pages.yml

@@ -25,8 +25,6 @@ jobs:
         uses: actions/checkout@v4
       - name: Configure Pages
         uses: actions/configure-pages@v5
-        with:
-          enablement: true
       - name: Upload static site
         uses: actions/upload-pages-artifact@v3
         with:

app.js

@@ -300,12 +300,14 @@
     const parts = location.hash.replace(/^#\/?/, "").split("/").filter(Boolean);
     if (!parts.length) return { route: "home" };
     if (parts[0] === "lesson") return { route: "lesson", id: parts[1] };
+    if (parts[0] === "validation" && parts[1] === "m01" && parts.length === 2) return { route: "validation-m01" };
     if (["course", "diagnostic", "toolkit"].includes(parts[0])) return { route: parts[0] };
     return { route: "not-found" };
   }
 
   function render() {
     const { route, id } = parseRoute();
+    if (route === "validation-m01") return;
     const views = { home: homeView, course: courseView, lesson: () => lessonView(id), diagnostic: diagnosticView, toolkit: toolkitView, "not-found": notFoundView };
     document.querySelector("#main").innerHTML = views[route]();
     setActiveNav(route);
@@ -324,4 +326,4 @@
   });
   window.addEventListener("hashchange", render);
   render();
-})();
+})();

docs/README.md

@@ -25,6 +25,12 @@ The reference prototype is not the long-term architecture.
 ### Content
 - `content/CONTENT_MODEL.md` — canonical entities and rules for lessons, drills, cases, assessments, and artifacts.
 
+### Validation
+- `validation/M01-VALIDATION-PROTOCOL.md` — operational protocol for the first end-to-end learner validation cycle.
+- `validation/M01-READINESS-AUDIT.md` — curriculum, learning-model, and content-contract audit before real learner sessions.
+- `validation/M01-SESSION-RECORD-TEMPLATE.md` — per-participant evidence and facilitator observation template.
+- `validation/M01-COHORT-REVIEW-TEMPLATE.md` — cohort synthesis and explicit Phase 1 exit decision record.
+
 ### Architecture
 - `architecture/ARCHITECTURE.md` — current-state and target-state architecture.
 - `architecture/adr/0001-reference-prototype-to-v1.md` — decision record for the A → C strategy.
@@ -36,6 +42,12 @@ The reference prototype is not the long-term architecture.
 - `superpowers/specs/2026-09-03-pmo01-v0-design.md` — historical V0 design. It remains useful context but is not the current architecture source of truth.
 - `superpowers/specs/2026-09-06-pmo01-platform-foundation-design.md` — current platform foundation design.
 
+## Current gate
+
+The technical/reference-prototype work required to run the first M01 validation cohort is prepared. The project remains in **Phase 1 — Validate the learning model** until real learner evidence is reviewed.
+
+Do not begin Phase 2 contract freeze solely because the prototype and CI are ready. Phase 2 requires an explicit cohort decision recorded with `validation/M01-COHORT-REVIEW-TEMPLATE.md`.
+
 ## Source-of-truth precedence
 
 When documents conflict, use this order:

docs/ROADMAP.md

@@ -162,8 +162,20 @@ Only after core learning quality and state model are stable, evaluate separately
 
 Each is an independent product decision, not a default consequence of “scaling”.
 
-## Immediate next decision
+## Current gate — complete Phase 1 with real learner evidence
 
-Before code migration begins, review and accept the platform foundation documents in `docs/`.
+The platform foundation and the technical M01 validation slice are prepared for review. The remaining Phase 1 gate is empirical, not architectural.
 
-After acceptance, write an implementation plan for **Phase 1 only** rather than a single plan spanning the entire roadmap.
+Before Phase 2 begins:
+
+1. run at least 5 completed M01 learner sessions using `docs/validation/M01-VALIDATION-PROTOCOL.md`;
+2. record each session with `docs/validation/M01-SESSION-RECORD-TEMPLATE.md`;
+3. review diagnostic reasoning delta, field transfer, reflection quality, interaction usefulness, reliability/friction, and content-model fit;
+4. record one explicit cohort decision with `docs/validation/M01-COHORT-REVIEW-TEMPLATE.md`:
+   - **Promote to Phase 2**;
+   - **Revise and retest**;
+   - **Reject mechanism**.
+
+`docs/validation/M01-READINESS-AUDIT.md` documents the current curriculum/content-contract fit before learner testing.
+
+Do not freeze v1 domain contracts, select a framework, or start a v1 migration until the cohort decision is **Promote to Phase 2**.

docs/superpowers/plans/2026-09-06-m01-learning-validation.md

@@ -133,4 +133,32 @@
 - [x] Upgrade GitHub Actions runtime dependencies to current major versions used by the workflow.
 - [x] Inspect final Actions run after documentation/CI changes and require GREEN.
 - [x] Review final diff for scope creep and architecture violations: Phase 1 only; no backend/auth/framework migration; legacy `app.js`, `course-data.js`, and `styles.css` unchanged.
-- [ ] Update PR #2 from draft only after the verification run for this final plan-reconciliation commit is GREEN.
+- [x] Update PR #2 from draft after verification; PR #2 is ready-for-review and mergeable.
+
+## Gate verification record — 2026-09-06
+
+### VERIFIED
+
+- PR #2 head is `050ea6d26197ba68f8e82d8dc34306f4c6678332`; it remains open and is not merged into `main`.
+- Stacked documentation head before this reconciliation was `82c4418de634ed2b824de5714bab34dec4e74ae9`.
+- GitHub Actions run #49 on that head completed successfully.
+- CI executed JavaScript syntax checks and `node --test tests/*.test.js`; all 19 tests passed, 0 failed, 0 skipped.
+- Full scope review of PR #2 confirms Phase 1-only changes: validation runtime/data/styles/tests/CI/docs; no backend, auth, CMS, AI subsystem, framework migration, or v1 rewrite.
+- Full scope review of the stacked docs layer confirms documentation/readiness-only changes; no runtime/application files changed.
+
+### UNEXECUTED
+
+- No merge of PR #2 into `main`.
+- No Phase 2 domain-contract freeze.
+- No framework selection or v1 migration.
+- No real learner cohort execution in this code gate.
+
+### BLOCKED
+
+- Phase 2 remains blocked on the empirical learner-evidence gate in Issue #4: at least 5 completed M01 learner sessions and one explicit cohort decision (`Promote`, `Revise and retest`, or `Reject mechanism`).
+
+### Next step
+
+1. Require GREEN CI on the new plan-reconciliation HEAD created by this update.
+2. If GREEN, treat the technical/scope gate as closed.
+3. Execute Issue #4 learner cohort before any Phase 2 work.

docs/validation/M01-COHORT-REVIEW-TEMPLATE.md

@@ -0,0 +1,231 @@
+# M01 Cohort Review Template
+
+Use this document after the first learner cohort is complete. The first review should normally include at least **5 completed sessions**.
+
+This is a product/learning decision record, not a statistical significance report.
+
+## Cohort metadata
+
+- **Review date:**
+- **Sessions included:**
+- **Sessions excluded:**
+- **Reason for exclusions:**
+- **Experience mix:**
+- **Facilitator(s):**
+
+## Per-session summary
+
+| Participant ID | Baseline | Post | Delta | Improved dimensions | Individual signal | Field transfer | Major friction | Delayed follow-up |
+|---|---:|---:|---:|---:|---|---|---|---|
+| | | | | | | | | |
+| | | | | | | | | |
+| | | | | | | | | |
+| | | | | | | | | |
+| | | | | | | | | |
+
+## L1 — Diagnostic reasoning delta
+
+Review the direction and distribution of change rather than only the average.
+
+- **Positive individual signals (`+3` and ≥2 improved dimensions):**
+- **No-signal sessions:**
+- **Negative-delta sessions:**
+- **Median delta:**
+- **Range:**
+
+### Dimension-level pattern
+
+| Dimension | Improved | Unchanged | Worse | Interpretation |
+|---|---:|---:|---:|---|
+| Mechanism | | | | |
+| Evidence | | | | |
+| Trade-offs | | | | |
+| Intervention | | | | |
+| Change condition | | | | |
+
+Questions:
+
+1. Is improvement broad across reasoning dimensions or concentrated in one item?
+2. Is any item too easy/hard to discriminate before and after learning?
+3. Is wording ambiguity a plausible alternative explanation for score movement?
+4. Does free-text reasoning support the same conclusion as multiple-choice scores?
+
+## L2 — Transfer
+
+For participants who studied M01:
+
+- **Credible field applications:**
+- **Partial applications:**
+- **Restatement-only / no transfer:**
+- **Not completed:**
+
+Prototype transfer rate:
+
+```text
+credible or policy-defined completed field applications
+-------------------------------------------------------
+participants who studied the module
+```
+
+Do not interpret a filled form as transfer when intervention/evidence does not follow from the diagnosis.
+
+### Common transfer patterns
+
+- Mechanisms learners identified:
+- Interventions learners attempted:
+- Signals/evidence learners used:
+- Where learners reverted to symptom/person-level reasoning:
+
+## L3 — Reflection quality
+
+Count/classify whether reflections show:
+
+- changed diagnosis;
+- changed planned action;
+- new evidence requirement;
+- testable remaining uncertainty;
+- lesson restatement without mental-model change.
+
+Key qualitative patterns:
+
+## L4 — Delayed retrieval / application
+
+- **Delayed checks run:**
+- **Independent transfer retained:**
+- **Partial:**
+- **Absent:**
+
+Observations:
+
+- Did participants reconstruct the model without course vocabulary prompts?
+- Did transfer survive a different project domain?
+- Did immediate post-case gains persist?
+
+Do not introduce a `mastered` rule from a small cohort. Record evidence only.
+
+## Decision Drill review
+
+### `m01-drill-system`
+
+- Preferred choice selected immediately by most learners: yes / no / unclear
+- Meaningful misconception exposed: yes / no / mixed
+- Feedback changed reasoning: yes / no / mixed
+- Transfer contribution observed: yes / no / unclear
+- Recommendation: keep / revise / remove
+- Reason:
+
+### `m01-drill-diagnostic`
+
+- Preferred choice selected immediately by most learners: yes / no / unclear
+- Meaningful misconception exposed: yes / no / mixed
+- Feedback changed reasoning: yes / no / mixed
+- Transfer contribution observed: yes / no / unclear
+- Recommendation: keep / revise / remove
+- Reason:
+
+## Integrative case review
+
+- Case felt structurally similar but non-identical to baseline: yes / no / mixed
+- Case tested multiple concepts rather than recall: yes / no / mixed
+- Scoring dimensions remained interpretable: yes / no / mixed
+- Free-text diagnosis added useful evidence beyond choices: yes / no / mixed
+- Recommendation: keep / revise / replace
+
+## Rubric review
+
+For each dimension, note ambiguity, ceiling/floor effects, or mismatch between option score and observed reasoning.
+
+| Dimension | Keep | Revise | Evidence |
+|---|---|---|---|
+| Mechanism | | | |
+| Evidence | | | |
+| Trade-offs | | | |
+| Intervention | | | |
+| Change condition | | | |
+
+### Promotion threshold review
+
+The current `+3 total / ≥2 dimensions` rule is a development heuristic.
+
+- Did it classify sessions in a way consistent with qualitative reasoning evidence?
+- Did it create obvious false positives?
+- Did it create obvious false negatives?
+- Recommendation: keep for next prototype cycle / revise / stop using
+
+Do not convert this threshold into mastery semantics.
+
+## Reliability / UX review
+
+Count and classify:
+
+- response/state loss;
+- reload/navigation recovery failures;
+- persistence errors;
+- keyboard/accessibility blockers;
+- route/sequence confusion;
+- baseline contamination;
+- abandonment points;
+- wording/UI interfering with reasoning.
+
+### Blocking defects
+
+List defects that invalidate or materially distort learner evidence:
+
+## Content-contract fit review
+
+Start from `M01-READINESS-AUDIT.md` and record whether learner-driven revisions create a real new content-domain requirement.
+
+### Expected migration enrichments
+
+These are not special cases by themselves:
+
+- competency/outcome metadata;
+- structured drill analysis;
+- explicit rubric IDs/versioning;
+- explicit field-application artifact/evidence/privacy metadata.
+
+### New exceptions discovered
+
+List only requirements that cannot be represented cleanly by the current canonical entities:
+
+## Phase 1 exit decision
+
+Choose exactly one:
+
+### A. Promote to Phase 2
+
+Use only when:
+
+- learner evidence indicates meaningful reasoning improvement or useful discrimination;
+- field transfer is credible enough to preserve as a requirement;
+- major learner friction is known and non-blocking;
+- no unresolved content-domain ambiguity remains.
+
+### B. Revise and retest
+
+Use when the learning mechanism looks promising but:
+
+- wording/rubric distorts measurement;
+- an interaction is weak;
+- transfer is incomplete;
+- UX/reliability interferes with evidence;
+- content-contract assumptions changed materially.
+
+### C. Reject mechanism
+
+Use when an interaction or module format adds complexity without producing useful reasoning or transfer evidence.
+
+## Recorded decision
+
+- **Decision:** A / B / C
+- **Rationale:**
+- **Evidence supporting the decision:**
+- **Required changes before next gate:**
+- **Owner:**
+- **Date:**
+
+## Phase 2 authorization
+
+Phase 2 contract freeze is authorized only if the recorded decision is **A. Promote to Phase 2**.
+
+If the decision is B or C, do not begin v1 domain freeze or framework selection.