docs(v0): record D20 hybrid review authority boundary (closes #36) #43

Merged

pdurlej merged 1 commit from claude/patchwarden-hybrid-review-authority into main

2026-05-26 14:36:13 +02:00

claude commented

2026-05-26 14:34:57 +02:00

Collaborator

Summary

Records the merge-safety authority boundary across Patchwarden / reviewer lanes / Iskra / Platform / Operator before reviewer-lane implementation (#37 cloud_review field + #28-#30 reviewer orchestration trio) lands. Per Oracle consult patchwarde-auditlm-boundary (2026-05-26) + platform W6d/W8.1 dogfood evidence (pdurlej/platform#500, #503, #504).

Closes #36.

What changed (2 files, +61/-0)

docs/decisions.md — adds D20 + summary table row:

One-line summary: "Patchwarden decides. LLM reviewers suspect. Iskra contextualizes. Platform executes. Operator arbitrates."
Explicitly states LLM output cannot approve or merge
Lists hard manual classes (secrets, workflows, runtime/deploy, branch protection/auth, Patchwarden governance, large/stale/unparseable)
Cites platform dogfood evidence (#500, #503, #504) + Oracle consult
Names risk if wrong: reviewer-lane drift into model-owned merge authority would collapse Patchwarden into "smart commenter" category (CodeRabbit/Bugbot territory) and break D2 patent-grant rationale + D6/D7 cloud-allowed-but-policy-bounded discipline
Names mitigation: PR review checklist for #28/#29/#30/#37 includes "does any code path post Forgejo APPROVED reviews or call merge endpoints from a reviewer-lane code path?" → MUST be no
Architectural enforcement (not just convention) — review_run.py never imports merge helpers, forgejo_client.py has no merge endpoints in reviewer-lane scope

docs/architecture.md — adds new "Hybrid review authority boundary" section between "The Patchwarden ↔ Iskra boundary" and "Repo strategy":

5-row authority matrix (Patchwarden / reviewer lanes / Iskra / Platform / Operator) with what each CAN and CANNOT do
Hard manual classes restated
Architectural enforcement details (code paths that prevent drift)
AuditLM note: inspiration only, not dependency/fork (AGPL + dead project signals)

What did NOT change

❌ No code (per issue spec — "No implementation code changes in this issue")
❌ No policy schema (that's #37 work)
❌ No platform workflow changes
❌ No AuditLM import/fork
❌ No Ollama integration (#37 onwards)
docs/risks.md left untouched (R1/R2 already cover Patchwarden ↔ Iskra collapse risk; this PR adds the positive version of the boundary, not new risks)

Why now

Issue #36 was created by codex 2026-05-26 after Oracle consult + platform W6d/W8.1 evidence converged on a single insight: reviewer-lane implementation (#37 + #28-#30) needs the authority boundary recorded before code lands, not after. Otherwise drift into model-owned merge authority is a slow-bleed risk — easy to add a client.post_approved_review() call in #29 prompt rendering if nobody documented why that's forbidden.

Verification

grep -c "^## D" docs/decisions.md returns 20 (D1-D14 + D8b + D15-D20)
decisions.md summary table has 21 rows (header + 20 D-rows)
architecture.md has new H2 section "Hybrid review authority boundary" with 5-row authority matrix
No edits outside docs/decisions.md + docs/architecture.md
D20 cites platform PRs #500, #503, #504
D20 lists all 6 hard-manual classes (secrets / workflows / runtime / branch-protection / Patchwarden governance / large-stale-unparseable)

Trace

Oracle consult: patchwarde-auditlm-boundary, 2026-05-26 (operator → codex → claude flow)
Platform PRs cited: pdurlej/platform#500, #503, #504
Related Patchwarden issues: #37 (cloud_review field — lands next), #28 (reviewer lane config loader), #29 (prompt rendering), #30 (finding comments), #32 (platform dogfood playbook), #33 (boring PR lifecycle fixture)

Suggested status

Merge now — atomic docs-only PR, no code, no schema changes, no platform touch. Blocks #37 implementation start (the boundary must be in main before reviewer-lane code paths get written).

🤖 claude (Patchwarden dedicated thread) — per codex+Oracle task handoff 2026-05-26, F1 kill-criterion claude-as-Patchwarden-executor mandate active.

## Summary Records the merge-safety authority boundary across Patchwarden / reviewer lanes / Iskra / Platform / Operator **before** reviewer-lane implementation (#37 cloud_review field + #28-#30 reviewer orchestration trio) lands. Per Oracle consult `patchwarde-auditlm-boundary` (2026-05-26) + platform W6d/W8.1 dogfood evidence ([`pdurlej/platform#500`](https://git.pdurlej.com/pdurlej/platform/issues/500), [`#503`](https://git.pdurlej.com/pdurlej/platform/issues/503), [`#504`](https://git.pdurlej.com/pdurlej/platform/issues/504)). Closes [#36](https://git.pdurlej.com/pdurlej/patchwarden/issues/36). ## What changed (2 files, +61/-0) **`docs/decisions.md`** — adds **D20** + summary table row: - One-line summary: *"Patchwarden decides. LLM reviewers suspect. Iskra contextualizes. Platform executes. Operator arbitrates."* - Explicitly states LLM output cannot approve or merge - Lists hard manual classes (secrets, workflows, runtime/deploy, branch protection/auth, Patchwarden governance, large/stale/unparseable) - Cites platform dogfood evidence (#500, #503, #504) + Oracle consult - Names risk if wrong: reviewer-lane drift into model-owned merge authority would collapse Patchwarden into "smart commenter" category (CodeRabbit/Bugbot territory) and break D2 patent-grant rationale + D6/D7 cloud-allowed-but-policy-bounded discipline - Names mitigation: PR review checklist for #28/#29/#30/#37 includes *"does any code path post Forgejo APPROVED reviews or call merge endpoints from a reviewer-lane code path?"* → MUST be no - Architectural enforcement (not just convention) — `review_run.py` never imports merge helpers, `forgejo_client.py` has no merge endpoints in reviewer-lane scope **`docs/architecture.md`** — adds new **"Hybrid review authority boundary"** section between *"The Patchwarden ↔ Iskra boundary"* and *"Repo strategy"*: - 5-row authority matrix (Patchwarden / reviewer lanes / Iskra / Platform / Operator) with what each CAN and CANNOT do - Hard manual classes restated - Architectural enforcement details (code paths that prevent drift) - AuditLM note: inspiration only, not dependency/fork (AGPL + dead project signals) ## What did NOT change - ❌ No code (per issue spec — "No implementation code changes in this issue") - ❌ No policy schema (that's #37 work) - ❌ No platform workflow changes - ❌ No AuditLM import/fork - ❌ No Ollama integration (#37 onwards) - `docs/risks.md` left untouched (R1/R2 already cover Patchwarden ↔ Iskra collapse risk; this PR adds the *positive* version of the boundary, not new risks) ## Why now Issue #36 was created by codex 2026-05-26 after Oracle consult + platform W6d/W8.1 evidence converged on a single insight: reviewer-lane implementation (#37 + #28-#30) needs the authority boundary recorded *before* code lands, not after. Otherwise drift into model-owned merge authority is a slow-bleed risk — easy to add a `client.post_approved_review()` call in #29 prompt rendering if nobody documented why that's forbidden. ## Verification - [ ] `grep -c "^## D" docs/decisions.md` returns 20 (D1-D14 + D8b + D15-D20) - [ ] decisions.md summary table has 21 rows (header + 20 D-rows) - [ ] architecture.md has new H2 section "Hybrid review authority boundary" with 5-row authority matrix - [ ] No edits outside `docs/decisions.md` + `docs/architecture.md` - [ ] D20 cites platform PRs #500, #503, #504 - [ ] D20 lists all 6 hard-manual classes (secrets / workflows / runtime / branch-protection / Patchwarden governance / large-stale-unparseable) ## Trace - Oracle consult: `patchwarde-auditlm-boundary`, 2026-05-26 (operator → codex → claude flow) - Platform PRs cited: `pdurlej/platform#500`, `#503`, `#504` - Related Patchwarden issues: #37 (cloud_review field — lands next), #28 (reviewer lane config loader), #29 (prompt rendering), #30 (finding comments), #32 (platform dogfood playbook), #33 (boring PR lifecycle fixture) ## Suggested status **Merge now** — atomic docs-only PR, no code, no schema changes, no platform touch. Blocks #37 implementation start (the boundary must be in `main` before reviewer-lane code paths get written). --- 🤖 claude (Patchwarden dedicated thread) — per codex+Oracle task handoff 2026-05-26, F1 kill-criterion claude-as-Patchwarden-executor mandate active.

Rows
Columns