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/integration/test_metrics_observability.py

@@ -242,6 +242,50 @@ async def test_rework_rate_and_attribution(obs_setup: dict) -> None:
     assert report.rework_cost_usd == pytest.approx(0.42)
     qa_row = next(a for a in report.by_agent if a.qa_fails > 0)
     assert qa_row.qa_fails == 1
+    assert qa_row.pm_rejects == 0
+    assert qa_row.ceo_rejects == 0
+
+
+@pytest.mark.asyncio
+async def test_rework_rate_attributes_pm_and_ceo_rejects(obs_setup: dict) -> None:
+    """task.request_changes / task.ceo_reject attribute to their rejector
+    exactly like task.qa_fail / task.pr_fail — the PM-merge-review reject and
+    the CEO reject are rework causes too, not just QA/PR-gate."""
+    db = obs_setup["db"]
+    pid, dev_id, qa_id = (
+        obs_setup["project_id"],
+        obs_setup["dev_id"],
+        obs_setup["qa_id"],
+    )
+    pm_reworked = _task(pid, dev_id, assigned_to=dev_id, revision_count=1)
+    ceo_reworked = _task(pid, dev_id, assigned_to=dev_id, revision_count=1)
+    db.add_all([pm_reworked, ceo_reworked])
+    await db.flush()
+    db.add_all(
+        [
+            _audit(
+                pm_reworked.id,
+                "needs_revision",
+                datetime.now(UTC) - timedelta(hours=1),
+                agent_id=qa_id,
+                event_type="task.request_changes",
+            ),
+            _audit(
+                ceo_reworked.id,
+                "needs_revision",
+                datetime.now(UTC) - timedelta(hours=1),
+                agent_id=qa_id,
+                event_type="task.ceo_reject",
+            ),
+        ]
+    )
+    await db.flush()
+
+    report = await obs_setup["svc"].get_rework_metrics(days=30)
+    # Both named events landed on the same rejector (qa_id) — one aggregate row.
+    combined = next(a for a in report.by_agent if a.pm_rejects or a.ceo_rejects)
+    assert combined.pm_rejects == 1
+    assert combined.ceo_rejects == 1
 
 
 @pytest.mark.asyncio

tests/integration/test_metrics_task.py

