feat: examples + output_shape on Lesson schema (#129)

[Gradata]

Closes #129.

Changes

• New Example dataclass with good/bad fields
• New optional fields on Lesson: examples: list[Example], output_shape: str | None
• Markdown round-trip preserved (parse_lessons + format_lessons)
• Rule injection emits structured <rule><goal/><shape/><good/><bad/></rule> XML when populated
• capture_example_from_correction populates examples on graduation (de-duped, cap=3)
• 4 new tests cover round-trip + back-compat + rendering + capture

Test plan

• pytest tests/test_lesson_examples.py -xvs — 4/4 pass
• Full suite (excluding integration): 4115 pass, 1 pre-existing flake (test_doctor_runs_on_brain, fixed in fix(test): de-flake test_doctor_runs_on_brain #157)

Layering check

No Layer 0 -> 2 imports introduced.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

• New dataclass Example: Added with good and bad fields for storing example sentence pairs, with to_dict()/from_dict() serialization methods
• Extended Lesson schema: Added optional examples: list[Example] (default empty) and output_shape: str | None (default None) for backward compatibility
• Structured XML rule injection: Brain rule template now emits <rule><goal/><shape/><good/><bad/></rule> blocks when examples or output_shape are populated; falls back to legacy bullet format when absent
• Markdown round-trip preservation: parse_lessons() and format_lessons() handle new metadata fields (Examples: JSON, Output shape: string) to enable serialization/deserialization
• Example capture on correction: capture_example_from_correction() populates lesson examples from corrections, auto-deduplicates, and caps stored examples to 3 most recent
• Backward compatible: Legacy pre-upgrade lessons parse with examples == [] and output_shape is None
• Test coverage: 4 new tests validating round-trip, back-compat, rendering, and capture behavior (all passing)
• No public API changes: Internal functions only; no breaking changes to exported entities

Walkthrough

This PR implements issue #129 by adding Example dataclass and optional examples/output_shape fields to the Lesson schema. Changes include parsing/formatting these fields in markdown round-trip serialization, rendering rich XML structures in prompt injection with examples and output shape constraints, and capturing correction pairs as examples with deduplication and capping logic.

Changes

Cohort / File(s)	Summary
Type Definitions Gradata/src/gradata/_types.py	Added Example dataclass with good/bad fields and to_dict()/from_dict() methods; extended Lesson with optional examples: list[Example] (default empty) and output_shape: str | None (default None) for backward compatibility.
Serialization/Deserialization Gradata/src/gradata/enhancements/self_improvement/_confidence.py	Updated parse_lessons() to recognize Examples: JSON payload and Output shape: metadata lines; updated format_lessons() to serialize these fields back to markdown, enabling round-trip persistence.
Prompt Rendering Gradata/src/gradata/rules/rule_engine/_formatting.py	Modified format_rules_for_prompt() to emit structured <rule> XML blocks with <goal>, optional <shape>, and <good>/<bad> elements when examples/output_shape exist; updated capture_example_from_correction() to append Example pairs with deduplication and 3-item limit.
Configuration Gradata/.gitignore	Added MagicMock/ directory to ignored paths.
Tests Gradata/tests/test_lesson_examples.py	Added comprehensive test suite validating serialization round-trip, backward-compat loading of legacy lessons, XML rendering with/without optional fields, and example capture with deduplication/capping.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(rules): slot-grouped brain injection + graduation-time classifier #138: Also modifies Lesson datamodel and lesson markdown round-trip serialization to add new metadata fields.
• fix(sdk): resolve 10 pyright type errors blocking CI #29: Also extends the Lesson dataclass in src/gradata/_types.py with new optional fields.

Suggested labels

feature

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 61.54% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: examples + output_shape on Lesson schema (#129)' clearly and specifically describes the main feature addition: new examples and output_shape fields on the Lesson dataclass.
Description check	✅ Passed	The description is well-organized and directly related to the changeset, covering new dataclasses, optional fields, markdown round-trip preservation, XML rendering, example capture logic, and test coverage.
Linked Issues check	✅ Passed	The code changes fully satisfy the linked issue requirements: Example dataclass added [#129], Lesson.examples and Lesson.output_shape fields added [#129], markdown round-trip preserved [#129], XML rendering implemented with fallback [#129], capture with dedup and cap=3 [#129], and unit tests covering all acceptance criteria [#129].
Out of Scope Changes check	✅ Passed	All changes are directly in-scope: .gitignore excludes MagicMock directory (supporting test infrastructure), _types.py adds required dataclasses, _confidence.py implements round-trip serialization, _formatting.py implements XML rendering, and tests validate the implementation. No unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/lesson-examples-output-shape

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/lesson-examples-output-shape

---

_{Review rate limit: 2/5 reviews remaining, refill in 24 minutes and 16 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}