@ferris1225/pi-subagents 4.1.6 → 4.1.7

package/README.md

@@ -119,7 +119,10 @@ The runtime deliberately keeps delegation conservative:
 - `worker` and `cleaner` remain distinct write-capable entry roles. Each updates
   existing README/docs/examples/comments directly affected by its change. After
   success, one enabled independent `reviewer` gate runs, with the existing bounded
-  worker ↔ reviewer fix loop for `REVIEW_FAIL`.
+  worker ↔ reviewer fix loop for `REVIEW_FAIL`. Every gate finding carries a
+  concrete fix instruction; the worker implements those instructions or ships a
+  sounder fix with an explicit pushback, and re-review judges the resulting code —
+  only open findings and defects the fix itself introduced can continue the loop.
 - When `documenter` is enabled, every managed reviewer gate is asked for a
   standalone `DOCUMENTATION: CLEAN` or `DOCUMENTATION: NEEDED` line. Only
   `REVIEW_PASS` can authorize the final sync: NEEDED includes
@@ -225,14 +228,19 @@ immediately, while NEEDED (or a missing marker on that passing gate) runs one
 final docs sync. A failure uses the bounded loop:
 
 ```text
-reviewer → worker fixes every open finding → reviewer checks again → …
+reviewer → worker applies each fix instruction (or rebuts with a sounder fix)
+         → reviewer re-reviews the result → …
                                           REVIEW_PASS ─┬─ CLEAN → deliver
                                                        └─ NEEDED/missing → documenter
 ```
 
 Each step gets a fresh model context. The chain shares the same code state and
 passes every full reviewer and worker report forward; it does not reuse one
-context window. Internal children bypass top-level lifecycle policy, so they
+context window. Re-review converges instead of re-auditing: it rules on every
+previous finding once, judges the code as it now stands (a sound worker fix
+counts even when it deviates from the instruction), and adds new findings only
+for defects the fix round's own edits introduced or exposed — issues unrelated
+to those edits belong to a fresh gate, not to the loop. Internal children bypass top-level lifecycle policy, so they
 cannot recursively start another chain. Gate reviewers keep documentation drift
 out of the code verdict while `documenter` is enabled by recording it under
 `## Documentation notes`; with documenter disabled, drift is a normal finding.

package/agents/reviewer.md

@@ -43,7 +43,7 @@ You are a senior, adversarial code reviewer. Find genuine defects and risks rath
 - Return only the review result. Do not repeat the task brief, summarize the implementation, narrate inspection/tool chronology, or explain a root cause when no finding depends on it. Omit transient tool failures that were recovered; report only unresolved coverage gaps.
 - Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself. When a final documenter is available, documentation drift is not a code-gate finding: record it in a short `## Documentation notes` section and carry it forward on re-review. When documenter is disabled, drift is a normal gate finding.
 - Every gate (never an advisory review) must classify documentation on its own standalone machine line. Emit `DOCUMENTATION: NEEDED` and include `## Documentation notes` when a sync is needed; otherwise emit `DOCUMENTATION: CLEAN`. Runtime treats a missing marker conservatively as NEEDED. Do not emit this marker for advisory output.
-- In a gate, every code/test finding enters auto-fix, with no severity tiers. A direct REVIEW_PASS is final for code: CLEAN delivers directly, while NEEDED/missing runs one conditional documentation sync without reopening the gate. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
+- In a gate, every code/test finding enters auto-fix, with no severity tiers, and every gate finding must end with a concrete fix instruction — what to change, where, and how to verify the fix — because a worker implements exactly those instructions unless it can justify a sounder fix and push back. A direct REVIEW_PASS is final for code: CLEAN delivers directly, while NEEDED/missing runs one conditional documentation sync without reopening the gate. On re-review, judge the code as it now stands: a finding is resolved when the pending diff fixes it soundly, whether or not the worker followed your instruction. Rule on each open finding once, concretely adjudicate worker pushback, add only defects the fix introduced or exposed — never issues unrelated to this round's edits — and never re-open a verified resolution.
 - Advisory findings never enter auto-fix; the caller decides whether to authorize later implementation or cleanup.
 
 ## Output
@@ -64,7 +64,7 @@ For a gate review:
 ## Files Reviewed
 - path/to/file.ts
 ## Findings
-- file.ts:42 — concrete issue and why it breaks
+- file.ts:42 — concrete issue and why it breaks — Fix: the change to make and how to verify it
 (Write "None" when no finding remains.)
 ## Documentation notes
 - exact stale surface and required correction

package/agents/worker.md

@@ -34,6 +34,10 @@ Never commit, push, publish, tag, release, or bump a package version. The parent
 - You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
   brief lacks context that needs broad code discovery, state concretely what an `explorer` should
   retrieve for the caller — do not guess.
+- In an auto-fix round, apply your own judgment to the reviewer's fix instructions: implement each
+  instruction when it is sound; when it is wrong, out of scope, or a sounder fix exists, implement
+  your fix and push back in your report — cite the finding, refute the instruction's reasoning,
+  and describe what you shipped instead. A deviation without reasoning will be re-opened.
 - The parent runtime automatically runs one enabled `reviewer` gate after a successful top-level worker and preserves the bounded worker/reviewer fix loop. A final `documenter` runs only when that terminal review reports documentation drift or omits its marker (or when reviewer is disabled). Report a complete handoff, but do not ask the caller to duplicate downstream roles. Never treat your own verification as the final gate.
 
 ## Output format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.6",
