roboco/tests/unit/gateway/test_note_handoff.py

"""Tests for note(scope='handoff') — the role note-section write-path.

``note()`` only ever wrote the JOURNAL; ``scope='handoff'`` is how an agent
authors its dedicated SECTION (dev_notes / quick_context / auditor_notes …)
through the ``apply_structured_note`` chokepoint. These cover the routing,
ownership, validation→remediation, and journal-trail behaviours.
"""

from __future__ import annotations

from unittest.mock import AsyncMock, MagicMock
from uuid import uuid4

import pytest
from roboco.foundation.policy.content import ContentValidationError
from roboco.services.gateway.content_actions import ContentActions, ContentActionsDeps


def _make_deps(**overrides: object) -> ContentActionsDeps:
    task = overrides.get("task") or AsyncMock()
    return ContentActionsDeps(
        task=task,
        git=overrides.get("git") or AsyncMock(),
        a2a=overrides.get("a2a") or AsyncMock(),
        journal=overrides.get("journal") or AsyncMock(),
        workspace=overrides.get("workspace") or AsyncMock(),
        notifications=overrides.get("notifications") or AsyncMock(),
        notification_delivery=overrides.get("notification_delivery") or AsyncMock(),
        evidence_repo=overrides.get("evidence_repo") or AsyncMock(),
    )


def _dev_task_svc(task_id: object, role: str = "developer") -> AsyncMock:
    """A task service whose active/context task is owned by the caller."""
    svc = AsyncMock()
    svc.agent_for.return_value = MagicMock(role=role)
    svc.get_journal_context_task_for_agent.return_value = MagicMock(id=task_id)
    svc.record_section_note.return_value = None
    return svc


@pytest.mark.asyncio
async def test_handoff_developer_writes_dev_notes_from_text() -> None:
    """A developer handoff routes to the 'developer' content type, defaulting
    the payload to {'summary': text} when no explicit section is given."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id)
    ca = ContentActions(_make_deps(task=svc))

    summary = "Implemented the endpoint and added happy-path tests."
    env = await ca.note(agent_id=agent_id, text=summary, scope="handoff")

    assert env.as_dict()["error"] is None
    svc.record_section_note.assert_awaited_once()
    called_task_id, content_type, payload = svc.record_section_note.call_args.args
    assert called_task_id == task_id
    assert content_type == "developer"
    assert payload == {"summary": summary}


@pytest.mark.asyncio
async def test_handoff_passes_explicit_section_through() -> None:
    """An explicit ``section`` dict is the payload (e.g. PM resumption)."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id, role="cell_pm")
    ca = ContentActions(_make_deps(task=svc))

    section = {"done": "Planned the decomposition.", "next": "Cells implement."}
    env = await ca.note(
        agent_id=agent_id, text="handoff", scope="handoff", section=section
    )

    assert env.as_dict()["error"] is None
    _tid, content_type, payload = svc.record_section_note.call_args.args
    assert content_type == "resumption"
    assert payload == section


@pytest.mark.asyncio
async def test_handoff_also_writes_journal_trail_entry() -> None:
    """The section write drops a journal trail entry so it shows in the log."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id)
    journal = AsyncMock()
    ca = ContentActions(_make_deps(task=svc, journal=journal))

    await ca.note(agent_id=agent_id, text="Did the thing thoroughly.", scope="handoff")

    journal.write_entry.assert_awaited_once()


@pytest.mark.asyncio
async def test_handoff_role_without_section_is_rejected() -> None:
    """A role with no dedicated section (board/advisory) cannot handoff."""
    agent_id = uuid4()
    svc = AsyncMock()
    svc.agent_for.return_value = MagicMock(role="product_owner")
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(agent_id=agent_id, text="observation", scope="handoff")
    body = env.as_dict()

    assert body["error"] == "invalid_state"
    assert "no dedicated note section" in body["message"]
    svc.record_section_note.assert_not_awaited()


@pytest.mark.asyncio
async def test_handoff_validation_error_returns_remediation_not_422() -> None:
    """A malformed section payload becomes a remediation Envelope, never a 422
    (a raw 422 would trip the do-server circuit breaker)."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id, role="auditor")
    svc.record_section_note.side_effect = ContentValidationError(
        "severity", "field required"
    )
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(
        agent_id=agent_id,
        text="risk spotted",
        scope="handoff",
        section={"summary": "x"},
    )
    body = env.as_dict()

    assert body["error"] == "invalid_state"
    assert "severity" in body["message"]
    assert "auditor" in body["remediate"]