@@ -19,6 +19,7 @@ from roboco.db.tables import (
     AgentTable,
     AuditLogTable,
     ProjectTable,
+    TaskReviewFindingTable,
     TaskTable,
 )
 from roboco.models.base import (
@@ -242,3 +243,75 @@ async def test_in_flight_open_stint_and_open_window_decompose(setup: dict) -> No
     assert m.wall_clock_seconds > 0  # open task -> now
     # The open final window (in_progress) still decomposes.
     assert "in_progress" in {s.status for s in m.stages}
+
+
+@pytest.mark.asyncio
+async def test_task_metrics_includes_pm_ceo_rejects_and_findings_counts(
+    setup: dict,
+) -> None:
+    """pm_rejects/ceo_rejects mirror qa_fails/pr_fails for the other two named
+    bounce events; findings_open/findings_total read the revision-findings
+    ledger (open vs total rows) for this task."""
+    db = setup["db"]
+    tid = uuid4()
+    db.add(
+        TaskTable(
+            id=tid,
+            title="t",
+            description="d",
+            acceptance_criteria=["ac"],
+            task_type=TaskType.CODE,
+            nature=TaskNature.TECHNICAL,
+            status=TaskStatus.NEEDS_REVISION,
+            team=Team.BACKEND,
+            project_id=setup["project_id"],
+            created_by=setup["dev_id"],
+            assigned_to=setup["dev_id"],
+            revision_count=2,
+            estimated_complexity=Complexity.MEDIUM,
+            started_at=_T0,
+        )
+    )
+    db.add_all(
+        [
+            _audit(tid, "claimed", _T0),
+            _audit(tid, "needs_revision", _sec(60), event_type="task.request_changes"),
+            _audit(tid, "needs_revision", _sec(120), event_type="task.ceo_reject"),
+        ]
+    )
+    # The ledger's task_id carries a real FK (unlike audit_log.target_id /
+    # spawn_session.task_id, both plain columns) — the referenced task must
+    # be flushed first.
+    await db.flush()
+    db.add_all(
+        [
+            TaskReviewFindingTable(
+                id=uuid4(),
+                task_id=tid,
+                origin="qa",
+                round=1,
+                author_slug="be-qa",
+                severity="major",
+                expected="x",
+                actual="y",
+                status="verified",
+            ),
+            TaskReviewFindingTable(
+                id=uuid4(),
+                task_id=tid,
+                origin="pm",
+                round=2,
+                author_slug="be-pm",
+                severity="blocker",
+                expected="x",
+                actual="y",
+                status="open",
+            ),
+        ]
+    )
+    await db.flush()
+
+    m = await setup["svc"].get_task_metrics(tid)
+    assert m is not None
+    assert (m.pm_rejects, m.ceo_rejects) == (1, 1)
+    assert (m.findings_open, m.findings_total) == (1, 2)

tests/integration/test_task_findings_route.py

@@ -0,0 +1,215 @@
+"""GET /api/tasks/{id}/findings — the revision-findings ledger read route.
+
+Read-only feed for the panel's Findings tab: newest round first, plus
+per-origin status-count summary. Mirrors test_tasks_route_privileged_fields.py's
+fixture shape.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any, cast
+from uuid import UUID, uuid4
+
+import pytest
+import pytest_asyncio
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from roboco.api.deps import get_agent_context, get_db
+from roboco.api.routes.tasks import router as tasks_router
+from roboco.db.tables import AgentTable, ProjectTable, TaskReviewFindingTable, TaskTable
+from roboco.models import AgentRole, AgentStatus, Team
+from roboco.models.base import TaskNature, TaskStatus, TaskType
+from roboco.models.permissions import AgentContext
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+
+@pytest_asyncio.fixture
+async def findings_client(db_session: AsyncSession) -> AsyncIterator[dict]:
+    pm = AgentTable(
+        id=uuid4(),
+        name="PM",
+        slug=f"pm-{uuid4().hex[:8]}",
+        role=AgentRole.MAIN_PM,
+        team=None,
+        status=AgentStatus.ACTIVE,
+        model_config={},
+        system_prompt="pm",
+        capabilities=[],
+        permissions={},
+        metrics={},
+    )
+    db_session.add(pm)
+    await db_session.flush()
+    project = ProjectTable(
+        id=uuid4(),
+        name="TF-Proj",
+        slug=f"tf-proj-{uuid4().hex[:6]}",
+        git_url="https://example.com/tf.git",
+        assigned_cell=Team.BACKEND,
+        created_by=pm.id,
+    )
+    db_session.add(project)
+    await db_session.flush()
+
+    app = FastAPI()
+    app.include_router(tasks_router, prefix="/api/tasks")
+
+    async def _override_db() -> AsyncIterator[AsyncSession]:
+        yield db_session
+
+    async def _override_agent() -> AgentContext:
+        return AgentContext(
+            agent_id=cast("UUID", pm.id), role=AgentRole.MAIN_PM, team=None
+        )
+
+    app.dependency_overrides[get_db] = _override_db
+    app.dependency_overrides[get_agent_context] = _override_agent
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        yield {"client": client, "agent": pm, "project": project, "db": db_session}
+    app.dependency_overrides.clear()
+
+
+def _seed_task(setup: dict, **kw: Any) -> TaskTable:
+    task = TaskTable(
+        id=uuid4(),
+        title=kw.pop("title", "t"),
+        description=kw.pop("description", "d"),
+        acceptance_criteria=["ac"],
+        status=kw.pop("status", TaskStatus.NEEDS_REVISION),
+        priority=2,
+        task_type=TaskType.CODE,
+        nature=TaskNature.TECHNICAL,
+        project_id=setup["project"].id,
+        created_by=setup["agent"].id,
+        team=Team.BACKEND,
+    )
+    setup["db"].add(task)
+    return task
+
+
+def _seed_finding(
+    task_id: Any, *, round: int, origin: str, status: str
+) -> TaskReviewFindingTable:
+    return TaskReviewFindingTable(
+        id=uuid4(),
+        task_id=task_id,
+        origin=origin,
+        round=round,
+        author_slug="be-qa",
+        file="roboco/services/task.py",
+        line=42,
+        severity="major",
+        criterion=None,
+        expected="the endpoint returns 404",
+        actual="the endpoint returns 500",
+        fix="add a not-found guard",
+        evidence=None,
+        status=status,
+        created_at=datetime.now(UTC),
+    )
+
+
+_HDR = {"X-Agent-ID": "ignored", "X-Agent-Role": "main_pm"}
+
+
+@pytest.mark.asyncio
+async def test_findings_404_for_missing_task(findings_client: dict) -> None:
+    client = findings_client["client"]
+    response = await client.get(f"/api/tasks/{uuid4()}/findings", headers=_HDR)
+    assert response.status_code == HTTPStatus.NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_findings_empty_for_never_bounced_task(findings_client: dict) -> None:
+    client = findings_client["client"]
+    task = _seed_task(findings_client, status=TaskStatus.IN_PROGRESS)
+    await findings_client["db"].flush()
+    response = await client.get(f"/api/tasks/{task.id}/findings", headers=_HDR)
+    assert response.status_code == HTTPStatus.OK
+    body = response.json()
+    assert body["findings"] == []
+    assert body["summary"] == []
+    assert body["total"] == 0
+    assert body["truncated"] is False
+
+
+@pytest.mark.asyncio
+async def test_findings_newest_round_first_with_summary(findings_client: dict) -> None:
+    client = findings_client["client"]
+    task = _seed_task(findings_client)
+    await findings_client["db"].flush()
+    findings_client["db"].add_all(
+        [
+            _seed_finding(task.id, round=1, origin="qa", status="verified"),
+            _seed_finding(task.id, round=2, origin="pr_gate", status="open"),
+        ]
+    )
+    await findings_client["db"].flush()
+
+    response = await client.get(f"/api/tasks/{task.id}/findings", headers=_HDR)
+    assert response.status_code == HTTPStatus.OK
+    body = response.json()
+
+    assert [f["round"] for f in body["findings"]] == [2, 1]
+    assert body["findings"][0]["origin"] == "pr_gate"
+    assert body["findings"][0]["status"] == "open"
+    assert body["findings"][0]["expected"] == "the endpoint returns 404"
+
+    summary_by_origin = {s["origin"]: s for s in body["summary"]}
+    assert summary_by_origin["qa"] == {
+        "origin": "qa",
+        "open": 0,
+        "addressed": 0,
+        "verified": 1,
+        "waived": 0,
+    }
+    assert summary_by_origin["pr_gate"]["open"] == 1
+    assert body["total"] == len(body["findings"])
+    assert body["truncated"] is False
+
+
+_LIST_CAP = 500
+
+
+@pytest.mark.asyncio
+async def test_findings_summary_survives_list_truncation(
+    findings_client: dict,
+) -> None:
+    """Past the 500-row list cap, summary/total come from SQL aggregates over
+    the WHOLE ledger and truncated flags the capped list — the counts must
+    never be silently wrong for a big ledger."""
+    client = findings_client["client"]
+    task = _seed_task(findings_client)
+    await findings_client["db"].flush()
+    findings_client["db"].add_all(
+        [
+            _seed_finding(task.id, round=1, origin="qa", status="open")
+            for _ in range(_LIST_CAP + 1)
+        ]
+    )
+    await findings_client["db"].flush()
+
+    response = await client.get(f"/api/tasks/{task.id}/findings", headers=_HDR)
+    assert response.status_code == HTTPStatus.OK
+    body = response.json()
+
+    assert len(body["findings"]) == _LIST_CAP
+    assert body["total"] == _LIST_CAP + 1
+    assert body["truncated"] is True
+    assert body["summary"] == [
+        {
+            "origin": "qa",
+            "open": _LIST_CAP + 1,
+            "addressed": 0,
+            "verified": 0,
+            "waived": 0,
+        }
+    ]

tests/integration/test_task_service_transitions.py

@@ -2797,9 +2797,11 @@ async def test_qa_fail_appends_issues_and_calls_fail_qa(
     )
     assert out is not None
     assert out.status == TaskStatus.NEEDS_REVISION
-    # Issues block was appended to dev_notes
-    assert "typo" in (out.dev_notes or "")
-    assert "missing test" in (out.dev_notes or "")
+    # qa_fail no longer raw-appends issues onto dev_notes (the data-loss bug
+    # the revision-findings ledger fix retires) — the choreographer's
+    # fail_review verb persists them structurally (ledger + QaNote) before
+    # this call. dev_notes is untouched here.
+    assert out.dev_notes is None
 
 
 @pytest.mark.asyncio

tests/integration/v1/test_full_pending_to_completed.py

@@ -76,6 +76,7 @@ class _MockChoreographer:
         _agent_id: object,
         _task_id: object,
         _notes: object,
+        **_kwargs: object,
     ) -> Envelope:
         self._state["task_status"] = "awaiting_qa"
         return Envelope.ok(