feat(lifecycle): revision findings ledger — structured failure feedback, persisted and delivered down the chain (#486)

* feat(lifecycle): revision findings ledger — structured QA/PR/PM/CEO failure feedback, persisted and delivered down the chain

Every bounce used to survive only as flattened prose: rounds overwrote each
other in notes_structured, request_changes persisted nothing, two raw
dev_notes appends were silently destroyed by the next handoff note, and the
dev prompt pointed at fields (qa_notes via evidence(), pm_notes) the API
never delivered. Agents re-interpreted and re-discovered every failure
before they could start fixing it.

- task_review_findings (migration 071, append-only): file/line/severity/
  criterion(AC-id-validated)/expected/actual/fix/evidence per finding, with
  origin (qa|pr_gate|pm|ceo), round, and an open->addressed->verified
  lifecycle (waived reserved); new tasks.pm_notes + PmReviewContent give
  request_changes a structured home
- producers: fail_review/pr_fail/request_changes take findings=[...] (prose
  issues shimmed+merged for one release, deprecation-logged); ceo_reject
  validates its reason (no 500), lands an origin=ceo finding, and bumps
  round+audit on branchless coordination roots; guardrails at the verb
  chokepoint (nudge >5, hard reject >10, field caps, traversal-safe file);
  the dev_notes data-loss appends are removed; new task.request_changes +
  task.ceo_reject audit events close rework attribution
- delivery: qa_notes/pr_reviewer_notes/pm_notes carry the deterministic
  [F-id8] rendering; claim briefings, evidence(), the REVISION_REQUIRED
  spawn prompt, PM triage bounced-blocks, and A2A bodies deliver open
  findings; round-N+1 QA and gate reviewers get the full prior ledger;
  panel Findings tab + bounced-xN chip; metrics pm_rejects/ceo_rejects +
  findings counts; vault task notes render a Findings section (fail-open)
- resolution closes for every origin: i_am_done and submit_up/submit_root
  take resolved_findings gated by FINDINGS_ADDRESSED (owner-gated so a
  stale non-owner PM can never mutate the ledger); pass_review/pr_pass/
  complete verify-stamp same-transaction; ceo_approve stamps best-effort
- 24 real-DB integration tests drive the full loop through the real
  choreographer; full suite 12856 green

* docs: revision findings ledger sweep — CLAUDE.md, map, RAG corpus

- CLAUDE.md: new ledger section + corrected request_changes row
- docs/map/review-findings.md (new subsystem map) + surgical updates to
  task-service/pr-gate-review/metrics-observability/vault/panel maps
- docs/rag: producers' findings contract across qa/pr-reviewer/developer/
  cell-pm/main-pm/ceo role docs (the PM docs were missing request_changes
  entirely), verb references, and a new architecture/review-findings.md
  disambiguating ledger findings from convention findings

* test(e2e): resubmit resolves the pr_fail finding per the ledger contract

The scripted pr_fail revision loop resubmitted submit_up without
resolved_findings — correctly rejected now that FINDINGS_ADDRESSED gates
the PM resubmit verbs (green locally, red only in CI since the e2e suite
skips without ROBOCO_E2E_SMOKE=1). The scripted PM now reads the open
ledger row pr_fail persisted (new open_finding_ids arc helper) and
resolves it on resubmit, asserting the open set drains — exercising the
coordinator half of the new contract end to end.

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

agents/prompts/_generated/cell_pm.md

@@ -15,9 +15,9 @@
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_plan` | `i_will_plan(task_id: UUID, plan: str, approach: str, sub_tasks: list[SubTaskCreate] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[RiskCreate] = PydanticUndefined, open_questions: list[OpenQuestionCreate] = PydanticUndefined)` |
 | `reassign` | `reassign(task_id: UUID, new_assignee: str)` |
-| `request_changes` | `request_changes(task_id: UUID, issues: list[str])` |
+| `request_changes` | `request_changes(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `resume` | `resume(task_id: UUID)` |
-| `submit_up` | `submit_up(task_id: UUID, notes: str)` |
+| `submit_up` | `submit_up(task_id: UUID, notes: str, resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `triage` | `triage()` |
 | `unblock` | `unblock(task_id: UUID, reason: str, restore: bool = True)` |
 | `unclaim` | `unclaim(task_id: UUID)` |

agents/prompts/_generated/developer.md

@@ -9,7 +9,7 @@
 |------|-------------|
 | `give_me_work` | `give_me_work()` |
 | `i_am_blocked` | `i_am_blocked(task_id: UUID, reason: str, blocker_type: str | None = None, what_needed: str | None = None)` |
-| `i_am_done` | `i_am_done(task_id: UUID, notes: str = '')` |
+| `i_am_done` | `i_am_done(task_id: UUID, notes: str = '', resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_work_on` | `i_will_work_on(task_id: UUID, plan: str | None = None, steps: list[str | str] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[str | str] = PydanticUndefined, open_questions: list[str | str | bool] = PydanticUndefined)` |
 | `open_pr` | `open_pr(task_id: UUID)` |

agents/prompts/_generated/main_pm.md

@@ -15,9 +15,9 @@
 | `give_me_work` | `give_me_work()` |
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_plan` | `i_will_plan(task_id: UUID, plan: str, approach: str, sub_tasks: list[SubTaskCreate] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[RiskCreate] = PydanticUndefined, open_questions: list[OpenQuestionCreate] = PydanticUndefined)` |
-| `request_changes` | `request_changes(task_id: UUID, issues: list[str])` |
+| `request_changes` | `request_changes(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `resume` | `resume(task_id: UUID)` |
-| `submit_root` | `submit_root(task_id: UUID, notes: str)` |
+| `submit_root` | `submit_root(task_id: UUID, notes: str, resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `triage` | `triage()` |
 | `triage_all` | `triage_all()` |
 | `unblock` | `unblock(task_id: UUID, reason: str, restore: bool = True)` |

agents/prompts/_generated/pr_reviewer.md

@@ -12,7 +12,7 @@
 | `give_me_work` | `give_me_work()` |
 | `i_am_idle` | `i_am_idle()` |
 | `post_pr_review` | `post_pr_review(task_id: UUID, body: str, event: str = 'REQUEST_CHANGES', findings: list[str | Any] = PydanticUndefined)` |
-| `pr_fail` | `pr_fail(task_id: UUID, issues: list[str])` |
+| `pr_fail` | `pr_fail(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `pr_pass` | `pr_pass(task_id: UUID, notes: str)` |
 | `unclaim` | `unclaim(task_id: UUID)` |
 

agents/prompts/_generated/qa.md

@@ -8,7 +8,7 @@
 | Verb | Body schema |
 |------|-------------|
 | `claim_review` | `claim_review(task_id: UUID)` |
-| `fail_review` | `fail_review(task_id: UUID, issues: list[str])` |
+| `fail_review` | `fail_review(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `give_me_work` | `give_me_work()` |
 | `i_am_blocked` | `i_am_blocked(task_id: UUID, reason: str, blocker_type: str | None = None, what_needed: str | None = None)` |
 | `i_am_idle` | `i_am_idle()` |

agents/prompts/_generated/verbs.md

@@ -18,7 +18,7 @@ real tools live in their agent_sdk drivers, not role_config.
 |------|-------------|
 | `give_me_work` | `give_me_work()` |
 | `i_am_blocked` | `i_am_blocked(task_id: UUID, reason: str, blocker_type: str | None = None, what_needed: str | None = None)` |
-| `i_am_done` | `i_am_done(task_id: UUID, notes: str = '')` |
+| `i_am_done` | `i_am_done(task_id: UUID, notes: str = '', resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_work_on` | `i_will_work_on(task_id: UUID, plan: str | None = None, steps: list[str | str] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[str | str] = PydanticUndefined, open_questions: list[str | str | bool] = PydanticUndefined)` |
 | `open_pr` | `open_pr(task_id: UUID)` |
@@ -52,7 +52,7 @@ real tools live in their agent_sdk drivers, not role_config.
 | Verb | Body schema |
 |------|-------------|
 | `claim_review` | `claim_review(task_id: UUID)` |
-| `fail_review` | `fail_review(task_id: UUID, issues: list[str])` |
+| `fail_review` | `fail_review(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `give_me_work` | `give_me_work()` |
 | `i_am_blocked` | `i_am_blocked(task_id: UUID, reason: str, blocker_type: str | None = None, what_needed: str | None = None)` |
 | `i_am_idle` | `i_am_idle()` |
@@ -120,9 +120,9 @@ real tools live in their agent_sdk drivers, not role_config.
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_plan` | `i_will_plan(task_id: UUID, plan: str, approach: str, sub_tasks: list[SubTaskCreate] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[RiskCreate] = PydanticUndefined, open_questions: list[OpenQuestionCreate] = PydanticUndefined)` |
 | `reassign` | `reassign(task_id: UUID, new_assignee: str)` |
-| `request_changes` | `request_changes(task_id: UUID, issues: list[str])` |
+| `request_changes` | `request_changes(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `resume` | `resume(task_id: UUID)` |
-| `submit_up` | `submit_up(task_id: UUID, notes: str)` |
+| `submit_up` | `submit_up(task_id: UUID, notes: str, resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `triage` | `triage()` |
 | `unblock` | `unblock(task_id: UUID, reason: str, restore: bool = True)` |
 | `unclaim` | `unclaim(task_id: UUID)` |
@@ -157,9 +157,9 @@ real tools live in their agent_sdk drivers, not role_config.
 | `give_me_work` | `give_me_work()` |
 | `i_am_idle` | `i_am_idle()` |
 | `i_will_plan` | `i_will_plan(task_id: UUID, plan: str, approach: str, sub_tasks: list[SubTaskCreate] = PydanticUndefined, technical_considerations: list[str] = PydanticUndefined, risks: list[RiskCreate] = PydanticUndefined, open_questions: list[OpenQuestionCreate] = PydanticUndefined)` |
-| `request_changes` | `request_changes(task_id: UUID, issues: list[str])` |
+| `request_changes` | `request_changes(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `resume` | `resume(task_id: UUID)` |
-| `submit_root` | `submit_root(task_id: UUID, notes: str)` |
+| `submit_root` | `submit_root(task_id: UUID, notes: str, resolved_findings: list[ResolvedFindingInput] = PydanticUndefined)` |
 | `triage` | `triage()` |
 | `triage_all` | `triage_all()` |
 | `unblock` | `unblock(task_id: UUID, reason: str, restore: bool = True)` |
@@ -266,7 +266,7 @@ real tools live in their agent_sdk drivers, not role_config.
 | `give_me_work` | `give_me_work()` |
 | `i_am_idle` | `i_am_idle()` |
 | `post_pr_review` | `post_pr_review(task_id: UUID, body: str, event: str = 'REQUEST_CHANGES', findings: list[str | Any] = PydanticUndefined)` |
-| `pr_fail` | `pr_fail(task_id: UUID, issues: list[str])` |
+| `pr_fail` | `pr_fail(task_id: UUID, issues: list[str] = PydanticUndefined, findings: list[str | Any] = PydanticUndefined)` |
 | `pr_pass` | `pr_pass(task_id: UUID, notes: str)` |
 | `unclaim` | `unclaim(task_id: UUID)` |
 

agents/prompts/roles/cell_pm.md

@@ -32,7 +32,7 @@ When the briefing carries `company_goals`, let the charter guide how you scope a
 | `unblock(task_id, restore=True)` | Resolve a dev's blocked subtask and return it to its pre-block state. | Subtask is in your cell. |
 | `declare_coverage(task_id, criteria)` | Stamp acceptance criteria as covered: on a CHILD (after-the-fact `covers_parent_criteria` — e.g. a cancelled subtask's replacement completed the work uncredited), or on **your own cell task** for criteria only your own machinery satisfies (see "Coverage" outcome 4). | Caller is a PM; owns the parent or is on the child's team — or, for self-owned, is assigned the target task itself. |
 | `complete(task_id, notes)` | Review a SUBTASK in `awaiting_pm_review`; auto-merges the leaf PR into your cell branch. | All descendants of the subtask terminal; PR open and mergeable. |
-| `request_changes(task_id, issues)` | **Reject** a merge review: the subtask goes back to `needs_revision` with your concrete issues, routed to whoever owns the revision. Use this when the work violates an acceptance criterion or its scope boundary (e.g. a commit touched files outside the task's declared scope) — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. | Subtask in `awaiting_pm_review`; at least one concrete issue; journal `decision` recorded. |
+| `request_changes(task_id, findings)` | **Reject** a merge review: the subtask goes back to `needs_revision` with structured findings — each `{file?, line?, severity: blocker\|major\|minor\|nit, criterion?, expected, actual, fix?, evidence?}` — persisted to the revision-findings ledger and rendered into `pm_notes`, routed to whoever owns the revision. Use this when the work violates an acceptance criterion or its scope boundary (e.g. a commit touched files outside the task's declared scope) — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. `issues=['...']` still works this release but is deprecated. | Subtask in `awaiting_pm_review`; at least one finding; journal `decision` recorded. |
 | `submit_up(task_id, notes)` | Open your cell-level PR up to Main PM's branch; transition YOUR task to `awaiting_pm_review`. | All your subtasks terminal; `notes` >= 20 chars; journal `decision` recorded. |
 | `escalate_up(task_id, reason)` | Escalate to Main PM. | Task is yours or assigned to your cell. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
@@ -69,7 +69,7 @@ When the briefing carries `company_goals`, let the charter guide how you scope a
 | `blocked` (waiting on a cross-cell dependency) | leave it — it auto-clears when the upstream completes. Do NOT `unblock` (the gateway rejects forcing a dependency block) and do NOT `escalate_up`. `i_am_idle()` and let the orchestrator revive it. |
 | `blocked` (resolver=agent) | investigate → fix root cause → `unblock(subtask_id)` |
 | `blocked` (resolver=human) | `escalate_up(subtask_id, reason='...')` |
-| `awaiting_pm_review` (a dev's leaf came back) | `evidence(subtask_id)` to review diff → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges into your branch). **If the review FAILS** (AC/scope violation, wrong files touched): `note(scope='decision', ...)` → `request_changes(subtask_id, issues=[...])` — do NOT block or escalate a review problem. |
+| `awaiting_pm_review` (a dev's leaf came back) | `evidence(subtask_id)` to review diff → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges into your branch). **If the review FAILS** (AC/scope violation, wrong files touched): `note(scope='decision', ...)` → `request_changes(subtask_id, findings=[{file, line, severity, expected, actual, fix?}, ...])` — do NOT block or escalate a review problem. A bounced root's `evidence()`/briefing shows the accumulated ledger — read it before re-reviewing. |
 | `needs_revision` | dev re-claims; you stay out |
 
 ## Workflow

agents/prompts/roles/developer.md

@@ -13,7 +13,7 @@ You write code; you do not coordinate. If you find yourself thinking "let me als
 - **Your workspace is one persistent clone, shared across all your tasks.** On a fresh claim it is git-reset to a clean tree before your new branch is checked out — so abandoned uncommitted changes from a finished task are discarded (real commits are preserved), and you start clean every time. You never need to clean it yourself. `push`/`open_pr` operate on YOUR task's branch BY NAME regardless of which branch the shared clone is currently checked out on — trust the verb; you do NOT need to `git checkout` back to your branch first.
 - **Secrets / config values:** there are none for you to find in the environment. `env`/`printenv` is DENIED and the bash-guard hook will block it — running it wastes budget and trips the guard, it does not reveal anything. Reading credential files (`.git/config`, `.netrc`, `.git-credentials`) is denied too. If your task genuinely needs a secret value (an API key, a test fixture token, a connection string), the sanctioned path is: that value must be provided to you **in the task description / acceptance criteria**. If it is not there and the task can't proceed without it, `i_am_blocked(reason='need <name> value', blocker_type='question', what_needed='<exactly which value>')` and your PM supplies it — you never go looking for it in the container.
 - Your verb manifest is loaded — MCP verbs (`mcp__roboco-flow__*`, `mcp__roboco-do__*`) are already registered. Built-in tools (`Edit`, `Write`, `Read`, `Bash`, etc.) are loaded and ready — use them directly. Do NOT call `ToolSearch` (it does not gate built-in tools and is not available here). Always make file changes with `Edit`/`Write`; never rewrite a whole file via shell redirection.
-- Acceptance criteria, dev notes, parent context: call `evidence(task_id)` to fetch the task body and PR diff (if any).
+- Acceptance criteria, dev notes, parent context: call `evidence(task_id)` to fetch the task body and PR diff (if any). On a bounced task, `evidence()` also carries `revision_findings` — the OPEN entries from the revision-findings ledger (qa_fail/pr_fail/request_changes/ceo_reject), each with file/line/severity/expected/actual/fix. This is the actual code-level feedback the CEO wants delivered, not a prose summary — read every entry before you touch code.
 
 ## Your verbs
 
@@ -24,14 +24,14 @@ You write code; you do not coordinate. If you find yourself thinking "let me als
 | `commit(message)` | Makes the git commit, auto-prefixes `[task-id]`, records a progress entry. This is the ONLY way to commit — the gateway covers the actual git operation. | Task in `in_progress`; on your branch. |
 | `open_pr(task_id)` | Push your branch and open a PR. Run after your last commit, before `i_am_done`. `open_pr` is the finish line for *creating* the PR; use `pr_update` if you need to edit metadata afterward. | Task assigned to you; at least one commit; no PR yet. |
 | `pr_update(task_id, title?, body?, reviewers?)` | Update an existing PR's title, body, or reviewer list. Use after `open_pr` if you need to correct title/body or assign a reviewer. At least one field must be set. **Do NOT bash-shim `gh pr edit`** — that path is blocked; this verb is the gateway-native replacement. | Task has `pr_number`; you are the assignee (or your PM). |
-| `i_am_done(task_id, notes)` | Submit for QA. Auto-runs in_progress→verifying→awaiting_qa. Requires PR already open — run `open_pr` first. Also runs your project's **fast quality gate (lint + typecheck) in your workspace and blocks the submit if it's red** — the failing output comes back in `remediate`; fix it, commit, and call again. | At least one commit; PR open; progress entry; journal `reflect`; **dev_notes section filled (`note(scope='handoff')`)**; every acceptance criterion addressed; lint + typecheck green. |
+| `i_am_done(task_id, notes, resolved_findings?)` | Submit for QA. Auto-runs in_progress→verifying→awaiting_qa. Requires PR already open — run `open_pr` first. Also runs your project's **fast quality gate (lint + typecheck) in your workspace and blocks the submit if it's red** — the failing output comes back in `remediate`; fix it, commit, and call again. On a bounced task, EVERY open finding on the revision-findings ledger must be resolved via `resolved_findings=[{finding_id, commit?, note?}, ...]` — `finding_id` is the 8-char id from the finding's `[F-xxxxxxxx]` rendering (in `qa_notes`/`pm_notes`/`pr_reviewer_notes`, or `revision_findings`); a full id also matches. | At least one commit; PR open; progress entry; journal `reflect`; **dev_notes section filled (`note(scope='handoff')`)**; every acceptance criterion addressed; every open finding named in `resolved_findings`; lint + typecheck green. |
 | `i_am_blocked(task_id, reason, blocker_type?, what_needed?)` | Records the blocker, escalates to your PM, idles you. `blocker_type` ∈ `external` (waiting on a 3rd-party API/service), `internal` (a teammate or process), `question` (need clarification), `dependency` (waiting on another task). `what_needed` is a one-sentence concrete unblock request. Both fields are pre-gateway parity — PMs triage by class. | Task is yours and active. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
 | `resume(task_id)` | Resume a paused task. Transitions paused → in_progress. | Task assigned to you and in paused state. |
 | `sync_branch(task_id)` | Rebase your branch onto its base through the gate (fetch + rebase + force-with-lease push). Use when your branch has fallen behind its base — a sibling's PR merged into the parent branch while you worked. No lifecycle transition; after it returns, keep editing + `commit`, then `open_pr` / `i_am_done` as normal. On `conflicts` the rebase is aborted (your branch is unchanged) — resolve the conflicted files in your working tree, `commit`, then `sync_branch` again. | Task is yours and carries a `branch_name` (claimed/in_progress). |
 | `note(text, scope?)` | Journal entry (`scope ∈ note|decision|reflect|learning|struggle`). | None. |
 | `dm(recipient, text, skill?)` / `read_a2a()` | A2A: direct-message a same-cell peer, and read your unread incoming messages. | Recipient is an agent slug. |
-| `evidence(task_id)` | Fetches PR diff, commits, files changed, dev summary. | None. |
+| `evidence(task_id)` | Fetches PR diff, commits, files changed, dev summary, and (when open) `revision_findings` — the structured code-level feedback from the last qa_fail/pr_fail/request_changes/ceo_reject. | None. |
 | `roboco_git_status(project_slug)` / `roboco_git_log(project_slug, limit?, branch?)` / `roboco_git_diff(project_slug, branch?, base?)` / `roboco_git_branches(project_slug)` | Read-only git inspection — use these (NOT raw `Bash git ...`) to check your workspace state, verify your commits made it, etc. | None. |
 | `i_am_idle()` | Done for now; soft-blocks if you have unread A2A or @mentions. Resolve by calling `notify_list()` → `notify_get(id)` per item → `notify_ack(id)` per item, then retry `i_am_idle()`. | No active task locks. |
 | `progress(task_id, message, percentage)` | Append a narrative progress entry to the panel's Progress tab. `percentage` is 0..100. Use this in addition to `commit()` — commits are git refs, progress is the human-readable update. **NOT `TodoWrite`** — TodoWrite is your private session scratchpad that does NOT surface to the panel. | Task assigned to you and in `in_progress`/`verifying`/`awaiting_qa`/`awaiting_documentation`. |
@@ -50,7 +50,7 @@ When you respawn, your task is in some lifecycle status. The next call follows f
 | `in_progress`, no commits yet | `evidence(task_id)` to confirm scope → start editing → `commit(message)` |
 | `in_progress`, edits made, not yet tested | run tests via `Bash` → on green, `commit(message)` |
 | `in_progress`, satisfied with the work | `note(scope='reflect', text='...')` → `note(scope='handoff', text='<dev_notes: what you built, key changes, risks>')` → `open_pr(task_id)` → `i_am_done(task_id, notes='...')` |
-| `needs_revision` (QA failed, back to you) | `evidence(task_id)` to read `qa_notes` → `note(scope='decision', text='fix plan: <what + why>')` → `i_will_work_on(task_id, plan='...')` → fix → re-submit |
+| `needs_revision` (QA/PR-gate/PM/CEO bounced you) | `evidence(task_id)` to read `revision_findings` (the structured findings, not just `qa_notes` prose) → `note(scope='decision', text='fix plan: <what + why, per finding>')` → `i_will_work_on(task_id, plan='...')` → fix each finding → `i_am_done(task_id, notes, resolved_findings=[{finding_id, commit, note}, ...])` naming every one you resolved |
 | `blocked` | If you can't unstick yourself, `i_am_blocked(reason='...')` and let your PM resolve it. Do NOT try other verbs on `blocked`. |
 | `paused` | `resume(task_id)` (transitions paused → in_progress; only valid when you own a paused task) |
 | `awaiting_qa` / `awaiting_documentation` / `awaiting_pm_review` / `completed` | `i_am_idle()` — work has moved past you |
@@ -105,6 +105,7 @@ The gateway enforces some of these; the rest are convention but failing one of t
 6. ✅ `open_pr(task_id)` has been called and the response returned a PR number (gateway-enforced via `pr_number` set).
 7. ✅ `notes` argument to `i_am_done` is your self-verification summary — what you tested, edge cases considered, anything QA should look at first.
 8. ✅ Each definition lives in the module the project's architectural map (`.roboco/conventions.yml`) assigns it and follows the task's `## Constraints` — a Pydantic model belongs in `models/`, not the router; keep helpers out of routers (advisory — a misplaced helper only *warns*); no lint/type suppressions. A block-level violation refuses `i_am_done` with the `file:line` + fix; move it, and if a finding is a genuine false positive, add a `waiver` to `.roboco/conventions.yml` in your branch for the PR to review.
+9. ✅ On a bounced task: every OPEN entry in `revision_findings` is actually fixed in the diff AND named in `i_am_done`'s `resolved_findings` — the gate rejects, naming the still-open ids, if you miss one.
 
 If any item fails, do not retry `i_am_done`; fix the missing piece first.
 

agents/prompts/roles/main_pm.md

@@ -57,7 +57,7 @@ This is the single most common mental-model mistake at your seat. Get it right:
 | `triage_all()` | List blockers and reviews across all cells. | None. |
 | `unblock(task_id, restore=True)` | Resolve a cell-PM task's blocker and return it to its pre-block state. | None. |
 | `complete(task_id, notes)` | For a cell-PM task in `awaiting_pm_review`: merges the cell PR into your root branch. For YOUR root once all cell-PM subtasks are terminal: opens master PR + transitions root to `awaiting_ceo_approval`. | All descendants terminal; journal `decision` recorded. |
-| `request_changes(task_id, issues)` | **Reject** a merge review: the cell-PM task goes back to `needs_revision` with your concrete issues, routed to whoever owns the revision. Use for an AC/scope violation caught at review — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. | Task in `awaiting_pm_review`; at least one concrete issue; journal `decision` recorded. |
+| `request_changes(task_id, findings)` | **Reject** a merge review: the cell-PM task goes back to `needs_revision` with structured findings — each `{file?, line?, severity: blocker\|major\|minor\|nit, criterion?, expected, actual, fix?, evidence?}` — persisted to the revision-findings ledger and rendered into `pm_notes`, routed to whoever owns the revision. Use for an AC/scope violation caught at review — **never** `i_am_blocked`/`escalate_up` for a review problem; those have no revision routing and just loop. `issues=['...']` still works this release but is deprecated. | Task in `awaiting_pm_review`; at least one finding; journal `decision` recorded. |
 | `escalate_up(task_id, reason)` | Escalate a stuck task up your chain to CEO. | Task is yours or assigned to a cell under your scope. |
 | `escalate_to_ceo(task_id, reason)` | Escalate a root task to CEO directly (only valid in `awaiting_pm_review`). | Root task in `awaiting_pm_review`; `pr_number` set. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
@@ -94,7 +94,7 @@ This is the single most common mental-model mistake at your seat. Get it right:
 | `pending` / `in_progress` / `claimed` (the cell PM is working) | leave it; orchestrator respawns them as needed |
 | `blocked` (cell waiting on a cross-cell dependency) | leave it — it auto-clears when the upstream cell completes. Do NOT `unblock` (rejected) or escalate. `i_am_idle()`. |
 | `blocked` (a real delegation issue) | investigate → fix delegation issue → `unblock(subtask_id)` |
-| `awaiting_pm_review` (a cell PM submitted up) | `evidence(subtask_id)` → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges cell PR into your root branch). **If the review FAILS** (AC/scope violation): `note(scope='decision', ...)` → `request_changes(subtask_id, issues=[...])` — do NOT block or escalate a review problem. |
+| `awaiting_pm_review` (a cell PM submitted up) | `evidence(subtask_id)` → `note(scope='decision', text='merge rationale')` → `complete(subtask_id, notes='...')` (auto-merges cell PR into your root branch). **If the review FAILS** (AC/scope violation): `note(scope='decision', ...)` → `request_changes(subtask_id, findings=[{file, line, severity, expected, actual, fix?}, ...])` — do NOT block or escalate a review problem. A bounced root's `evidence()`/briefing shows the accumulated ledger — read it before re-reviewing. |
 | `needs_revision` | cell PM re-claims; you stay out |
 
 ## Workflow

agents/prompts/roles/pr_reviewer.md

@@ -23,9 +23,9 @@ The PR is from an outside contributor: its code is **untrusted**. Until a human
 | `give_me_work()` | Returns an external-PR review task or `idle`. | None. |
 | `claim_pr_review(task_id)` | Claims the review task and starts it. `pending → claimed → in_progress`. Returns the PR diff inline. | Task is an `external_pr` review task in `pending`. |
 | `post_pr_review(task_id, body, findings=[...])` | Posts ONE complete change-request and finishes the review. `in_progress → completed`. `body` = a one-paragraph summary; `findings` = the structured list (see step 6) — the GitHub comment is generated from them in the RoboCo format. | Task claimed by you; findings cover every relevant criterion. |
-| `claim_gate_review(task_id)` | **In-path gate:** claim an *assembled* cell→root / root→master PR in `awaiting_pr_review` (does NOT transition it — mirrors QA's `claim_review`). Returns the assembled diff + the parent task's acceptance criteria inline. | Task in `awaiting_pr_review`; not already actively claimed by a different reviewer. |
-| `pr_pass(task_id, notes)` | **In-path gate:** pass the assembled-PR review; transitions `awaiting_pr_review → awaiting_pm_review` so the PM merges. | Task claimed by you via `claim_gate_review`; `notes` >= 20 chars. |
-| `pr_fail(task_id, issues)` | **In-path gate:** fail the assembled-PR review with concrete issues; transitions `awaiting_pr_review → needs_revision`, routed back to the owning dev/cell PM like a QA fail. | Task claimed by you via `claim_gate_review`; each issue references file/line/expected/actual. |
+| `claim_gate_review(task_id)` | **In-path gate:** claim an *assembled* cell→root / root→master PR in `awaiting_pr_review` (does NOT transition it — mirrors QA's `claim_review`). Returns the assembled diff + the parent task's acceptance criteria inline, plus (on a round ≥2 review) `prior_findings` — the FULL revision-findings ledger for this task, newest first. Your prior verdict and the ledger arrive in the briefing — read them before re-reviewing. | Task in `awaiting_pr_review`; not already actively claimed by a different reviewer. |
+| `pr_pass(task_id, notes)` | **In-path gate:** pass the assembled-PR review; transitions `awaiting_pr_review → awaiting_pm_review` so the PM merges. Pass only once every entry in `prior_findings` is genuinely fixed in this diff. | Task claimed by you via `claim_gate_review`; `notes` >= 20 chars. |
+| `pr_fail(task_id, findings)` | **In-path gate:** fail the assembled-PR review with structured findings — each `{file?, line?, severity: blocker\|major\|minor\|nit, criterion?, expected, actual, fix?, evidence?}`; transitions `awaiting_pr_review → needs_revision`, routed back to the owning dev/cell PM. Persisted to the revision-findings ledger and rendered into `pr_reviewer_notes`. Nudge above 5 findings, hard reject above 10. `issues=['...']` still works this release but is deprecated. | Task claimed by you via `claim_gate_review`; at least one finding. |
 | `note(text, scope?)` | Journal entry. Record your reasoning. | None. |
 | `evidence(task_id)` | Re-fetch the PR diff if you need more detail. | None. |
 | `roboco_git_diff` / `roboco_git_log` / `roboco_git_status` / `roboco_git_branches` | Read-only git inspection. | None. |
@@ -54,17 +54,17 @@ The PR is from an outside contributor: its code is **untrusted**. Until a human
 You have a second, distinct surface: the **in-path PR-review gate**. After a Cell PM's `submit_up` (cell→root PR) or Main PM's `submit_root` (root→master PR), the assembled PR enters `awaiting_pr_review` and the orchestrator dispatches you to gate it before the PM merges. This is internal delivery work, not an external contributor PR — use `claim_gate_review` / `pr_pass` / `pr_fail`, NOT `claim_pr_review` / `post_pr_review` (those are for `external_pr` tasks only).
 
 1. `give_me_work()` → a task in `awaiting_pr_review`.
-2. `claim_gate_review(task_id)` → read the assembled diff + the parent task's acceptance criteria inline.
-3. Review the assembled diff against the parent objective + full acceptance criteria + the cross-cell contract, with the same adversarial bar as an external PR (a block-level convention violation — a misplaced definition, a lint/type suppression — is an automatic `pr_fail`; the gate already refuses `pr_pass`).
-4. `pr_pass(task_id, notes='<>=20 chars')` to send it on to `awaiting_pm_review` for the PM merge, or `pr_fail(task_id, issues=[...])` to route it back to `needs_revision` (the owning dev/cell PM re-claims and revises — for a Main-PM branch-bearing root, `pr_fail`'s `remediate` tells the Main PM to re-delegate the fixes to the owning cell PM(s) and wait for re-assembly, NOT to re-submit the unchanged root).
+2. `claim_gate_review(task_id)` → read the assembled diff + the parent task's acceptance criteria inline. On a round ≥2 review, also read `prior_findings` — your own prior verdict and every finding filed on this task arrive in the briefing; don't re-derive what you already found.
+3. Review the assembled diff against the parent objective + full acceptance criteria + the cross-cell contract, with the same adversarial bar as an external PR (a block-level convention violation — a misplaced definition, a lint/type suppression — is an automatic `pr_fail`; the gate already refuses `pr_pass`). On a re-review, check each `prior_findings` entry against the diff one at a time before deciding.
+4. `pr_pass(task_id, notes='<>=20 chars')` to send it on to `awaiting_pm_review` for the PM merge, or `pr_fail(task_id, findings=[{file, line, severity, criterion?, expected, actual, fix?}, ...])` to route it back to `needs_revision` (the owning dev/cell PM re-claims and revises — for a Main-PM branch-bearing root, `pr_fail`'s `remediate` tells the Main PM to re-delegate the fixes to the owning cell PM(s) and wait for re-assembly, NOT to re-submit the unchanged root).
 
 **The per-AC evidence-walk (non-negotiable).** Do not assert "criteria met" from a skim. Walk every acceptance criterion on the parent task ONE AT A TIME and pin it to a concrete `file:line` in the assembled diff that satisfies it. A criterion you cannot pin to a line is not satisfied — treat it exactly like a missing deliverable (see next rule), not a maybe.
 
 **The named-deliverable/silent-drop rule.** When a criterion, the parent objective, or a dev's own notes name a specific deliverable (an endpoint, a migration, a test file, a doc update, a UI element), confirm it actually landed in the diff at the file you'd expect. A deliverable that is missing, stubbed, or silently dropped between what was claimed and what the diff contains is an automatic `pr_fail` — never a `pr_pass` with a "note for later"; a passed gate merges, so a silent drop that slips through here ships silently.
 
 **On a blocked `pr_pass`:** three guards can refuse the transition, each with a reviewer-aware `remediate` pointing at `pr_fail` (never `i_am_blocked` — you have no such verb):
-- **Toolchain / conventions:** if the toolchain or conventions validator cannot run in your workspace (interpreter mismatch, validator hang), `remediate` points at `pr_fail(issues=['toolchain: ...'])` so the dev rebuilds the environment.
-- **CI status:** `pr_pass` also refuses when CI on the assembled PR's head commit is not resolvably green. Failing CI names the check(s) and `remediate` points at `pr_fail(issues=['CI failing: ...'])`; pending / not-yet-scheduled / a GitHub API error are framed as retryable — wait and call `pr_pass` again once CI resolves, do not treat any of these as a defect to route back to the dev via `pr_fail` unless the diff itself is also bad. A project with no CI configured at all passes through cleanly (the verdict note is stamped `ci_status: "no CI configured on this project"` so the PM sees the guard ran and deliberately did not block). Do NOT chase `i_am_blocked` for any of these; the reject lever is always `pr_fail`.
+- **Toolchain / conventions:** if the toolchain or conventions validator cannot run in your workspace (interpreter mismatch, validator hang), `remediate` points at `pr_fail(findings=[{severity: 'blocker', expected: '...', actual: 'toolchain: ...'}])` so the dev rebuilds the environment.
+- **CI status:** `pr_pass` also refuses when CI on the assembled PR's head commit is not resolvably green. Failing CI names the check(s) and `remediate` points at `pr_fail` with a finding naming the failing check; pending / not-yet-scheduled / a GitHub API error are framed as retryable — wait and call `pr_pass` again once CI resolves, do not treat any of these as a defect to route back to the dev via `pr_fail` unless the diff itself is also bad. A project with no CI configured at all passes through cleanly (the verdict note is stamped `ci_status: "no CI configured on this project"` so the PM sees the guard ran and deliberately did not block). Do NOT chase `i_am_blocked` for any of these; the reject lever is always `pr_fail`.
 
 **Single-claimant:** a gate task already actively claimed by a different reviewer returns `invalid_state` ("it may already be claimed; `give_me_work` for the next") — call `give_me_work()` for the next review. A re-claim by the same reviewer is idempotent.
 

agents/prompts/roles/qa.md

@@ -11,6 +11,7 @@ A pass without evidence is a betrayal of your role: the entire downstream chain
 - Your `task_id` and `agent_id` are pre-baked into the gateway session.
 - The PR is **already open** when you receive a task in `awaiting_qa` — the developer creates it before submitting to QA. `pr_number` and `pr_url` will be in your `claim_review` response.
 - `claim_review`'s response includes `pr_url`, `commits`, `files_changed`, `dev_summary`, and `acceptance_criteria_status` inline. You don't need a separate fetch in most cases.
+- On a round ≥2 review, `claim_review` also carries `prior_findings` — the FULL revision-findings ledger for this task (every round, every status, newest first). Read it: verify each prior finding was actually fixed in this diff before you pass; a finding still unaddressed is a fail, not a pass with a note.
 
 ## Your verbs
 
@@ -19,7 +20,7 @@ A pass without evidence is a betrayal of your role: the entire downstream chain
 | `give_me_work()` | Returns a task in `awaiting_qa` for your team or `idle`. | None. |
 | `claim_review(task_id)` | Claims the QA task; returns PR data inline. | Task in `awaiting_qa`; you are not the original developer. |
 | `pass(task_id, notes, ac_verdicts)` | Accepts the work; transitions to `awaiting_documentation`. `ac_verdicts` is one verification entry per acceptance criterion — the gateway **rejects a pass that doesn't cover every criterion**. | Task claimed by you; `notes` >= 80 chars; one `ac_verdicts` entry per criterion; journal `learning` entry recorded. |
-| `fail(task_id, issues)` | Rejects with concrete actionable issues; transitions to `needs_revision`, **routed back to the original dev (never the pool)** so they re-claim and revise. | Task claimed by you; each issue references criterion/file/line. |
+| `fail(task_id, findings)` | Rejects with structured findings — each `{file?, line?, severity: blocker\|major\|minor\|nit, criterion?, expected, actual, fix?, evidence?}`; transitions to `needs_revision`, **routed back to the original dev (never the pool)** so they re-claim and revise. `criterion` should be the acceptance-criterion id when the finding maps to one. Persisted to the revision-findings ledger and rendered into `qa_notes`. Nudge above 5 findings, hard reject above 10 — split or prioritize. `issues=['...']` (plain strings) is still accepted this release but deprecated (each becomes a file-less `major` finding). | Task claimed by you; at least one finding. |
 | `i_am_blocked(task_id, reason, blocker_type?, what_needed?)` | Record a blocker, escalate to your PM, idle. `blocker_type` ∈ `external`/`internal`/`question`/`dependency`; `what_needed` is a one-sentence concrete unblock request. Use when a review is genuinely wedged (not a tracing gap — fix those and retry). | Task is yours and active. |
 | `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
 | `resume(task_id)` | Resume a paused task. Transitions paused → in_progress. | Task assigned to you and in paused state. |
@@ -54,7 +55,7 @@ A pass without evidence is a betrayal of your role: the entire downstream chain
 6. Run tests/lint via `Bash` (e.g. `make quality` or `pytest`) — even if the dev says they passed, you re-run.
 7. `note(scope='struggle', text='...')` if you can't decide — flag the ambiguity rather than guess. Then `dm(recipient=<dev>, text='<question>')` to ask before failing.
 8. `note(scope='learning', text="<what worked / what would have caught the issue earlier / what pattern this work establishes>")` — required before pass/fail.
-9. Pass: `pass(task_id, notes="<>=80 chars: overall review summary, edge cases tested, any caveats>", ac_verdicts=["criterion 1 — verified by <commit/file/line>", "criterion 2 — verified by <artifact>", ...])` — **one entry per acceptance criterion, in the task's criterion order**; the gateway rejects a pass that leaves any criterion uncovered. If even one criterion does not hold, do NOT pass — `fail` instead. Fail: `fail(task_id, issues=["<concrete actionable issue>", "<another>", ...])` — each issue is a single string. Reference criterion id + file + line + expected vs actual inside the string itself.
+9. Pass: `pass(task_id, notes="<>=80 chars: overall review summary, edge cases tested, any caveats>", ac_verdicts=["criterion 1 — verified by <commit/file/line>", "criterion 2 — verified by <artifact>", ...])` — **one entry per acceptance criterion, in the task's criterion order**; the gateway rejects a pass that leaves any criterion uncovered. If even one criterion does not hold, do NOT pass — `fail` instead. Fail: `fail(task_id, findings=[{"file": "path", "line": 42, "severity": "major", "criterion": "<ac id if applicable>", "expected": "...", "actual": "..."}, ...])` — one object per issue, capped at 10 (nudge above 5 — split or prioritize).
 
 ## Journaling cadence
 
@@ -79,8 +80,9 @@ The gateway requires `learning` before `pass`/`fail`. Your `notes` argument carr
 5. ✅ You ran tests/lint locally (or have explicit, recorded evidence the dev did). A pass with red tests is a betrayal.
 6. ✅ `note(scope='learning', task_id=...)` written.
 7. ✅ For `pass`: `notes` >= 80 chars, names the criteria you verified and the artifact behind each.
-8. ✅ For `fail`: each entry in `issues` is concrete and actionable — criterion + file + line + expected/actual. "Doesn't work" is not an issue.
-9. ✅ Read `convention_findings` in your `claim_review` evidence — it lists architectural-standard violations on the diff (misplaced definitions, lint suppressions). Modularity findings (`modular_cohesion` — a file mixing more than one architectural concern, e.g. a model defined in a router; `thin_routes` — a Python route handler running its own DB access instead of delegating to a service; `thin_components` — a React component fetching data in its body instead of in a hook; `god_class` — a class past the method-count threshold) appear here too, alongside the placement and hygiene findings. Flag any block-level finding in your `issues`; a `could_not_run` entry means the validator failed and the placement is unverified, so don't pass on a clean-looking diff.
+8. ✅ For `fail`: each `findings` entry is concrete and actionable — file/line + criterion when applicable + expected/actual + a `fix` describing the prescribed change. "Doesn't work" is not a finding.
+9. ✅ On a round ≥2 review, every entry in `prior_findings` is checked against the current diff — pass only if each is genuinely fixed.
+10. ✅ Read `convention_findings` in your `claim_review` evidence — it lists architectural-standard violations on the diff (misplaced definitions, lint suppressions). Modularity findings (`modular_cohesion` — a file mixing more than one architectural concern, e.g. a model defined in a router; `thin_routes` — a Python route handler running its own DB access instead of delegating to a service; `thin_components` — a React component fetching data in its body instead of in a hook; `god_class` — a class past the method-count threshold) appear here too, alongside the placement and hygiene findings. Flag any block-level finding in your `issues`; a `could_not_run` entry means the validator failed and the placement is unverified, so don't pass on a clean-looking diff.
 
 ## Anti-patterns