feat: in-path PR-review gate — per-cell + main reviewers (#229)

* feat(lifecycle): add the in-path PR-review gate status + reviewer verbs Insert awaiting_pr_review between the assembled-PR submit and the PM merge, giving the merge level the rejection capability it structurally lacks — today only qa_fail and ceo_reject ever reach needs_revision, so a PM review is a merge button with no teeth. - New Status awaiting_pr_review + submit_for_review / pr_pass / pr_fail actions (pr_pass -> awaiting_pm_review, pr_fail -> needs_revision, mirroring the QA gate). - Reviewer verbs claim_gate_review / pr_pass / pr_fail, and a main-PM submit_root verb (the root analogue of the cell PM's submit_up; opens the root->master PR). - Extend the self-review-symmetry validator to the new sign-off actions. - Mirror the value into the ORM TaskStatus enum + the A2A state map, and add the postgres taskstatus enum value (migration 040, forward-only like 037). - Regenerate the per-role verb tables; add gate spec tests. Spec surface only; the gateway methods + dispatch are wired in follow-ups, so the verbs are advertised but dormant (flow_server tolerates unregistered verbs). * feat(identity): add the three cell PR-review-gate reviewers The in-path gate needs a reviewer per cell so each cell's assembled cell->root PR is reviewed by a stack-specialized agent, while pr-reviewer-1 serves the root->master gate (and keeps doing inbound external PRs). - be/fe/ux-pr-reviewer: PR_REVIEWER role, team-scoped (so dispatch routes each cell's gate to its own reviewer); seeded identities + ROLE_TEAM_RULES + names. AI agent count 22 -> 25. - They reuse the existing roboco-agent-pr-reviewer image (AGENT_IMAGES maps the three slugs to it, as be-dev-1/-2 share one image) — no new image. - Tracing table: pr_pass/pr_fail require a learning entry (parity with post_pr_review), submit_root mirrors submit_up, claim_gate_review is waived (its tracing applies on pr_pass/pr_fail) — completes the verb surface added in the prior commit. - Update the roster-pinning identity tests. * feat(gateway): wire the in-path PR-review gate end to end Make the assembled-PR review gate operational across the choreographer, the TaskService transitions, and the v1 flow surface. - TaskService: submit_for_review (in_progress→awaiting_pr_review), pr_gate_claim (no-transition reviewer claim), pr_pass (→awaiting_pm_review), pr_fail (→needs_revision); mirror qa_pass/qa_fail (clear claim, actor-mismatch warn, issues appended for the PM's revision). VerbRunner gains the matching atomic handlers + a create_root_pr side effect. - Repoint submit_up to compose submit_for_review (cell→root PR enters the gate), and add a main-PM submit_root verb (opens the root→master PR, enters the gate). - Split main_pm_complete: a code root must pass the gate first (requires awaiting_pm_review; rejects an in_progress code root toward submit_root and no longer reopens the PR), while a branchless coordination root still walks straight through, ungated. - PRGateMixin (claim_gate_review / pr_pass / pr_fail) composed onto the Choreographer; flow_server forwarders + v1 routes (pr_reviewer + main_pm) + request schemas. - Tests: gate spec + the updated submit_up / main_pm_complete expectations + new real-DB integration tests driving submit_for_review→pr_gate_claim→pr_pass and pr_fail through the real enforcement layer. * feat(orchestrator): dispatch the in-path PR-review gate Make the gate live in the dispatch loop. - _dispatch_pr_gate_work: route awaiting_pr_review tasks to reviewers by level — a cell→root task to its cell reviewer (be/fe/ux-pr-reviewer), the root→master task to pr-reviewer-1. The reviewer self-claims via claim_gate_review (no pre-claim, mirroring the external-PR dispatcher); registered in _dispatch_all_work. _select_agent_for_cell learns the pr_reviewer role. - _build_pr_gate_prompt: anchors the reviewer to the parent objective + full acceptance criteria + the FE<->BE contract, then pr_pass / pr_fail. - _readiness_check_role_for_status: awaiting_pr_review -> pr_reviewer. - Fail routing: pr_fail reassigns the failed assembled task to its PM (_revision_pm_for_task: cell PM for a cell team, Main PM for the root), and the revision dispatcher is generalized from coordination-roots-only to any PM-owned needs_revision task so the gate-failed task is re-coordinated instead of deadlocking. * docs: document the in-path PR-review gate + the cell reviewers (22→25) Reflect the shipped gate across the canonical + RAG docs. - CLAUDE.md: agent count 22→25, the cell reviewers in the org chart, an awaiting_pr_review state + the gate transitions + a gate note in the lifecycle section, and submit_root / claim_gate_review / pr_pass / pr_fail in the verb surface table. - docs/rag/architecture: org-structure (count, cell-reviewer roster, cells table), agent-uuids (be/fe/ux-pr-reviewer rows), agent-model (role + team rows). - docs/rag/roles/pr-reviewer: the in-path gate section + the gate verbs. - Wrap reviewer.id with UUID(str(...)) in the gate DB tests for mypy. * docs: finish the gate doc sweep across README + RAG + generated artifacts Catch the remaining surfaces beyond the canonical docs. - README + how-to: agent count 22→25, the 6-agent cells (+ PR Reviewer), the main reviewer's root→master gate role. - RAG: permissions + tool-permissions + task-tools list the gate verbs (claim_gate_review / pr_pass / pr_fail) for pr_reviewer; regenerate the lifecycle artifacts (intent-verbs, status-transitions, the per-role lifecycle-*.md prompts, panel lifecycle.json) from the spec via build_lifecycle_artifacts.py so they carry the new status + verbs. * fix(migration): shorten the 040 revision id to fit alembic_version VARCHAR(32) The revision id '040_taskstatus_awaiting_pr_review' is 33 chars; alembic's alembic_version.version_num column is VARCHAR(32), so recording the migration on a real 'alembic upgrade head' failed with 'value too long for type character varying(32)' (surfaced on the NAS deploy). The test suite missed it: the test DB is built via Base.metadata.create_all and the parity test only renders SQL offline, so nothing actually applied the migration chain. - Rename to '040_awaiting_pr_review' (22 chars). - Add a guard test asserting every revision id fits the VARCHAR(32) column. - Verified by applying the full chain 001->040 against real Postgres: it now reaches head and records '040_awaiting_pr_review' without truncation. * fix(migration): land the actual 040 revision-id shortening + guard test The prior commit captured only the file rename (git add aborted on the deleted old path), leaving the long revision id and missing the guard test. This commit carries the real content: revision id '040_awaiting_pr_review' (22 chars) and the revision-id length guard. Re-verified against real Postgres — the full chain reaches head and records the short id without truncation. * fix(product): flush cell deletes before inserts when re-mapping projects Editing a product's cell->project map (PATCH /api/products/{id}) 409'd with 'duplicate key value violates unique constraint uq_product_projects_product_team' whenever a team already had a mapping. _replace_cells clears the old rows and appends the new ones, but within a single flush SQLAlchemy orders INSERTs before DELETEs for the same table, so the new (product_id, team) rows collided with the not-yet-deleted old ones. Flush the deletes first. Pre-existing bug (unrelated to the PR-review gate); surfaced on the NAS. New real-Postgres regression test re-maps all three cells to different projects — it fails with the unique violation without the fix and passes with it. The existing update test only changed WHICH team was mapped, so it never collided. * fix(gateway): let main_pm submit_root past the shared submit-up guard submit_root reused the cell PM's _submit_up_ownership_guard, which hardcoded agent.role != cell_pm and rejected the Main PM with "submit_up is reserved for cell_pm". A branch-bearing code root could then never close: submit_root bounced to complete, while complete required awaiting_pm_review (reachable only via submit_root) and bounced back — a circular rejection. Both callers already run the spec gate (can_invoke_intent), which enforces submit_up→cell_pm and submit_root→main_pm, so the guard's role re-check was redundant for submit_up and wrong for submit_root. Broaden it to accept either PM role as a defense-in-depth non-PM reject. Adds the first choreographer-level submit_root test (the gap that let this ship). * fix(gateway): proactively steer both PMs to their bubble-up verb The submit_root deadlock had a sibling steering gap: nothing told a PM which verb opens the gate. The delegate next-hint said only 'i_am_idle when done', and complete's in_progress rejection named submit_root for the Main PM but left the Cell PM with a bare 'not ready for completion' — no submit_up pointer, the same guess-the-verb trap. - delegate hint now names the role-correct verb (root → submit_root, cell parent → submit_up) proactively, before any rejection. - cell_pm_complete's in_progress rejection now steers to submit_up, mirroring the Main PM's submit_root gate hint. Tests cover both the cell-PM steer and the role-aware delegate hint. * docs: correct who-merges-which-PR across the gate docs + complete description Audit of the gate docs found the merge actors mis-stated in several places — the exact ambiguity that risks 'the reviewer/PM merges the root PR' confusion: - complete IntentSpec description said 'Main PM merges root PR' — false; main_pm_complete escalates and the CEO merges root→master. Corrected (propagated to intent-verbs.md, lifecycle.json, generated role prompts via build_lifecycle_artifacts.py). - task-tools.md: submit_up target was awaiting_pm_review (should be awaiting_pr_review); Main PM flow had no submit_root — added it. - README.md: lifecycle diagram now shows the awaiting_pr_review gate. - cell-pm.md / main-pm.md: dropped the stale 'submit_up hands work to the Main PM who merges your cell branch' model — the cell PM merges its own gated cell→root PR; the Main PM owns the root + submit_root; the CEO merges master. Added submit_root to the main-pm manifest. - git-commits.md, pr-creation.md, tool-permissions.md, git-tools.md: stopped attributing root→master PR opening to complete (it's submit_root). No behavior change; verb wiring + state machine verified gap-free this session (the pr_fail→needs_revision→PM respawn loop closes correctly). * fix(orchestrator): stop closure respawn waiting the reaper window A PM that finished its subtasks and idled left its parent 'paused' with a fresh last_heartbeat_at. _is_recently_paused gated closure respawn on _claim_heartbeat_ttl — the REAPER window (stale_claim_reap_seconds: 600s default, 1800s on the NAS) — so the parent sat untouched for up to 10-30 minutes before its PM was respawned to close it. The whole chain stalled behind it. The race that guard actually protects against (i_am_idle auto-pauses, then the agent is marked IDLE + its container tears down) is seconds, and the live-session case is already covered by _is_agent_active. Introduce a dedicated short debounce (pm_closure_recently_paused_seconds, default 45s) and gate closure on that instead. The existing test fixture masked this by setting _claim_heartbeat_ttl to claim_stale_seconds (180s), not the production reaper value. Fixture now mirrors production; adds a regression test that a parent paused past the debounce but within the reaper window respawns immediately. * feat(gate): post the in-path review verdict on the assembled PR The in-path gate previously left no trace on the PR it gated — pr_pass / pr_fail were pure status transitions. Now each verdict is posted as a GitHub review on the assembled PR itself (server-side, bot account), so the decision is visible on the very PR the PM merges. - pr_pass → APPROVE, pr_fail → REQUEST_CHANGES on a cell→root PR. - The root→master PR ALWAYS gets a plain COMMENT, never APPROVE/REQUEST_ CHANGES: only the CEO acts on master, so the gate must never leave an approval that could satisfy branch protection (letting someone else merge) nor a blocking review that could impede the CEO's merge. - Best-effort and AFTER the DB transition — a GitHub failure is logged, never rolls back the gate decision. Reuses git.post_pr_review's existing self-review→COMMENT downgrade for the org's own PRs. Adds _project_slug_for to the ChoreographerHelpers protocol (mypy) and a unit suite covering event selection, the master-bound COMMENT rule, the no-PR skip, and failure-swallowing. Docs updated (pr-reviewer, task-tools). --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-08-03 07:23:24 +02:00 · 2026-06-20 09:27:29 +02:00
parent 463c952b16
commit 5fe1e6df58
56 changed files with 2061 additions and 206 deletions
@@ -415,14 +415,49 @@ async def test_cell_pm_complete_not_assigned_returns_not_authorized() -> None:


@pytest.mark.asyncio
-async def test_main_pm_complete_opens_master_pr_and_escalates() -> None:
+async def test_cell_pm_complete_in_progress_steers_to_submit_up() -> None:
+    """Mirror of the main-PM submit_root steer: a cell task still in_progress
+    must enter the gate via submit_up first. The rejection must NAME submit_up
+    so the cell PM isn't left guessing the verb (the gap that deadlocked the
+    main PM on submit_root)."""
+    pm_id = uuid4()
+    task_id = uuid4()
+    t = MagicMock(
+        id=task_id,
+        status="in_progress",
+        assigned_to=pm_id,
+        parent_task_id=uuid4(),
+        branch_name="feature/backend/parent123",
+    )
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    task_svc.all_subtasks_terminal.return_value = True
+    journal_svc = AsyncMock()
+    journal_svc.has_decision_for_task.return_value = True
+    journal_svc.latest_decision_at.return_value = datetime.now(UTC)
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.cell_pm_complete(
+        pm_id, task_id, notes="cell scope assembled; ready to bubble up"
+    )
+    assert env.error is not None
+    assert "submit_up" in (env.remediate or "")
+
+
+@pytest.mark.asyncio
+async def test_main_pm_complete_escalates_code_root_without_reopening_pr() -> None:
+    """A code root reaches main_pm_complete already in awaiting_pm_review —
+    submit_root opened the root→master PR and the main reviewer pr_passed it —
+    so complete just escalates to the CEO and does NOT reopen the PR."""
    main_pm_id = uuid4()
    root_task_id = uuid4()
    t = MagicMock(
        id=root_task_id,
        status="awaiting_pm_review",
        assigned_to=main_pm_id,
-        pr_number=None,
+        pr_number=99,
        branch_name="feature/backend/root123",
        parent_task_id=None,
        team="backend",
@@ -433,7 +468,6 @@ async def test_main_pm_complete_opens_master_pr_and_escalates() -> None:
    task_svc.escalate_to_ceo.return_value = after
    task_svc.all_subtasks_terminal.return_value = True
    git_svc = AsyncMock()
-    git_svc.create_pr.return_value = {"pr_number": 99, "pr_url": "https://x/y/pull/99"}
    journal_svc = AsyncMock()
    journal_svc.has_decision_for_task.return_value = True
    journal_svc.latest_decision_at.return_value = datetime.now(UTC)
@@ -446,19 +480,52 @@ async def test_main_pm_complete_opens_master_pr_and_escalates() -> None:
    )
    assert env.error is None
    assert env.status == "awaiting_ceo_approval"
-    git_svc.create_pr.assert_awaited_once_with(
-        "feature/backend/root123",
-        parent="master",
-        is_root_pr=True,
-    )
+    git_svc.create_pr.assert_not_awaited()
    task_svc.escalate_to_ceo.assert_awaited_once()


@pytest.mark.asyncio
-async def test_main_pm_complete_advances_in_progress_root_to_ceo() -> None:
-    """#183: a root resumed to in_progress (subtasks all done) has no submit_up
-    to reach awaiting_pm_review. main_pm_complete opens the root→master PR,
-    walks the root through awaiting_pm_review, then escalates to CEO."""
+async def test_main_pm_complete_rejects_in_progress_code_root_toward_submit_root() -> (
+    None
+):
+    """A code root must pass the in-path gate first. main_pm_complete rejects it
+    while still in_progress and points the Main PM at submit_root."""
+    main_pm_id = uuid4()
+    root_task_id = uuid4()
+    t = MagicMock(
+        id=root_task_id,
+        status="in_progress",
+        assigned_to=main_pm_id,
+        pr_number=None,
+        branch_name="feature/main_pm/root123",
+        parent_task_id=None,
+        team="main_pm",
+    )
+    task_svc = AsyncMock()
+    task_svc.get.return_value = t
+    task_svc.all_subtasks_terminal.return_value = True
+    git_svc = AsyncMock()
+    journal_svc = AsyncMock()
+    journal_svc.has_decision_for_task.return_value = True
+    journal_svc.latest_decision_at.return_value = datetime.now(UTC)
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, git=git_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.main_pm_complete(
+        main_pm_id, root_task_id, notes="root scope reviewed; ready for CEO sign-off"
+    )
+    assert env.error is not None
+    assert "submit_root" in (env.remediate or "")
+    task_svc.escalate_to_ceo.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_submit_root_accepts_main_pm_and_enters_the_gate() -> None:
+    """submit_root is the Main PM's entry to the in-path gate. It reuses the
+    cell PM's _submit_up_guard for ownership/state, so the ownership guard must
+    NOT hardcode-reject main_pm — otherwise submit_root and complete point at
+    each other and a code root can never close (the circular-rejection bug)."""
    main_pm_id = uuid4()
    root_task_id = uuid4()
    in_prog = MagicMock(
@@ -470,6 +537,48 @@ async def test_main_pm_complete_advances_in_progress_root_to_ceo() -> None:
        parent_task_id=None,
        team="main_pm",
    )
+    gated = MagicMock(**{**in_prog.__dict__, "status": "awaiting_pr_review"})
+    task_svc = AsyncMock()
+    task_svc.get.return_value = in_prog
+    task_svc.submit_for_review.return_value = gated
+    task_svc.all_subtasks_terminal.return_value = True
+    task_svc.uncovered_parent_acceptance_criteria.return_value = []
+    task_svc.agent_for.return_value = MagicMock(role="main_pm", team="main_pm")
+    task_svc.session.begin_nested = MagicMock(
+        return_value=MagicMock(__aenter__=AsyncMock(), __aexit__=AsyncMock())
+    )
+    git_svc = AsyncMock()
+    journal_svc = AsyncMock()
+    journal_svc.has_decision_for_task.return_value = True
+    journal_svc.latest_decision_at.return_value = datetime.now(UTC)
+    journal_svc.has_reflect_for_task.return_value = True
+    deps = _make_deps(task=task_svc, git=git_svc, journal=journal_svc)
+    c = Choreographer(deps)
+
+    env = await c.submit_root(
+        main_pm_id, root_task_id, notes="root scope assembled; opening root→master PR"
+    )
+    assert env.error is None, env.as_dict()
+    assert env.status == "awaiting_pr_review"
+    task_svc.submit_for_review.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_main_pm_complete_walks_branchless_coordination_root_to_ceo() -> None:
+    """A branchless coordination root (product fan-out, no repo/PR) skips the
+    in-path gate: main_pm_complete walks it in_progress→awaiting_pm_review and
+    escalates to the CEO. No root→master PR is created (it has no branch)."""
+    main_pm_id = uuid4()
+    root_task_id = uuid4()
+    in_prog = MagicMock(
+        id=root_task_id,
+        status="in_progress",
+        assigned_to=main_pm_id,
+        pr_number=None,
+        branch_name=None,
+        parent_task_id=None,
+        team="main_pm",
+    )
    awaiting = MagicMock(**{**in_prog.__dict__, "status": "awaiting_pm_review"})
    after = MagicMock(**{**in_prog.__dict__, "status": "awaiting_ceo_approval"})
    task_svc = AsyncMock()
@@ -478,7 +587,6 @@ async def test_main_pm_complete_advances_in_progress_root_to_ceo() -> None:
    task_svc.escalate_to_ceo.return_value = after
    task_svc.all_subtasks_terminal.return_value = True
    git_svc = AsyncMock()
-    git_svc.create_pr.return_value = {"pr_number": 99, "pr_url": "https://x/y/pull/99"}
    journal_svc = AsyncMock()
    journal_svc.has_decision_for_task.return_value = True
    journal_svc.latest_decision_at.return_value = datetime.now(UTC)
@@ -487,16 +595,11 @@ async def test_main_pm_complete_advances_in_progress_root_to_ceo() -> None:
    c = Choreographer(deps)

    env = await c.main_pm_complete(
-        main_pm_id, root_task_id, notes="root scope reviewed; ready for CEO sign-off"
+        main_pm_id, root_task_id, notes="coordination root reviewed; ready for CEO"
    )
    assert env.error is None
    assert env.status == "awaiting_ceo_approval"
-    git_svc.create_pr.assert_awaited_once_with(
-        "feature/main_pm/root123",
-        parent="master",
-        is_root_pr=True,
-    )
-    # #183: the in_progress→awaiting_pm_review hop must run before escalation.
+    git_svc.create_pr.assert_not_awaited()
    task_svc.submit_pm_review.assert_awaited_once()
    task_svc.escalate_to_ceo.assert_awaited_once()

@@ -883,10 +883,11 @@ async def test_delegate_invalid_team_enum_rejected() -> None:

@pytest.mark.asyncio
 async def test_submit_up_opens_pr_and_keeps_cell_pm_assignment() -> None:
-    """#182: submit_up opens the cell→root PR and moves the cell task to
-    awaiting_pm_review, but does NOT hand it off to Main PM. The cell PM
-    owns cell completion (it is respawned to `complete` the task), so the
-    assignment stays put — no reassign."""
+    """submit_up opens the cell→root PR and moves the cell task into the
+    in-path PR-review gate (awaiting_pr_review), but does NOT hand it off to
+    Main PM. The cell PM owns cell completion (it is respawned to `complete`
+    after the cell reviewer pr_passes), so the assignment stays put — no
+    reassign."""
    pm_id = uuid4()
    task_id = uuid4()
    t = MagicMock(
@@ -899,7 +900,7 @@ async def test_submit_up_opens_pr_and_keeps_cell_pm_assignment() -> None:
    )
    after = MagicMock(
        id=task_id,
-        status="awaiting_pm_review",
+        status="awaiting_pr_review",
        assigned_to=pm_id,
        parent_task_id=None,
        branch_name="feature/backend/abc123",
@@ -909,7 +910,7 @@ async def test_submit_up_opens_pr_and_keeps_cell_pm_assignment() -> None:
    task_svc.get.return_value = t
    task_svc.agent_for.return_value = MagicMock(role="cell_pm", team="backend")
    task_svc.all_subtasks_terminal.return_value = True
-    task_svc.submit_pm_review.return_value = after
+    task_svc.submit_for_review.return_value = after
    git_svc = AsyncMock()
    git_svc.create_pr.return_value = {"pr_number": 12, "pr_url": "x"}
    journal_svc = AsyncMock()
@@ -919,10 +920,10 @@ async def test_submit_up_opens_pr_and_keeps_cell_pm_assignment() -> None:
    c = Choreographer(deps)

    env = await c.submit_up(
-        pm_id, task_id, notes="cell completed all subtasks; ready for main pm"
+        pm_id, task_id, notes="cell completed all subtasks; ready for review"
    )
    assert env.error is None
-    assert env.status == "awaiting_pm_review"
+    assert env.status == "awaiting_pr_review"
    git_svc.create_pr.assert_awaited_once()
    task_svc.reassign.assert_not_called()

@@ -0,0 +1,105 @@
+"""The in-path gate posts its verdict on the assembled PR.
+
+pr_pass / pr_fail leave a review on the PR the PM (or CEO) eventually merges,
+so the gate decision is visible on the PR itself — never a silent transition.
+The root→master PR only ever gets a COMMENT (only the CEO acts on master).
+"""
+
+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_choreographer(git: AsyncMock) -> Choreographer:
+    base: dict[str, Any] = {
+        "task": AsyncMock(),
+        "work_session": AsyncMock(),
+        "git": git,
+        "a2a": AsyncMock(),
+        "journal": AsyncMock(),
+        "audit": AsyncMock(),
+        "evidence_repo": AsyncMock(),
+    }
+    c = Choreographer(ChoreographerDeps(**base))
+    # _project_slug_for hits the project service; stub it for the unit.
+    c._project_slug_for = AsyncMock(return_value="proj")  # type: ignore[method-assign]
+    return c
+
+
+def _task(*, parent_task_id: Any, pr_number: int | None = 77) -> MagicMock:
+    return MagicMock(id=uuid4(), parent_task_id=parent_task_id, pr_number=pr_number)
+
+
+@pytest.mark.asyncio
+async def test_cell_pass_posts_approve() -> None:
+    git = AsyncMock()
+    c = _make_choreographer(git)
+    await c._post_gate_review_to_pr(
+        _task(parent_task_id=uuid4()), "pr_pass", "be-pr-reviewer", "looks good"
+    )
+    git.post_pr_review.assert_awaited_once()
+    _slug, _pr, body = git.post_pr_review.await_args.args
+    assert git.post_pr_review.await_args.kwargs["event"] == "APPROVE"
+    assert "PASSED" in body
+    assert "be-pr-reviewer" in body
+
+
+@pytest.mark.asyncio
+async def test_cell_fail_posts_request_changes() -> None:
+    git = AsyncMock()
+    c = _make_choreographer(git)
+    await c._post_gate_review_to_pr(
+        _task(parent_task_id=uuid4()),
+        "pr_fail",
+        "be-pr-reviewer",
+        "Issues:\n- seam mismatch",
+    )
+    assert git.post_pr_review.await_args.kwargs["event"] == "REQUEST_CHANGES"
+    assert "CHANGES REQUESTED" in git.post_pr_review.await_args.args[2]
+
+
+@pytest.mark.asyncio
+async def test_root_pass_posts_comment_never_approve() -> None:
+    """The root→master PR must never get an APPROVE — only the CEO merges it."""
+    git = AsyncMock()
+    c = _make_choreographer(git)
+    await c._post_gate_review_to_pr(
+        _task(parent_task_id=None), "pr_pass", "pr-reviewer-1", "root scope clean"
+    )
+    assert git.post_pr_review.await_args.kwargs["event"] == "COMMENT"
+    assert "master" in git.post_pr_review.await_args.args[2]
+
+
+@pytest.mark.asyncio
+async def test_root_fail_posts_comment_never_blocks_master() -> None:
+    git = AsyncMock()
+    c = _make_choreographer(git)
+    await c._post_gate_review_to_pr(
+        _task(parent_task_id=None), "pr_fail", "pr-reviewer-1", "Issues:\n- x"
+    )
+    assert git.post_pr_review.await_args.kwargs["event"] == "COMMENT"
+
+
+@pytest.mark.asyncio
+async def test_no_pr_number_skips_post() -> None:
+    git = AsyncMock()
+    c = _make_choreographer(git)
+    await c._post_gate_review_to_pr(
+        _task(parent_task_id=uuid4(), pr_number=None), "pr_pass", "r", "n"
+    )
+    git.post_pr_review.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_github_failure_is_swallowed() -> None:
+    """A posting failure must not propagate — the gate transition already ran."""
+    git = AsyncMock()
+    git.post_pr_review.side_effect = RuntimeError("github down")
+    c = _make_choreographer(git)
+    # Must not raise.
+    await c._post_gate_review_to_pr(_task(parent_task_id=uuid4()), "pr_pass", "r", "n")
@@ -83,13 +83,13 @@ async def test_runner_runs_side_effects_after_db_commit() -> None:

@pytest.mark.asyncio
 async def test_submit_up_creates_pr_before_transition() -> None:
-    """#180: submit_up's create_pr (pre_side_effect) runs BEFORE the
-    submit_pm_review transition.
+    """submit_up's create_pr (pre_side_effect) runs BEFORE the
+    submit_for_review transition.

-    submit_pm_review rejects (returns None) unless pr_created is already
-    set; create_pr persists pr_number onto the task row. With the old
-    composes→side_effects ordering the transition ran first, returned
-    None, and the trailing create_pr crashed on ``None.branch_name``.
+    submit_for_review needs the cell→root PR to already exist (the reviewer
+    reviews it); create_pr persists pr_number onto the task row. With a
+    composes→side_effects ordering the transition would run first and the
+    trailing create_pr would crash — so the pre-side-effect must run first.
    """
    calls: list[str] = []

@@ -98,11 +98,11 @@ async def test_submit_up_creates_pr_before_transition() -> None:
        return_value=MagicMock(__aenter__=AsyncMock(), __aexit__=AsyncMock())
    )

-    def _submit_pm_review(*_args: object, **_kwargs: object) -> MagicMock:
-        calls.append("submit_pm_review")
-        return MagicMock(status="awaiting_pm_review")
+    def _submit_for_review(*_args: object, **_kwargs: object) -> MagicMock:
+        calls.append("submit_for_review")
+        return MagicMock(status="awaiting_pr_review")

-    task_svc.submit_pm_review = AsyncMock(side_effect=_submit_pm_review)
+    task_svc.submit_for_review = AsyncMock(side_effect=_submit_for_review)

    git_svc = AsyncMock()

@@ -123,8 +123,8 @@ async def test_submit_up_creates_pr_before_transition() -> None:
    ctx = spec.Context(notes="cell scope complete; bubbling up to main pm")

    await runner.run_intent("submit_up", task, agent, ctx)
-    assert calls == ["create_pr", "submit_pm_review"], (
-        f"create_pr must precede submit_pm_review for submit_up; got {calls}"
+    assert calls == ["create_pr", "submit_for_review"], (
+        f"create_pr must precede submit_for_review for submit_up; got {calls}"
    )