feat(content): structured content schema models + renderers

tests/unit/foundation/policy/content/test_content_models.py

@@ -0,0 +1,220 @@
+"""Validation tests for the structured content schema models."""
+
+from __future__ import annotations
+
+import pytest
+from roboco.foundation.policy.content import (
+    AuditorNote,
+    ContentValidationError,
+    DeveloperNote,
+    DocNote,
+    PrReviewContent,
+    QaNote,
+    ResumptionNote,
+    TaskDescription,
+    validate_content,
+)
+from roboco.foundation.policy.content.enums import Severity, Verdict
+
+# --------------------------------------------------------------------------- #
+# Valid construction
+# --------------------------------------------------------------------------- #
+
+
+def test_pr_review_valid() -> None:
+    c = PrReviewContent(
+        summary="The change is correct and covered by tests.",
+        findings=[
+            {
+                "file": "roboco/services/git.py",
+                "line": 42,
+                "severity": "major",
+                "expected": "raises on 422",
+                "actual": "swallows the error",
+            }
+        ],
+        verdict="changes_requested",
+    )
+    assert c.findings[0].severity is Severity.MAJOR
+    assert c.verdict is Verdict.CHANGES_REQUESTED
+
+
+def test_qa_valid() -> None:
+    c = QaNote(
+        summary="Reviewed all acceptance criteria against the diff.",
+        ac_verdicts=[
+            {"criterion": "AC1 returns 400", "status": "verified", "how": "test passes"}
+        ],
+        verdict="passed",
+    )
+    assert c.ac_verdicts[0].status == "verified"
+
+
+def test_task_description_valid() -> None:
+    c = TaskDescription(
+        objective="Add a structured PR-review comment format.",
+        what_this_builds=["a reviewer schema"],
+        the_work=[
+            {
+                "team": "backend",
+                "summary": "schema + gateway",
+                "items": ["model", "verb"],
+            }
+        ],
+        acceptance_criteria=["reviewer notes land in their own slot"],
+    )
+    assert c.the_work[0].team.value == "backend"
+
+
+def test_resumption_valid() -> None:
+    c = ResumptionNote(
+        done="schema landed", next="wire the gateway", where_to_look=["models.py"]
+    )
+    assert c.next == "wire the gateway"
+
+
+# --------------------------------------------------------------------------- #
+# Rejection
+# --------------------------------------------------------------------------- #
+
+
+def test_validate_content_unknown_type() -> None:
+    with pytest.raises(ContentValidationError) as exc:
+        validate_content("nonsense", {})
+    assert exc.value.field == "content_type"
+
+
+def test_pr_review_missing_summary_rejected() -> None:
+    with pytest.raises(ContentValidationError) as exc:
+        validate_content("pr_review", {"verdict": "approved"})
+    assert exc.value.field == "summary"
+
+
+def test_pr_review_trivial_summary_rejected() -> None:
+    with pytest.raises(ContentValidationError):
+        validate_content("pr_review", {"summary": "wip", "verdict": "approved"})
+
+
+def test_pr_review_negative_verdict_requires_findings() -> None:
+    with pytest.raises(ContentValidationError):
+        validate_content(
+            "pr_review",
+            {
+                "summary": "Looks broken but no detail given here.",
+                "verdict": "failed",
+                "findings": [],
+            },
+        )
+
+
+def test_pr_review_approved_allows_empty_findings() -> None:
+    c = validate_content(
+        "pr_review",
+        {"summary": "All criteria met, nothing to change.", "verdict": "approved"},
+    )
+    assert isinstance(c, PrReviewContent)
+
+
+def test_qa_verdict_must_be_pass_or_fail() -> None:
+    with pytest.raises(ContentValidationError) as exc:
+        validate_content(
+            "qa",
+            {
+                "summary": "Reviewed the acceptance criteria thoroughly.",
+                "ac_verdicts": [
+                    {"criterion": "c", "status": "verified", "how": "test"}
+                ],
+                "verdict": "approved",
+            },
+        )
+    assert exc.value.field == "verdict"
+
+
+def test_qa_requires_ac_verdicts() -> None:
+    with pytest.raises(ContentValidationError) as exc:
+        validate_content(
+            "qa",
+            {
+                "summary": "Reviewed everything carefully here.",
+                "ac_verdicts": [],
+                "verdict": "passed",
+            },
+        )
+    assert exc.value.field == "ac_verdicts"
+
+
+def test_task_description_requires_work() -> None:
+    with pytest.raises(ContentValidationError) as exc:
+        validate_content(
+            "task_description",
+            {
+                "objective": "Build the thing properly.",
+                "the_work": [],
+                "acceptance_criteria": ["x"],
+            },
+        )
+    assert exc.value.field == "the_work"
+
+
+def test_work_unit_rejects_non_cell_team() -> None:
+    with pytest.raises(ContentValidationError):
+        validate_content(
+            "task_description",
+            {
+                "objective": "Build the thing properly.",
+                "the_work": [{"team": "board", "summary": "do it", "items": ["a"]}],
+                "acceptance_criteria": ["x"],
+            },
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Graceful coercion (lone scalar -> one-element list)
+# --------------------------------------------------------------------------- #
+
+
+def test_findings_single_dict_coerced_to_list() -> None:
+    c = validate_content(
+        "pr_review",
+        {
+            "summary": "One finding passed as a bare dict.",
+            "verdict": "changes_requested",
+            "findings": {
+                "file": "a.py",
+                "severity": "nit",
+                "expected": "trailing newline",
+                "actual": "no newline",
+            },
+        },
+    )
+    assert isinstance(c, PrReviewContent)
+    assert len(c.findings) == 1
+
+
+def test_where_to_look_single_string_coerced() -> None:
+    c = validate_content(
+        "resumption",
+        {
+            "done": "did the thing",
+            "next": "do next thing",
+            "where_to_look": "models.py",
+        },
+    )
+    assert isinstance(c, ResumptionNote)
+    assert c.where_to_look == ["models.py"]
+
+
+def test_developer_and_doc_and_auditor_models() -> None:
+    assert isinstance(
+        validate_content("developer", {"summary": "Implemented the schema layer."}),
+        DeveloperNote,
+    )
+    assert isinstance(
+        validate_content("doc", {"summary": "Documented the new endpoints."}), DocNote
+    )
+    assert isinstance(
+        validate_content(
+            "auditor", {"summary": "No concerns with this change.", "severity": "info"}
+        ),
+        AuditorNote,
+    )

tests/unit/foundation/policy/content/test_content_renderers.py

@@ -0,0 +1,92 @@
+"""Markdown rendering tests for the structured content models.
+
+Assert structure (labeled sections + the content appears) rather than exact
+bytes, so the renderers stay refactorable.
+"""
+
+from __future__ import annotations
+
+from roboco.foundation.policy.content import (
+    PrReviewContent,
+    QaNote,
+    ResumptionNote,
+    TaskDescription,
+)
+
+
+def test_pr_review_renders_sections_and_findings_table() -> None:
+    md = PrReviewContent(
+        summary="The guard is missing on the 422 path.",
+        findings=[
+            {
+                "file": "roboco/services/git.py",
+                "line": 42,
+                "severity": "blocker",
+                "expected": "retry as COMMENT",
+                "actual": "raises",
+            }
+        ],
+        verdict="changes_requested",
+    ).render_markdown()
+    assert "## Summary" in md
+    assert "## Findings" in md
+    assert "| File | Line | Severity | Expected → Actual |" in md
+    assert "`roboco/services/git.py`" in md
+    assert "blocker" in md
+    assert "## Verdict" in md
+    assert "changes requested" in md
+
+
+def test_qa_renders_checklist() -> None:
+    md = QaNote(
+        summary="Verified every acceptance criterion against the diff.",
+        ac_verdicts=[
+            {
+                "criterion": "AC1 returns 400",
+                "status": "verified",
+                "how": "test passes",
+            },
+            {"criterion": "AC2 logs", "status": "failed", "how": "no log emitted"},
+        ],
+        verdict="failed",
+    ).render_markdown()
+    assert "## Acceptance Criteria" in md
+    assert "✅" in md and "❌" in md
+    assert "AC1 returns 400" in md
+    assert "## Verdict" in md
+
+
+def test_resumption_renders_done_next_where() -> None:
+    md = ResumptionNote(
+        done="schema module landed",
+        next="wire the gateway chokepoint",
+        where_to_look=[
+            "foundation/policy/content/models.py",
+            "services/content_notes.py",
+        ],
+    ).render_markdown()
+    assert "## Done" in md
+    assert "## Next" in md
+    assert "## Where to look" in md
+    assert "content_notes.py" in md
+    # No machine markers ever leak into the human resumption note.
+    assert "original_developer" not in md
+    assert "documenter:" not in md
+
+
+def test_task_description_renders_all_sections() -> None:
+    md = TaskDescription(
+        objective="Add the structured content standard.",
+        what_this_builds=["a schema layer", "a gateway gate"],
+        the_work=[
+            {"team": "backend", "summary": "models + verbs", "items": ["model", "verb"]}
+        ],
+        notes=["reuse the Team enum"],
+        acceptance_criteria=["reviewer notes are isolated"],
+    ).render_markdown()
+    assert "## Objective" in md
+    assert "## What This Builds" in md
+    assert "## The Work" in md
+    assert "**Backend**" in md
+    assert "## Notes" in md
+    assert "## Acceptance Criteria" in md