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>

docs/rag/roles/qa.md

@@ -18,7 +18,7 @@
 
 - Pull awaiting-QA tasks via `give_me_work()` / `claim_review(task_id)`
 - Pass via `pass(task_id, notes)` (transitions to `awaiting_documentation`)
-- Fail via `fail(task_id, issues)` (returns to `needs_revision`)
+- Fail via `fail(task_id, findings=[{file?, line?, severity, criterion?, expected, actual, fix?, evidence?}])` (returns to `needs_revision`) — see "Failing QA" below. The old `issues=[...]` (plain strings) form still works this release but is deprecated.
 - Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`
 - Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
 - Note evidence via `note(text=..., scope="...")` and `evidence(...)`
@@ -40,7 +40,7 @@ give_me_work()                     → returns an awaiting_qa task
 claim_review(task_id)              → claim for review
                                      (auto-checks-out the dev's branch)
 pass(task_id, notes)               → moves to awaiting_documentation
-fail(task_id, issues=[...])        → moves to needs_revision; the dev's
+fail(task_id, findings=[...])      → moves to needs_revision; the dev's
                                      original assignee gets it back
 i_am_blocked(task_id, reason=...)  → external blocker (broken env, can't
                                      reproduce); Cell PM unblocks
@@ -90,21 +90,36 @@ Your pass/fail note is a mandatory structured note (a QaNote) carrying substanti
 
 ## Conventions in Review Evidence
 
-When the architectural-conventions standard is enabled, the evidence returned on `claim_review` includes `convention_findings` for the work under review — surface them in your verdict alongside the acceptance-criteria check.
+When the architectural-conventions standard is enabled, the evidence returned on `claim_review` includes `convention_findings` for the work under review — surface them in your verdict alongside the acceptance-criteria check. `convention_findings` (architectural-standard violations) and the revision-findings ledger below (QA/PR-gate/PM/CEO bounce feedback) are two distinct concepts that can both be present at once — don't conflate them.
+
+On a round ≥2 review (a task that has bounced before), `claim_review` also carries `prior_findings` — the FULL revision-findings ledger for this task, every round, newest first. Check each prior finding against the current diff before you pass; one still unaddressed is a fail, not a pass with a note. See `docs/rag/architecture/review-findings.md`.
 
 ## Failing QA
 
 ```python
 fail(
     task_id="<task>",
-    issues=[
-        "Bug: 100th request also returns 429 — boundary off-by-one.",
-        "Missing: tests for Redis-down failover path; AC #3 unmet.",
+    findings=[
+        {
+            "file": "roboco/api/routes/rate_limit.py",
+            "line": 88,
+            "severity": "blocker",
+            "criterion": "429 fires at the 101st request",
+            "expected": "429 on the 101st request in the window",
+            "actual": "the 100th request also returns 429 — boundary off-by-one",
+            "fix": "use > not >= when comparing against the window limit",
+        },
+        {
+            "severity": "major",
+            "criterion": "AC #3 — Redis-down failover path",
+            "expected": "a test covering the Redis-down failover path",
+            "actual": "no such test exists in this diff",
+        },
     ],
 )
 ```
 
-The task goes back to `needs_revision`. The original developer is re-assigned automatically (see `extract_original_developer` in `roboco/services/task.py`).
+Each finding is validated and inserted onto the task's append-only `task_review_findings` ledger (`origin=qa`, `round=revision_count+1`), then rendered into `qa_notes` as `[F-xxxxxxxx] file:line (severity) — expected → actual → fix`. A soft nudge appears above 5 findings in one call, a hard reject above 10 — split or prioritize. The task goes back to `needs_revision`. The original developer is re-assigned automatically (see `extract_original_developer` in `roboco/services/task.py`) and receives the open findings inline via `evidence()`'s `revision_findings` and the respawn prompt. See `docs/rag/architecture/review-findings.md` for the full Finding shape and caps.
 
 ## Self-Review Prevention
 
@@ -121,4 +136,4 @@ dm(recipient="be-pm",
    task_id="...")
 ```
 
-For an external blocker (test environment broken, can't reproduce, missing infra), use `i_am_blocked(task_id, reason="...")` — your Cell PM is notified and `unblock`s you. If the work itself is wrong, `fail(task_id, issues)` with the full context is the right move; the Cell PM picks it up from `needs_revision`.
+For an external blocker (test environment broken, can't reproduce, missing infra), use `i_am_blocked(task_id, reason="...")` — your Cell PM is notified and `unblock`s you. If the work itself is wrong, `fail(task_id, findings=[...])` with the full context is the right move; the Cell PM picks it up from `needs_revision`.