feat(feedback): add L3 agent-feedback contract — patchwarden.repair_instruction.v1 #159

New issue

Closed

opened 2026-06-23 23:10:10 +02:00 by claude · 0 comments

claude commented

2026-06-23 23:10:10 +02:00

Collaborator

Context (D28 Loop 3 — the missing closing loop)

D28 records the gate→closed-loop-controller reframe. Loop 3 (agent feedback contract) is the one that's missing, and it's the highest-leverage piece for the unattended self-merge loop (D27 / docs/product/self-usable-milestone.md).

Today Patchwarden can say blocked, and review-quorum already emits per-lane next-actions (none / redrive_review_lane / fix_review_findings, #142) — a seed, but not a full repair packet. For an agent to iterate without the operator, it must receive a precise, machine-readable instruction, not guess from prose.

Goal

A read-only contract that converts any blocking Patchwarden verdict into an agent-actionable repair packet:

blocked because X — the action that resolves it is Y — acceptance is gate X going green for this head.

Desired shape (inspiration, not limits)

patchwarden.repair_instruction.v1 (or extend existing artifacts with a next_agent_action block — your call on shape).
One entry per blocker, each with: source gate/finding code, human reason, deterministic action (e.g. "produce sandbox_smoke evidence for <sha> via the external producer", "rerun command Z", "add required section to issue body"), and acceptance = the specific gate/check passing for the exact head.
Head-bound (target_sha); dedupe key so a redrive loop doesn't churn duplicate packets.
Feeds the redrive path so the loop is PR → gates → fail → repair_instruction → agent fixes → redrive → gates → pass → controller.
#155's actionable simplification suggestions fold in here as one finding-source (not a separate Ponytail module — see D25 + the #155 narrow).

Hard boundary (the D28 / D20 line)

Policy-derived, NOT model-authored. The packet says which gate failed and what deterministic action satisfies it — never "rewrite function foo this way." Prescribing code would cross into review/authorship authority (D20). Concrete repair steps/commands/evidence-to-produce are fine; code edits are not.
Read-only / fail-closed / no side effects. external_write_allowed=false; no issue creation, no dispatch, no approve/merge. Malformed / stale / head-mismatched input → fail closed.
stdlib-only, no new dependency.

Acceptance

New read-only CLI command emits the repair-instruction artifact for a blocking contract/quorum/evidence verdict.
Artifact is exact-head bound; emits at least one actionable, policy-derived repair entry per blocker, each with an acceptance condition.
Schema + sanitized example under spec/schemas/; registered in the handoff-contract registry.
Tests prove: malformed/stale/mismatched inputs fail closed; no code-authorship content; no writes.
patchwarden status / docs/status.html reflect Loop 3 (PW-G003/G017 next action).

Refs: D28 (#158), #142 (lane-action seed), #155 (simplification suggestions fold-in); docs/product/self-usable-milestone.md.

## Context (D28 Loop 3 — the missing closing loop) D28 records the gate→closed-loop-controller reframe. **Loop 3 (agent feedback contract) is the one that's missing, and it's the highest-leverage piece for the unattended self-merge loop** (D27 / `docs/product/self-usable-milestone.md`). Today Patchwarden can say `blocked`, and `review-quorum` already emits per-lane next-actions (`none` / `redrive_review_lane` / `fix_review_findings`, #142) — a seed, but not a full repair packet. For an agent to iterate **without the operator**, it must receive a precise, machine-readable instruction, not guess from prose. ## Goal A read-only contract that converts any blocking Patchwarden verdict into an agent-actionable repair packet: > blocked **because** X — the action that resolves it is **Y** — **acceptance** is gate X going green for this head. ## Desired shape (inspiration, not limits) - `patchwarden.repair_instruction.v1` (or extend existing artifacts with a `next_agent_action` block — your call on shape). - One entry per blocker, each with: source gate/finding `code`, human reason, **deterministic action** (e.g. "produce `sandbox_smoke` evidence for `<sha>` via the external producer", "rerun command Z", "add required section to issue body"), and **acceptance** = the specific gate/check passing for the exact head. - Head-bound (`target_sha`); dedupe key so a redrive loop doesn't churn duplicate packets. - Feeds the redrive path so the loop is `PR → gates → fail → repair_instruction → agent fixes → redrive → gates → pass → controller`. - `#155`'s actionable simplification suggestions fold in here as one finding-source (not a separate Ponytail module — see D25 + the #155 narrow). ## Hard boundary (the D28 / D20 line) - **Policy-derived, NOT model-authored.** The packet says *which gate failed and what deterministic action satisfies it* — never "rewrite function foo this way." Prescribing code would cross into review/authorship authority (D20). Concrete repair *steps/commands/evidence-to-produce* are fine; code edits are not. - **Read-only / fail-closed / no side effects.** `external_write_allowed=false`; no issue creation, no dispatch, no approve/merge. Malformed / stale / head-mismatched input → fail closed. - **stdlib-only**, no new dependency. ## Acceptance - New read-only CLI command emits the repair-instruction artifact for a blocking contract/quorum/evidence verdict. - Artifact is exact-head bound; emits at least one actionable, policy-derived repair entry per blocker, each with an acceptance condition. - Schema + sanitized example under `spec/schemas/`; registered in the handoff-contract registry. - Tests prove: malformed/stale/mismatched inputs fail closed; no code-authorship content; no writes. - `patchwarden status` / `docs/status.html` reflect Loop 3 (PW-G003/G017 next action). Refs: D28 (#158), #142 (lane-action seed), #155 (simplification suggestions fold-in); `docs/product/self-usable-milestone.md`.

Rows
Columns