From 46dd0384f5f05a6d51e486930123603f8fc07386 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:53:07 +0500 Subject: [PATCH 01/12] docs: add project documentation map --- docs/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..94b496b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ +# PMO01 Documentation Map + +This directory is the source of truth for product, learning, content, architecture, and delivery decisions. + +## Current strategy + +PMO01 follows an **A → C** evolution path: + +1. Treat the current `main` implementation as a **reference prototype**. +2. Validate which learning and product mechanisms are worth keeping. +3. Design a separate scalable v1 architecture. +4. Migrate only validated content, interactions, and data contracts into v1. + +The reference prototype is not the long-term architecture. + +## Documents + +### Product +- `product/PRODUCT.md` — product purpose, users, value proposition, principles, non-goals. +- `product/LEARNING_MODEL.md` — how PMO01 expects learning to happen. +- `product/CURRICULUM.md` — competency map and curriculum contract. +- `product/PRODUCT_REQUIREMENTS.md` — product capabilities and staged requirements. +- `product/METRICS.md` — validation and learning-effectiveness metrics. + +### Content +- `content/CONTENT_MODEL.md` — canonical entities and rules for lessons, drills, cases, assessments, and artifacts. + +### 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. + +### Delivery +- `ROADMAP.md` — gates from prototype validation to scalable v1. + +### Design specs +- `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. + +## Source-of-truth precedence + +When documents conflict, use this order: + +1. Accepted ADRs. +2. Current platform foundation design. +3. Product and architecture documents listed above. +4. Historical V0 specs. +5. Existing prototype implementation. + +The prototype describes what exists today. It does not override an accepted product or architecture decision for v1. From 3e44a2f5b7ddc8ef1f7f5406260ccdd027481b59 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:53:30 +0500 Subject: [PATCH 02/12] docs: define PMO01 product contract --- docs/product/PRODUCT.md | 78 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/product/PRODUCT.md diff --git a/docs/product/PRODUCT.md b/docs/product/PRODUCT.md new file mode 100644 index 0000000..6975520 --- /dev/null +++ b/docs/product/PRODUCT.md @@ -0,0 +1,78 @@ +# PMO01 Product Contract + +## Product purpose + +PMO01 is a learning platform for developing senior-level Project Management judgment through diagnosis, decisions, field application, and reflection. + +It is not primarily a reference library, certification-prep course, or tool tutorial. + +## Core promise + +Help a learner move from managing tasks and ceremonies to diagnosing projects as systems and making higher-quality management decisions under uncertainty. + +## Primary learner + +PMO01 initially targets working or recently working project/process/delivery managers who already understand basic PM vocabulary and want to improve decision quality, systems thinking, and practical execution. + +V1 must not require that the learner works in a specific framework such as Scrum, Kanban, SAFe, or PMBOK. + +## Job to be done + +When a project becomes delayed, uncertain, overloaded, politically difficult, or hard to diagnose, the learner should be able to: + +1. identify the system mechanism producing the visible symptom; +2. distinguish output from outcome; +3. surface assumptions and uncertainty; +4. reason about dependencies, queues, constraints, decision latency, and feedback; +5. choose an intervention with explicit trade-offs; +6. collect evidence from the real project; +7. update the diagnosis after observing the result. + +## Product principles + +1. **Decision quality over content consumption.** Reading does not equal mastery. +2. **Real-project transfer over trivia.** Exercises should connect to work the learner actually manages. +3. **Systems thinking over ceremony memorization.** Frameworks are tools, not the organizing model. +4. **Evidence over confidence.** Completion and mastery must be tied to observable evidence where possible. +5. **Reflection over correctness theater.** Plausible trade-offs are more useful than simplistic green/red answers. +6. **Content and learning engine are separate.** The platform must support future curricula without rewriting the application. +7. **Quiet interface.** Editorial readability and reasoning take precedence over decorative gamification. +8. **Progressive architecture.** Do not introduce backend, AI, accounts, or generalized engines before a validated need exists. + +## Product boundaries + +### In scope for the PM curriculum +- systems diagnosis; +- value and outcomes; +- dependencies and flow; +- uncertainty and risk; +- decision architecture; +- information and feedback; +- operating mechanisms; +- interventions and learning loops. + +### Not the primary focus +- Jira usage; +- Scrum role memorization; +- PMBOK terminology drills; +- generic productivity advice; +- motivational content; +- certification exam preparation. + +## Platform ambition + +PMO01 should eventually support multiple professional learning programs while keeping the first PM curriculum coherent and deep. + +Possible future curricula may include Product Management, Team Leadership, Process Management, and AI-enabled management, but none are v1 requirements. + +## Current product state + +The current `main` branch is a reference prototype containing a static browser application, 10 modules / 20 lessons, seven-flow diagnostics, local progress and notes, and a toolkit. + +This prototype is used to validate product and learning assumptions. It is not the target architecture. + +## Definition of product success + +PMO01 succeeds if learners can demonstrate better project diagnosis and intervention reasoning after using the platform, not merely finish lessons. + +The validation model is defined in `METRICS.md`. From e3fed941127377756fe18179f94a788b06436919 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:53:59 +0500 Subject: [PATCH 03/12] docs: define PMO01 learning model --- docs/product/LEARNING_MODEL.md | 143 +++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/product/LEARNING_MODEL.md diff --git a/docs/product/LEARNING_MODEL.md b/docs/product/LEARNING_MODEL.md new file mode 100644 index 0000000..b756c74 --- /dev/null +++ b/docs/product/LEARNING_MODEL.md @@ -0,0 +1,143 @@ +# PMO01 Learning Model + +## Learning objective + +PMO01 is designed to change how a learner diagnoses and manages projects, not only what they can recall. + +The core instructional loop is: + +```text +Concept + ↓ +Case + ↓ +Decision + ↓ +Feedback + ↓ +Reflection + ↓ +Transfer to a real project + ↓ +Evidence + ↓ +Updated mental model +``` + +## What counts as learning + +A learner has not mastered a concept because they opened a page or selected the expected answer. + +Evidence of learning should progress through four levels: + +1. **Recognize** — identify the concept in a described situation. +2. **Reason** — explain mechanism, consequences, and trade-offs. +3. **Apply** — use the concept in an unfamiliar case. +4. **Transfer** — apply it to a real project and produce evidence from the intervention. + +The platform may track completion before it can reliably track mastery, but it must not label page visits as mastery. + +## Canonical lesson sequence + +A lesson should normally contain: + +1. **Problem frame** — why the concept matters. +2. **Principle** — the central claim. +3. **Mental model** — a reusable representation. +4. **Mechanism** — why the system behaves this way. +5. **Failure pattern** — a plausible but weak management response. +6. **Worked example** — the model applied to a concrete situation. +7. **Decision drill** — a realistic choice with consequences and trade-offs. +8. **Application task** — work on the learner's own project. +9. **Evidence criteria** — observable conditions for claiming the task was completed. +10. **Reflection prompt** — what changed in the learner's model or next decision. + +Not every lesson needs separate UI blocks for all ten stages. The sequence is an instructional contract, not a layout requirement. + +## Decision drills + +Decision drills are not trivia questions. + +A valid drill: + +- describes a realistic project situation; +- provides multiple plausible actions; +- forces prioritization or trade-offs; +- reveals analysis after the learner chooses; +- explains downstream consequences; +- can have a preferred action without pretending all ambiguity disappears. + +A weak drill asks for a definition or rewards superficial recall. + +## Boss cases / integrative cases + +Each module should end with an integrative case that combines multiple concepts from the module. + +A boss case should require the learner to: + +1. diagnose the system; +2. identify missing or misleading evidence; +3. choose an intervention; +4. explain why competing interventions are weaker or premature; +5. state what evidence would cause them to change course. + +## Field practice + +Every module should produce at least one reusable artifact or intervention on a real or recent project. + +Examples: + +- system map; +- assumption map; +- dependency graph; +- decision-latency map; +- experiment design; +- feedback-loop design; +- operating rule; +- intervention review. + +The artifact exists to improve a decision, not to satisfy a template requirement. + +## Feedback model + +Feedback should explain: + +- what mechanism the learner noticed or missed; +- what trade-off their action creates; +- what evidence matters next; +- what alternative action becomes appropriate under different conditions. + +Avoid celebratory correctness UI as the primary signal of learning. + +## Mastery model + +V1 should separate these states: + +- `unseen` — not engaged with; +- `studied` — lesson completed; +- `applied` — application task submitted or explicitly evidenced; +- `mastered` — demonstrated reasoning/application under a defined assessment rule. + +The exact mastery algorithm is intentionally deferred until PMO01 has enough evidence to define it without fake precision. + +## Spacing and retrieval + +For scalable v1, the content model must permit later addition of spaced review and retrieval practice. These are optional future capabilities, not requirements for the reference prototype. + +If added, review should target mental models and decisions, not rote terminology. + +## Personalization + +Personalization should eventually adapt sequence, examples, and review based on demonstrated gaps. It must not replace the curriculum's competency model with opaque AI recommendations. + +The diagnostic can recommend a starting point, but diagnostic scores are hypotheses about learning needs, not proof of competence. + +## Learning-quality gate + +Before a learning interaction is promoted into scalable v1, it should pass three questions: + +1. Does it expose a meaningful reasoning difference between stronger and weaker PM judgment? +2. Does the feedback explain mechanism and trade-offs rather than only the expected answer? +3. Can the learner transfer the idea to a different case or real project? + +If not, the interaction should be revised or removed. From 5fff23c08143c23944694076d316e8e7df14ab13 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:54:42 +0500 Subject: [PATCH 04/12] docs: define PMO01 curriculum contract --- docs/product/CURRICULUM.md | 123 +++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/product/CURRICULUM.md diff --git a/docs/product/CURRICULUM.md b/docs/product/CURRICULUM.md new file mode 100644 index 0000000..2c0a1e7 --- /dev/null +++ b/docs/product/CURRICULUM.md @@ -0,0 +1,123 @@ +# PMO01 Curriculum Contract + +## Purpose + +The curriculum defines what a strong PM should be able to diagnose and do after completing PMO01. It is independent from the current number of modules or the UI used to deliver them. + +## Organizing model: seven project flows + +PMO01 uses seven flows as the primary diagnostic lens: + +1. **Value** — how work connects to an observable user or business outcome. +2. **Work** — how work moves through the delivery system. +3. **Information** — how quickly relevant facts reach the people who need them. +4. **Decisions** — how decisions are made, owned, and delayed. +5. **Dependencies** — what blocks downstream valuable action. +6. **Uncertainty** — what must be true but has not yet been demonstrated. +7. **Feedback** — how the system detects error and updates behavior. + +These flows are the stable conceptual backbone. Module boundaries may change during content validation. + +## Target competencies + +A learner completing the core PM curriculum should be able to: + +### C1. System diagnosis +- define the project as a system producing an outcome; +- distinguish symptom, mechanism, systemic condition, and intervention; +- identify the flow in which a failure originates rather than only where it appears. + +### C2. Outcome and value reasoning +- distinguish output from outcome; +- express causal assumptions between work and business/user effect; +- identify weak links in an outcome hypothesis. + +### C3. Dependency and criticality reasoning +- model technical, organizational, decision, and external dependencies; +- reason about downstream impact rather than list priority; +- identify constraints and high-leverage nodes. + +### C4. Flow management +- identify queues, work accumulation, batching, handoff loss, and bottlenecks; +- understand why local utilization can reduce system throughput; +- select interventions that improve flow rather than local productivity optics. + +### C5. Uncertainty and risk +- make assumptions explicit; +- prioritize uncertainty by confidence, impact, and reversibility; +- design evidence-producing experiments before irreversible commitments. + +### C6. Decision architecture +- identify decision rights and decision latency; +- design escalation and ownership mechanisms; +- separate reversible from difficult-to-reverse decisions. + +### C7. Information and feedback +- identify missing, delayed, or distorted information; +- design feedback loops with clear consumers and decisions; +- distinguish status reporting from information that changes action. + +### C8. Intervention design +- choose a management intervention based on mechanism rather than symptom; +- define expected effect, risk, early signal, and stop/change condition; +- review intervention results and update the mental model. + +## Curriculum progression + +The canonical progression is: + +```text +Observe the system +→ Model causes and flows +→ Expose uncertainty and constraints +→ Choose an intervention +→ Collect evidence +→ Update the system +``` + +This progression matters more than preserving any historical module numbering. + +## Module contract + +Every production module must define: + +- `id` and title; +- competency targets; +- prerequisite competencies, if truly required; +- 2–5 lessons with distinct learning outcomes; +- at least one decision drill; +- one integrative/boss case; +- one field application artifact or intervention; +- evidence criteria; +- expected learner effort; +- assessment rule for any claimed mastery. + +## Lesson outcome contract + +Each lesson outcome must use observable behavior. Prefer: + +> "Given X project evidence, the learner can diagnose Y and choose Z with an explicit rationale." + +Avoid outcomes such as: + +- understand queues; +- learn dependencies; +- know risk management. + +## Current prototype mapping + +The existing prototype contains 10 modules and 20 lessons organized around the seven flows and adjacent system-management concepts. That content is treated as **candidate curriculum**, not automatically canonical curriculum. + +Before migration to v1, each lesson must be audited against: + +1. a target competency; +2. a unique learning outcome; +3. a valid decision/application activity; +4. evidence criteria; +5. redundancy with neighboring lessons. + +Lessons that fail this audit should be merged, rewritten, or removed rather than migrated unchanged. + +## Future curricula + +The platform architecture should permit other professional curricula, but PMO01 core content remains a separately versioned curriculum package. Future programs must define their own competency maps rather than reuse the seven PM flows by default. From bbfdba660025fa87e522a3438ab6eeb5c332e278 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:55:14 +0500 Subject: [PATCH 05/12] docs: define PMO01 content model --- docs/content/CONTENT_MODEL.md | 188 ++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 docs/content/CONTENT_MODEL.md diff --git a/docs/content/CONTENT_MODEL.md b/docs/content/CONTENT_MODEL.md new file mode 100644 index 0000000..d13019a --- /dev/null +++ b/docs/content/CONTENT_MODEL.md @@ -0,0 +1,188 @@ +# PMO01 Content Model + +## Goal + +Separate learning content from presentation and runtime behavior so that curricula can evolve, be versioned, validated, and reused without editing application code. + +## Canonical entities + +### Program + +A complete curriculum package. + +Required fields: + +```yaml +id: pm-core +version: 1 +slug: project-management +locale: ru +status: draft | validated | published | retired +``` + +### Module + +A coherent competency unit inside a program. + +Required fields: + +```yaml +id: flow-management +program: pm-core +order: 4 +title: Flow management +competencies: + - C4 +estimated_minutes: 240 +``` + +A module also references: + +- lesson IDs; +- integrative case ID; +- field application ID; +- prerequisite competency IDs when necessary. + +### Lesson + +A focused learning unit with one primary outcome. + +Required metadata: + +```yaml +id: queues +module: flow-management +order: 2 +title: Queues +estimated_minutes: 40 +competencies: + - C4 +outcome: "Given delivery evidence, diagnose harmful queue formation and choose a first intervention." +status: draft | validated | published | retired +``` + +Canonical lesson content sections: + +1. problem frame; +2. principle; +3. mental model; +4. mechanism; +5. failure pattern; +6. worked example; +7. decision drill references; +8. application task reference; +9. evidence criteria; +10. reflection prompt. + +The storage format may use Markdown plus structured front matter. UI components must consume parsed content rather than import lesson text from application source files. + +### Decision Drill + +```yaml +id: queues-drill-01 +competencies: + - C4 +scenario: ... +choices: + - id: a + text: ... +analysis: + preferred_choice: b + mechanism: ... + tradeoffs: ... + change_conditions: ... +``` + +A drill may have a preferred action, but feedback must explain context and trade-offs. + +### Integrative Case + +A multi-concept scenario used near the end of a module. + +Required properties: + +- case evidence; +- learner diagnosis prompt; +- intervention decision; +- rationale prompt; +- evidence/change-condition prompt; +- assessment rubric. + +### Field Application + +A task performed on a real or recent project. + +Required properties: + +- context requirement; +- action steps; +- expected artifact; +- evidence criteria; +- reflection prompts; +- privacy guidance when real work data is involved. + +### Artifact Template + +A reusable working document such as an assumption map or dependency map. + +Templates are content assets, not hard-coded download strings in application code. + +### Assessment Rubric + +Rubrics define how reasoning or application is evaluated. + +A rubric must contain observable dimensions rather than generic labels such as "good answer". + +Example dimensions: + +- mechanism identified; +- relevant evidence used; +- trade-offs acknowledged; +- intervention matches diagnosis; +- change condition stated. + +## Learner-state entities + +Content definitions must not contain learner state. + +Learner state belongs to the learning runtime and references immutable content IDs. + +Minimum conceptual state: + +```ts +type LearningState = + | 'unseen' + | 'studied' + | 'applied' + | 'mastered'; +``` + +Runtime records should be keyed by program version + content ID so future content changes do not silently corrupt historical progress. + +## Versioning rules + +1. Editorial correction with unchanged learning outcome may keep the same content version. +2. A changed learning outcome, rubric, or assessment semantics requires a new version. +3. Published IDs are stable and must not be reused for different concepts. +4. Retired content remains resolvable for historical learner records. +5. Migration between program versions must be explicit when accounts/server persistence exist. + +## Validation rules + +Before content is published, automated or editorial validation should verify: + +- unique IDs; +- valid module/lesson references; +- valid competency references; +- deterministic ordering; +- required fields present; +- no broken drill/case/artifact references; +- no published lesson without a measurable outcome. + +## V1 storage recommendation + +Use structured Markdown/YAML or an equivalent repository-native content format first. + +Do not introduce a CMS until authoring friction, multi-author workflows, publishing permissions, or content volume demonstrate the need. + +The application must depend on a content interface, not on the repository storage format directly. This keeps a future CMS migration possible without rewriting learning UI. From cfa04658bb8dd327df309190ed4c42a75c1db10e Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:55:44 +0500 Subject: [PATCH 06/12] docs: define staged PMO01 product requirements --- docs/product/PRODUCT_REQUIREMENTS.md | 166 +++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/product/PRODUCT_REQUIREMENTS.md diff --git a/docs/product/PRODUCT_REQUIREMENTS.md b/docs/product/PRODUCT_REQUIREMENTS.md new file mode 100644 index 0000000..9367d92 --- /dev/null +++ b/docs/product/PRODUCT_REQUIREMENTS.md @@ -0,0 +1,166 @@ +# PMO01 Product Requirements + +## Scope model + +PMO01 evolves through explicit validation gates. Requirements are separated into: + +- **Reference prototype requirements** — what the current implementation is allowed to prove. +- **V1 core requirements** — what the first scalable architecture must support. +- **Deferred capabilities** — features that require evidence before implementation. + +## Reference prototype + +The prototype exists to validate learning format and curriculum assumptions. + +Required behavior: + +- present PM learning content in a readable editorial interface; +- support navigation across the current curriculum; +- store lightweight progress locally; +- store learner notes locally; +- provide a diagnostic starting point; +- expose reusable field-work templates; +- support real-project application tasks; +- remain deployable as a static site. + +The current implementation already demonstrates most of this behavior. + +## V1 core capabilities + +### P1. Structured content ingestion + +The application must load program/module/lesson/case/drill/artifact definitions through a validated content interface. + +Acceptance conditions: + +- UI code contains no lesson body text; +- invalid content references fail validation before publication; +- one content package can be replaced by another without changing core learning UI. + +### P2. Curriculum navigation + +The learner can: + +- browse programs, modules, and lessons; +- continue from recent work; +- understand what a module develops; +- see prerequisite guidance when it materially affects learning. + +### P3. Learning interactions + +The runtime supports at minimum: + +- decision drills; +- integrative cases; +- field application prompts; +- reflection prompts; +- rubric-based assessment data structures. + +Not every assessment must be automatically scored. + +### P4. Progress model + +The product must distinguish engagement from learning evidence. + +Minimum states: + +- unseen; +- studied; +- applied; +- mastered. + +V1 may initially support only part of the transition logic, but the data model must not collapse these states into a single completion boolean. + +### P5. Learner work + +The learner can persist: + +- notes; +- drill/case decisions where useful; +- field application artifacts or structured responses; +- progress state. + +The first scalable release may still store data locally if validation does not yet require accounts. Storage implementation must be isolated behind an interface. + +### P6. Diagnostics + +Diagnostics may recommend where to start or what to revisit. + +Requirements: + +- recommendation logic is inspectable and deterministic unless explicitly redesigned; +- diagnostic result is described as guidance, not proof of mastery; +- diagnostic questions map to competencies or flows. + +### P7. Accessibility and readability + +The learning experience must support: + +- keyboard navigation for interactive controls; +- readable narrow and wide layouts; +- semantic document structure; +- visible focus states; +- sufficient text contrast; +- no essential information conveyed by color alone. + +### P8. Content version awareness + +Learner state must reference stable content IDs and program/content versions so future curriculum changes do not silently rewrite historical meaning. + +### P9. Observability + +Before large-scale growth work, the product must be able to observe the minimum learning funnel defined in `METRICS.md`. + +Instrumentation can be added only when there is a deployment model that can collect data ethically and legally. + +## Deferred capabilities + +Do not implement these without a separate decision/spec: + +- accounts and authentication; +- cloud sync; +- team/organization dashboards; +- payments; +- CMS; +- AI tutor; +- AI assessment; +- social features; +- leaderboards; +- XP/currency systems; +- generalized knowledge graph; +- adaptive sequencing engine; +- native mobile applications; +- certificates; +- enterprise reporting. + +## Quality attributes + +### Maintainability +- content is separated from runtime; +- domain modules have explicit interfaces; +- no single application file owns routing, rendering, learner state, and learning logic at scale. + +### Portability +- core content and learning model should not depend on GitHub Pages; +- hosting can change without rewriting curricula. + +### Testability +- content validation is automated; +- learning-state transitions are unit-testable; +- drill/case behavior is testable independently from full-page rendering; +- critical navigation paths have integration coverage. + +### Performance +- static content should render with minimal client JavaScript; +- interactive code should load only where required where practical; +- performance budgets should be defined when the v1 framework is selected. + +## Release gate for scalable v1 + +Do not start broad feature expansion until: + +1. the prototype learning format has been tested with real learners; +2. at least one module has validated drills, integrative assessment, and field transfer; +3. the canonical content model is stable enough to represent that module without special cases; +4. migration requirements are known; +5. the target architecture has an accepted ADR/spec. From c2c399523bed801e6d2377a8c09189d2425f7a0b Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:56:27 +0500 Subject: [PATCH 07/12] docs: define current and target PMO01 architecture --- docs/architecture/ARCHITECTURE.md | 259 ++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 docs/architecture/ARCHITECTURE.md diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md new file mode 100644 index 0000000..e94a1af --- /dev/null +++ b/docs/architecture/ARCHITECTURE.md @@ -0,0 +1,259 @@ +# PMO01 Architecture + +## Architecture status + +PMO01 currently has two architectural descriptions: + +1. the working static prototype on `main`; +2. the historical V0 Astro design spec. + +Neither is automatically the target v1 architecture. + +The accepted strategy is **A → C**: + +- preserve the current prototype as a product/learning reference; +- validate useful mechanisms; +- design a scalable v1 architecture from validated requirements; +- migrate selectively. + +## Current reference prototype + +Current implementation characteristics: + +```text +index.html + ↓ +app.js + ├── routing + ├── rendering + ├── learner state + ├── diagnostics + ├── interaction binding + └── toolkit behavior + +course-data.js + ├── flows + ├── modules + ├── lessons + ├── diagnostics + └── tools + +localStorage + └── learner progress / notes / diagnostic answers +``` + +Strengths: + +- extremely low operational complexity; +- deployable as static files; +- useful as a learning-format prototype; +- no backend dependency; +- fast to change during discovery. + +Scaling constraints: + +- content is embedded in JavaScript application data; +- routing, rendering, interaction logic, and learner state are concentrated in one application file; +- binary completion cannot represent stronger learning evidence; +- no explicit content version model; +- diagnostics are coupled directly to prototype data structures; +- adding many programs or authors would increase coupling and review risk; +- server-backed identity, sync, analytics, or AI would require new boundaries rather than incremental additions inside `app.js`. + +## Architectural principles for v1 + +1. **Content is data, not application code.** +2. **Learning domain logic is independent from page rendering.** +3. **Learner state is behind an interface.** Local and remote persistence must be replaceable. +4. **Content IDs and versions are stable.** +5. **Static-first delivery remains preferred while requirements permit it.** +6. **Interactive behavior is introduced only where learning needs it.** +7. **AI is an optional adapter, not the source of curriculum truth.** +8. **Framework choice follows validated product requirements.** Do not select v1 technology solely because the old V0 spec named Astro. + +## Target logical architecture + +```text + ┌─────────────────────┐ + │ Content packages │ + │ programs/modules/...│ + └──────────┬──────────┘ + │ validate/parse + ┌──────────▼──────────┐ + │ Content service │ + │ stable read model │ + └──────────┬──────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ +┌─────────▼────────┐ ┌─────────▼────────┐ ┌────────▼─────────┐ +│ Learning runtime│ │ Curriculum nav │ │ Assessment logic │ +│ state transitions│ │ sequence/context │ │ rubrics/evidence │ +└─────────┬────────┘ └─────────┬────────┘ └────────┬─────────┘ + └────────────────────┼────────────────────┘ + │ + ┌──────────▼──────────┐ + │ Presentation layer │ + │ pages/components/UI │ + └──────────┬──────────┘ + │ + ┌──────────▼──────────┐ + │ Learner repository │ + │ local or remote │ + └─────────────────────┘ +``` + +## Core boundaries + +### 1. Content package + +Owns curriculum definitions and editorial material. + +Does not own: + +- learner progress; +- UI components; +- authentication; +- analytics transport. + +### 2. Content service + +Consumes validated content definitions and exposes a stable application-facing interface. + +Examples of conceptual reads: + +```ts +getProgram(programId) +getModule(moduleId) +getLesson(lessonId) +getNextLearningUnit(currentId) +getAssessment(assessmentId) +``` + +Storage format is hidden behind this boundary. + +### 3. Learning runtime + +Owns state transitions and rules such as: + +- studied; +- applied; +- mastered; +- recent activity; +- evidence references. + +It must not render HTML or know where content files live. + +### 4. Assessment domain + +Owns decision drills, case responses, rubrics, and evidence semantics. + +Automated scoring is optional. The model must allow human/self/AI-assisted evaluation later without redefining content IDs. + +### 5. Learner repository + +Persistence interface for progress, responses, and notes. + +Initial implementations may use browser storage. Future implementations may use a backend. + +The UI must not call `localStorage` directly. + +### 6. Presentation layer + +Owns navigation, reading experience, controls, feedback presentation, and accessibility. + +It consumes domain interfaces and does not define curriculum semantics. + +## Data flow + +### Lesson load + +```text +route +→ content service resolves lesson +→ runtime loads learner state +→ page renders lesson + state +``` + +### Decision drill + +```text +learner selects action +→ assessment domain records response +→ feedback model resolves analysis +→ learner repository persists response +→ UI displays mechanism/trade-offs +``` + +### Field application + +```text +application task +→ learner creates evidence / response +→ repository stores reference or content +→ assessment/runtime updates applied state when criteria are met +``` + +## Error handling principles + +V1 should fail explicitly for content-integrity errors. + +Examples: + +- duplicate IDs; +- missing referenced drill; +- invalid module order; +- unknown competency reference; +- incompatible content version. + +These should fail build/publish validation rather than produce broken learner pages. + +Runtime persistence failures should preserve the learning page and surface a clear state-saving error rather than discard learner input silently. + +## Technology decision + +No final v1 framework is accepted yet. + +The historical Astro recommendation remains a candidate because static-first content and interactive islands fit the product well, but framework selection should be made in a dedicated architecture decision after the validation gate. + +Candidate evaluation criteria: + +- content pipeline quality; +- static generation; +- TypeScript support; +- accessibility ergonomics; +- testability; +- deployment portability; +- incremental interactivity; +- migration cost from the prototype; +- future support for authenticated/server-backed features without corrupting domain boundaries. + +## Migration strategy + +Do not rewrite the entire prototype before validation. + +Migration should happen vertically: + +1. select one validated module; +2. express it in the canonical content model; +3. implement content validation; +4. implement the minimum learning runtime; +5. reproduce its learning experience in v1; +6. compare behavior and usability; +7. only then migrate remaining validated modules. + +The reference prototype remains available for comparison until v1 reaches functional parity for validated learning paths. + +## Testing architecture + +Required test layers for v1: + +- content schema/relationship validation; +- unit tests for learning-state transitions; +- unit tests for diagnostic recommendation rules; +- interaction tests for drills/cases; +- navigation integration tests; +- a small number of end-to-end learner paths; +- accessibility checks for interactive controls. + +Do not build a large E2E suite before domain contracts stabilize. From 9aa2add1073a0817524f7657969f98522ff455ab Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:56:59 +0500 Subject: [PATCH 08/12] docs: define PMO01 validation metrics --- docs/product/METRICS.md | 168 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 docs/product/METRICS.md diff --git a/docs/product/METRICS.md b/docs/product/METRICS.md new file mode 100644 index 0000000..2271d1b --- /dev/null +++ b/docs/product/METRICS.md @@ -0,0 +1,168 @@ +# PMO01 Metrics and Validation + +## Principle + +PMO01 should optimize for improvement in project-management judgment, not lesson completion alone. + +Metrics are split into: + +1. learning-quality metrics; +2. behavior/engagement metrics; +3. product-quality metrics; +4. migration gates. + +## North-star learning question + +> After using PMO01, can a learner diagnose a project situation and choose a stronger intervention with better reasoning than before? + +No single percentage can prove this. Validation should combine structured assessment and qualitative evidence. + +## Learning-quality metrics + +### L1. Diagnostic reasoning delta + +Measure performance on structurally similar but non-identical cases before and after a module. + +Score dimensions: + +- mechanism identified; +- relevant evidence selected; +- trade-offs acknowledged; +- intervention matches diagnosis; +- change condition stated. + +Use a stable rubric. Do not reuse identical questions for pre/post measurement. + +### L2. Transfer rate + +Definition: + +```text +learners who complete a real-project application with evidence +-------------------------------------------------------------- +learners who study the corresponding module +``` + +This is more important than page completion. + +### L3. Reflection quality + +Sample learner reflections and classify whether they show: + +- changed diagnosis; +- changed planned action; +- new evidence requirement; +- unchanged/restated lesson content only. + +This can be reviewed manually during prototype validation. + +### L4. Delayed retrieval / application + +Where feasible, check whether the learner can apply the concept to a new case after a delay rather than immediately after reading. + +This becomes more important before any mastery label is introduced. + +## Engagement metrics + +These diagnose friction; they are not proof of learning. + +Track when infrastructure exists: + +- module start rate; +- lesson completion rate; +- decision-drill participation; +- field-application start/completion; +- return rate after first session; +- time to first meaningful application; +- abandonment point by learning unit. + +Avoid optimizing for total minutes spent. + +## Product-quality metrics + +### P1. Content integrity + +- zero broken references in published content; +- zero duplicate published IDs; +- 100% of published lessons mapped to measurable outcomes and competencies. + +### P2. Reliability + +For persisted learner work: + +- no silent loss of notes/responses; +- recoverable state after ordinary page reload/navigation; +- explicit error when persistence fails. + +### P3. Accessibility + +Critical learner paths must be keyboard operable and semantically readable. + +### P4. Performance + +Define numerical budgets when the v1 framework/deployment model is selected. Until then, the constraint is static-first rendering with minimal client JavaScript. + +## Prototype validation protocol + +Before broad v1 implementation, validate at least one complete module with real learners. + +Recommended minimum study: + +1. baseline case; +2. module learning experience; +3. boss/integrative case; +4. real-project application; +5. short interview about reasoning and friction; +6. delayed follow-up case when practical. + +The goal is to discover learning and product failure modes, not to establish statistically generalizable effect size at prototype scale. + +## Promotion gate: interaction + +A learning interaction can be promoted into v1 when it demonstrates at least one of: + +- reveals a meaningful reasoning difference; +- changes the learner's diagnosis; +- improves transfer to a real project; +- exposes a misconception worth addressing. + +Interactions that only create engagement or cosmetic progress should not become architectural requirements. + +## Promotion gate: module + +A prototype module is ready for migration when: + +- learning outcomes are explicit; +- every lesson maps to competencies; +- at least one decision drill has useful feedback; +- the integrative case exercises multiple concepts; +- field transfer is possible; +- rubric/evidence criteria are usable; +- major learner friction is known; +- no unresolved content-model special case is required to represent it. + +## V1 success gate + +Do not claim scalable v1 is successful because migration is technically complete. + +V1 must preserve or improve: + +- reading usability; +- reasoning quality; +- transfer completion; +- learner-state reliability; + +while making content maintenance and future program growth materially easier. + +## Metrics anti-patterns + +Do not use these as primary success measures: + +- number of pages; +- number of lessons; +- raw time on site; +- XP earned; +- streak length; +- percentage of content opened. + +They may describe use but not the product's learning promise. From 075603e070c9943cfbc29f0c414915c40150e8f3 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:57:25 +0500 Subject: [PATCH 09/12] docs: record A to C evolution strategy --- .../adr/0001-reference-prototype-to-v1.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/architecture/adr/0001-reference-prototype-to-v1.md diff --git a/docs/architecture/adr/0001-reference-prototype-to-v1.md b/docs/architecture/adr/0001-reference-prototype-to-v1.md new file mode 100644 index 0000000..c470d51 --- /dev/null +++ b/docs/architecture/adr/0001-reference-prototype-to-v1.md @@ -0,0 +1,101 @@ +# ADR 0001 — Evolve from Reference Prototype to Scalable V1 + +- Status: Accepted +- Date: 2026-09-06 + +## Context + +PMO01 has a working static prototype on `main` and a historical V0 design that proposed Astro, Markdown-first content, and a single FLOW vertical slice. + +The working prototype moved beyond that V0 scope: it contains a broader curriculum, diagnostics, local learner state, notes, and tools. At the same time, its implementation couples content, routing, rendering, learner state, and interactions too tightly for long-term multi-program growth. + +Three options were considered: + +### Option A — Keep evolving the current prototype + +Advantages: + +- low immediate cost; +- preserves working behavior; +- fastest path for experiments. + +Disadvantages: + +- increasing coupling; +- difficult content/version management; +- poor foundation for accounts, richer assessment, multiple curricula, or teams; +- high risk of turning prototype structure into permanent architecture. + +### Option B — Return to the historical V0 Astro design + +Advantages: + +- simpler vertical slice; +- clean static/content-first direction. + +Disadvantages: + +- discards useful work and product discoveries; +- treats an older design document as more authoritative than observed prototype requirements; +- framework choice precedes renewed validation. + +### Option C — Immediately rewrite as a scalable v1 + +Advantages: + +- strongest theoretical separation of concerns; +- removes prototype constraints early. + +Disadvantages: + +- high overengineering risk; +- architecture could encode unvalidated learning interactions; +- migration scope is large before the product has proven what must be retained. + +## Decision + +Use **A → C**. + +1. Preserve the current `main` implementation as a **reference prototype**. +2. Stop treating prototype architecture as the default place for long-term expansion. +3. Validate learning format, curriculum elements, diagnostics, and interactions with real users. +4. Define stable product, learning, content, and data contracts. +5. Design scalable v1 after those contracts are sufficiently validated. +6. Migrate vertically, starting with one validated module. +7. Retire prototype behavior only after v1 reproduces or improves the validated learning experience. + +## Consequences + +### Positive + +- avoids throwing away working product evidence; +- delays irreversible architecture decisions; +- provides a controlled migration path; +- makes content and learning logic first-class domains; +- enables future programs without making them current requirements. + +### Negative + +- two implementations may coexist temporarily; +- some prototype work will not be migrated; +- short-term feature requests may need to be rejected if they deepen prototype coupling; +- migration requires explicit comparison and content audit. + +## Guardrails + +Until a v1 architecture spec is accepted: + +- do not add backend/auth/CMS/AI architecture to the prototype; +- do not expand `course-data.js` as if it were the permanent content system; +- do not turn `app.js` into a generalized platform runtime; +- prototype-only experiments are allowed when cheap and reversible; +- new prototype work should be justified by a validation question. + +## Revisit conditions + +Revisit this ADR only if: + +- the reference prototype proves inadequate even for validation; +- a hard external requirement forces server-backed functionality before the validation gate; +- the content model cannot represent a validated learning module without major special cases; +- evidence shows a different product direction. From 5c8024b70f5161ac20b2122291e080ab6b66c91e Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:57:55 +0500 Subject: [PATCH 10/12] docs: add PMO01 staged roadmap --- docs/ROADMAP.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/ROADMAP.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..04b1614 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,169 @@ +# PMO01 Roadmap + +## Strategy + +PMO01 evolves through validation gates, not feature accumulation. + +```text +Reference prototype +→ learning validation +→ content contract validation +→ v1 architecture decision +→ one-module vertical migration +→ measured parity/improvement +→ broader migration +→ optional platform expansion +``` + +## Phase 0 — Stabilize the reference prototype + +Goal: make the existing product reliable enough to use as a learning experiment without turning it into the permanent architecture. + +Deliverables: + +- current product behavior documented; +- current curriculum treated as candidate content; +- no major new platform subsystems added; +- obvious prototype-breaking defects fixed when they block validation; +- a small set of representative learning paths selected for testing. + +Exit gate: + +- the prototype can support a learner through at least one complete module without critical usability/data-loss issues. + +## Phase 1 — Validate the learning model + +Goal: determine which learning mechanisms actually improve PM reasoning and transfer. + +Deliverables: + +- select one representative module; +- audit lesson outcomes against `CURRICULUM.md`; +- improve at least one decision drill; +- create or validate one integrative case; +- create one real-project field application; +- define a rubric; +- run learner tests using the protocol in `METRICS.md`. + +Exit gate: + +- evidence indicates the module format can reveal and improve reasoning, not merely deliver content; +- major interaction/content failures are known; +- the validated module can be represented by `CONTENT_MODEL.md` without ad hoc exceptions. + +## Phase 2 — Freeze v1 domain contracts + +Goal: define the minimum stable contracts that implementation may depend on. + +Deliverables: + +- final v1 content schema; +- stable content IDs/version rules; +- learning-state transition model; +- assessment/rubric model; +- learner repository interface; +- diagnostic mapping contract; +- migration rules from prototype content/state where relevant. + +Exit gate: + +- contracts can represent the validated module end-to-end; +- unresolved questions are implementation details, not domain ambiguity. + +## Phase 3 — Select v1 technical architecture + +Goal: choose framework and deployment architecture based on validated requirements. + +Deliverables: + +- compare candidate approaches; +- architecture ADR; +- repository/file structure; +- build/test/deploy strategy; +- performance/accessibility constraints; +- plan for local persistence and future remote persistence boundary. + +Likely candidates may include Astro or another TypeScript static-first framework, but no framework is selected by this roadmap. + +Exit gate: + +- selected architecture implements the domain contracts without coupling content to presentation; +- migration cost is understood; +- no deferred subsystem has been smuggled into v1 requirements. + +## Phase 4 — Build one-module v1 vertical slice + +Goal: prove the target architecture with one validated module. + +Deliverables: + +- content validation pipeline; +- content service; +- curriculum navigation; +- learning runtime; +- learner repository implementation; +- decision drill interaction; +- integrative case interaction; +- field application workflow; +- accessibility and core tests; +- deployment. + +Exit gate: + +- the validated module works end-to-end in v1; +- learner experience is at least as good as the prototype; +- content can be edited without touching UI runtime code; +- state transitions and content relationships have automated tests. + +## Phase 5 — Migrate validated PM curriculum + +Goal: move only content that passes curriculum and learning-quality audits. + +Process per module: + +1. audit outcomes and competency mapping; +2. remove duplication; +3. validate drills/cases/application; +4. convert to canonical content model; +5. migrate assets/templates; +6. test content integrity; +7. publish; +8. compare learner behavior/feedback with prototype where possible. + +Exit gate: + +- all production modules satisfy curriculum/content contracts; +- prototype is no longer required for validated PM paths. + +## Phase 6 — Introduce server-backed learner state only if needed + +Possible triggers: + +- cross-device progress is a validated retention need; +- learner work must persist beyond one browser; +- authenticated cohorts/organizations are required; +- analytics require durable learner/event identity; +- paid product requires account entitlement. + +Deliverables require a separate spec/ADR. + +## Phase 7 — Optional intelligence and scale features + +Only after core learning quality and state model are stable, evaluate separately: + +- AI tutor; +- AI-assisted rubric feedback; +- adaptive review; +- personalized sequencing; +- multi-program catalog; +- team/enterprise learning; +- authoring/CMS workflows; +- payments/certificates. + +Each is an independent product decision, not a default consequence of “scaling”. + +## Immediate next decision + +Before code migration begins, review and accept the platform foundation documents in `docs/`. + +After acceptance, write an implementation plan for **Phase 1 only** rather than a single plan spanning the entire roadmap. From 840a06056052811fb7e2b18f102368bc468a0322 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:58:44 +0500 Subject: [PATCH 11/12] docs: define PMO01 platform foundation design --- ...-09-06-pmo01-platform-foundation-design.md | 332 ++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-06-pmo01-platform-foundation-design.md diff --git a/docs/superpowers/specs/2026-09-06-pmo01-platform-foundation-design.md b/docs/superpowers/specs/2026-09-06-pmo01-platform-foundation-design.md new file mode 100644 index 0000000..3364abc --- /dev/null +++ b/docs/superpowers/specs/2026-09-06-pmo01-platform-foundation-design.md @@ -0,0 +1,332 @@ +# PMO01 Platform Foundation Design + +## Status + +Proposed design approved in principle on 2026-09-06: evolve via **A → C** — preserve the current implementation as a reference prototype, validate learning mechanisms, then build a separate scalable v1 architecture from validated contracts. + +This document is the current platform-foundation design. The earlier `2026-09-03-pmo01-v0-design.md` remains historical context and does not define the target architecture. + +## Problem + +PMO01 currently has useful product behavior but conflicting architectural direction: + +- the working `main` branch is a static JavaScript application containing a broad PM curriculum, diagnostics, learner progress, notes, and tools; +- the historical V0 design proposed Astro, Markdown-first content, one FLOW module, and a smaller vertical slice. + +Continuing the current implementation indefinitely would make content, learning logic, state, rendering, and future platform capabilities increasingly coupled. Rewriting immediately would risk designing around unvalidated assumptions. + +## Decision + +Adopt a staged architecture transition. + +### A — Reference prototype + +The current `main` implementation is retained as the reference implementation for product and learning validation. + +It answers questions such as: + +- Is the curriculum useful? +- Do learners understand the seven-flow model? +- Do application tasks transfer to real projects? +- Do diagnostics help choose a learning path? +- Which interactions change reasoning? + +It is not the long-term platform architecture. + +### C — Scalable v1 + +A separate v1 architecture will be implemented only after one representative module has validated learning outcomes, interactions, assessment, and field transfer. + +V1 will separate: + +1. content packages; +2. content validation/read model; +3. curriculum navigation; +4. learning-state runtime; +5. assessment/evidence logic; +6. learner persistence; +7. presentation. + +Framework selection is deferred until the domain contracts are validated. Astro remains a candidate, not a decision. + +## Product contract + +The product exists to improve senior-level PM diagnosis and intervention reasoning under uncertainty. + +The learner should progress from: + +```text +task/status management +→ system diagnosis +→ mechanism reasoning +→ explicit trade-offs +→ evidence-producing intervention +→ reflection and model update +``` + +The platform is not primarily a Scrum/Jira/PMBOK tutorial or certification course. + +Canonical product rules are in `docs/product/PRODUCT.md`. + +## Learning architecture + +The core learning loop is: + +```text +Concept +→ Case +→ Decision +→ Feedback +→ Reflection +→ Transfer +→ Evidence +→ Updated mental model +``` + +Learning evidence progresses through: + +- recognize; +- reason; +- apply; +- transfer. + +Runtime state must not treat page visits as mastery. + +Canonical runtime learning states are: + +- `unseen`; +- `studied`; +- `applied`; +- `mastered`. + +The exact mastery algorithm is deferred until evidence supports one. + +See `docs/product/LEARNING_MODEL.md`. + +## Curriculum architecture + +The seven project flows remain the core PM diagnostic model: + +- value; +- work; +- information; +- decisions; +- dependencies; +- uncertainty; +- feedback. + +The stable contract is competency-based, not tied to the current 10-module numbering. + +The existing 10 modules / 20 lessons are candidate curriculum. Before migration, each lesson must demonstrate: + +- competency mapping; +- measurable outcome; +- non-redundant purpose; +- decision/application activity; +- evidence criteria. + +See `docs/product/CURRICULUM.md`. + +## Content architecture + +Content becomes repository-native structured data rather than JavaScript runtime data. + +Canonical entities: + +- Program; +- Module; +- Lesson; +- Decision Drill; +- Integrative Case; +- Field Application; +- Artifact Template; +- Assessment Rubric. + +Content must use stable IDs and version-aware references. Published IDs are never reused for a different concept. + +V1 UI must consume a content interface rather than import lesson bodies from application source files. + +See `docs/content/CONTENT_MODEL.md`. + +## Target logical architecture + +```text +Content package + │ + ▼ +validation/parser + │ + ▼ +Content service + │ + ┌────┼─────────────┐ + ▼ ▼ ▼ +Nav Learning Assessment + runtime domain + └────┼─────────────┘ + ▼ +Presentation + │ + ▼ +Learner repository +(local first; remote later if validated) +``` + +Key constraints: + +- presentation does not own learning semantics; +- learner state is behind an interface; +- content storage format is behind an interface; +- diagnostics map to explicit competencies/flows; +- assessment feedback is deterministic/inspectable unless separately redesigned; +- AI cannot become the source of curriculum truth. + +See `docs/architecture/ARCHITECTURE.md`. + +## Product requirements + +The scalable v1 must support: + +1. structured content ingestion and validation; +2. curriculum navigation; +3. decision drills, integrative cases, field applications, and reflection; +4. multi-state learning progress; +5. persisted learner work through an isolated repository interface; +6. inspectable diagnostics; +7. accessibility/readability; +8. content version awareness; +9. minimum observability when an ethical/legal collection mechanism exists. + +Explicitly deferred: + +- authentication; +- cloud sync; +- CMS; +- payments; +- AI tutor; +- AI assessment; +- social/gamification engines; +- knowledge graphs; +- enterprise dashboards; +- native mobile applications. + +See `docs/product/PRODUCT_REQUIREMENTS.md`. + +## Validation design + +The next implementation phase is not “build v1”. It is **validate one representative module end-to-end**. + +Validation requires: + +1. baseline case; +2. module learning experience; +3. integrative case; +4. real-project application; +5. rubric-based review; +6. qualitative friction/reasoning review; +7. delayed follow-up case when practical. + +The goal is to identify which mechanisms deserve promotion into v1. + +Primary success question: + +> Can the learner make a better diagnosis and intervention decision after using the module? + +See `docs/product/METRICS.md`. + +## Migration design + +Migration is vertical, not wholesale. + +For the first migrated module: + +1. validate learning outcomes and interactions in the prototype; +2. express the module in the canonical content model; +3. implement content validation; +4. implement minimum content service; +5. implement minimum learning runtime and learner repository; +6. reproduce drills/case/application in v1; +7. compare usability and learning evidence with the prototype; +8. fix architecture/content-contract failures; +9. only then migrate additional modules. + +Prototype and v1 may coexist temporarily. + +## Error handling + +### Content integrity + +Broken references, duplicate IDs, unknown competency mappings, and incompatible versions must fail validation before publication. + +### Learner persistence + +Persistence failures must not silently discard learner work. UI must preserve unsaved input where possible and surface a clear error. + +### Unsupported content + +If the v1 content runtime encounters an unsupported entity/version, it should fail explicitly during validation or render a controlled unavailable state rather than partially interpreting content. + +## Testing design + +V1 testing should prioritize domain contracts: + +- schema/relationship validation; +- learning-state transition unit tests; +- diagnostic-rule unit tests; +- drill/case interaction tests; +- navigation integration tests; +- accessibility checks; +- a small number of end-to-end learning paths. + +Large E2E coverage is deferred until contracts stabilize. + +Prototype testing remains limited to defects that block learning validation. + +## Documentation architecture + +The following documents are required sources of truth: + +- `docs/README.md` — documentation precedence and map; +- `docs/product/PRODUCT.md` — product contract; +- `docs/product/LEARNING_MODEL.md` — instructional model; +- `docs/product/CURRICULUM.md` — competencies and curriculum rules; +- `docs/product/PRODUCT_REQUIREMENTS.md` — staged product capabilities; +- `docs/product/METRICS.md` — learning/product validation; +- `docs/content/CONTENT_MODEL.md` — content entities and versioning; +- `docs/architecture/ARCHITECTURE.md` — architecture boundaries and migration; +- `docs/architecture/adr/0001-reference-prototype-to-v1.md` — accepted A → C decision; +- `docs/ROADMAP.md` — gated delivery sequence. + +Documents that are intentionally deferred until their triggering phase: + +- detailed v1 framework ADR; +- backend/auth architecture; +- analytics/event taxonomy; +- privacy/data-retention policy for server-side learner data; +- AI tutor/assessment policy; +- billing/entitlement model; +- CMS/editorial workflow; +- multi-tenant/enterprise model. + +Creating these now would imply requirements that have not been validated. + +## Acceptance criteria for platform foundation + +The foundation design is complete when: + +1. A → C is recorded as an accepted architecture strategy. +2. The reference prototype and target v1 are clearly distinguished. +3. Product purpose and non-goals are explicit. +4. The learning model separates study, application, and mastery. +5. Curriculum is competency-based and not coupled to historical module numbering. +6. Content has stable entities, IDs, and version rules. +7. Target architecture separates content, learning logic, persistence, and presentation. +8. Deferred capabilities are explicit. +9. Validation metrics and promotion gates are defined. +10. Roadmap starts with learning validation, not a framework rewrite. + +## Next step after approval + +After this foundation is reviewed and approved, create a detailed implementation plan for **Phase 1 — validate one representative module**. + +Do not create a full v1 implementation plan yet. The v1 plan depends on evidence and domain-contract changes discovered during Phase 1. From 8a688037cfe1790317153ddd506992416ff9e6c6 Mon Sep 17 00:00:00 2001 From: tim8es <108188608+tim8es@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:59:06 +0500 Subject: [PATCH 12/12] docs: mark current app as reference prototype --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index 9d80d9f..c1ee772 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Практическая программа по Project Management уровня senior+. +> **Статус:** текущая реализация — reference prototype для проверки продукта и модели обучения. Она не считается целевой архитектурой масштабируемой платформы. Актуальная стратегия и источники истины находятся в [`docs/`](docs/README.md). + Это не курс по Scrum, Jira или PMBOK. Программа учит рассматривать проект как систему преобразования неопределенности в ценный результат и управлять семью потоками: 1. ценность; @@ -21,6 +23,31 @@ - сохранение прогресса и заметок в браузере; - итоговый capstone длительностью 2–4 недели. +## Стратегия развития + +Проект развивается по схеме **A → C**: + +1. текущий сайт сохраняется как reference prototype; +2. на нем проверяются учебные механики и curriculum; +3. подтвержденные требования фиксируются как продуктовые и доменные контракты; +4. после validation gate строится отдельная масштабируемая v1; +5. контент и механики мигрируют в v1 вертикально, только после проверки. + +Не следует расширять текущие `app.js` и `course-data.js` как постоянную платформенную архитектуру. + +## Документация + +Начать с [`docs/README.md`](docs/README.md). + +Ключевые документы: + +- [`docs/product/PRODUCT.md`](docs/product/PRODUCT.md) — продуктовый контракт; +- [`docs/product/LEARNING_MODEL.md`](docs/product/LEARNING_MODEL.md) — модель обучения; +- [`docs/product/CURRICULUM.md`](docs/product/CURRICULUM.md) — competency/curriculum contract; +- [`docs/content/CONTENT_MODEL.md`](docs/content/CONTENT_MODEL.md) — модель контента; +- [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) — текущая и целевая архитектура; +- [`docs/ROADMAP.md`](docs/ROADMAP.md) — этапы и validation gates. + ## Запуск локально Сайт не требует сборки. Откройте `index.html` или запустите любой статический HTTP-сервер из корня репозитория.