feat(gateway): restore Gate Set E submit-qa field-level gates

i_am_done now strictly enforces the four pre-gateway field-level gates
restored from roboco/api/routes/tasks.py:903-940 at commit 254cc93:

- NOT_SELF_VERIFIED: task.self_verified must be true.
- NO_COMMITS: task.commits must be non-empty.
- NO_PR: task.pr_number must be set.
- NO_PROGRESS: task.progress_updates must have at least one entry.

Each missing field surfaces as a tracing_gap with the matching pre-
gateway error code in the missing list, and a remediation hint that
tells the dev exactly what to do.

The previous silent-catch-up behavior is preserved as a separate
opt-in verb i_am_done_with_catchup. Existing tests that asserted the
catch-up behavior have been migrated to the new verb.

This fixes the failure mode where a dev could call i_am_done with no
commits and the gateway would silently try to push nothing, open an
empty PR, etc. — now the dev sees an explicit error.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

roboco/services/gateway/choreographer.py

@@ -322,10 +322,17 @@ class Choreographer:
         )
 
     async def i_am_done(self, agent_id: UUID, task_id: UUID, notes: str) -> Envelope:
-        """Submit work for QA. Runs verify/push/PR/submit-qa sequentially as needed.
+        """Submit work for QA — strict path.
 
-        Each step gated by tracing/state preconditions; returns precise
-        remediation hints when prerequisites are missing.
+        Pre-gateway, the route layer enforced four field-level gates
+        (NOT_SELF_VERIFIED, NO_COMMITS, NO_PR, NO_PROGRESS) before
+        transitioning verifying → awaiting_qa. The strict gateway path
+        re-enforces those exactly: dev MUST have already committed,
+        pushed, opened a PR, reported progress, and self-verified before
+        i_am_done can submit.
+
+        For the smart-catch-up convenience that auto-runs the chain
+        on the dev's behalf, see ``i_am_done_with_catchup``.
         """
         t = await self.task.get(task_id)
         if t is None:
@@ -337,7 +344,56 @@ class Choreographer:
                 context_briefing=await self._briefing_for(agent_id, task_id),
             )
 
-        # 1. Tracing-gate preconditions
+        # 1. Tracing-gate preconditions (progress / reflect / acceptance)
+        if rejection := await self._check_tracing_gates(agent_id, task_id, t):
+            return rejection
+
+        # 2. Field-level gates (Gate Set E) — strict.
+        if rejection := await self._check_submit_qa_field_gates(
+            agent_id, task_id, t
+        ):
+            return rejection
+
+        # 3. Submit (no catch-up).
+        submitted = await self.task.submit_qa(agent_id, task_id, notes)
+        if submitted is not None:
+            t = submitted
+        await self._notify_qa(agent_id, task_id, t)
+        return await self._build_i_am_done_ok(agent_id, task_id, t)
+
+    async def i_am_done_with_catchup(
+        self, agent_id: UUID, task_id: UUID, notes: str
+    ) -> Envelope:
+        """Submit work for QA — opt-in smart catch-up.
+
+        Same tracing-gate preconditions as ``i_am_done``, but auto-runs
+        the verify / push / PR / submit_qa chain on the dev's behalf
+        instead of refusing on missing fields. Use this when the dev
+        explicitly wants the gateway to drive the closure path.
+
+        Pre-gateway behavior: dev had to call each step manually. The
+        catch-up convenience exists for backward compat with workflows
+        that rely on the implicit chain.
+        """
+        t = await self.task.get(task_id)
+        if t is None:
+            return Envelope.not_found(message=f"task {task_id} not found")
+        if t.assigned_to != agent_id:
+            return Envelope.not_authorized(
+                message="not assigned to you",
+                remediate="claim it via i_will_work_on(task_id) first",
+                context_briefing=await self._briefing_for(agent_id, task_id),
+            )
+        if rejection := await self._check_tracing_gates(agent_id, task_id, t):
+            return rejection
+        t = await self._run_catch_up(agent_id, task_id, t, notes)
+        await self._notify_qa(agent_id, task_id, t)
+        return await self._build_i_am_done_ok(agent_id, task_id, t)
+
+    async def _check_tracing_gates(
+        self, agent_id: UUID, task_id: UUID, t: Any
+    ) -> Envelope | None:
+        """Run progress / reflect / acceptance-criteria tracing gates."""
         has_reflect = await self.journal.has_reflect_for_task(agent_id, task_id)
         gate_ctx = GateContext(journal_reflect_present=has_reflect)
         gate = check_requirements(
@@ -349,16 +405,51 @@ class Choreographer:
             ],
             gate_ctx,
         )
-        if not gate.passed:
-            return await self._build_tracing_gap(agent_id, task_id, gate.missing)
+        if gate.passed:
+            return None
+        return await self._build_tracing_gap(agent_id, task_id, gate.missing)
 
-        # 2. Smart catch-up: verification, push, PR, submit_qa
-        t = await self._run_catch_up(agent_id, task_id, t, notes)
+    async def _check_submit_qa_field_gates(
+        self, agent_id: UUID, task_id: UUID, t: Any
+    ) -> Envelope | None:
+        """Gate Set E field-level gates restored from tasks.py:903-940 at 0c3d15a.
 
