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.
This commit is contained in:
Renn F
2026-05-08 11:54:31 +02:00
parent 2eeefb2ee1
commit 6806516015
20 changed files with 125 additions and 79 deletions
@@ -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"