diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index be1eb25..6a1d143 100644 --- a/.github/workflows/pages.yml +++ b/.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: diff --git a/app.js b/app.js index 3ef5930..f7835ac 100644 --- a/app.js +++ b/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(); -})(); +})(); \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 94b496b..0749751 100644 --- a/docs/README.md +++ b/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: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 04b1614..6c78040 100644 --- a/docs/ROADMAP.md +++ b/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**. diff --git a/docs/superpowers/plans/2026-09-06-m01-learning-validation.md b/docs/superpowers/plans/2026-09-06-m01-learning-validation.md index 0ada375..2278773 100644 --- a/docs/superpowers/plans/2026-09-06-m01-learning-validation.md +++ b/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. diff --git a/docs/validation/M01-COHORT-REVIEW-TEMPLATE.md b/docs/validation/M01-COHORT-REVIEW-TEMPLATE.md new file mode 100644 index 0000000..9913f74 --- /dev/null +++ b/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. diff --git a/docs/validation/M01-READINESS-AUDIT.md b/docs/validation/M01-READINESS-AUDIT.md new file mode 100644 index 0000000..c88659e --- /dev/null +++ b/docs/validation/M01-READINESS-AUDIT.md @@ -0,0 +1,350 @@ +# M01 Validation Readiness Audit + +## Purpose + +This audit closes the non-human part of PMO01 Phase 1 before real learner sessions. + +It checks whether the current M01 validation slice: + +1. has an explicit curriculum/competency target; +2. exercises the learning model rather than page completion; +3. can later be represented by the canonical content model without turning experimental measurement mechanics into permanent product requirements; +4. has known gaps documented before learner evidence is collected. + +This document is a **readiness audit**, not a Phase 1 exit decision. Phase 1 cannot exit without real learner evidence. + +## Sources reviewed + +- `docs/product/CURRICULUM.md` +- `docs/product/LEARNING_MODEL.md` +- `docs/product/METRICS.md` +- `docs/content/CONTENT_MODEL.md` +- current M01 candidate lessons in `course-data.js` +- `m01-validation-data.js` +- `docs/validation/M01-VALIDATION-PROTOCOL.md` + +## Executive result + +**Status: READY FOR LEARNER TESTING / NOT READY FOR PHASE 2.** + +The M01 slice is coherent enough to run the first real validation cohort. Its core learning target is narrow enough to measure, its interactions test meaningful PM reasoning, and no current observation requires a new permanent content entity solely to support the baseline/post experiment. + +The remaining Phase 1 blocker is empirical: + +> Run real learner sessions and determine whether M01 changes diagnosis/intervention reasoning and transfers to real project work. + +Do not freeze v1 contracts or select a framework before that gate. + +--- + +## 1. Curriculum scope + +### Recommended module competency contract + +M01 should be treated as targeting: + +- **Primary: C1 — System diagnosis** +- **Secondary: C8 — Intervention design** + +M01 uses examples involving dependencies, decisions, information, and feedback, but it should **not** claim mastery of C3, C6, or C7 from this module alone. Those concepts appear as evidence inside system diagnosis; their full competency treatment belongs to later curriculum units. + +This keeps the measured construct narrow enough for a meaningful pre/post comparison. + +### Candidate module outcome + +Current prototype outcome: + +> Построить карту семи потоков реального проекта и найти главный системный разрыв. + +Recommended canonical outcome after validation: + +> Given evidence from a real or described project, the learner can distinguish a visible symptom from a reproducible system mechanism, identify the most relevant flow break, choose a first intervention aimed at that mechanism, and state an early condition for changing course. + +This outcome is observable and maps directly to C1 + C8 and the five validation rubric dimensions. + +--- + +## 2. Lesson outcome audit + +| Lesson | Current instructional role | Recommended observable outcome | Competencies | Status | +|---|---|---|---|---| +| `project-system` | Changes unit of analysis from task/date to system/flow | Given project evidence, map the seven flows, separate facts from interpretations, and identify one system break that plausibly explains downstream symptoms. | C1 | Ready to test; canonical metadata missing | +| `system-diagnostic` | Traces symptom to reproducible system condition before intervening | Given a recurring project symptom, trace symptom → mechanism → system condition, choose an intervention aimed at the mechanism, and define an early signal that could invalidate the intervention. | C1, C8 | Ready to test; canonical metadata missing | + +### Findings + +- The lessons have distinct instructional jobs; they are not duplicates. +- Both practices require observable learner work rather than recall. +- The second lesson extends the first from system framing into intervention design. +- Current prototype fields use `thesis`, `body`, `model`, `practice`, and `criteria`, not the future canonical lesson metadata. This is a **migration transformation**, not a reason to modify the prototype now. + +### Learner-test question + +Watch for whether participants actually distinguish the two lessons: + +- Lesson 1 should change **where they look**. +- Lesson 2 should change **how they explain cause and choose action**. + +If learners experience both as the same idea, revise or merge before migration. + +--- + +## 3. Rubric audit + +The M01 validation rubric uses five dimensions: + +1. mechanism; +2. evidence; +3. trade-offs; +4. intervention; +5. change condition. + +This is consistent with: + +- C1: symptom/mechanism/system diagnosis; +- C8: intervention, expected effect, risk/trade-off, early signal/change condition; +- the L1 diagnostic-reasoning metric in `METRICS.md`; +- the Assessment Rubric examples in `CONTENT_MODEL.md`. + +### Decision + +**Keep the five dimensions stable for the first learner cohort.** + +Do not tune weights or thresholds between participants unless a question is clearly invalid. Changing rubric semantics mid-cohort would make pre/post and participant comparisons harder to interpret. + +The current `+3 total / 2 improved dimensions` rule remains a prototype development signal, not a mastery threshold or statistical claim. + +--- + +## 4. Decision Drill audit + +### `m01-drill-system` + +What it tests: + +- symptom response vs system response; +- whether an external dependency becomes an explicit managed node rather than hidden waiting time. + +Why it is useful: + +- all choices are plausible management reactions; +- the preferred answer changes the system rather than blaming the late task; +- feedback explains why local schedule compensation is weaker. + +Risk to observe: + +- the preferred answer may be too obvious after immediately reading the lesson. + +Learner-session signal: + +- useful if it exposes a misconception, causes a rationale change, or helps later transfer; +- weak if nearly everyone selects the preferred choice instantly and cannot articulate a meaningful contrast. + +### `m01-drill-diagnostic` + +What it tests: + +- stopping the causal chain at a reproducible decision/interface condition rather than QA or an individual developer. + +Why it is useful: + +- it directly tests C1 and C8; +- it distinguishes downstream detection from upstream mechanism; +- feedback explains the system condition rather than only marking correctness. + +Risk to observe: + +- wording around “где остановить причинную цепь” may require facilitator observation for ambiguity. + +### Content-model fit + +Canonical Decision Drill requires structured fields such as competencies and analysis of mechanism/trade-offs/change conditions. + +The prototype currently stores most analysis as per-choice feedback. Before v1 migration this should be transformed into structured canonical analysis, but no new entity type is required. + +**Classification: representable with enrichment; no content-model exception.** + +--- + +## 5. Integrative post-case audit + +The post-case is structurally similar to baseline but uses a different project scenario. It exercises all five rubric dimensions and requires free-text diagnosis before the scored choices. + +It satisfies the learning-model intent to test: + +- diagnosis; +- missing/relevant evidence; +- trade-off reasoning; +- intervention choice; +- change condition. + +### Content-model fit + +The canonical Integrative Case expects: + +- case evidence; +- diagnosis prompt; +- intervention decision; +- rationale prompt; +- evidence/change-condition prompt; +- assessment rubric. + +All of these concepts exist in the current post-case, although some are encoded as separate scored questions rather than named canonical fields. + +Before migration, convert the case into canonical structured content and reference an explicit rubric ID/version. + +**Classification: representable by canonical Integrative Case + Assessment Rubric; no new entity required.** + +--- + +## 6. Field Application audit + +Current M01 field application collects: + +- project/context and outcome; +- symptom; +- mechanism; +- intervention; +- early signal; +- observed evidence; +- next decision. + +This is a strong match to the intended transfer chain: + +`diagnosis → intervention → evidence → updated decision` + +### Content-model gaps before migration + +The canonical Field Application should make these properties explicit rather than infer them from UI fields: + +- `context_requirement`; +- `action_steps`; +- `expected_artifact`; +- `evidence_criteria`; +- `reflection_prompts`; +- `privacy_guidance`. + +The prototype contains enough material to derive these properties, but they are not yet first-class metadata. + +Recommended expected artifact for M01: + +> A short intervention record containing the observed symptom, proposed system mechanism, one minimal intervention, an early signal, observed evidence, and the next decision. + +Recommended evidence criteria: + +- mechanism is not merely a person or symptom; +- intervention acts on the proposed mechanism; +- early signal is observable before the final outcome where possible; +- evidence distinguishes observed result from an untested expectation; +- next decision follows from evidence rather than from course completion. + +Recommended privacy guidance: + +> Use anonymized project descriptions and omit confidential names, customer data, credentials, commercial terms, or sensitive internal metrics when they are not necessary for reasoning. + +**Classification: representable with metadata enrichment; no content-model exception.** + +--- + +## 7. Reflection audit + +The current reflection prompts ask what changed in: + +- diagnosis; +- first action; +- evidence requirements; +- remaining uncertainty. + +This maps directly to L3 Reflection Quality in `METRICS.md` and the learning-model requirement to update the learner's mental model. + +Reflection should remain qualitative during Phase 1. Do not add an automatic “reflection score” before learner samples show a stable, useful classification rule. + +**Classification: representable as Field Application / module reflection prompts.** + +--- + +## 8. What is validation harness vs production content + +This boundary is critical for v1 quality. + +### Validation harness — do not automatically migrate as permanent content entities + +- baseline case used to establish pre-learning reasoning; +- pre/post blinding behavior; +- prototype promotion threshold (`+3` / 2 dimensions); +- cohort/session measurement protocol; +- facilitator interview; +- comparison display used to inspect learning delta. + +These exist to **measure the product while it is being validated**. They are not automatically part of the learner-facing production curriculum. + +### Candidate production learning content + +- M01 lesson outcomes/content; +- Decision Drills that prove useful; +- integrative case; +- field application; +- reflection prompts that support transfer; +- assessment rubric semantics that remain useful after learner testing. + +### Consequence + +Do **not** add a permanent `BaselineAssessment` entity to `CONTENT_MODEL.md` merely because the Phase 1 experiment uses one. + +If future product requirements later need diagnostic/pre-assessment content in production, specify that separately from the current validation harness. + +--- + +## 9. Learner-state boundary + +The current prototype stores validation work separately in `pm01-validation-m01-v1` and reads legacy lesson completion from `pm01-state-v1`. + +This is appropriate for the reference prototype but is not the future learner repository contract. + +For v1, learner records should eventually reference: + +- program version; +- immutable content ID/version; +- interaction/attempt identity where needed; +- learning-state transition evidence. + +Do not design those stable contracts until Phase 1 evidence confirms which interactions and evidence must survive migration. + +--- + +## 10. Phase 1 promotion-gate status + +| Gate | Current status | Evidence still needed | +|---|---|---| +| Explicit learning outcomes | **Provisionally pass** | Confirm wording after learner observations | +| Lesson → competency mapping | **Provisionally pass** | C1 primary, C8 secondary; validate scope | +| Useful Decision Drill | **Implemented / unproven** | Real learner misconception/decision evidence | +| Integrative case | **Implemented / unproven** | Pre/post reasoning delta with real learners | +| Field transfer possible | **Implemented / unproven** | Credible real-project applications | +| Rubric usable | **Implemented / unproven** | Check ambiguity and discrimination in sessions | +| Major learner friction known | **Not passed** | Must observe real sessions | +| No unresolved content-model special case | **Provisionally pass** | Re-check after learner-driven revisions | + +## Decision + +### Current decision: RUN LEARNER SESSIONS + +Do not start Phase 2 contract freeze yet. + +Run at least **5 completed M01 sessions** using `M01-VALIDATION-PROTOCOL.md` and the session record template. Then review: + +1. diagnostic reasoning delta; +2. improved rubric dimensions; +3. drill usefulness; +4. credible field transfer; +5. reflection quality; +6. interface/content friction; +7. any learner-driven content-model exception. + +Possible gate outcomes remain: + +- **Promote to Phase 2** — evidence supports the learning format and no unresolved content-domain ambiguity remains; +- **Revise and retest** — interaction/content/rubric/friction distorts the result; +- **Reject mechanism** — an interaction adds complexity without useful learning evidence. + +Until one of those decisions is documented, Phase 2 is intentionally blocked. diff --git a/docs/validation/M01-SESSION-RECORD-TEMPLATE.md b/docs/validation/M01-SESSION-RECORD-TEMPLATE.md new file mode 100644 index 0000000..10a0c0a --- /dev/null +++ b/docs/validation/M01-SESSION-RECORD-TEMPLATE.md @@ -0,0 +1,178 @@ +# M01 Learner Session Record Template + +> Copy this file for each participant. Use a non-identifying participant ID. Do not record sensitive project details unless they are essential to the learning observation. + +## Session metadata + +- **Participant ID:** +- **Date:** +- **Role:** +- **Experience level:** +- **Facilitator:** +- **Browser/device:** +- **Fresh validation state confirmed:** yes / no + +## Baseline + +- **Baseline total (0–15):** +- **Mechanism:** +- **Evidence:** +- **Trade-offs:** +- **Intervention:** +- **Change condition:** +- **Free-text diagnosis summary:** +- **Observed reasoning pattern:** +- **Question ambiguity/friction:** + +> Baseline score and explanatory feedback must remain hidden from the participant until post-case submission. + +## Learning experience + +### Lesson 1 — `project-system` + +- What appeared to change in where the participant looked for the problem? +- Did they distinguish facts from interpretations? +- Did the seven-flow model help or add noise? +- Friction/ambiguity: + +### Decision Drill — `m01-drill-system` + +- **First choice:** +- **Why:** +- **Did feedback change the rationale?** yes / no / unclear +- **Misconception exposed:** +- **Interaction useful?** yes / partial / no +- **Reason:** + +### Lesson 2 — `system-diagnostic` + +- Could the participant distinguish symptom → mechanism → system condition? +- Did they move away from person-level explanations? +- Could they connect intervention to mechanism? +- Friction/ambiguity: + +### Decision Drill — `m01-drill-diagnostic` + +- **First choice:** +- **Why:** +- **Did feedback change the rationale?** yes / no / unclear +- **Misconception exposed:** +- **Interaction useful?** yes / partial / no +- **Reason:** + +## Integrative post-case + +- **Post total (0–15):** +- **Mechanism:** +- **Evidence:** +- **Trade-offs:** +- **Intervention:** +- **Change condition:** +- **Total delta:** +- **Improved dimensions:** +- **Prototype individual signal:** pass / not pass +- **Free-text diagnosis summary:** +- **What changed compared with baseline:** +- **Question ambiguity/friction:** + +## Field application + +- **Real/recent project used:** yes / no +- **Description sufficiently anonymized:** yes / no / n/a +- **Mechanism credible:** yes / partial / no +- **Intervention acts on mechanism:** yes / partial / no +- **Early signal observable:** yes / partial / no +- **Evidence actually observed:** yes / not yet / unclear +- **Next decision follows from evidence:** yes / partial / no +- **Overall transfer:** credible / partial / restatement only / not completed +- **Facilitator notes:** + +## Reflection + +Classify each item based on the participant's response. + +- **Changed diagnosis:** clear / partial / absent +- **Changed planned action:** clear / partial / absent +- **New evidence requirement:** clear / partial / absent +- **Remaining uncertainty made testable:** clear / partial / absent +- **Mostly restated lesson content:** yes / no / mixed + +Key quote or paraphrased observation: + +## Short interview + +### 1. What did you initially think the project problem was? + +Notes: + +### 2. What changed in your diagnosis after the module? + +Notes: + +### 3. Which part of the module caused that change? + +Notes: + +### 4. Which feedback felt obvious, misleading, or unconvincing? + +Notes: + +### 5. Could you use the model tomorrow without opening the course? Where? + +Notes: + +### 6. What information would you now request earlier on a real project? + +Notes: + +### 7. Where did the interface or wording interfere with your reasoning? + +Notes: + +## Reliability and UX observations + +- Any response/state loss: yes / no +- Reload/navigation recovery worked: yes / no / not tested +- Persistence error surfaced explicitly if applicable: yes / no / n/a +- Keyboard-critical path issue: yes / no / not tested +- Major abandonment/friction point: +- Other prototype defect: + +## Content-model observations + +Did the learner reveal any requirement that the current production content model cannot represent without a one-off exception? + +- yes / no / unclear + +If yes, describe the requirement without proposing architecture prematurely: + +## Delayed follow-up + +- **Run:** yes / no +- **Delay:** +- **New case/domain:** +- **Independent reconstruction of mechanism:** yes / partial / no +- **Intervention matched diagnosis:** yes / partial / no +- **Change condition/evidence stated:** yes / partial / no +- **Needed course terminology as prompt:** yes / no +- **Transfer persisted:** yes / partial / no / unclear + +## Session-level review + +- **Learning signal:** positive / mixed / absent / uninterpretable +- **Transfer evidence:** strong / partial / absent +- **Interaction usefulness:** strong / mixed / weak +- **Major friction:** none / manageable / blocking +- **Rubric ambiguity:** none / manageable / blocking +- **Recommended action for M01:** keep / revise / investigate / exclude session +- **Reason:** + +## Data handling + +Do not store: + +- credentials or access tokens; +- customer/person names when unnecessary; +- confidential contract/commercial terms; +- sensitive internal metrics when an abstract value or direction is sufficient; +- personal data not required to interpret the learning result. diff --git a/docs/validation/M01-VALIDATION-PROTOCOL.md b/docs/validation/M01-VALIDATION-PROTOCOL.md index d479b66..0805e38 100644 --- a/docs/validation/M01-VALIDATION-PROTOCOL.md +++ b/docs/validation/M01-VALIDATION-PROTOCOL.md @@ -43,7 +43,7 @@ Use people who can reason about real delivery work, for example: - Team Lead with delivery ownership; - Product/operations role that regularly coordinates dependencies and decisions. -Record experience level rather than filtering to one exact seniority. For the first cycle, aim for at least **5 completed sessions** before making a module-level promotion decision. More sessions are useful when results conflict. +Record experience level rather than filtering to one exact seniority. For the first cycle, require at least **5 completed sessions** before making a module-level promotion decision. More sessions are useful when results conflict. Do not use the course author as evidence of learning effectiveness. @@ -183,6 +183,21 @@ Record: Do not introduce an automatic mastery rule until delayed evidence has been reviewed across multiple sessions. +## Minimum evidence packet + +For each completed learner session, retain only the evidence needed for the Phase 1 decision: + +- anonymized participant ID and role/experience; +- baseline total, post total, delta, and improved dimensions; +- baseline and post free-text diagnoses; +- whether each Decision Drill exposed or changed reasoning; +- field transfer: credible / partial / no; +- reflection showing changed diagnosis/action/evidence requirement, or no meaningful change; +- major UX/reliability/content ambiguity that could distort the result; +- delayed-transfer evidence when available. + +Do not add new engineering telemetry or product instrumentation for this cohort. Use the existing session record template and manual evidence capture. + ## Session record For each participant record outside the product, using anonymized IDs where possible: @@ -209,7 +224,7 @@ Do not store sensitive project details when an anonymized description is suffici Do not migrate M01 into v1 solely because CI is green or the UI works. -After at least 5 completed learner sessions, review these five areas: +After at least **5 completed learner sessions**, review these five areas: ### 1. Learning signal @@ -248,10 +263,10 @@ Record every special case needed to represent M01. If the module requires one-of ## Promotion decision -Possible outcomes: +After the minimum cohort is complete, record exactly one outcome: -- **Promote** — learning mechanism and transfer evidence are strong enough to become v1 requirements. -- **Revise and retest** — promising signal, but content, rubric, interaction, or friction is materially distorting results. -- **Reject mechanism** — interaction adds complexity without useful reasoning evidence. +- **Promote to Phase 2** — learning mechanism and transfer evidence are strong enough to become v1 requirements. +- **Revise and retest** — promising signal, but content, rubric, interaction, or friction materially distorts results. +- **Reject mechanism** — interaction or module format adds complexity without useful reasoning/transfer evidence. -Document the decision and evidence before beginning the v1 vertical slice. +Until one of these outcomes is recorded after at least 5 completed sessions, Phase 2 and v1 work remain blocked. diff --git a/index.html b/index.html index 57a8347..0846e17 100644 --- a/index.html +++ b/index.html @@ -9,12 +9,6 @@ content="Практическая программа по проектному управлению как инженерии систем исполнения." /> PM 0.1 — Инженерия исполнения - - - @@ -55,4 +49,4 @@ - + \ No newline at end of file diff --git a/tests/m01-app-smoke.test.js b/tests/m01-app-smoke.test.js index 0663415..0fa9b29 100644 --- a/tests/m01-app-smoke.test.js +++ b/tests/m01-app-smoke.test.js @@ -5,6 +5,7 @@ const path = require('node:path'); const vm = require('node:vm'); const domain = require('../learning-domain.js'); +const baseAppCode = fs.readFileSync(path.join(__dirname, '..', 'app.js'), 'utf8'); const validationDataCode = fs.readFileSync(path.join(__dirname, '..', 'm01-validation-data.js'), 'utf8'); const validationAppCode = fs.readFileSync(path.join(__dirname, '..', 'm01-validation-app.js'), 'utf8'); @@ -53,6 +54,61 @@ function runValidationApp(route, initialStorage = {}) { return { main, moduleList, localStorage }; } +function runHashchangeOwnershipHandoff() { + const main = { innerHTML: '', focus() {} }; + const sidebarProgress = { innerHTML: '' }; + const mobileNav = { classList: { remove() {}, toggle() { return false; } } }; + const menuButton = { addEventListener() {}, setAttribute() {} }; + const listeners = { hashchange: [] }; + const microtasks = []; + const document = { + querySelector(selector) { + if (selector === '#main') return main; + if (selector === '#sidebar-progress') return sidebarProgress; + if (selector === '#mobile-nav') return mobileNav; + if (selector === '#menu-button') return menuButton; + return null; + }, + querySelectorAll() { return []; }, + }; + const localStorage = storageFrom(); + const window = { + PM01: { modules: [], flows: [], diagnostics: [], tools: [] }, + PM01Learning: domain, + addEventListener(type, callback) { + if (!listeners[type]) listeners[type] = []; + listeners[type].push(callback); + }, + scrollTo() {}, + confirm() { return true; }, + }; + const context = { + window, + document, + localStorage, + location: { hash: '#/unknown' }, + queueMicrotask(callback) { microtasks.push(callback); }, + console, + Date, + }; + vm.createContext(context); + vm.runInContext(validationDataCode, context, { filename: 'm01-validation-data.js' }); + vm.runInContext(baseAppCode, context, { filename: 'app.js' }); + vm.runInContext(validationAppCode, context, { filename: 'm01-validation-app.js' }); + + assert.equal(listeners.hashchange.length, 2, 'base and extension hashchange handlers must both be registered'); + main.innerHTML = 'sentinel-before-validation'; + context.location.hash = '#/validation/m01'; + + listeners.hashchange[0](); + const afterBaseRouter = main.innerHTML; + + listeners.hashchange[1](); + while (microtasks.length) microtasks.shift()(); + + return { afterBaseRouter, afterExtension: main.innerHTML }; +} + test('fresh validation route renders baseline without exposing learning drills or post-case controls', () => { const { main } = runValidationApp('validation/m01'); @@ -111,3 +167,10 @@ test('course route receives a single M01 validation CTA from the extension', () assert.match(moduleList.inserted, /data-validation-cta/); assert.match(moduleList.inserted, /#\/validation\/m01/); }); + +test('hashchange hands validation/m01 to the extension without base-router DOM overwrite', () => { + const { afterBaseRouter, afterExtension } = runHashchangeOwnershipHandoff(); + + assert.equal(afterBaseRouter, 'sentinel-before-validation', 'base router must yield without writing #main'); + assert.match(afterExtension, /01 · Baseline/, 'validation extension must own and render the route'); +}); diff --git a/tests/static-contract.test.js b/tests/static-contract.test.js index 3e9c090..badac28 100644 --- a/tests/static-contract.test.js +++ b/tests/static-contract.test.js @@ -9,6 +9,7 @@ function read(name) { } const html = read('index.html'); +const baseApp = read('app.js'); const validationApp = read('m01-validation-app.js'); const validationStyles = read('m01-validation.css'); @@ -25,6 +26,11 @@ test('index loads validation styles and data, domain, base app, then validation } }); +test('base router reserves the M01 validation route instead of rendering not-found before the extension', () => { + assert.equal(baseApp.includes('route: "validation-m01"'), true, 'base router must recognize validation/m01'); + assert.equal(baseApp.includes('if (route === "validation-m01")'), true, 'base renderer must yield validation/m01 to the extension'); +}); + test('validation extension owns the M01 validation route and course CTA', () => { assert.equal(validationApp.includes("validation/m01"), true, 'missing validation route'); assert.equal(validationApp.includes('data-validation-cta'), true, 'missing M01 validation CTA contract');