Require pedagogical metadata across curriculum

Author: lucasbellesi

CONTRIBUTING.md

@@ -70,7 +70,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
 
 - New concept modules should follow the existing folder layout.
 - Every concept README in implemented levels should include:
-  - recommended `## Learning Metadata` before `## Quick Run` with difficulty, estimated time, prerequisites, and cross-language guidance
+  - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Cross-Language Lens`
   - `## Quick Run`
   - `## Topics Covered`
   - `## Common Pitfalls`
@@ -81,7 +81,8 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
   - `README.md`
   - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, or `main.py`)
   - the same learner goal, input/output shape, and acceptance expectations as the corresponding C++ checkpoint
-  - recommended `## Learning Metadata` with difficulty, estimated time, prerequisites, and checkpoint focus
+  - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Learning Focus`
+- Every implemented level README should include required `## Learning Metadata` before `## Module Order` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Study Strategy`.
 - Checkpoint README structure should mirror the matching C++ checkpoint style, not the module README contract.
 - Every `example/main.*` file should include intent-first comments for:
   - program flow,

README.md

@@ -86,12 +86,11 @@ All concept module README files under `languages/<language>/<level>/<module>/REA
 
 Reference: [Module README Style](languages/cpp/MODULE_README_STYLE.md)
 
-A standardized `## Learning Metadata` block is also recommended before `## Quick Run` for modules and major checkpoints. Use it to record:
+A standardized `## Learning Metadata` block is required before `## Quick Run` for implemented modules and checkpoints. Implemented level READMEs should also include it before `## Module Order`. Use these fields:
 
-- difficulty
-- estimated time
-- prerequisites
-- cross-language comparison guidance
+- modules: difficulty, estimated time, prerequisites, cross-language comparison guidance
+- checkpoints: difficulty, estimated time, prerequisites, learning focus
+- level READMEs: difficulty, estimated time, prerequisites, study strategy
 
 Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<language>/assessments/*` should mirror the corresponding C++ checkpoint style:
 

languages/cpp/01-foundations/README.md

@@ -2,6 +2,13 @@
 
 This level builds the beginner mental model for writing small C++ programs.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 3-5 hours across modules, project, and assessment.
+- Prerequisites: None; this is the entry level for each active track.
+- Study Strategy: Work in module order, run every example, solve both exercises in each module, then finish the matching project and assessment.
+
 ## Module Order
 
 1. [types-and-io](./types-and-io/README.md)

languages/cpp/01-foundations/arrays-and-vectors/README.md

@@ -2,6 +2,13 @@
 
 This module introduces fixed-size and dynamic collections in C++.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/control-flow`, `01-foundations/functions`.
+- Cross-Language Lens: Compare `vector`, `List<T>`, slices, and Python lists as different tradeoffs for dynamic sequence handling.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/control-flow/README.md

@@ -2,6 +2,13 @@
 
 This module teaches branching and repetition in C++ programs.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/types-and-io`, `01-foundations/operators-and-expressions`.
+- Cross-Language Lens: Compare braces-and-loops in C++, C#, and Go with Python indentation while keeping the underlying branching logic identical.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/formatted-output-and-iomanip/README.md

@@ -2,6 +2,13 @@
 
 This module teaches readable numeric and table output formatting.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/types-and-io`, `01-foundations/operators-and-expressions`.
+- Cross-Language Lens: Compare stream manipulators, format strings, `fmt`, and Python formatting for the same reporting task.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/functions/README.md

@@ -2,6 +2,13 @@
 
 This module introduces reusable logic through function design.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/control-flow`, `01-foundations/operators-and-expressions`.
+- Cross-Language Lens: Compare helper-function design, argument passing defaults, and overloading support across the four tracks.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/operators-and-expressions/README.md

@@ -2,6 +2,13 @@
 
 This module covers arithmetic, relational, and logical expressions in C++.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/types-and-io`.
+- Cross-Language Lens: Compare integer division, boolean logic, and truthiness rules before assuming the same expression means the same thing in every language.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/scope-and-lifetime-basics/README.md

@@ -2,6 +2,13 @@
 
 This module explains where variables are visible and how long they live.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/functions`, `01-foundations/control-flow`.
+- Cross-Language Lens: Compare block scope everywhere, then contrast deterministic destruction in C++ with garbage-collected lifetime in the other tracks.
+
 ## Quick Run
 
 ```bash

languages/cpp/01-foundations/strings/README.md

@@ -2,6 +2,13 @@
 
 This module introduces practical text handling with `std::string`.
 
+## Learning Metadata
+
+- Difficulty: Beginner.
+- Estimated Time: 20-35 minutes.
+- Prerequisites: `01-foundations/types-and-io`, `01-foundations/control-flow`.
+- Cross-Language Lens: Compare immutable string handling, indexing rules, and tokenization helpers in each language.
+
 ## Quick Run
 
 ```bash