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>

tests/unit/services/test_task.py

@@ -34,6 +34,7 @@ from roboco.services.task import (
     VIDEO_SOURCE,
     GatewayAgentView,
     TaskService,
+    _ceo_reject_finding_texts,
     get_task_service,
 )
 from sqlalchemy import select
@@ -538,7 +539,12 @@ async def test_qa_pass_delegates_to_pass_qa() -> None:
 
 
 @pytest.mark.asyncio
-async def test_qa_fail_appends_issues_to_dev_notes() -> None:
+async def test_qa_fail_does_not_touch_dev_notes() -> None:
+    """qa_fail must NOT raw-append issues onto dev_notes (the data-loss bug the
+    revision-findings ledger fix retires) — the choreographer's fail_review verb
+    already persisted the concrete findings structurally (the ledger + the
+    QaNote) before this call. The next developer handoff note must be free to
+    fully overwrite dev_notes without destroying anything qa_fail wrote."""
     qa_id = uuid4()
     task = _build_task(dev_notes=None, claimed_by=qa_id)
     svc = TaskService(MagicMock(flush=AsyncMock()))
@@ -547,9 +553,7 @@ async def test_qa_fail_appends_issues_to_dev_notes() -> None:
     _bind(svc, "fail_qa", fail_qa_mock)
     issues = ["missing test", "no docstring"]
     await svc.qa_fail(qa_id, task.id, "blocking", issues)
-    assert task.dev_notes is not None
-    assert "missing test" in task.dev_notes
-    assert "no docstring" in task.dev_notes
+    assert task.dev_notes is None
     fail_qa_mock.assert_awaited_once_with(task.id, notes="blocking", agent_role="qa")
 
 
@@ -896,9 +900,12 @@ async def test_admin_set_status_non_blocked_source_keeps_claim() -> None:
 
 @pytest.mark.asyncio
 async def test_request_changes_routes_leaf_back_to_original_dev() -> None:
-    """PM merge-review reject: awaiting_pm_review -> needs_revision, issues
-    appended for the dev, task re-owned by the original developer (the QA-fail
-    routing), stale claimant cleared."""
+    """PM merge-review reject: awaiting_pm_review -> needs_revision, task
+    re-owned by the original developer (the QA-fail routing), stale claimant
+    cleared. Issues no longer raw-append onto dev_notes (the data-loss bug the
+    revision-findings ledger fix retires — the choreographer's request_changes
+    verb persists them structurally, into pm_notes + the ledger, before this
+    call) so dev_notes stays exactly as it was."""
     dev = uuid4()
     pm = uuid4()
     task = _build_task(
@@ -919,8 +926,7 @@ async def test_request_changes_routes_leaf_back_to_original_dev() -> None:
     assert task.assigned_to == dev
     assert task.claimed_by == dev
     assert task.active_claimant_id is None
-    assert "[PM REVIEW ISSUES]" in (task.dev_notes or "")
-    assert "frontend/CLAUDE.md modified out of scope" in (task.dev_notes or "")
+    assert task.dev_notes is None
 
 
 @pytest.mark.asyncio
@@ -2134,3 +2140,42 @@ async def test_list_completed_video_tasks_bounded_to_scan_limit(
     assert not missing_new, (
         f"{len(missing_new)} newest unrendered tasks dropped by the bound"
     )
+
+
+# ---------------------------------------------------------------------------
+# _ceo_reject_finding_texts — caller-side truncation for the ceo_reject finding
+# ---------------------------------------------------------------------------
+
+_CEO_ACTUAL_CAP = 300
+_CEO_EVIDENCE_CAP = 2000
+
+
+def test_ceo_reject_finding_texts_short_reason_untruncated() -> None:
+    actual, evidence = _ceo_reject_finding_texts("redo the auth flow")
+    assert actual == "redo the auth flow"
+    assert evidence is None
+
+
+def test_ceo_reject_finding_texts_truncates_over_actual_cap() -> None:
+    reason = "x" * (_CEO_ACTUAL_CAP + 50)
+    actual, evidence = _ceo_reject_finding_texts(reason)
+    assert len(actual) <= _CEO_ACTUAL_CAP
+    assert actual.endswith("]")
+    assert "chars omitted" in actual
+    # The untruncated reason survives in evidence (well under its own cap).
+    assert evidence == reason
+
+
+def test_ceo_reject_finding_texts_caps_evidence_too() -> None:
+    reason = "y" * (_CEO_EVIDENCE_CAP + 500)
+    actual, evidence = _ceo_reject_finding_texts(reason)
+    assert len(actual) <= _CEO_ACTUAL_CAP
+    assert evidence is not None
+    assert len(evidence) <= _CEO_EVIDENCE_CAP
+    assert "chars omitted" in evidence
+
+
+def test_ceo_reject_finding_texts_strips_whitespace() -> None:
+    actual, evidence = _ceo_reject_finding_texts("  redo it  ")
+    assert actual == "redo it"
+    assert evidence is None