refactor(gateway): rename submit_for_qa to open_pr; pin atomic preconditions

Pre-fix, submit_for_qa opened a PR (side effect) and returned OK with
next='call i_am_done' — agents read the verb name, assumed they were
done with QA handoff, never called i_am_done, and PRs ended up
orphaned (PR #12 in the 2026-05-08 trace).

Two changes:

1. Rename submit_for_qa -> open_pr so the verb name matches the
   semantic. The PR opens here; the actual QA handoff happens at
   i_am_done. Renamed across:
   - choreographer/_impl.py (method)
   - mcp/flow_server.py (tool registration + _TOOLS dict)
   - api/routes/v2/flow_dev.py (route + handler)
   - api/schemas/v2/flow.py (OpenPrRequest)
   - services/gateway/verb_gates.py (_STATE_VERBS)
   - services/gateway/role_config.py (developer flow manifest)
   - services/gateway/content_actions.py (commit-success next= hint)
   - agent_sdk/server.py (post-tool guidance map)
   - runtime/orchestrator.py (developer prompt)
   - agents/prompts/{base,roles/developer,_generated/*}.md
   - tests/unit/gateway/test_submit_for_qa.py -> test_open_pr.py
   - tests/unit/api/routes/v2/test_flow_dev.py
   - tests/unit/gateway/test_verb_gates.py
   - tests/unit/api/test_correlation_id.py
   - tests/unit/mcp_servers/test_flow_server.py
   - tests/integration/test_full_lifecycle_real_db.py

2. New regression test (test_open_pr_does_not_create_pr_if_no_commits)
   pins the atomic invariant: preconditions (assignee, commits,
   no-prior-PR) must be checked BEFORE git.create_pr/push_branch run.
   Any future re-ordering breaks the test.

Tests: 3128 passing (3127 + 1 new), 100% coverage, ruff clean.

Note: TaskService.submit_for_qa() (the v1-layer service method) is
INTENTIONALLY not renamed — it's a different layer used by the v1
routes. The rename here is only the gateway verb surface.

tests/integration/test_full_lifecycle_real_db.py

@@ -322,10 +322,10 @@ async def test_dev_can_claim_pending_task_via_gateway(
 async def test_dev_full_chain_through_awaiting_qa(
     db_session: AsyncSession, lifecycle_setup: dict[str, Any]
 ) -> None:
-    """claim → commit → submit_for_qa → i_am_done lands in awaiting_qa.
+    """claim → commit → open_pr → i_am_done lands in awaiting_qa.
 
     Drives the full developer-side closure path. Verifies:
-      - submit_for_qa records pr_number on the task (commits + PR pre-flight)
+      - open_pr records pr_number on the task (commits + PR pre-flight)
       - i_am_done auto-runs submit_verification (P1-3) → verifying → awaiting_qa
       - Heartbeat refreshes after each verb (`_touch`)
       - active_claimant_id remains set through dev's tenure
@@ -353,7 +353,7 @@ async def test_dev_full_chain_through_awaiting_qa(
 
     # 2. Commit (via stub git directly + record progress on task — the gateway
     # path through ContentActions.commit calls task.add_progress, which we
-    # simulate here so submit_for_qa's commits-precondition is satisfied).
+    # simulate here so open_pr's commits-precondition is satisfied).
     await stub_git.commit(
         branch_name=_BRANCH,
         message=f"[{str(task.id)[:8]}] feat(api): add /healthz",
@@ -361,9 +361,9 @@ async def test_dev_full_chain_through_awaiting_qa(
     )
     await task_service.add_progress(task.id, dev_agent.id, "implemented /healthz")
 
-    # 3. submit_for_qa — push + open PR. After this, task.pr_number is set.
-    env = await c.submit_for_qa(dev_agent.id, task.id)
-    assert env.error is None, f"submit_for_qa failed: {env.message}"
+    # 3. open_pr — push + open PR. After this, task.pr_number is set.
+    env = await c.open_pr(dev_agent.id, task.id)
+    assert env.error is None, f"open_pr failed: {env.message}"
     refreshed = await task_service.get(task.id)
     assert refreshed is not None
     assert refreshed.pr_number == _PR_NUMBER, "P0-7 / S-02: PR recorded on task"
@@ -418,7 +418,7 @@ async def test_full_chain_through_doc_handoff(
         task_id=task.id,
     )
     await task_service.add_progress(task.id, dev_agent.id, "implemented /healthz")
-    await c.submit_for_qa(dev_agent.id, task.id)
+    await c.open_pr(dev_agent.id, task.id)
     env = await c.i_am_done(dev_agent.id, task.id, "tests pass; route works")
     assert env.error is None
     assert env.status == "awaiting_qa"

tests/unit/api/routes/v2/test_flow_dev.py

@@ -157,20 +157,20 @@ def test_i_am_blocked_rejects_empty_reason() -> None:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_dispatches_task_id() -> None:
-    """POST submit_for_qa forwards task_id."""
+async def test_open_pr_dispatches_task_id() -> None:
+    """POST open_pr forwards task_id."""
     mock_chore = MagicMock()
-    mock_chore.submit_for_qa = AsyncMock(
+    mock_chore.open_pr = AsyncMock(
         return_value=_make_envelope(status="awaiting_qa", task_id=_TASK_ID)
     )
     client = TestClient(_build_app(mock_chore))
     resp = client.post(
-        "/api/v2/flow/developer/submit_for_qa",
+        "/api/v2/flow/developer/open_pr",
         json={"task_id": _TASK_ID},
         headers=_HEADERS,
     )
     assert resp.status_code == _HTTP_200
-    mock_chore.submit_for_qa.assert_awaited_once()
+    mock_chore.open_pr.assert_awaited_once()
 
 
 @pytest.mark.asyncio

tests/unit/api/test_correlation_id.py

@@ -155,7 +155,7 @@ def _reload_mcp_module(monkeypatch: pytest.MonkeyPatch, dotted: str) -> ModuleTy
                 "flow_tools": [
                     "give_me_work",
                     "i_will_work_on",
-                    "submit_for_qa",
+                    "open_pr",
                     "i_am_done",
                     "i_am_blocked",
                     "unclaim",

tests/unit/gateway/test_choreographer_impl_branches.py

@@ -1049,3 +1049,38 @@ async def test_i_will_work_on_envelope_carries_introspection_on_rejection() -> N
     assert isinstance(body["valid_next_verbs"], list)
     # Lifecycle verbs are NOT in the list for a completed task.
     assert "i_will_work_on" not in body["valid_next_verbs"]
+
+
+@pytest.mark.asyncio
+async def test_open_pr_does_not_create_pr_if_no_commits() -> None:
+    """Atomic invariant: if commits[] is empty, open_pr must NOT call
+    git.create_pr. Pre-fix this was already true at the verb level, but
+    this test pins it as a regression: any future refactor that
+    re-orders precondition vs side effect breaks the test."""
+    dev_id = uuid4()
+    task_id = uuid4()
+    task = MagicMock(
+        status="in_progress",
+        assigned_to=dev_id,
+        commits=[],
+        pr_number=None,
+        branch_name="feature/backend/abc",
+        id=task_id,
+        title="t",
+        team="backend",
+        task_type="code",
+    )
+    task_svc = AsyncMock()
+    task_svc.get.return_value = task
+    task_svc.agent_for.return_value = MagicMock(role="developer", team="backend")
+    git_svc = AsyncMock()
+    git_svc.create_pr = AsyncMock()
+    git_svc.push_branch = AsyncMock()
+    deps = _make_deps(task=task_svc, git=git_svc)
+    c = Choreographer(deps)
+    env = await c.open_pr(dev_id, task_id)
+    body = env.as_dict()
+    assert body["error"] == "invalid_state"
+    assert "no commits" in body["message"]
+    git_svc.create_pr.assert_not_called()
+    git_svc.push_branch.assert_not_called()

tests/unit/gateway/test_open_pr.py

@@ -1,4 +1,4 @@
-"""submit_for_qa pushes the current branch and opens a PR.
+"""open_pr pushes the current branch and opens a PR.
 
 Gate E (commit c5c2016) made `i_am_done` strict — requires `pr_number` set.
 The catch-up flow is off the dev manifest. Devs need an explicit verb that
@@ -44,7 +44,7 @@ def _make_deps(**overrides: AsyncMock) -> ChoreographerDeps:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_pushes_and_opens_pr() -> None:
+async def test_open_pr_pushes_and_opens_pr() -> None:
     aid = uuid4()
     tid = uuid4()
     t = MagicMock(
@@ -69,7 +69,7 @@ async def test_submit_for_qa_pushes_and_opens_pr() -> None:
     deps = _make_deps(task=task_svc, git=git_svc, work_session=work_session_svc)
     c = Choreographer(deps)
 
-    env = await c.submit_for_qa(aid, tid)
+    env = await c.open_pr(aid, tid)
 
     git_svc.push_branch.assert_awaited()
     git_svc.create_pr.assert_awaited()
@@ -79,7 +79,7 @@ async def test_submit_for_qa_pushes_and_opens_pr() -> None:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_rejects_when_not_assigned() -> None:
+async def test_open_pr_rejects_when_not_assigned() -> None:
     aid = uuid4()
     other = uuid4()
     tid = uuid4()
@@ -98,7 +98,7 @@ async def test_submit_for_qa_rejects_when_not_assigned() -> None:
     deps = _make_deps(task=task_svc, git=git_svc)
     c = Choreographer(deps)
 
-    env = await c.submit_for_qa(aid, tid)
+    env = await c.open_pr(aid, tid)
 
     git_svc.push_branch.assert_not_awaited()
     git_svc.create_pr.assert_not_awaited()
@@ -106,7 +106,7 @@ async def test_submit_for_qa_rejects_when_not_assigned() -> None:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_rejects_when_no_commits() -> None:
+async def test_open_pr_rejects_when_no_commits() -> None:
     aid = uuid4()
     tid = uuid4()
     t = MagicMock(
@@ -124,7 +124,7 @@ async def test_submit_for_qa_rejects_when_no_commits() -> None:
     deps = _make_deps(task=task_svc, git=git_svc)
     c = Choreographer(deps)
 
-    env = await c.submit_for_qa(aid, tid)
+    env = await c.open_pr(aid, tid)
 
     git_svc.push_branch.assert_not_awaited()
     git_svc.create_pr.assert_not_awaited()
@@ -134,7 +134,7 @@ async def test_submit_for_qa_rejects_when_no_commits() -> None:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_idempotent_when_pr_already_open() -> None:
+async def test_open_pr_idempotent_when_pr_already_open() -> None:
     aid = uuid4()
     tid = uuid4()
     t = MagicMock(
@@ -152,7 +152,7 @@ async def test_submit_for_qa_idempotent_when_pr_already_open() -> None:
     deps = _make_deps(task=task_svc, git=git_svc)
     c = Choreographer(deps)
 
-    env = await c.submit_for_qa(aid, tid)
+    env = await c.open_pr(aid, tid)
 
     git_svc.push_branch.assert_not_awaited()
     git_svc.create_pr.assert_not_awaited()
@@ -162,7 +162,7 @@ async def test_submit_for_qa_idempotent_when_pr_already_open() -> None:
 
 
 @pytest.mark.asyncio
-async def test_submit_for_qa_returns_not_found_for_unknown_task() -> None:
+async def test_open_pr_returns_not_found_for_unknown_task() -> None:
     aid = uuid4()
     tid = uuid4()
     task_svc = AsyncMock()
@@ -170,6 +170,6 @@ async def test_submit_for_qa_returns_not_found_for_unknown_task() -> None:
     deps = _make_deps(task=task_svc)
     c = Choreographer(deps)
 
-    env = await c.submit_for_qa(aid, tid)
+    env = await c.open_pr(aid, tid)
 
     assert env.error == "not_found"

tests/unit/gateway/test_verb_gates.py

@@ -33,7 +33,7 @@ def test_developer_pending_task_can_claim() -> None:
 def test_developer_in_progress_task_can_commit_and_finish() -> None:
     verbs = valid_next_verbs("developer", _task("in_progress"))
     assert "commit" in verbs
-    assert "submit_for_qa" in verbs
+    assert "open_pr" in verbs
     assert "i_am_done" in verbs
     assert "i_am_blocked" in verbs
 
@@ -140,7 +140,7 @@ def test_completed_task_offers_no_lifecycle_verbs() -> None:
     # Idle / observation verbs may still be offered; lifecycle verbs aren't.
     assert "i_will_work_on" not in verbs
     assert "commit" not in verbs
-    assert "submit_for_qa" not in verbs
+    assert "open_pr" not in verbs
 
 
 def test_unknown_role_returns_empty_list() -> None:

tests/unit/mcp_servers/test_flow_server.py

@@ -24,7 +24,7 @@ _FULL_MANIFEST = {
     "flow_tools": [
         "give_me_work",
         "i_will_work_on",
-        "submit_for_qa",
+        "open_pr",
         "i_am_done",
         "i_am_blocked",
         "unclaim",