+  "version": "4.1.7",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/fixloop.ts

@@ -3,6 +3,10 @@
  *
  * Successful top-level worker/cleaner runs continue through an independent
  * code review gate; bounded worker → reviewer fix rounds close its findings.
+ * Gate findings carry concrete fix instructions that the worker implements
+ * unless it can justify a sounder fix and push back; re-review adjudicates on
+ * the resulting code (open findings plus fix-introduced defects only) so the
+ * rounds converge instead of re-auditing from scratch.
  * Reviewers classify documentation drift explicitly, so the low-cost final
  * documenter runs only when needed (or conservatively when an older/custom
  * reviewer omits the marker). Direct passing/failing gates use the same policy.
@@ -139,8 +143,9 @@ export function getManagedWorkflowPlan(
 
 /**
  * Build the worker task brief for one fix round from a reviewer's findings.
- * The worker gets the full review text so it can address concrete file:line
- * issues, with instructions to fix every reported finding and self-verify.
+ * The worker gets the full review text — findings plus their fix instructions
+ * — and closes every finding either by implementing the instruction or by
+ * shipping a sounder fix with an explicit per-finding pushback.
  */
 export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, maxRounds: number): string {
 	const review = getResultOutput(reviewerResult);
@@ -153,13 +158,15 @@ export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, m
 		review,
 		`---`,
 		``,
-		`Fix EVERY finding in the reviewer's findings list — there is no severity triage; all of them get fixed.`,
-		`If a finding is factually wrong or clearly out of scope, say so explicitly instead of fixing it.`,
+		`Each finding in the reviewer's report carries a fix instruction. Close EVERY finding — there is no severity triage; all of them get fixed.`,
+		`You own the fix: when an instruction is factually wrong, clearly out of scope, or a sounder fix exists, implement YOUR fix instead,`,
+		`then push back explicitly per finding — cite it, refute the instruction's reasoning, and state what you shipped instead.`,
+		`A pushback without a working alternative or concrete reasoning will be re-opened.`,
 		`Do NOT refactor unrelated code beyond what the findings require.`,
 		`Synchronize any existing README/docs/examples/comments directly affected by your fixes; do not broaden into standalone documentation maintenance.`,
 		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and any conditional final documentation sync.`,
 		`After editing, run the project's format/build/tests when they exist and report`,
-		`exactly what you changed (paths + short rationale) so a reviewer can verify.`,
+		`exactly what you changed (paths + short rationale) plus any pushback, so a reviewer can verify.`,
 		remaining > 0
 			? `A reviewer will re-review your changes automatically after you finish.`
 			: `This is the last auto-fix round; the workflow conditionally runs any needed final documentation sync and then delivers.`,
@@ -304,6 +311,8 @@ export function buildFinalReviewBrief(
 		``,
 		`Run \`git status\` and \`git diff\` and inspect the actual pending code; the report is context, not proof.`,
 		`Remain read-only. Verify correctness, regressions, and tests.`,
+		`Attach a concrete fix instruction to EVERY gate finding: what to change, where, and how to verify the fix.`,
+		`A worker will implement your instructions unless it can justify a sounder fix and push back, so make each instruction specific enough to act on.`,
 		...(options.documenterPending
 			? [
 				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding.`,
@@ -321,10 +330,11 @@ export function buildFinalReviewBrief(
 
 /**
  * The re-review brief handed to the reviewer after a worker fix round. Includes
- * the prior review and worker report so the reviewer can adjudicate rejections
+ * the prior review and worker report so the reviewer can adjudicate pushback
  * instead of restating findings. The convergence contract keeps rounds from
- * ping-ponging: rule on the open findings once, add only defects this round's
- * edits introduced, never re-open a verified resolution.
+ * ping-ponging: judge the resulting code (not instruction obedience), rule on
+ * the open findings once, add only defects this round's edits introduced,
+ * never re-open a verified resolution.
  */
 export function buildReReviewBrief(
 	reviewerResult: SingleResult,
@@ -342,16 +352,17 @@ export function buildReReviewBrief(
 		review,
 		`---`,
 		``,
-		`The worker's report (what it changed, plus any finding it rejected as factually wrong or out of scope):`,
+		`The worker's report (what it changed, plus any pushback where it replaced your fix instruction with its own fix):`,
 		`---`,
 		workerReport,
 		`---`,
 		``,
-		`Rule on EVERY previous finding: resolved, or still open. A finding the worker rejected must be`,
-		`adjudicated ONCE — accept the rejection unless you can concretely refute the worker's reasoning;`,
-		`never simply restate the finding for another round.`,
-		`Run \`git diff\` to see what changed, then add NEW findings only when they are defects this round's`,
-		`edits introduced or exposed (or a load-bearing issue the earlier review genuinely missed).`,
+		`Rule on EVERY previous finding: resolved, or still open. Judge the code as it now stands — a finding is`,
+		`resolved when the pending diff fixes it soundly, whether or not the worker followed your fix instruction.`,
+		`A finding the worker pushed back on must be adjudicated ONCE — accept the worker's fix unless you can`,
+		`concretely refute its reasoning; never simply restate the finding for another round.`,
+		`Run \`git diff\` to see what changed, then add NEW findings only for defects this round's edits introduced or exposed.`,
+		`Re-review never opens findings unrelated to this round's edits; issues the earlier review missed belong to a fresh gate.`,
 		`Do NOT re-open a finding you verified as resolved.`,
 		...(options.documenterPending
 			? [