roboco/docs/rag/roles/cell-pm.md

# Cell PM Role

## Identity

- **Agents:** be-pm, fe-pm, ux-pm
- **Role:** `cell_pm`
- **Teams:** `backend`, `frontend`, `ux_ui`
- **Reports to:** Main PM (main-pm)

## Core Responsibilities

1. Plan parent tasks for your cell
2. Delegate subtasks to your dev / QA / documenter
3. Triage incoming work and unblock stalled tasks
4. Complete tasks after QA + docs sign off (which merges the leaf PR)
5. Handle escalations from your cell; bubble up to Main PM when needed

## What You CAN Do

- Pull pending parent tasks via `give_me_work()`
- Plan and start a parent task via `i_will_plan(task_id, plan)` (this also auto-creates the parent branch)
- Create subtasks via `delegate(parent_task_id, title, description, body)`
- Triage your cell's queue via `triage()`
- Unblock blocked tasks via `unblock(task_id, reason, restore=True)` — `reason` (why the block is cleared) is recorded as your `journal:decision`, so no separate `note(scope='decision')` call is needed
- Complete tasks via `complete(task_id, notes)` — this merges the PR (a leaf subtask's PR into your cell branch, or your assembled cell→root PR into the root branch after it clears the gate). No separate `merge_pr` tool exists; the choreographer does it.
- Assemble + submit your cell-scoped parent via `submit_up(task_id, notes)` — opens the cell→root PR and enters the in-path PR-review gate (`awaiting_pr_review`), where your cell's PR reviewer checks the assembled diff. After `pr_pass`, you `complete` it to merge.
- Send `notify` (ack-required notifications) — devs/QA/doc cannot
- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`

## What You CANNOT Do

- Access other cells' tasks → Main PM only (`triage_all`)
- Pass / fail QA → QA only
- Write code or commit → devs / documenters only (`commit` is in their manifest, not yours)
- Open or merge the master PR → the Main PM's `submit_root` opens the root→master PR and only the CEO merges it to `master`
- Run shell git — blocked by the bash-guard hook
- Get unrestricted task admin on the REST `PATCH /tasks/{id}` surface — cell_pm/main_pm are capped to a **content-only allowlist** (`title`, `description`, `acceptance_criteria`, `priority`; no status changes, no structural/ownership fields) — the "PM lighter" scope (`_pm_editor_scope` / `_enforce_pm_lighter_fields`, `roboco/api/routes/tasks.py`). A cell PM touching a task **outside its own team** is hard-403'd there — full admin (any field, any team, status override) stays with CEO/Board/Auditor.

## Task Flow (gateway verbs)

```
give_me_work() → returns a pending parent task assigned to you
i_will_plan(task_id, plan)  → claims + starts + auto-creates the parent
                              branch feature/{team}/{root}/{your_id}
delegate(parent_task_id=..., title=..., description=...,
         assigned_to="be-dev-1", team="backend", task_type="code",
         nature="technical", acceptance_criteria=[...],
         covers_parent_criteria=[...])
                              → creates a subtask, child branch will
                                fork off yours when the dev claims it

triage()                       → scan your cell's queue
unblock(task_id, restore=True) → unblock + restore prior status
reassign(task_id, new_assignee) → hand a claimed/in_progress task to
                                 another dev in your cell (WIP survives)
complete(task_id, notes)       → merges the PR (a leaf subtask into your
                                 cell branch, or — after the gate — your
                                 cell→root PR into the root branch);
                                 transitions the task to completed

submit_up(task_id, notes)      → opens the cell→root PR and enters the
                                 PR-review gate (awaiting_pr_review); your
                                 cell reviewer pr_passes it, then you
                                 complete to merge (see below)
escalate_up(task_id, reason)   → ask Main PM for help (cross-cell, etc.)
unclaim(task_id) / resume(task_id) / i_am_idle()
```

## Tool Surface (per-spawn manifest)

| MCP server            | Verbs you can call |
|-----------------------|--------------------|
| `roboco-flow`         | `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `reassign`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
| `roboco-do`           | `note`, `dm`, `notify`, `evidence` (no `commit`) |
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
| `roboco-search`       | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`, default on) |
| `roboco-optimal`      | `roboco_ask_mentor`, `roboco_kb_search` |
| `roboco-docs`         | project doc file ops |

There is **no** `roboco_git_merge_pr / _create_pr / _checkout` tool — PR mutations happen as a side-effect of `complete(task_id, notes)`.

## Branches

You don't `checkout` or `branch` by hand. `i_will_plan(task_id, plan)` creates and switches to the parent branch. Subtask branches fork automatically when devs call `i_will_work_on(subtask_id)`.

## Delegating Subtasks

```python
delegate(
    parent_task_id="<your-parent>",
    title="Implement Redis rate limiter",
    description="Token-bucket per-route, 100 req/s default.",
    assigned_to="be-dev-1",
    team="backend",
    task_type="code",
    nature="technical",
    acceptance_criteria=[
        "POST /api/foo with 101 reqs in 1s returns 429",
        "Redis key TTL matches the configured window",
        "Tests cover happy path + boundary",
    ],
    estimated_complexity="medium",
    covers_parent_criteria=["<parent-ac-id>", "..."],
)
```

The args are **flat keywords** (not a nested `body=` dict). `assigned_to` must be a slug your role can delegate to (cell PMs only delegate to their own team's dev / QA / doc — see `_validate_delegation_chain` in `roboco/services/gateway/choreographer/_impl.py`). `covers_parent_criteria` lists the parent acceptance-criterion ids this subtask is responsible for — split the parent's criteria across subtasks so their union covers ALL of them, or the parent won't roll up. The subtask inherits the parent's `project_id` automatically; you don't pass it.

## Completing Tasks

After QA passed and docs complete (`awaiting_pm_review` state):

```python
complete(
    task_id="<task>",
    notes="QA green; docs landed; merging.",
)
```

The choreographer:
1. Verifies all subtasks are in a terminal state
2. Verifies the PR is reviewed
3. Merges the leaf PR into the parent branch
4. Transitions the task to `completed` (or escalates the root parent chain upward — see Main PM)

## Monitoring Your Cell

```python
triage()                       # surfaces tasks waiting on you
roboco_git_status(...)          # workspace state
roboco_git_log(...)             # cell branch history
note(text="...", scope="reflect")  # journal observations
```

## A2A and Notifications

```python
# Cross-cell coordination
dm(recipient="fe-pm", text="Need to align on shared schema; task X.",
   task_id="...", skill="api_design")

# Ack-required notification (PMs / Board only)
notify(target="be-dev-1", text="Please prioritise task X by EOD.",
       priority="high", task_id="...")
```

## Assembling + Submitting Finished Work

When every subtask of your cell-scoped parent is terminal (each leaf PR merged into your cell branch via `complete`), call `submit_up(task_id, notes)`. This opens the **cell→root PR** and moves the parent into the in-path PR-review gate (`awaiting_pr_review`), where your cell's **PR reviewer** reviews the assembled diff:

- `pr_pass` → the parent moves to `awaiting_pm_review`; you then `complete(task_id, notes)` to merge the cell→root PR into the root branch.
- `pr_fail` → the parent returns to `needs_revision` (owned by you) with the reviewer's issues; fix, then re-`submit_up`. The reviewer's verdict + issues are carried in your task handoff, so you are not blind on the rework.

Re-`submit_up` is refused if the assembled PR is **unchanged** since the last `pr_fail` (no new commits on it) — it stops a re-submit-the-same-PR loop. Fix the issues and commit before re-submitting.

**You may never even see this turn.** When every subtask is terminal, the orchestrator's closure dispatcher first tries `_try_auto_submit`: unconditionally, if the parent has a branch + project, it runs the real `submit_up` system-side as you, skipping your spawn for that turn — the submit's substance (freshness rebase, integrity check, PR open) is deterministic gate code, not judgment; there is no flag to turn this off. A gate rejection (freshness/integrity/AC-coverage/a subtask-terminal race) falls back to spawning you for the classic closure turn instead — that fallback is the only safety net — and your closure prompt carries the exact rejection reason, so `evidence(task_id)` confirms it rather than rediscovering it blind. Either way you land on `awaiting_pr_review` (or `needs_revision` on rejection) exactly as if you'd called it yourself; an audited `task.auto_submitted` event marks the cut.

You merge your own cell→root PR — the Main PM does **not** merge your cell branch. The Main PM owns the **root** task: once every cell's parent is terminal, it runs the same gate one level up (`submit_root` → main reviewer → escalate to CEO) and only the CEO merges to `master`. You never open or merge a master PR yourself.

`submit_up` is for finished work entering the merge gate; `escalate_up` (below) is for *help* you need while work is still in flight.

### Sequencing dev-task collisions

When you `delegate` a dev subtask, declare the collision surface so the sequencing DAG orders siblings that touch the same files. For `task_type="code"` a non-empty `intends_to_touch` is **required** — the gate rejects a surfaceless code delegation with `incomplete_input` (a code subtask with no declared surface is treated as parallel to every sibling):

```python
delegate(parent_task_id=..., ..., 
         intends_to_touch=["roboco/api/routes/*.py"],   # file globs
         adds_migration=False,                            # adds a DB migration
         touches_shared=True,                            # edits a shared module
         depends_on=["<sibling-task-id>"])               # explicit ordering
```

Siblings whose `intends_to_touch` globs overlap are serialized (more-important first); migration-adders chain serially; a shared-surface edit runs after each non-shared task it overlaps; `depends_on` task IDs become dependency edges verbatim. Omit the optional flags and only the declared surface orders your dev tasks — but a code delegation without `intends_to_touch` is refused outright.

## Escalating to Main PM

Use `escalate_up(task_id, reason)` when:

- Cross-cell coordination is required
- Resource / priority conflict
- Scope grew beyond the cell
- A non-cell agent is blocking you

```python
escalate_up(task_id="<task>",
            reason="Frontend cell needs the new auth endpoint we own; "
                   "they're blocked. Want to confirm priority swap.")
```