mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
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>
This commit is contained in:
Renzo F
@@ -23,6 +23,7 @@
|
||||
- Triage your cell's queue via `triage()`
|
||||
- Unblock blocked tasks via `unblock(task_id, reason, restore=True)` — `reason` (why the block is cleared) is recorded as your `journal:decision`, so no separate `note(scope='decision')` call is needed
|
||||
- Complete tasks via `complete(task_id, notes)` — this merges the PR (a leaf subtask's PR into your cell branch, or your assembled cell→root PR into the root branch after it clears the gate). No separate `merge_pr` tool exists; the choreographer does it.
|
||||
- Reject a merge review via `request_changes(task_id, findings)` — sends a subtask in `awaiting_pm_review` back to `needs_revision` with structured findings (see "Rejecting a Merge Review" below).
|
||||
- Assemble + submit your cell-scoped parent via `submit_up(task_id, notes)` — opens the cell→root PR and enters the in-path PR-review gate (`awaiting_pr_review`), where your cell's PR reviewer checks the assembled diff. After `pr_pass`, you `complete` it to merge.
|
||||
- Send `notify` (ack-required notifications) — devs/QA/doc cannot
|
||||
- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`
|
||||
@@ -70,7 +71,7 @@ unclaim(task_id) / resume(task_id) / i_am_idle()
|
||||
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `reassign`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
|
||||
| `roboco-flow` | `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `reassign`, `complete`, `request_changes`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `dm`, `notify`, `evidence` (no `commit`) |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`, default on) |
|
||||
@@ -123,6 +124,28 @@ The choreographer:
|
||||
3. Merges the leaf PR into the parent branch
|
||||
4. Transitions the task to `completed` (or escalates the root parent chain upward — see Main PM)
|
||||
|
||||
## Rejecting a Merge Review
|
||||
|
||||
When a subtask lands in `awaiting_pm_review` and the work violates an acceptance criterion or its scope boundary (e.g. a commit touched files outside the task's declared scope), reject it instead of completing it:
|
||||
|
||||
```python
|
||||
note(scope="decision", text="Rejecting — commit touched files outside declared scope")
|
||||
request_changes(
|
||||
task_id="<subtask>",
|
||||
findings=[
|
||||
{
|
||||
"file": "roboco/api/routes/unrelated.py",
|
||||
"severity": "major",
|
||||
"expected": "changes scoped to the declared files",
|
||||
"actual": "this route was touched but was out of scope",
|
||||
"fix": "revert the out-of-scope hunk or split it into its own task",
|
||||
},
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Each finding is inserted onto the task's revision-findings ledger (`origin=pm`) and rendered into the new `pm_notes` note, then the subtask goes back to `needs_revision`, routed to whoever owns the revision. **Never** `i_am_blocked`/`escalate_up` for a review problem — those have no revision routing and just loop. The old `issues=[...]` (plain strings) form still works this release but is deprecated. See `docs/rag/architecture/review-findings.md`.
|
||||
|
||||
## Monitoring Your Cell
|
||||
|
||||
```python
|
||||
@@ -149,7 +172,7 @@ notify(target="be-dev-1", text="Please prioritise task X by EOD.",
|
||||
When every subtask of your cell-scoped parent is terminal (each leaf PR merged into your cell branch via `complete`), call `submit_up(task_id, notes)`. This opens the **cell→root PR** and moves the parent into the in-path PR-review gate (`awaiting_pr_review`), where your cell's **PR reviewer** reviews the assembled diff:
|
||||
|
||||
- `pr_pass` → the parent moves to `awaiting_pm_review`; you then `complete(task_id, notes)` to merge the cell→root PR into the root branch.
|
||||
- `pr_fail` → the parent returns to `needs_revision` (owned by you) with the reviewer's issues; fix, then re-`submit_up`. The reviewer's verdict + issues are carried in your task handoff, so you are not blind on the rework.
|
||||
- `pr_fail` → the parent returns to `needs_revision` (owned by you) with the reviewer's structured findings; fix, then re-`submit_up`. The reviewer's verdict + findings are carried in your task handoff (`revision_findings`), so you are not blind on the rework.
|
||||
|
||||
Re-`submit_up` is refused if the assembled PR is **unchanged** since the last `pr_fail` (no new commits on it) — it stops a re-submit-the-same-PR loop. Fix the issues and commit before re-submitting.
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ When a Main PM or Board member escalates a major task via `escalate_to_ceo`, it
|
||||
- **Approve** — merges the PR, task → `completed` (lifecycle `ceo_approve`)
|
||||
- **Request changes** — task → `needs_revision` (lifecycle `ceo_reject`)
|
||||
|
||||
Both are panel actions; the agent that escalated simply idles until the CEO decides.
|
||||
Both are panel actions; the agent that escalated simply idles until the CEO decides. Your rejection reason is no longer just a status note — it's persisted as one structured finding on the task's revision-findings ledger (visible in the task detail's Findings tab) and delivered to whoever reworks it via `evidence()`, exactly like a QA or PR-review bounce. An empty or placeholder reason is now rejected with a clear error instead of failing with a server error. See `docs/rag/architecture/review-findings.md`.
|
||||
|
||||
### X posts and roadmap items (panel-only, not gateway verbs)
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ open_pr(task_id) → opens the PR, transitions to awaiting_qa
|
||||
└── QA fails → returns to needs_revision; fix + commit + open_pr again
|
||||
|
||||
i_am_blocked(task_id, reason) → external dependency; cell PM unblocks
|
||||
i_am_done(task_id, notes) → batched verify + open_pr shortcut
|
||||
i_am_done(task_id, notes, resolved_findings?) → batched verify + open_pr shortcut
|
||||
unclaim(task_id) → release a task back to the queue
|
||||
resume(task_id) → recover after compact / restart
|
||||
i_am_idle() → no work in your queue right now
|
||||
@@ -97,6 +97,24 @@ When toolchain matching is enabled, `i_am_done` is refused if the project's test
|
||||
|
||||
When the architectural-conventions standard is enabled, `i_am_done` is refused on any block-level convention finding (e.g. a model defined in a router), reported with the offending `file:line` and a fix hint. A genuine false positive is cleared by committing a waiver in `.roboco/conventions.yml`.
|
||||
|
||||
## Recovering from a bounce (`needs_revision`)
|
||||
|
||||
QA (`fail`), the in-path PR reviewer (`pr_fail`), your PM (`request_changes`), or the CEO (`ceo_reject`) can bounce your task back to `needs_revision` — and now the feedback is structured, not just a prose note. `evidence(task_id)` carries `revision_findings`: the OPEN entries from the revision-findings ledger, each with `file`/`line`/`severity`/`expected`/`actual`/`fix`. Read every one before you touch code — this is the actual code-level feedback, not a summary of it.
|
||||
|
||||
Fix each finding, then resubmit naming what you resolved:
|
||||
|
||||
```python
|
||||
i_am_done(
|
||||
task_id="<task>",
|
||||
notes="...",
|
||||
resolved_findings=[
|
||||
{"finding_id": "a1b2c3d4", "commit": "<sha>", "note": "fixed the off-by-one"},
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
`finding_id` is the 8-char id from the finding's `[F-xxxxxxxx]` rendering (visible in `qa_notes`/`pm_notes`/`pr_reviewer_notes`, or in `revision_findings` itself). `i_am_done` refuses to resubmit while any open finding is left unnamed — the rejection lists the still-open ids so you don't have to guess. See `docs/rag/architecture/review-findings.md` for the full shape.
|
||||
|
||||
## A2A Collaboration
|
||||
|
||||
```python
|
||||
|
||||
@@ -75,7 +75,7 @@ triage_all() # actionable tasks across all teams (Main PM only)
|
||||
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `triage_all`, `give_me_work`, `i_will_plan`, `delegate`, `unblock`, `submit_root`, `complete`, `escalate_up`, `escalate_to_ceo`, `resume`, `unclaim`, `i_am_idle` |
|
||||
| `roboco-flow` | `triage`, `triage_all`, `give_me_work`, `i_will_plan`, `delegate`, `unblock`, `submit_root`, `complete`, `request_changes`, `escalate_up`, `escalate_to_ceo`, `resume`, `unclaim`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `dm`, `notify`, `evidence`, `pr_update` |
|
||||
| `roboco-docs` | `roboco_docs_write`, `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
@@ -111,7 +111,29 @@ master ← feature/main_pm/{root} ← feature/{cell}/{root}/{cell-pm} ←
|
||||
```
|
||||
|
||||
- A cell PM's `complete` merges a leaf PR into its cell branch; after the cell gate, its `complete` merges the cell→root PR into your root branch. You do not merge cell branches.
|
||||
- Once every cell's parent is terminal, **`submit_root(root_task_id, notes)`** opens the root→master PR and enters the in-path gate (`awaiting_pr_review`). The **main PR reviewer** checks the assembled root diff: `pr_pass` → `awaiting_pm_review`; `pr_fail` → `needs_revision` (owned by you, fix + re-`submit_root`). The reviewer's verdict + issues are carried in your task handoff, and re-`submit_root` is refused if the root PR is **unchanged** since the last `pr_fail` — fix and commit before re-submitting.
|
||||
- Once every cell's parent is terminal, **`submit_root(root_task_id, notes)`** opens the root→master PR and enters the in-path gate (`awaiting_pr_review`). The **main PR reviewer** checks the assembled root diff: `pr_pass` → `awaiting_pm_review`; `pr_fail` → `needs_revision` (owned by you, fix + re-`submit_root`). The reviewer's verdict + structured findings are carried in your task handoff (`revision_findings`), and re-`submit_root` is refused if the root PR is **unchanged** since the last `pr_fail` — fix and commit before re-submitting. If a still-open finding remains unresolved, `submit_root` itself refuses (name it via `resolved_findings=[...]` first — see `docs/rag/architecture/review-findings.md`).
|
||||
|
||||
### Rejecting a cell PM's merge review
|
||||
|
||||
When a cell PM's parent lands in `awaiting_pm_review` and the work violates an acceptance criterion or scope boundary, reject it instead of completing it — same shape as the Cell PM's own reject path:
|
||||
|
||||
```python
|
||||
note(scope="decision", text="Rejecting — cross-cell contract violated")
|
||||
request_changes(
|
||||
task_id="<cell-pm-task>",
|
||||
findings=[
|
||||
{
|
||||
"severity": "blocker",
|
||||
"criterion": "<parent-ac-id>",
|
||||
"expected": "the agreed API contract",
|
||||
"actual": "response shape diverges from what the frontend cell expects",
|
||||
"fix": "align the response schema to the contract doc before re-submitting",
|
||||
},
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Persisted to the revision-findings ledger (`origin=pm`) and rendered into `pm_notes`; the task returns to `needs_revision`, routed to whoever owns the revision. **Never** `i_am_blocked`/`escalate_up` for a review problem — those have no revision routing and just loop. The old `issues=[...]` (plain strings) form still works this release but is deprecated.
|
||||
- **The system may call `submit_root` for you.** When every cell's parent is terminal, the orchestrator's closure dispatcher tries `_try_auto_submit` first: unconditionally, with a branch + project on the root, it runs `submit_root` system-side as you — skipping your spawn for that turn, since the submit's substance is deterministic gate code, not judgment; there is no flag to turn this off. A gate rejection (freshness/integrity/AC-coverage/a subtask-terminal race) falls back to spawning you for the classic closure turn — that fallback is the only safety net — and your closure prompt carries the exact rejection reason, so `evidence(task_id)` confirms it rather than rediscovering it blind. Either way the root lands on `awaiting_pr_review` (or `needs_revision`) exactly as if you'd called it; an audited `task.auto_submitted` event marks the cut. A branchless coordination root (MegaTask umbrella) never auto-submits — it assembles no PR.
|
||||
- After `pr_pass`, `complete(root_task_id, notes)` escalates the root to the CEO (`awaiting_ceo_approval`) — it does **not** merge. A branchless coordination root (product fan-out, no repo) skips the gate and `complete` escalates directly.
|
||||
- The CEO approves and merges the root→master PR from the panel. Only the CEO ever merges to `master`.
|
||||
|
||||
@@ -17,13 +17,15 @@ The org's own in-flight integration PRs are skipped by the **inbound** poll abov
|
||||
|
||||
## In-path PR-review gate
|
||||
|
||||
The `pr_reviewer` role also runs the **in-path gate** on the org's OWN assembled delivery PRs — the merge-level review QA does not do. When a cell PM bubbles up its cell→root PR (`submit_up`) or the Main PM opens the root→master PR (`submit_root`), the task enters `awaiting_pr_review`. The cell reviewer (be/fe/ux-pr-reviewer) reviews its cell's assembled PR; pr-reviewer-1 reviews the root→master PR for the cross-cell integration seam (the bug class that lives where the FE and BE meet). Workflow: `claim_gate_review(task_id)` → review the assembled diff against the parent objective + every acceptance criterion + the FE↔BE contract → `note(scope="learning", ...)` → `pr_pass(task_id, notes)` (moves it on to the PM merge) or `pr_fail(task_id, issues)` (sends it back to `needs_revision`, like a QA fail). Either verdict is also posted on the assembled PR itself as a GitHub review (server-side, via the bot account) so the decision is visible on the PR the PM merges: `pr_pass` posts an APPROVE and `pr_fail` a REQUEST_CHANGES — except on the root→master PR, which only ever gets a plain COMMENT because only the CEO acts on `master`. This gate gives the merge level the reject teeth the PM otherwise lacks. Leaf dev tasks and branchless coordination roots skip the gate.
|
||||
The `pr_reviewer` role also runs the **in-path gate** on the org's OWN assembled delivery PRs — the merge-level review QA does not do. When a cell PM bubbles up its cell→root PR (`submit_up`) or the Main PM opens the root→master PR (`submit_root`), the task enters `awaiting_pr_review`. The cell reviewer (be/fe/ux-pr-reviewer) reviews its cell's assembled PR; pr-reviewer-1 reviews the root→master PR for the cross-cell integration seam (the bug class that lives where the FE and BE meet). Workflow: `claim_gate_review(task_id)` → review the assembled diff against the parent objective + every acceptance criterion + the FE↔BE contract → `note(scope="learning", ...)` → `pr_pass(task_id, notes)` (moves it on to the PM merge) or `pr_fail(task_id, findings=[{file?, line?, severity, criterion?, expected, actual, fix?, evidence?}])` (sends it back to `needs_revision`, like a QA fail — the old `issues=[...]` string form still works this release but is deprecated). Either verdict is also posted on the assembled PR itself as a GitHub review (server-side, via the bot account) so the decision is visible on the PR the PM merges: `pr_pass` posts an APPROVE and `pr_fail` a REQUEST_CHANGES — except on the root→master PR, which only ever gets a plain COMMENT because only the CEO acts on `master`. This gate gives the merge level the reject teeth the PM otherwise lacks. Leaf dev tasks and branchless coordination roots skip the gate.
|
||||
|
||||
On a round ≥2 review, `claim_gate_review` also returns `prior_findings` — the FULL revision-findings ledger for this task, newest first. Your own prior verdict and every finding filed on it arrive in the briefing; check each one against the current diff before deciding, rather than re-deriving what you already found. `pr_fail`'s findings are capped the same way QA's are: a soft nudge above 5 in one call, a hard reject above 10. See `docs/rag/architecture/review-findings.md`.
|
||||
|
||||
### Gate enforcement
|
||||
|
||||
When the architectural-conventions standard is enabled, `pr_pass` is refused on any block-level convention finding, the same way the developer's `i_am_done` is — the remediation hint points you at the offending `file:line` + the `pr_fail` verb (not `i_am_blocked`). When toolchain matching is enabled, `pr_pass` is likewise refused on a "broken" toolchain status. Your verdict note is a mandatory structured field (`pr_reviewer_notes`) written at `pr_pass` / `pr_fail`; it is persisted structured with a derived text mirror.
|
||||
|
||||
`pr_pass` also refuses while CI on the assembled PR's head commit is not resolvably green. Failing CI names the check(s) and points the remediation at `pr_fail(issues=['CI failing: ...'])`; pending / not-yet-scheduled / a transient GitHub API error are framed as retryable — wait and call `pr_pass` again once CI resolves, not 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 can see 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`.
|
||||
`pr_pass` also refuses while CI on the assembled PR's head commit is not resolvably green. Failing CI names the check(s) and points the remediation at `pr_fail` with a finding naming the failing check; pending / not-yet-scheduled / a transient GitHub API error are framed as retryable — wait and call `pr_pass` again once CI resolves, not 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 can see 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`.
|
||||
|
||||
**The per-AC evidence-walk is 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, not a maybe: a silently dropped AC is an automatic `pr_fail`.
|
||||
|
||||
@@ -35,7 +37,7 @@ You cannot `pr_pass` / `pr_fail` an assembled PR you authored (self-review guard
|
||||
|
||||
- Pull an inbound-PR review task via `give_me_work()` and claim it via `claim_pr_review(task_id)`.
|
||||
- Post your verdict via `post_pr_review(task_id, ...)` — the change-request lands on the PR as a GitHub review (server-side; you never push to the contributor's fork).
|
||||
- Run the in-path gate on the org's assembled delivery PRs: `claim_gate_review(task_id)` → `pr_pass(task_id, notes)` or `pr_fail(task_id, issues)`.
|
||||
- Run the in-path gate on the org's assembled delivery PRs: `claim_gate_review(task_id)` → `pr_pass(task_id, notes)` or `pr_fail(task_id, findings=[...])`.
|
||||
- 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(...)` and `evidence(...)`.
|
||||
|
||||
+23
-8
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user