@pytest.mark.asyncio
async def test_handoff_pm_resumption_from_top_level_done_next() -> None:
    """A PM authors the resumption section from TOP-LEVEL ``done``/``next``
    fields, not the nested ``section`` dict.

    Background (2026-06-27 live meltdown): minimax-m3:cloud running the PM
    roles emitted ``section={}`` (an empty object) for the handoff note 3
    times identically, ignoring the prose remediate. ``ResumptionNote`` requires
    ``done``+``next`` so the gate rejected ``done — Field required``, the
    do-server circuit breaker tripped after 3-4 rejections, and the tracing
    gate (which obligates a handoff note before ``delegate``) deadlocked the
    PM into a respawn loop. Root cause was structural: ``section: dict[str,
    Any]`` renders a tool schema with NO visible sub-fields, so a weak model
    emits ``{}`` while the SAME model fills the top-level ``string`` decision
    fields fine (proven live — those succeeded). The fix follows the
    precedent already in ``NoteRequest`` (the decision fields typed ``str =
    ""`` so the schema declares ``string``): promote ``done``/``next`` to
    top-level typed string params so the tool schema shows them
    machine-visible. Passing ``done``+``next`` with no ``section`` must write
    the resumption section successfully.
    """
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id, role="cell_pm")
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(
        agent_id=agent_id,
        text="handoff",
        scope="handoff",
        done="Planned the decomposition into 3 cell tasks.",
        next="Cells implement their slices in wave order.",
        where_to_look=["panel/tasks — wave column", "the decomposition note"],
    )

    body = env.as_dict()
    assert body["error"] is None
    _tid, content_type, payload = svc.record_section_note.call_args.args
    assert content_type == "resumption"
    assert payload["done"] == "Planned the decomposition into 3 cell tasks."
    assert payload["next"] == "Cells implement their slices in wave order."
    assert payload["where_to_look"] == [
        "panel/tasks — wave column",
        "the decomposition note",
    ]


@pytest.mark.asyncio
async def test_handoff_top_level_done_next_merge_into_explicit_section() -> None:
    """Top-level ``done``/``next`` fill any keys the explicit ``section`` omits
    without overwriting keys the agent already supplied — backward compatible
    with a capable model that passes ``section`` directly."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id, role="cell_pm")
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(
        agent_id=agent_id,
        text="handoff",
        scope="handoff",
        section={"done": "Already-specified done."},
        next="Top-level next fills the omitted next.",
    )

    assert env.as_dict()["error"] is None
    _tid, _ctype, payload = svc.record_section_note.call_args.args
    assert payload["done"] == "Already-specified done."
    assert payload["next"] == "Top-level next fills the omitted next."


@pytest.mark.asyncio
async def test_handoff_empty_done_next_empty_section_still_remediates() -> None:
    """The backstop holds: with no top-level ``done``/``next`` AND an empty
    ``section``, the resumption gate still rejects with the remediation
    envelope (never a raw 422) — so a model that ignores both paths still
    gets the actionable message rather than tripping a silent crash."""
    agent_id, task_id = uuid4(), uuid4()
    svc = _dev_task_svc(task_id, role="cell_pm")
    svc.record_section_note.side_effect = ContentValidationError(
        "done", "field required"
    )
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(agent_id=agent_id, text="handoff", scope="handoff", section={})
    body = env.as_dict()

    assert body["error"] == "invalid_state"
    assert "done" in body["message"]
    assert "resumption" in body["remediate"]


@pytest.mark.asyncio
async def test_handoff_no_task_to_attach_is_rejected() -> None:
    """With no active/context task and no explicit task_id, handoff refuses."""
    agent_id = uuid4()
    svc = AsyncMock()
    svc.agent_for.return_value = MagicMock(role="developer")
    svc.get_journal_context_task_for_agent.return_value = None
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(agent_id=agent_id, text="orphan note", scope="handoff")
    body = env.as_dict()

    assert body["error"] == "invalid_state"
    assert "task_id" in body["remediate"]
    svc.record_section_note.assert_not_awaited()


@pytest.mark.asyncio
async def test_handoff_explicit_task_not_owned_is_rejected() -> None:
    """An explicit task_id the caller does not own is an ownership violation."""
    agent_id, task_id = uuid4(), uuid4()
    svc = AsyncMock()
    svc.agent_for.return_value = MagicMock(role="developer")
    svc.get.return_value = MagicMock(
        id=task_id, assigned_to=uuid4(), project_id=uuid4(), product_id=None
    )
    ca = ContentActions(_make_deps(task=svc))

    env = await ca.note(
        agent_id=agent_id, text="poking another task", scope="handoff", task_id=task_id
    )
    body = env.as_dict()

    assert body["error"] == "not_authorized"
    svc.record_section_note.assert_not_awaited()