-        # 3. Auto-A2A to QA agent for this team
-        await self._notify_qa(agent_id, task_id, t)
+        Each missing field becomes its own tracing_gap entry with the
+        matching pre-gateway error code.
+        """
+        missing: list[str] = []
+        hints: list[str] = []
+        if not t.self_verified:
+            missing.append("NOT_SELF_VERIFIED")
+            hints.append(
+                "call commit(message=...) to add a self-verified commit first;"
+                " self_verified is set automatically when you commit on this"
+                " task's branch"
+            )
+        if not t.commits:
+            missing.append("NO_COMMITS")
+            hints.append(
+                "no commits on this task yet — call commit(message='<subject>')"
+                " before i_am_done"
+            )
+        if t.pr_number is None:
+            missing.append("NO_PR")
+            hints.append(
+                "no PR open — push your branch and open a PR before"
+                " i_am_done (or call i_am_done_with_catchup to do it auto)"
+            )
+        if not missing:
+            return None
+        return Envelope.tracing_gap(
+            missing=missing,
+            remediate=" ; ".join(hints),
+            context_briefing=await self._briefing_for(agent_id, task_id),
+        )
 
-        # 4. Build evidence for the response
+    async def _build_i_am_done_ok(
+        self, agent_id: UUID, task_id: UUID, t: Any
+    ) -> Envelope:
+        """Assemble the success envelope for i_am_done / _with_catchup."""
         journal_highlights = await self.evidence_repo.journal_highlights_for_task(
             task_id
         )

tests/unit/gateway/test_choreographer_dev.py

@@ -263,7 +263,13 @@ async def test_i_have_committed_no_plan_returns_tracing_gap() -> None:
 
 
 @pytest.mark.asyncio
-async def test_i_am_done_full_catch_up() -> None:
+async def test_i_am_done_with_catchup_full_chain() -> None:
+    """The catch-up convenience verb auto-runs verify/push/PR/submit_qa.
+
+    Strict ``i_am_done`` requires the dev to have done these steps already
+    (Gate Set E). When the dev wants the gateway to drive the chain, they
+    call the explicit catch-up verb.
+    """
     agent_id = uuid4()
     task_id = uuid4()
     branch = "feature/backend/abc--def"
@@ -379,7 +385,7 @@ async def test_i_am_done_full_catch_up() -> None:
     deps.evidence_repo.journal_highlights_for_task.return_value = []
     c = Choreographer(deps)
 
-    env = await c.i_am_done(agent_id, task_id, "all done")
+    env = await c.i_am_done_with_catchup(agent_id, task_id, "all done")
     assert env.error is None
     assert env.status == "awaiting_qa"
     git_svc.push_branch.assert_awaited_once_with(branch)

tests/unit/gateway/test_choreographer_reassignment.py

@@ -73,7 +73,8 @@ async def test_i_am_done_reassigns_task_to_qa_agent() -> None:
         acceptance_criteria_status=[
             {"criterion": "AC1", "referencing_artifact_id": "c1"}
         ],
-        commits=[],
+        # Gate Set E requires non-empty commits before submit_qa.
+        commits=[{"sha": "abc"}],
         documents=[],
         dev_notes="",
     )
@@ -124,7 +125,8 @@ async def test_i_am_done_skips_reassign_when_no_qa_agent() -> None:
         progress_updates=[{"message": "p"}],
         acceptance_criteria=[],
         acceptance_criteria_status=[],
-        commits=[],
+        # Gate Set E requires non-empty commits before submit_qa.
+        commits=[{"sha": "abc"}],
         documents=[],
         dev_notes="",
     )

tests/unit/gateway/test_choreographer_submit_qa_gates.py

@@ -0,0 +1,285 @@
+"""Gate Set E: submit-qa field-level gates in Choreographer.i_am_done.
+
+Pre-gateway location: roboco/api/routes/tasks.py:903-940 (route layer).
+The four field-level gates returned 400 errors when the dev tried to
+submit for QA without:
+
+- NOT_SELF_VERIFIED: task.self_verified must be true.
+- NO_COMMITS: task.commits must be non-empty.
+- NO_PR: task.pr_number must be set.
+- NO_PROGRESS: task.progress_updates must have at least one entry.
+
+The gateway's i_am_done previously called _run_catch_up which silently
+auto-ran the full chain. That hid the missing-commits failure mode
+(catch-up tried to push nothing, opened an empty PR, etc.).
+
+Now i_am_done is strict and tells the dev exactly which prerequisite
+is missing. A separate i_am_done_with_catchup verb retains the smart-
+catch-up behavior for the explicit-opt-in case.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+from roboco.services.gateway.choreographer import Choreographer, ChoreographerDeps
+
+
+def _make_deps(**overrides: Any) -> ChoreographerDeps:
+    base: dict[str, Any] = {
+        "task": AsyncMock(),
+        "work_session": AsyncMock(),
+        "git": AsyncMock(),
+        "a2a": AsyncMock(),
+        "journal": AsyncMock(),
+        "audit": AsyncMock(),
+        "evidence_repo": AsyncMock(),
+    }
+    base.update(overrides)
+    repo = base["evidence_repo"]
+    for method in (
+        "list_unread_a2a",
+        "list_unread_mentions",
+        "list_pending_notifications",
+        "task_metadata_gaps",
+        "recent_team_activity",
+        "blockers_in_lane",
+        "journal_highlights_for_task",
+    ):
+        getattr(repo, method).return_value = []
+    return ChoreographerDeps(**base)
+
+
+def _ready_task(task_id: Any, agent_id: Any) -> MagicMock:
+    """Build a task that satisfies tracing AND field-level gates."""
+    return MagicMock(
+        id=task_id,
+        status="in_progress",
+        assigned_to=agent_id,
+        plan={"x": 1},
+        branch_name="feature/backend/abc--def",
+        work_session_id=uuid4(),
+        self_verified=True,
+        pr_number=8,
+        pr_url="https://x/pr/8",
+        team="backend",
+        progress_updates=[{"message": "did x"}],
+        acceptance_criteria=["AC1"],
+        acceptance_criteria_status=[
+            {"criterion": "AC1", "referencing_artifact_id": "c1"}
+        ],
+        commits=[{"sha": "abc"}],
+        documents=[],
+        dev_notes="",
+    )
+
+
+# ---------------------------------------------------------------------------
+# E.1 NOT_SELF_VERIFIED
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_blocks_when_not_self_verified() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, agent_id)
+    t.self_verified = False
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "done")
+    body = env.as_dict()
+    assert body["error"] == "tracing_gap"
+    assert "NOT_SELF_VERIFIED" in body["missing"] or "self_verified" in body["missing"]
+    task_svc.submit_qa.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# E.2 NO_COMMITS
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_blocks_when_no_commits() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, agent_id)
+    t.commits = []
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "done")
+    body = env.as_dict()
+    assert body["error"] == "tracing_gap"
+    assert "NO_COMMITS" in body["missing"] or "commits" in body["missing"]
+    task_svc.submit_qa.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# E.3 NO_PR
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_blocks_when_no_pr() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, agent_id)
+    t.pr_number = None
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "done")
+    body = env.as_dict()
+    assert body["error"] == "tracing_gap"
+    assert "NO_PR" in body["missing"] or "pr_number" in body["missing"]
+    task_svc.submit_qa.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# E.4 NO_PROGRESS
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_blocks_when_no_progress() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, agent_id)
+    t.progress_updates = []
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "done")
+    body = env.as_dict()
+    assert body["error"] == "tracing_gap"
+    # progress>=1 is the existing tracing_gate Requirement key.
+    assert "progress>=1" in body["missing"] or "NO_PROGRESS" in body["missing"]
+    task_svc.submit_qa.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# E.5 happy path: all gates pass → submit_qa runs (NO catch-up)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_proceeds_when_all_gates_pass() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, agent_id)
+    after_submit = MagicMock(
+        **{**t.__dict__, "status": "awaiting_qa"},
+    )
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    task_svc.submit_qa.return_value = after_submit
+    task_svc.qa_agent_for_team.return_value = MagicMock(
+        id=uuid4(), skills=[{"id": "code_review"}]
+    )
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    work_svc = AsyncMock()
+    work_svc.files_changed.return_value = ["foo.py"]
+    deps = _make_deps(
+        task=task_svc, journal=journal_svc, work_session=work_svc
+    )
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "all done")
+    body = env.as_dict()
+    assert body["error"] is None
+    assert body["status"] == "awaiting_qa"
+    task_svc.submit_qa.assert_awaited_once()
+    # Strict path must NOT call submit_verification, push, or create_pr —
+    # those are catch-up side effects which are now opt-in only.
+    task_svc.submit_verification.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# E.6 i_am_done_with_catchup retains the smart-catch-up convenience.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_with_catchup_runs_full_chain() -> None:
+    agent_id = uuid4()
+    task_id = uuid4()
+    initial = _ready_task(task_id, agent_id)
+    initial.self_verified = False
+    initial.pr_number = None
+    after_verify = MagicMock(
+        **{**initial.__dict__, "self_verified": True, "status": "verifying"}
+    )
+    after_pr_refresh = MagicMock(
+        **{**after_verify.__dict__, "pr_number": 8, "pr_url": "https://x/pr/8"}
+    )
+    after_submit = MagicMock(
+        **{**after_pr_refresh.__dict__, "status": "awaiting_qa"}
+    )
+    task_svc = AsyncMock()
+    task_svc.get.side_effect = [initial, after_pr_refresh]
+    task_svc.submit_verification.return_value = after_verify
+    task_svc.submit_qa.return_value = after_submit
+    task_svc.qa_agent_for_team.return_value = MagicMock(
+        id=uuid4(), skills=[{"id": "code_review"}]
+    )
+    work_svc = AsyncMock()
+    work_svc.has_unpushed_commits.return_value = True
+    work_svc.files_changed.return_value = ["foo.py"]
+    git_svc = AsyncMock()
+    git_svc.create_pr.return_value = {"pr_number": 8, "pr_url": "https://x/pr/8"}
+    journal_svc = AsyncMock()
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(
+        task=task_svc,
+        journal=journal_svc,
+        work_session=work_svc,
+        git=git_svc,
+    )
+    c = Choreographer(deps)
+
+    env = await c.i_am_done_with_catchup(agent_id, task_id, "all done")
+    body = env.as_dict()
+    assert body["error"] is None
+    assert body["status"] == "awaiting_qa"
+    task_svc.submit_verification.assert_awaited_once()
+    git_svc.push_branch.assert_awaited_once()
+    git_svc.create_pr.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_i_am_done_blocks_unauthorized() -> None:
+    """Existing not_authorized check still applies."""
+    agent_id = uuid4()
+    other_id = uuid4()
+    task_id = uuid4()
+    t = _ready_task(task_id, other_id)
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    deps = _make_deps(task=task_svc)
+    c = Choreographer(deps)
+
+    env = await c.i_am_done(agent_id, task_id, "done")
+    body = env.as_dict()
+    assert body["error"] == "not_authorized"