polish

Sub-agent contract

/contract

polish is a three-wave evaluator-optimizer loop that applies to any artifact at any workflow stage. Wave 1 locks concrete, testable criteria. Waves 2 and 3 alternate (evaluator → generator) until all criteria pass or the iteration cap is reached. The evaluator is always spawned stateless — it never sees prior generation history — eliminating the sycophancy failure mode that plagues shared-context review loops.

The orchestrator coordinates but never edits the artifact directly. All revisions are produced by the Wave 3 generator, which receives only the blocking_gaps list from the evaluator (not its full reasoning). This constraint prevents scope-creep revisions and keeps each iteration focused on the delta between current state and the locked criteria.

On cap exhaust the orchestrator emits the best-scoring version plus a structured remaining_gaps report so the caller can decide whether to extend the cap, escalate to a human, or ship with known gaps documented.

---

Inputs

Field	Required	Description
artifact	yes	The text, spec, prompt, design doc, or code snippet to refine
goal	yes	Natural-language quality intent ("make this safe for external stakeholders")
criteria	no	Pre-supplied testable criteria — skips Wave 1 extraction if provided
threshold	no	pass_all (default) or pass_N where N is an integer
cap	no	Max refinement iterations (default: 4, max: 8)

---

Wave 1 — Criteria Extraction

Trigger: Always, unless criteria were supplied by the caller.

Agent: Single subagent. Reads artifact + goal. Produces:

{
  "criteria": [
    { "id": "C1", "text": "<concrete, binary-testable criterion>" },
    ...
  ],
  "threshold": "pass_all | pass_N",
  "cap": 4
}

Rules:

• Criteria must be falsifiable — "no jargon visible to end-users", not "improve clarity".
• Maximum 8 criteria. If the goal implies more, merge related ones.
• Criteria are locked after Wave 1. The evaluator may not add or modify them.