Merge pull request #1 from lucasbellesi/codex/educational-improvement-plan

Improve educational quality gates and exercise contracts

Author: lucasbellesi

CONTRIBUTING.md

@@ -40,6 +40,7 @@ For a faster loop while you are iterating, use a narrower command on the area yo
 - Lint: `./scripts/lint.ps1` or `bash ./scripts/lint.sh`
 - Smoke checks: `./scripts/smoke-languages.ps1` or `bash ./scripts/smoke-languages.sh`
 - Compiled-language builds: `./scripts/build-all.ps1` or `bash ./scripts/build-all.sh`
+- Generated artifact cleanup: `./scripts/clean-artifacts.ps1` or `bash ./scripts/clean-artifacts.sh`
 
 If you are changing one C++ file and want a local spot check before the full pass, you can still compile it directly with:
 
@@ -59,9 +60,10 @@ These smoke checks also compile standalone C# exercises by generating temporary
 TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`.
 
 The public PowerShell and Bash scripts are thin wrappers over the shared Python automation core in `scripts/automation.py`. Curriculum validation and smoke target metadata live in `scripts/automation_manifest.json`.
+The artifact cleanup command removes generated build outputs, reports, temporary binaries, and exercise report files while keeping restored dependencies such as `node_modules`.
 
 Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) when reviewing `example/main.*` files for teaching clarity and parity.
-During focused cleanup work, run `python scripts/automation.py audit-education-quality --fail-on-findings` to make learner-quality findings fail locally instead of only writing the advisory report.
+`verify-repo` fails on blocking education-quality findings: low example-comment ratio, missing output explanation markers, or boilerplate comments. Oversized example findings remain advisory. During focused cleanup work, run `python scripts/automation.py audit-education-quality --fail-on-findings` to make every learner-quality finding fail locally.
 
 4. Update related README files when behavior or structure changes.
 5. Open a pull request with a clear description of what changed and why.

README.md

@@ -160,7 +160,7 @@ bash ./scripts/verify-repo.sh
 bash ./scripts/lint.sh
 ~~~
 
-`verify-repo` validates curriculum structure, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, and TypeScript.
+`verify-repo` validates curriculum structure, the blocking education-quality gate, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, and TypeScript.
 
 Use narrower commands only when you want a faster loop on one area:
 
@@ -177,6 +177,7 @@ Use narrower commands only when you want a faster loop on one area:
 ./scripts/lint.ps1
 ./scripts/smoke-languages.ps1
 ./scripts/build-all.ps1
+./scripts/clean-artifacts.ps1
 ./scripts/verify-repo.ps1
 ~~~
 
@@ -193,19 +194,22 @@ bash ./scripts/audit-education-quality.sh
 bash ./scripts/lint.sh
 bash ./scripts/smoke-languages.sh
 bash ./scripts/build-all.sh
+bash ./scripts/clean-artifacts.sh
 bash ./scripts/verify-repo.sh
 ~~~
 
 GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, and TypeScript.
 
 The public PowerShell and Bash scripts remain the supported entrypoints, but they now delegate to a shared Python automation core under `scripts/automation.py` backed by `scripts/automation_manifest.json`.
 
+Use `clean-artifacts` when you want to remove generated build outputs, reports, temporary binaries, and exercise report files without removing dependencies such as `node_modules`.
+
 The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
 
 Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) to keep entry examples pedagogically consistent during reviews. The education audit command is advisory and writes markdown/json findings without failing CI.
 Use [EDUCATIONAL_ANTI_PATTERN_BACKLOG.md](EDUCATIONAL_ANTI_PATTERN_BACKLOG.md) for the prioritized anti-pattern vs corrected-example expansion plan.
 
-When you want to enforce the education audit during focused cleanup work, run:
+`verify-repo` now fails on blocking education-quality findings: low example-comment ratio, missing output explanation markers, or boilerplate comments. Oversized example findings remain advisory. When you want the stricter local cleanup mode that also fails on oversized examples, run:
 
 ~~~bash
 python scripts/automation.py audit-education-quality --fail-on-findings

languages/cpp/03-advanced/structs-and-classes/example/main.cpp

@@ -4,47 +4,29 @@
 
 #include <iostream>
 #include <string>
-#include <vector>
 using namespace std;
 
 struct Student {
+    // A struct is a good fit for simple public data.
     string name;
-    int age;
     double grade;
-
-    void print() const {
-        cout << "Student{name=\"" << name << "\", age=" << age << ", grade=" << grade << "}\n";
-    }
 };
 
 class BankAccount {
   public:
     BankAccount(const string& ownerName, double initialBalance)
-        : owner(ownerName), balance(initialBalance) {
-        if (balance < 0.0) {
-            balance = 0.0;
-        }
-    }
+        : owner(ownerName), balance(initialBalance < 0.0 ? 0.0 : initialBalance) {}
 
-    bool deposit(double amount) {
-        if (amount <= 0.0) {
+    bool applyTransaction(double amount) {
+        // A class can guard updates before private state changes.
+        if (balance + amount < 0.0) {
             return false;
         }
         balance += amount;
         return true;
     }
 
-    bool withdraw(double amount) {
-        if (amount <= 0.0 || amount > balance) {
-            return false;
-        }
-        balance -= amount;
-        return true;
-    }
-
-    const string& getOwner() const { return owner; }
-
-    double getBalance() const { return balance; }
+    void print() const { cout << "Owner: " << owner << "\nBalance: " << balance << '\n'; }
 
   private:
     string owner;
@@ -54,21 +36,20 @@ class BankAccount {
 // Walk through one fixed scenario so structs and classes behavior stays repeatable.
 int main() {
     // Prepare sample inputs that exercise the key structs and classes path.
-    vector<Student> students{{"Alex Johnson", 19, 8.7}, {"Maya Patel", 20, 9.1}};
+    Student first{"Alex Johnson", 8.7};
+    Student second{"Maya Patel", 9.1};
 
     // Report values so learners can verify the structs and classes outcome.
     cout << "Students (struct example):\n";
-    for (const Student& student : students) {
-        student.print();
-    }
+    cout << "Student{name=\"" << first.name << "\", grade=" << first.grade << "}\n";
+    cout << "Student{name=\"" << second.name << "\", grade=" << second.grade << "}\n";
 
     BankAccount account("Alex Johnson", 100.0);
-    account.deposit(40.0);
-    account.withdraw(25.0);
+    account.applyTransaction(40.0);
+    account.applyTransaction(-25.0);
 
     cout << "\nBank account (class example):\n";
-    cout << "Owner: " << account.getOwner() << '\n';
-    cout << "Balance: " << account.getBalance() << '\n';
+    account.print();
 
     return 0;
 }

languages/csharp/02-core/file-io-basics/example/main.cs

@@ -12,6 +12,7 @@ static bool TryParseScoreRow(string line, out string name, out int score)
         name = string.Empty;
         score = 0;
 
+        // Each valid row has one name token followed by one integer score.
         string[] parts = line.Split(' ', StringSplitOptions.RemoveEmptyEntries);
         if (parts.Length != 2 || !int.TryParse(parts[1], out score))
         {
@@ -26,50 +27,34 @@ static bool TryParseScoreRow(string line, out string name, out int score)
     static void Main()
     {
         // Prepare sample inputs that exercise the key file io basics path.
-        string runDirectory = Path.Combine(Path.GetTempPath(), "learn-lang-file-io-csharp");
-        Directory.CreateDirectory(runDirectory);
-        string inputPath = Path.Combine(runDirectory, "scores.txt");
-        string outputPath = Path.Combine(runDirectory, "summary.txt");
-
-        if (!File.Exists(inputPath))
-        {
-            File.WriteAllLines(inputPath, new[] { "ana 90", "bob 82", "invalid row", "carla 95" });
-        }
+        string inputPath = Path.Combine(Path.GetTempPath(), "learn-lang-file-io-csharp-scores.txt");
+        string outputPath = Path.Combine(
+            Path.GetTempPath(),
+            "learn-lang-file-io-csharp-summary.txt"
+        );
+        File.WriteAllLines(inputPath, new[] { "ana 90", "bob 82", "invalid row", "carla 95" });
 
         int validRows = 0;
         int sum = 0;
 
-        using (StreamReader reader = new StreamReader(inputPath))
+        // Read one row at a time so malformed rows can be skipped safely.
+        foreach (string line in File.ReadLines(inputPath))
         {
-            string? line;
-            while ((line = reader.ReadLine()) is not null)
+            if (!TryParseScoreRow(line, out string name, out int score))
             {
-                if (!TryParseScoreRow(line, out string name, out int score))
-                {
-                    continue;
-                }
-
-                validRows++;
-                sum += score;
-                // Report values so learners can verify the file io basics outcome.
-                Console.WriteLine($"{name} -> {score}");
+                continue;
             }
-        }
 
-        if (validRows == 0)
-        {
-            Console.WriteLine("No valid rows found.");
-            return;
+            validRows++;
+            sum += score;
+            // Report values so learners can verify the file io basics outcome.
+            Console.WriteLine($"{name} -> {score}");
         }
 
         double average = (double)sum / validRows;
 
-        using (StreamWriter writer = new StreamWriter(outputPath, false))
-        {
-            writer.WriteLine($"Rows: {validRows}");
-            writer.WriteLine($"Average: {average:F2}");
-        }
-
+        // Persist the summary separately from the console walkthrough.
+        File.WriteAllLines(outputPath, new[] { $"Rows: {validRows}", $"Average: {average:F2}" });
         Console.WriteLine($"Summary written to {outputPath}");
     }
 }

languages/csharp/02-core/input-validation/example/main.cs

@@ -12,6 +12,7 @@ static int ReadIntInRange(string prompt, int minValue, int maxValue)
         {
             Console.Write(prompt);
             string? raw = Console.ReadLine();
+            // Parse first, then validate the numeric range before returning.
             if (!int.TryParse(raw, out int value))
             {
                 Console.WriteLine("Invalid input type. Please enter an integer.");
@@ -34,6 +35,7 @@ static double ReadDoubleInRange(string prompt, double minValue, double maxValue)
         {
             Console.Write(prompt);
             string? raw = Console.ReadLine();
+            // The same validation shape works for decimal input too.
             if (!double.TryParse(raw, out double value))
             {
                 Console.WriteLine("Invalid input type. Please enter a decimal number.");
@@ -54,6 +56,7 @@ static double ReadDoubleInRange(string prompt, double minValue, double maxValue)
     static void Main()
     {
         // Prepare sample inputs that exercise the key input validation path.
+        // Only validated values reach the final summary.
         int age = ReadIntInRange("Enter your age (1-120): ", 1, 120);
         double gpa = ReadDoubleInRange("Enter your GPA (0.0-4.0): ", 0.0, 4.0);
 

languages/csharp/03-advanced/inheritance-and-polymorphism/example/main.cs

@@ -7,6 +7,7 @@
 // Helper setup for inheritance and polymorphism; this keeps the walkthrough readable.
 abstract class Shape
 {
+    // The base type names the behavior that every concrete shape must provide.
     public abstract double Area();
     public abstract string Name { get; }
 }
@@ -16,16 +17,10 @@ class Rectangle : Shape
     private readonly double width;
     private readonly double height;
 
-    public Rectangle(double widthValue, double heightValue)
-    {
-        width = widthValue;
-        height = heightValue;
-    }
+    public Rectangle(double widthValue, double heightValue) =>
+        (width, height) = (widthValue, heightValue);
 
-    public override double Area()
-    {
-        return width * height;
-    }
+    public override double Area() => width * height;
 
     public override string Name => "Rectangle";
 }
@@ -34,15 +29,9 @@ class Circle : Shape
 {
     private readonly double radius;
 
-    public Circle(double radiusValue)
-    {
-        radius = radiusValue;
-    }
+    public Circle(double radiusValue) => radius = radiusValue;
 
-    public override double Area()
-    {
-        return Math.PI * radius * radius;
-    }
+    public override double Area() => Math.PI * radius * radius;
 
     public override string Name => "Circle";
 }
@@ -55,6 +44,7 @@ static void Main()
         // Prepare sample inputs that exercise the key inheritance and polymorphism path.
         List<Shape> shapes = new List<Shape> { new Rectangle(3.0, 4.0), new Circle(2.0) };
 
+        // The loop depends on the Shape contract, not on concrete type checks.
         foreach (Shape shape in shapes)
         {
             // Report values so learners can verify the inheritance and polymorphism outcome.

languages/csharp/04-expert/memory-management-and-raii/example/main.cs

@@ -6,7 +6,7 @@
 // Helper setup for memory management and raii; this keeps the walkthrough readable.
 sealed class BufferLease : IDisposable
 {
-    private int[]? values;
+    private int[] values;
     private readonly string name;
     private bool disposed;
     private static int activeLeases;
@@ -24,34 +24,13 @@ public BufferLease(string name, int length)
 
     public void FillSequence(int start, int step)
     {
-        // Guard every public operation so use-after-dispose fails loudly.
-        EnsureNotDisposed();
-
         for (int i = 0; i < values!.Length; i++)
         {
             values[i] = start + (i * step);
         }
     }
 
-    public int Sum()
-    {
-        // Reading from the buffer is only valid while the lease is active.
-        EnsureNotDisposed();
-
-        int total = 0;
-        foreach (int value in values!)
-        {
-            total += value;
-        }
-
-        return total;
-    }
-
-    public string Describe()
-    {
-        EnsureNotDisposed();
-        return string.Join(" ", values!);
-    }
+    public string Describe() => string.Join(" ", values);
 
     public void Dispose()
     {
@@ -62,29 +41,11 @@ public void Dispose()
         }
 
         disposed = true;
-        values = null;
+        values = Array.Empty<int>();
         activeLeases--;
         Console.WriteLine($"[dispose] {name} active={activeLeases}");
         GC.SuppressFinalize(this);
     }
-
-    ~BufferLease()
-    {
-        // The finalizer is a last-resort safety net, not the normal cleanup path.
-        if (!disposed)
-        {
-            activeLeases--;
-            Console.WriteLine($"[finalizer] {name} active={activeLeases}");
-        }
-    }
-
-    private void EnsureNotDisposed()
-    {
-        if (disposed)
-        {
-            throw new ObjectDisposedException(name);
-        }
-    }
 }
 
 class Program
@@ -98,18 +59,10 @@ static void Main()
         // The using block calls Dispose automatically when the scope exits.
         using (BufferLease scores = new BufferLease("scores", 5))
         {
-            int threshold = 25;
             scores.FillSequence(10, 5);
 
             // Report buffer state while the lease is still valid.
             Console.WriteLine($"Scores: {scores.Describe()}");
-            Console.WriteLine($"Sum: {scores.Sum()}");
-            Console.WriteLine($"Threshold for review: {threshold}");
-
-            // A nested using declaration owns a second resource until the outer scope ends.
-            using BufferLease scratch = new BufferLease("scratch", 3);
-            scratch.FillSequence(1, 1);
-            Console.WriteLine($"Scratch buffer: {scratch.Describe()}");
             Console.WriteLine($"Active leases inside scope: {BufferLease.ActiveLeases}");
         }