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/tools/task-tools.md

@@ -13,7 +13,10 @@ i_will_work_on(task_id, plan="...")
                                 # checks out feature/{team}/{task-hierarchy}
 commit(message, files=None)     # content tool — repeat per change (auto-pushed)
 open_pr(task_id)                # pushes branch + opens the PR
-i_am_done(task_id, notes="")    # verifying -> awaiting_qa (PR must already be open)
+i_am_done(task_id, notes="", resolved_findings=None)
+                                # verifying -> awaiting_qa (PR must already be open);
+                                # on a bounced task, name every open ledger finding
+                                # via resolved_findings=[{finding_id, commit?, note?}]
 i_am_blocked(task_id, reason)   # external dependency; cell PM unblocks
 unclaim(task_id)                # release a claimed task back to the queue
 resume(task_id)                 # recover a paused task after compact/restart
@@ -28,12 +31,13 @@ There is no separate claim / start / pause verb — `i_will_work_on` composes cl
 give_me_work()                  # returns an awaiting_qa task
 claim_review(task_id)           # claim for review (auto-checks-out dev branch)
 pass_review(task_id, notes)     # awaiting_qa -> awaiting_documentation
-fail_review(task_id, issues=[...])
-                                # awaiting_qa -> needs_revision (dev gets it back)
+fail_review(task_id, findings=[{file?, line?, severity, criterion?, expected, actual, fix?, evidence?}])
+                                # awaiting_qa -> needs_revision (dev gets it back);
+                                # the deprecated issues=[str] shim still works this release
 unclaim(task_id) / resume(task_id) / i_am_idle()
 ```
 
-`notes` (on pass_review) and `issues` (on fail_review) must be substantive — the enforcement layer rejects empty or near-empty content. QA cannot review its own dev work (self-review guard rejects on `claim_review`).
+`notes` (on pass_review) and each `findings` entry (on fail_review) must be substantive — the enforcement layer rejects empty or near-empty content. QA cannot review its own dev work (self-review guard rejects on `claim_review`). Every `fail_review` finding is persisted to the append-only revision-findings ledger and rendered into `qa_notes`; a soft nudge fires above 5 findings, a hard reject above 10. On a round ≥2 review, `claim_review` also returns `prior_findings` (the full ledger) so you check what was filed before. See `docs/rag/architecture/review-findings.md`.
 
 ## Documenter flow
 
@@ -62,10 +66,16 @@ reassign(task_id, assigned_to)  # move a subtask to a different agent
 unblock(task_id, reason)        # blocked -> in_progress (PM only); reason is
                                 # recorded as your journal:decision (no separate
                                 # note needed)
-submit_up(task_id, notes)       # open cell->root PR; -> awaiting_pr_review
+submit_up(task_id, notes, resolved_findings=None)
+                                # open cell->root PR; -> awaiting_pr_review
                                 # (the cell PR reviewer gates it; after pr_pass
-                                #  the same Cell PM completes + merges)
+                                #  the same Cell PM completes + merges); a re-submit
+                                # after pr_fail must resolve every open finding first
 complete(task_id, notes)        # awaiting_pm_review -> completed (merges leaf PR)
+request_changes(task_id, findings=[...])
+                                # reject a subtask's merge review -> needs_revision,
+                                # routed to whoever owns the revision; structured
+                                # findings persist to the ledger + render into pm_notes
 escalate_up(task_id, reason)    # escalate to your escalation target
 ```
 
@@ -75,13 +85,15 @@ After `i_will_plan` and each `delegate`, the envelope includes a coverage view o
 
 ## Main PM flow
 
-The Main PM shares most Cell PM verbs (`i_will_plan`, `delegate`, `complete`, `unblock`, `triage`, `escalate_up`), **adds** the verbs below, and — unlike a Cell PM — has **no** `submit_up` or `reassign`. Its bubble-up verb is `submit_root` (the root analogue of the Cell PM's `submit_up`):
+The Main PM shares most Cell PM verbs (`i_will_plan`, `delegate`, `complete`, `request_changes`, `unblock`, `triage`, `escalate_up`), **adds** the verbs below, and — unlike a Cell PM — has **no** `submit_up` or `reassign`. Its bubble-up verb is `submit_root` (the root analogue of the Cell PM's `submit_up`):
 
 ```python
 triage_all()                    # list actionable tasks across all teams
-submit_root(task_id, notes)     # open root->master PR; -> awaiting_pr_review
+submit_root(task_id, notes, resolved_findings=None)
+                                # open root->master PR; -> awaiting_pr_review
                                 # (the main PR reviewer gates it; after pr_pass,
-                                #  complete escalates to the CEO)
+                                #  complete escalates to the CEO); a re-submit
+                                # after pr_fail must resolve every open finding first
 escalate_to_ceo(task_id, reason)
                                 # awaiting_pm_review -> awaiting_ceo_approval
 give_me_work()                  # Main PM may also pull work directly
@@ -125,9 +137,12 @@ The PR Reviewer reviews inbound external/fork (and, behind a flag, internal) PRs
 The same role also runs the **in-path PR-review gate** on the org's own assembled delivery PRs — the merge-level review before the PM merges:
 
 ```python
-claim_gate_review(task_id)      # claim an awaiting_pr_review task; returns the assembled diff
+claim_gate_review(task_id)      # claim an awaiting_pr_review task; returns the assembled
+                                # diff + (on round >=2) prior_findings, the full ledger
 pr_pass(task_id, notes)         # assembled PR is correct -> awaiting_pm_review (the PM merges)
-pr_fail(task_id, issues)        # send it back -> needs_revision, like a QA fail
+pr_fail(task_id, findings=[...])
+                                # send it back -> needs_revision, like a QA fail;
+                                # the deprecated issues=[str] shim still works this release
 ```
 
 Both verdicts are also posted on the assembled PR itself as a GitHub review (server-side, bot account) so the decision is visible on the PR the PM merges: `pr_pass` → APPROVE, `pr_fail` → REQUEST_CHANGES — except the root→master PR, which only ever gets a plain COMMENT (only the CEO acts on `master`).