@pourkit/cli 0.0.0-next-20260621094003 → 0.0.0-next-20260621233457

package/dist/cli.js

@@ -442,6 +442,25 @@ function checkRemovedFields(raw) {
             );
           }
         }
+        const strategy = target.strategy;
+        if (strategy && typeof strategy === "object") {
+          const review = strategy.review;
+          if (review && typeof review === "object") {
+            if ("passWithNotesRefactorAttempts" in review) {
+              throw new Error(
+                `targets[${i}].strategy.review.passWithNotesRefactorAttempts has been removed; PASS_WITH_NOTES no longer triggers Refactor.`
+              );
+            }
+            const reviewer = review.reviewer;
+            if (reviewer && typeof reviewer === "object") {
+              if ("passWithNotesRefactorAttempts" in reviewer) {
+                throw new Error(
+                  `targets[${i}].strategy.review.reviewer.passWithNotesRefactorAttempts has been removed; PASS_WITH_NOTES no longer triggers Refactor.`
+                );
+              }
+            }
+          }
+        }
       }
     }
   }
@@ -773,14 +792,12 @@ function parseConfig(raw) {
                 reviewReviewer.outputRetries
               ),
               criteria: reviewReviewer.criteria,
-              includeReviewHistory: reviewReviewer.includeReviewHistory,
-              passWithNotesRefactorAttempts: reviewReviewer.passWithNotesRefactorAttempts
+              includeReviewHistory: reviewReviewer.includeReviewHistory
             },
             refactor: applyStageAgentDefaults(
               reviewRefactor
             ),
-            maxIterations: review.maxIterations,
-            passWithNotesRefactorAttempts: review.passWithNotesRefactorAttempts ?? 2
+            maxIterations: review.maxIterations
           },
           ...verifyLabeled ? { verify: { commands: verifyLabeled } } : {},
           issueFinalReview: {
@@ -1168,9 +1185,11 @@ function parseReviewVerdict(output) {
 }
 
 // commands/review.ts
+import { Effect as Effect3 } from "effect";
+
+// issues/issue-review-loop.ts
 import {
   existsSync as existsSync6,
-  mkdirSync as mkdirSync5,
   readFileSync as readFileSync6,
   readdirSync as readdirSync2,
   writeFileSync as writeFileSync3
@@ -1465,7 +1484,7 @@ function buildRunContextMarkdown(options) {
     );
   }
   if (sections.includes("verification-commands")) {
-    parts.push(...renderCommandList(target, "Verification Commands"));
+    parts.push(...renderCommandList(target, "Verification Commands", repoRoot2));
   }
   if (sections.includes("review-criteria")) {
     parts.push(...renderCriteria(reviewerCriteria));
@@ -1483,14 +1502,27 @@ function buildRunContextMarkdown(options) {
   }
   return parts.join("\n");
 }
-function renderCommandList(target, heading) {
+function renderCommandList(target, heading, repoRoot2) {
   const commands = getVerificationCommands(target);
+  const wrapperCommand = buildRunVerificationCommand(target);
   const parts = [
     `## ${heading}`,
     "",
-    `Run this command from the repository root: \`${buildRunVerificationCommand(target)}\``,
+    `Run this command from the repository root: \`${wrapperCommand}\``,
+    "",
+    "Use the wrapper as the configured verification method for Builder, Reviewer, Refactor, and Issue Final Review handoffs. Run the underlying commands directly only when no wrapper path can run, and record that degraded path in the role's artifact or handoff notes.",
     ""
   ];
+  if (isPourkitSourceRepo(repoRoot2)) {
+    parts.push(
+      "Pourkit self-development fallback:",
+      "",
+      `- If \`${wrapperCommand}\` fails before running configured commands because the installed CLI rejects this worktree's config schemaVersion, build and rerun the same target with the worktree-local CLI: \`npm run build --workspace pourkit\`, then \`node pourkit/dist/cli.js run-verification --target ${target.name}\`.`,
+      '- Treat local CLI wrapper success as valid configured verification and record it as `verification.method: "local-wrapper"` in Issue Final Review artifacts, or as local-wrapper verification in Builder/Reviewer/Refactor handoff notes.',
+      '- Fall back to the underlying configured commands only if the worktree-local CLI cannot be built or invoked; record that degraded path as `verification.method: "commands"` in Issue Final Review artifacts, or as direct-command verification in Builder/Reviewer/Refactor handoff notes, and explain why the wrapper path could not run.',
+      ""
+    );
+  }
   if (commands.length > 0) {
     parts.push(
       "Configured commands executed by the wrapper:",
@@ -1503,6 +1535,17 @@ function renderCommandList(target, heading) {
   }
   return parts;
 }
+function isPourkitSourceRepo(repoRoot2) {
+  if (!repoRoot2) return false;
+  const packagePath = join5(repoRoot2, "pourkit", "package.json");
+  if (!existsSync4(packagePath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync4(packagePath, "utf-8"));
+    return parsed.name === "@pourkit/cli";
+  } catch {
+    return false;
+  }
+}
 function renderParentPrdContext(issue, parentPrdIssue, repoRoot2) {
   const parent = extractIssueSection(issue.body, "Parent");
   const parentRef = parent?.match(/\bPRD-\d+\b/i)?.[0]?.toUpperCase() ?? issue.title.match(/^\s*(PRD-\d+)\s*\/\s*I-\d+\b/i)?.[1]?.toUpperCase();
@@ -1971,7 +2014,7 @@ function validateRecoveryDecision(artifact, allowedDecisions) {
   return { valid: true, decision };
 }
 
-// commands/review.ts
+// issues/issue-review-loop.ts
 import { Effect as Effect2, Layer as Layer2 } from "effect";
 var ReviewArtifactValidationError = class extends Error {
   constructor(message) {
@@ -2162,6 +2205,172 @@ function validateReviewArtifact(output, verdict, iteration, priorRefactorArtifac
     }
   }
 }
+function renderReviewHistory(reviewHistory) {
+  if (reviewHistory.length === 0) {
+    return "";
+  }
+  return `## Review History
+
+${reviewHistory.map((entry, index) => `### Iteration ${index + 1}
+
+${entry.trimEnd()}`).join("\n\n")}
+
+`;
+}
+function renderReviewCriteriaEffect(repoRoot2, criteria, fs) {
+  return Effect2.gen(function* () {
+    const parts = [];
+    for (const criterion of criteria) {
+      const snippetPath = join6(
+        repoRoot2,
+        ".pourkit",
+        "managed",
+        "prompts",
+        `reviewer-${criterion}.snippet.md`
+      );
+      const exists = yield* fs.exists(snippetPath).pipe(Effect2.orDie);
+      if (exists) {
+        const content = yield* fs.readFile(snippetPath).pipe(Effect2.orDie);
+        parts.push(content.trimEnd());
+      } else {
+        parts.push(`- ${criterion}`);
+      }
+    }
+    return parts.join("\n\n");
+  });
+}
+function loadReviewerPromptTemplateEffect(repoRoot2, promptTemplate, criteriaBlock, fs) {
+  return Effect2.gen(function* () {
+    const promptTemplatePath = resolvePromptTemplatePath(
+      repoRoot2,
+      promptTemplate
+    );
+    const exists = yield* fs.exists(promptTemplatePath).pipe(Effect2.orDie);
+    const promptBody = exists ? yield* fs.readFile(promptTemplatePath).pipe(Effect2.orDie) : promptTemplate;
+    const hasCriteriaPlaceholder = promptBody.includes("{{REVIEW_CRITERIA}}");
+    return {
+      content: promptBody.replace(/\{\{REVIEW_CRITERIA\}\}/g, criteriaBlock),
+      hasCriteriaPlaceholder
+    };
+  });
+}
+function buildReviewerPromptEffect(repoRoot2, promptTemplate, criteria, artifactPathInWorktree, iteration, fs, reviewHistory = [], priorRefactorArtifacts, humanHandoffResolved, priorReviewerArtifacts) {
+  return Effect2.gen(function* () {
+    const criteriaBlock = yield* renderReviewCriteriaEffect(
+      repoRoot2,
+      criteria,
+      fs
+    );
+    const { content: renderedTemplate, hasCriteriaPlaceholder } = yield* loadReviewerPromptTemplateEffect(
+      repoRoot2,
+      promptTemplate,
+      criteriaBlock,
+      fs
+    );
+    const priorRefactorBlock = priorRefactorArtifacts ? `${priorRefactorArtifacts}` : "";
+    const priorRefactorProtocolReminder = priorRefactorArtifacts ? `## Prior Refactor Protocol Reminder
+
+MANDATORY: because this prompt contains ## Prior Refactor Artifacts, your artifact must contain ## Prior Refactor Response Assessment exactly, before verdict. Section headings must match the names defined in this protocol exactly.
+
+` : "";
+    const priorReviewerBlock = priorReviewerArtifacts ? `${priorReviewerArtifacts}` : "";
+    const humanHandoffBoundary = humanHandoffResolved ? `## Human-Resolved Handoff Boundary
+
+A prior review emitted \`NEEDS_HUMAN\` and stopped the agent loop. The issue has since been moved back to \`ready-for-agent\`.
+
+Before carrying forward old blockers, inspect newer issue comments and the current worktree. Treat prior Reviewer and Refactor Artifacts as historical context, not active findings unless they still apply.
+
+` : "";
+    return appendProtectedWorkGuidance(`${renderedTemplate}
+
+## Shared Run Context
+
+Read the selected issue requirements, planning context (including plan and PRD content when present), branch context, verification commands, and artifact paths from: ${RUN_CONTEXT_PATH_IN_WORKTREE}
+
+## Initial Verification Pass
+
+- First read ${RUN_CONTEXT_PATH_IN_WORKTREE} only far enough to identify the configured verification commands.
+- Before reviewing code, diffs, artifacts, or prior findings, run the configured verification wrapper yourself from the Worktree.
+- If ${RUN_CONTEXT_PATH_IN_WORKTREE} provides a worktree-local CLI fallback, use that fallback before considering direct command execution.
+- Run underlying verification commands directly only when no wrapper path can run, and record why verification used direct commands.
+- If a configured command fails, keep reviewing after recording the failure details; use the failure output as review evidence.
+- If a command cannot run because the environment is missing required setup, dependencies, or scripts outside agent control, treat it as a human handoff blocker.
+- If no verification commands are configured, note that and proceed with normal review.
+
+## Scope Evidence Rules
+
+- Use the Run Context's canonical base ref, for example \`origin/<base>\`, for scope diffs and commit ranges.
+- Do not use bare PRD/base branch names such as \`PRD-0063\`, \`main\`, or \`dev\` for scope decisions; local branches with those names may be stale.
+- Only call a file or commit out of scope when it is part of the working branch's delta from the canonical base ref.
+- Do not recommend reverting accepted sibling/base work. If a file is present or changed on the canonical base ref, it is not this Issue's scope overreach.
+- If scope evidence is ambiguous, use \`NEEDS_HUMAN\` or ask for a runner/base mismatch decision instead of telling Refactor to revert files.
+
+${hasCriteriaPlaceholder ? "" : `## Review Criteria
+
+${criteriaBlock}
+
+`}${humanHandoffBoundary}${priorReviewerBlock}${renderReviewHistory(reviewHistory)}${priorRefactorBlock}${priorRefactorProtocolReminder}## Output
+
+Write your review to: ${artifactPathInWorktree}
+
+Before handoff, run: pourkit validate-artifact reviewer ${artifactPathInWorktree} --iteration ${iteration}${priorRefactorArtifacts ? " --prior-refactor-artifacts" : ""}
+
+Do not provide a separate chat response. The runner only reads the file above.
+
+End the file with exactly one wrapped verdict token: <verdict>PASS</verdict>, <verdict>PASS_WITH_NOTES</verdict>, <verdict>NEEDS_REFACTOR</verdict>, <verdict>FAIL</verdict>, or <verdict>NEEDS_HUMAN</verdict>. The verdict token must appear exactly once in the output.
+
+Findings must include an ID column with values in the format R${iteration}.F{findingNumber} (e.g., R${iteration}.F1, R${iteration}.F2) and a Supersedes column referencing the finding ID being superseded (or a hyphen for new findings).
+
+When verdict is NEEDS_HUMAN, include Human Handoff Summary and Human Handoff Reason sections before the final verdict token.`);
+  });
+}
+function recoverReviewOutputFromString(logContent) {
+  const startIndex = logContent.indexOf("## Findings");
+  if (startIndex === -1) return null;
+  const verdictMatch = logContent.slice(startIndex).match(
+    /<verdict>(PASS|PASS_WITH_NOTES|NEEDS_REFACTOR|FAIL|NEEDS_HUMAN)<\/verdict>/
+  );
+  if (!verdictMatch || verdictMatch.index === void 0) return null;
+  const recoveredOutput = logContent.slice(startIndex, startIndex + verdictMatch.index + verdictMatch[0].length).trim();
+  return recoveredOutput.length > 0 ? recoveredOutput : null;
+}
+function recoverReviewOutputFromLog(logPath) {
+  if (!existsSync6(logPath)) {
+    return null;
+  }
+  const logContent = readFileSync6(logPath, "utf-8");
+  return recoverReviewOutputFromString(logContent);
+}
+function readReviewArtifact(artifactPath, logPath) {
+  if (existsSync6(artifactPath)) {
+    const output = readFileSync6(artifactPath, "utf-8");
+    if (output.trim()) {
+      return output;
+    }
+  }
+  const recoveredOutput = logPath ? recoverReviewOutputFromLog(logPath) : null;
+  if (recoveredOutput) {
+    writeFileSync3(artifactPath, recoveredOutput, "utf-8");
+    return recoveredOutput;
+  }
+  if (!existsSync6(artifactPath)) {
+    throw new Error(`Reviewer did not produce output at ${artifactPath}`);
+  }
+  throw new Error(`Reviewer produced empty output at ${artifactPath}`);
+}
+function bridgeExecutionProvider(ep) {
+  return Layer2.succeed(
+    ExecutionProvider,
+    ExecutionProvider.of({
+      execute: (opts) => Effect2.tryPromise({
+        try: () => ep.execute(opts),
+        catch: (e) => new Error(
+          e instanceof Error ? e.message : `Execution failed: ${String(e)}`
+        )
+      })
+    })
+  );
+}
 function runReviewCommandEffect(options) {
   const {
     executionProvider,
@@ -2314,100 +2523,43 @@ function runReviewCommandEffect(options) {
     return { verdict: parsedVerdict, output, artifactPath };
   });
 }
-function bridgeExecutionProvider(ep) {
-  return Layer2.succeed(
-    ExecutionProvider,
-    ExecutionProvider.of({
-      execute: (opts) => Effect2.tryPromise({
-        try: () => ep.execute(opts),
-        catch: (e) => new Error(
-          e instanceof Error ? e.message : `Execution failed: ${String(e)}`
-        )
-      })
-    })
-  );
-}
-function buildReviewerPromptEffect(repoRoot2, promptTemplate, criteria, artifactPathInWorktree, iteration, fs, reviewHistory = [], priorRefactorArtifacts, humanHandoffResolved, priorReviewerArtifacts) {
+function buildRefactorPromptEffect(repoRoot2, promptTemplate, latestReview, artifactPathInWorktree, iteration, fs) {
   return Effect2.gen(function* () {
-    const criteriaBlock = yield* renderReviewCriteriaEffect(
-      repoRoot2,
-      criteria,
-      fs
-    );
-    const { content: renderedTemplate, hasCriteriaPlaceholder } = yield* loadReviewerPromptTemplateEffect(
+    const promptTemplatePath = resolvePromptTemplatePath(
       repoRoot2,
-      promptTemplate,
-      criteriaBlock,
-      fs
+      promptTemplate
     );
-    const priorRefactorBlock = priorRefactorArtifacts ? `${priorRefactorArtifacts}` : "";
-    const priorRefactorProtocolReminder = priorRefactorArtifacts ? `## Prior Refactor Protocol Reminder
-
-MANDATORY: because this prompt contains ## Prior Refactor Artifacts, your artifact must contain ## Prior Refactor Response Assessment exactly, before verdict. Section headings must match the names defined in this protocol exactly.
-
-` : "";
-    const priorReviewerBlock = priorReviewerArtifacts ? `${priorReviewerArtifacts}` : "";
-    const humanHandoffBoundary = humanHandoffResolved ? `## Human-Resolved Handoff Boundary
-
-A prior review emitted \`NEEDS_HUMAN\` and stopped the agent loop. The issue has since been moved back to \`ready-for-agent\`.
-
-Before carrying forward old blockers, inspect newer issue comments and the current worktree. Treat prior Reviewer and Refactor Artifacts as historical context, not active findings unless they still apply.
-
-` : "";
-    return appendProtectedWorkGuidance(`${renderedTemplate}
+    const exists = yield* fs.exists(promptTemplatePath).pipe(Effect2.orDie);
+    const promptBody = exists ? yield* fs.readFile(promptTemplatePath).pipe(Effect2.orDie) : promptTemplate;
+    const findingIds = extractLatestFindingIds(latestReview, iteration);
+    const findingArgs = findingIds.map((id) => ` --finding-id ${id}`).join("");
+    return appendProtectedWorkGuidance(`${promptBody}
 
 ## Shared Run Context
 
 Read the selected issue requirements, planning context (including plan and PRD content when present), branch context, verification commands, and artifact paths from: ${RUN_CONTEXT_PATH_IN_WORKTREE}
 
-## Initial Verification Pass
-
-- First read ${RUN_CONTEXT_PATH_IN_WORKTREE} only far enough to identify the configured verification commands.
-- Before reviewing code, diffs, artifacts, or prior findings, run each configured verification command yourself from the Worktree.
-- Run the commands exactly as configured. Do not substitute narrower commands unless the configured command cannot run.
-- If a configured command fails, keep reviewing after recording the failure details; use the failure output as review evidence.
-- If a command cannot run because the environment is missing required setup, dependencies, or scripts outside agent control, treat it as a human handoff blocker.
-- If no verification commands are configured, note that and proceed with normal review.
+## Verification Handoff
 
-## Scope Evidence Rules
+- Run the verification wrapper listed in ${RUN_CONTEXT_PATH_IN_WORKTREE} after making changes.
+- If ${RUN_CONTEXT_PATH_IN_WORKTREE} provides a worktree-local CLI fallback, use that fallback before considering direct command execution.
+- Run underlying verification commands directly only when no wrapper path can run, and record why verification used direct commands in the Refactor Artifact.
+- If configured verification fails because of fixable Issue work, fix the work and rerun verification before handoff.
+- Failed or blocked verification prohibits <promise>COMPLETE</promise>.
 
-- Use the Run Context's canonical base ref, for example \`origin/<base>\`, for scope diffs and commit ranges.
-- Do not use bare PRD/base branch names such as \`PRD-0063\`, \`main\`, or \`dev\` for scope decisions; local branches with those names may be stale.
-- Only call a file or commit out of scope when it is part of the working branch's delta from the canonical base ref.
-- Do not recommend reverting accepted sibling/base work. If a file is present or changed on the canonical base ref, it is not this Issue's scope overreach.
-- If scope evidence is ambiguous, use \`NEEDS_HUMAN\` or ask for a runner/base mismatch decision instead of telling Refactor to revert files.
-
-${hasCriteriaPlaceholder ? "" : `## Review Criteria
-
-${criteriaBlock}
-
-`}${humanHandoffBoundary}${priorReviewerBlock}${renderReviewHistory(reviewHistory)}${priorRefactorBlock}${priorRefactorProtocolReminder}## Output
-
-Write your review to: ${artifactPathInWorktree}
+## Latest Review
 
-Before handoff, run: pourkit validate-artifact reviewer ${artifactPathInWorktree} --iteration ${iteration}${priorRefactorArtifacts ? " --prior-refactor-artifacts" : ""}
+${latestReview.trimEnd()}
 
-Do not provide a separate chat response. The runner only reads the file above.
+## Output
 
-End the file with exactly one wrapped verdict token: <verdict>PASS</verdict>, <verdict>PASS_WITH_NOTES</verdict>, <verdict>NEEDS_REFACTOR</verdict>, <verdict>FAIL</verdict>, or <verdict>NEEDS_HUMAN</verdict>. The verdict token must appear exactly once in the output.
+Write your refactor artifact to: ${artifactPathInWorktree}
 
-Findings must include an ID column with values in the format R${iteration}.F{findingNumber} (e.g., R${iteration}.F1, R${iteration}.F2) and a Supersedes column referencing the finding ID being superseded (or a hyphen for new findings).
+Before handoff, run: pourkit validate-artifact refactor ${artifactPathInWorktree} --iteration ${iteration}${findingArgs}
 
-When verdict is NEEDS_HUMAN, include Human Handoff Summary and Human Handoff Reason sections before the final verdict token.`);
+When you are done, finish with <promise>COMPLETE</promise>.`);
   });
 }
-function renderReviewHistory(reviewHistory) {
-  if (reviewHistory.length === 0) {
-    return "";
-  }
-  return `## Review History
-
-${reviewHistory.map((entry, index) => `### Iteration ${index + 1}
-
-${entry.trimEnd()}`).join("\n\n")}
-
-`;
-}
 function renderPriorRefactorArtifactsEffect(worktreePath, currentIteration) {
   return Effect2.gen(function* () {
     const fb = yield* FileSystem;
@@ -2468,78 +2620,54 @@ ${iterationsBlocks}
 `;
   });
 }
-function loadReviewerPromptTemplateEffect(repoRoot2, promptTemplate, criteriaBlock, fs) {
-  return Effect2.gen(function* () {
-    const promptTemplatePath = resolvePromptTemplatePath(
-      repoRoot2,
-      promptTemplate
-    );
-    const exists = yield* fs.exists(promptTemplatePath).pipe(Effect2.orDie);
-    const promptBody = exists ? yield* fs.readFile(promptTemplatePath).pipe(Effect2.orDie) : promptTemplate;
-    const hasCriteriaPlaceholder = promptBody.includes("{{REVIEW_CRITERIA}}");
-    return {
-      content: promptBody.replace(/\{\{REVIEW_CRITERIA\}\}/g, criteriaBlock),
-      hasCriteriaPlaceholder
-    };
-  });
-}
-function renderReviewCriteriaEffect(repoRoot2, criteria, fs) {
+function persistIterationArtifactEffect(worktreePath, output, iteration, fs) {
   return Effect2.gen(function* () {
-    const parts = [];
-    for (const criterion of criteria) {
-      const snippetPath = join6(
-        repoRoot2,
-        ".pourkit",
-        "managed",
-        "prompts",
-        `reviewer-${criterion}.snippet.md`
-      );
-      const exists = yield* fs.exists(snippetPath).pipe(Effect2.orDie);
-      if (exists) {
-        const content = yield* fs.readFile(snippetPath).pipe(Effect2.orDie);
-        parts.push(content.trimEnd());
-      } else {
-        parts.push(`- ${criterion}`);
-      }
-    }
-    return parts.join("\n\n");
+    const dir = join6(worktreePath, ".pourkit", ".tmp", "reviewers");
+    yield* fs.mkdir(dir).pipe(Effect2.catchAll(() => Effect2.void));
+    yield* fs.writeFile(join6(dir, `iteration-${iteration}.md`), output).pipe(Effect2.catchAll(() => Effect2.void));
   });
 }
-function recoverReviewOutputFromString(logContent) {
-  const startIndex = logContent.indexOf("## Findings");
-  if (startIndex === -1) return null;
-  const verdictMatch = logContent.slice(startIndex).match(
-    /<verdict>(PASS|PASS_WITH_NOTES|NEEDS_REFACTOR|FAIL|NEEDS_HUMAN)<\/verdict>/
-  );
-  if (!verdictMatch || verdictMatch.index === void 0) return null;
-  const recoveredOutput = logContent.slice(startIndex, startIndex + verdictMatch.index + verdictMatch[0].length).trim();
-  return recoveredOutput.length > 0 ? recoveredOutput : null;
-}
-function recoverReviewOutputFromLog(logPath) {
-  if (!existsSync6(logPath)) {
-    return null;
-  }
-  const logContent = readFileSync6(logPath, "utf-8");
-  return recoverReviewOutputFromString(logContent);
-}
-function readReviewArtifact(artifactPath, logPath) {
-  if (existsSync6(artifactPath)) {
-    const output = readFileSync6(artifactPath, "utf-8");
-    if (output.trim()) {
-      return output;
-    }
+function mapResult(result) {
+  const base = {
+    output: result.output,
+    iterations: result.iterations,
+    lifetimeIterations: result.lifetimeIterations,
+    refactorCompletedForLastReview: result.refactorCompletedForLastReview,
+    refactorArtifactPaths: result.refactorArtifactPaths
+  };
+  if (result.exhaustedMaxIterations) {
+    return {
+      status: "exhausted_max_iterations",
+      reviewVerdict: result.verdict === "FAIL" ? "FAIL" : "NEEDS_REFACTOR",
+      reviewArtifactPath: result.artifactPath,
+      ...base,
+      reason: "max_iterations"
+    };
   }
-  const recoveredOutput = logPath ? recoverReviewOutputFromLog(logPath) : null;
-  if (recoveredOutput) {
-    writeFileSync3(artifactPath, recoveredOutput, "utf-8");
-    return recoveredOutput;
+  if (result.verdict === "NEEDS_HUMAN") {
+    return {
+      status: "needs_human",
+      reviewVerdict: "NEEDS_HUMAN",
+      reviewArtifactPath: result.artifactPath,
+      ...base
+    };
   }
-  if (!existsSync6(artifactPath)) {
-    throw new Error(`Reviewer did not produce output at ${artifactPath}`);
+  if (result.verdict === "FAIL") {
+    return {
+      status: "needs_human",
+      reviewVerdict: "NEEDS_HUMAN",
+      reviewArtifactPath: result.artifactPath,
+      ...base
+    };
   }
-  throw new Error(`Reviewer produced empty output at ${artifactPath}`);
+  return {
+    status: "passed",
+    reviewVerdict: result.verdict,
+    reviewArtifactPath: result.artifactPath,
+    ...base
+  };
 }
-function runReviewWithRefactorLoop(options) {
+function runIssueReviewLoop(options) {
   const {
     executionProvider,
     config,
@@ -2565,7 +2693,6 @@ function runReviewWithRefactorLoop(options) {
     return Effect2.die(new Error("No refactorer config found"));
   }
   const maxIterations = strategy.review.maxIterations;
-  const passWithNotesRefactorAttempts = strategy.review.passWithNotesRefactorAttempts;
   let resolvedStartingIteration = startingLifetimeIteration;
   {
     const reviewersDir = join6(worktreePath, ".pourkit", ".tmp", "reviewers");
@@ -2598,7 +2725,6 @@ function runReviewWithRefactorLoop(options) {
       iteration: 0,
       lastResult: null,
       reviewHistory: [],
-      passWithNotesRefactorAttemptsRemaining: passWithNotesRefactorAttempts,
       accumulatedRefactorPaths: [],
       doneResult: null
     };
@@ -2654,11 +2780,7 @@ function runReviewWithRefactorLoop(options) {
             }
           };
         }
-        if (reviewResult.verdict === "PASS_WITH_NOTES" && s.passWithNotesRefactorAttemptsRemaining === 0) {
-          logger.step(
-            "info",
-            "PASS_WITH_NOTES refactor attempts exhausted, treating as PASS"
-          );
+        if (reviewResult.verdict === "PASS_WITH_NOTES") {
           return {
             ...s,
             done: true,
@@ -2666,7 +2788,7 @@ function runReviewWithRefactorLoop(options) {
             lastResult: reviewResult,
             reviewHistory: updatedHistory,
             doneResult: {
-              verdict: "PASS",
+              verdict: reviewResult.verdict,
               output: reviewResult.output,
               artifactPath: reviewResult.artifactPath,
               iterations: iteration,
@@ -2677,14 +2799,6 @@ function runReviewWithRefactorLoop(options) {
             }
           };
         }
-        let updatedPassWithNotesRefactorAttemptsRemaining = s.passWithNotesRefactorAttemptsRemaining;
-        if (reviewResult.verdict === "PASS_WITH_NOTES") {
-          updatedPassWithNotesRefactorAttemptsRemaining--;
-          logger.step(
-            "info",
-            `PASS_WITH_NOTES refactor attempts remaining: ${updatedPassWithNotesRefactorAttemptsRemaining}`
-          );
-        }
         if (reviewResult.verdict === "NEEDS_HUMAN") {
           logger.step("info", "NEEDS_HUMAN verdict, stopping review loop");
           return {
@@ -2705,7 +2819,7 @@ function runReviewWithRefactorLoop(options) {
             }
           };
         }
-        if (reviewResult.verdict === "NEEDS_REFACTOR" || reviewResult.verdict === "PASS_WITH_NOTES" || reviewResult.verdict === "FAIL") {
+        if (reviewResult.verdict === "NEEDS_REFACTOR" || reviewResult.verdict === "FAIL") {
           logger.step("info", "Running refactor agent");
           const refactorArtifactPathInWorktree = join6(
             ".pourkit",
@@ -2861,7 +2975,6 @@ function runReviewWithRefactorLoop(options) {
             iteration,
             lastResult: reviewResult,
             reviewHistory: updatedHistory,
-            passWithNotesRefactorAttemptsRemaining: updatedPassWithNotesRefactorAttemptsRemaining,
             accumulatedRefactorPaths: updatedAccumulated,
             doneResult: null
           };
@@ -2871,7 +2984,6 @@ function runReviewWithRefactorLoop(options) {
           iteration,
           lastResult: reviewResult,
           reviewHistory: updatedHistory,
-          passWithNotesRefactorAttemptsRemaining: updatedPassWithNotesRefactorAttemptsRemaining,
           accumulatedRefactorPaths: s.accumulatedRefactorPaths,
           doneResult: null
         };
@@ -2882,7 +2994,7 @@ function runReviewWithRefactorLoop(options) {
     }
     logger.step("warn", `Max review iterations (${maxIterations}) exhausted`);
     return {
-      verdict: "FAIL",
+      verdict: finalState.lastResult?.verdict ?? "FAIL",
       output: finalState.lastResult?.output ?? "",
       artifactPath: finalState.lastResult?.artifactPath ?? "",
       iterations: finalState.iteration,
@@ -2894,45 +3006,10 @@ function runReviewWithRefactorLoop(options) {
   });
   const executionLayer = bridgeExecutionProvider(executionProvider);
   return program.pipe(
-    Effect2.provide(Layer2.merge(executionLayer, FileSystemDefault))
+    Effect2.provide(Layer2.merge(executionLayer, FileSystemDefault)),
+    Effect2.map(mapResult)
   );
 }
-function persistIterationArtifactEffect(worktreePath, output, iteration, fs) {
-  return Effect2.gen(function* () {
-    const dir = join6(worktreePath, ".pourkit", ".tmp", "reviewers");
-    yield* fs.mkdir(dir).pipe(Effect2.catchAll(() => Effect2.void));
-    yield* fs.writeFile(join6(dir, `iteration-${iteration}.md`), output).pipe(Effect2.catchAll(() => Effect2.void));
-  });
-}
-function buildRefactorPromptEffect(repoRoot2, promptTemplate, latestReview, artifactPathInWorktree, iteration, fs) {
-  return Effect2.gen(function* () {
-    const promptTemplatePath = resolvePromptTemplatePath(
-      repoRoot2,
-      promptTemplate
-    );
-    const exists = yield* fs.exists(promptTemplatePath).pipe(Effect2.orDie);
-    const promptBody = exists ? yield* fs.readFile(promptTemplatePath).pipe(Effect2.orDie) : promptTemplate;
-    const findingIds = extractLatestFindingIds(latestReview, iteration);
-    const findingArgs = findingIds.map((id) => ` --finding-id ${id}`).join("");
-    return appendProtectedWorkGuidance(`${promptBody}
-
-## Shared Run Context
-
-Read the selected issue requirements, planning context (including plan and PRD content when present), branch context, verification commands, and artifact paths from: ${RUN_CONTEXT_PATH_IN_WORKTREE}
-
-## Latest Review
-
-${latestReview.trimEnd()}
-
-## Output
-
-Write your refactor artifact to: ${artifactPathInWorktree}
-
-Before handoff, run: pourkit validate-artifact refactor ${artifactPathInWorktree} --iteration ${iteration}${findingArgs}
-
-When you are done, finish with <promise>COMPLETE</promise>.`);
-  });
-}
 
 // pr/pr-description.ts
 var CONVENTIONAL_TITLE_PATTERN = /^(feat|fix|perf|refactor|docs|test|chore|ci|build)(\([^)]+\))?!?:\s+\S/;
@@ -3183,6 +3260,12 @@ var ISSUE_FINAL_REVIEW_SCOPE_VERDICTS = [
   "incidental",
   "out-of-scope"
 ];
+var ISSUE_FINAL_REVIEW_VERIFICATION_METHODS = [
+  "wrapper",
+  "local-wrapper",
+  "commands",
+  "none"
+];
 function invalid(options, reason, diagnostics = []) {
   return {
     ok: false,
@@ -3490,6 +3573,15 @@ function validateIssueFinalReviewArtifact(parsed, options) {
       diagnostics
     };
   }
+  if ("method" in verification && !ISSUE_FINAL_REVIEW_VERIFICATION_METHODS.includes(
+    verification.method
+  )) {
+    return {
+      ok: false,
+      reason: 'verification.method must be "wrapper", "local-wrapper", "commands", or "none"',
+      diagnostics
+    };
+  }
   diagnostics.push("verification: present");
   const verificationWasRecorded = verification.required === true || Array.isArray(verification.commands) && verification.commands.length > 0;
   if (parsed.verdict === "pass" && verificationWasRecorded) {
@@ -3504,6 +3596,20 @@ function validateIssueFinalReviewArtifact(parsed, options) {
         ]
       };
     }
+    if (typeof verification.method !== "string") {
+      return {
+        ok: false,
+        reason: "Issue Final Review pass with verification evidence requires verification.method",
+        diagnostics
+      };
+    }
+    if (verification.method === "none") {
+      return {
+        ok: false,
+        reason: 'Issue Final Review pass with verification evidence requires verification.method other than "none"',
+        diagnostics
+      };
+    }
     diagnostics.push("pass verification: valid");
   }
   if (parsed.selfRetouched === true && parsed.verdict === "pass") {
@@ -3708,10 +3814,10 @@ init_common();
 import { Exit as Exit3 } from "effect";
 
 // failure-resolution/effect-runtime.ts
-import { Effect as Effect4 } from "effect";
+import { Effect as Effect5 } from "effect";
 
 // shared/effect-runtime.ts
-import { Effect as Effect3, Exit } from "effect";
+import { Effect as Effect4, Exit } from "effect";
 import { UnknownException } from "effect/Cause";
 var initialized = false;
 function initializeEffectRuntime() {
@@ -3720,7 +3826,7 @@ function initializeEffectRuntime() {
 }
 function runEffect(program) {
   ensureEffectRuntime();
-  return Effect3.runPromiseExit(program);
+  return Effect4.runPromiseExit(program);
 }
 function ensureEffectRuntime() {
   if (!initialized) {
@@ -3898,23 +4004,23 @@ function recordStageAttempt(worktreePath, record) {
 
 // failure-resolution/effect-runtime.ts
 function baseRefreshEffect(options) {
-  return Effect4.promise(() => refreshStaleIssueBranch(options)).pipe(
-    Effect4.flatMap(
+  return Effect5.promise(() => refreshStaleIssueBranch(options)).pipe(
+    Effect5.flatMap(
       (result) => {
         switch (result.status) {
           case "refreshed":
-            return Effect4.succeed({ status: "refreshed" });
+            return Effect5.succeed({ status: "refreshed" });
           case "skipped-current":
-            return Effect4.succeed({ status: "skipped-current" });
+            return Effect5.succeed({ status: "skipped-current" });
           case "conflicted":
-            return Effect4.fail(
+            return Effect5.fail(
               new RebaseConflict({
                 conflictedPaths: result.conflictedPaths,
                 message: result.message
               })
             );
           case "refused-published-history":
-            return Effect4.fail(
+            return Effect5.fail(
               new PublishedHistoryRisk({
                 prNumber: result.prNumber,
                 prState: result.prState
@@ -3929,8 +4035,8 @@ async function runBaseRefreshAttempt(options) {
   const attemptId = createStageAttemptId();
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   const program = baseRefreshEffect(options).pipe(
-    Effect4.tapBoth({
-      onSuccess: (success) => Effect4.sync(() => {
+    Effect5.tapBoth({
+      onSuccess: (success) => Effect5.sync(() => {
         recordStageAttempt(options.worktreePath, {
           id: attemptId,
           stage: "baseRefresh",
@@ -3939,7 +4045,7 @@ async function runBaseRefreshAttempt(options) {
           outcome: "success"
         });
       }),
-      onFailure: (failure) => Effect4.sync(() => {
+      onFailure: (failure) => Effect5.sync(() => {
         recordStageAttempt(options.worktreePath, {
           id: attemptId,
           stage: "baseRefresh",
@@ -4862,7 +4968,15 @@ function loadBuilderPrompt(repoRoot2, promptTemplate) {
 
 ## Shared Run Context
 
-Read the selected issue requirements, planning context (including plan and PRD content when present), comments, branch context, verification commands, and artifact paths from: ${RUN_CONTEXT_PATH_IN_WORKTREE}`);
+Read the selected issue requirements, planning context (including plan and PRD content when present), comments, branch context, verification commands, and artifact paths from: ${RUN_CONTEXT_PATH_IN_WORKTREE}
+
+## Verification Handoff
+
+- Run the verification wrapper listed in ${RUN_CONTEXT_PATH_IN_WORKTREE}.
+- If ${RUN_CONTEXT_PATH_IN_WORKTREE} provides a worktree-local CLI fallback, use that fallback before considering direct command execution.
+- Run underlying verification commands directly only when no wrapper path can run, and report why verification used direct commands.
+- If configured verification fails because of fixable Issue work, fix the work and rerun verification before handoff.
+- Failed or blocked verification prohibits <promise>COMPLETE</promise>.`);
 }
 async function syncRemoteBaseRef(worktreePath, baseRef, logger) {
   const remoteBase = parseRemoteBaseRef(baseRef);
@@ -4907,9 +5021,9 @@ import { readFileSync as readFileSync12 } from "fs";
 init_common();
 import { join as join10 } from "path";
 import { readFile } from "fs/promises";
-import { Effect as Effect5 } from "effect";
+import { Effect as Effect6 } from "effect";
 function collectFinalizerContextEffect(options) {
-  return Effect5.gen(function* () {
+  return Effect6.gen(function* () {
     const git = yield* GitOperations;
     const fs = yield* FileSystem;
     const remoteBase = remoteTargetBase(options.targetBase);
@@ -4922,8 +5036,8 @@ function collectFinalizerContextEffect(options) {
       ],
       { cwd: options.worktreePath }
     ).pipe(
-      Effect5.catchAll(
-        (error) => Effect5.fail(
+      Effect6.catchAll(
+        (error) => Effect6.fail(
           new Error(`Failed to collect commit range: ${error.message}`)
         )
       )
@@ -4938,9 +5052,9 @@ function collectFinalizerContextEffect(options) {
     let reviewArtifact;
     if (options.reviewArtifactPath) {
       const content = yield* fs.readFile(options.reviewArtifactPath).pipe(
-        Effect5.catchIf(
+        Effect6.catchIf(
           (error) => error.message.includes("ENOENT") || error.message.includes("no such file"),
-          () => Effect5.fail(
+          () => Effect6.fail(
             new Error(
               `Review artifact not found at ${options.reviewArtifactPath}. Ensure the review stage completed before running finalizer generation.`
             )
@@ -4948,7 +5062,7 @@ function collectFinalizerContextEffect(options) {
         )
       );
       if (!content.trim()) {
-        return yield* Effect5.fail(
+        return yield* Effect6.fail(
           new Error(
             `Review artifact at ${options.reviewArtifactPath} is empty. Ensure the review stage produced output before running finalizer generation.`
           )
@@ -5024,12 +5138,12 @@ Before handoff, run: pourkit validate-artifact finalizer ${artifactPathInWorktre
 }
 
 // commands/pr-description-agent.ts
-import { Effect as Effect6, Layer as Layer3 } from "effect";
+import { Effect as Effect7, Layer as Layer3 } from "effect";
 function bridgeExecutionProvider2(ep) {
   return Layer3.succeed(
     ExecutionProvider,
     ExecutionProvider.of({
-      execute: (opts) => Effect6.tryPromise({
+      execute: (opts) => Effect7.tryPromise({
         try: () => ep.execute(opts),
         catch: (e) => new Error(
           e instanceof Error ? e.message : `Execution failed: ${String(e)}`
@@ -5047,7 +5161,7 @@ function runFinalizerAgent(options) {
     "agent-output.md"
   );
   const artifactPath = join11(options.worktreePath, artifactPathInWorktree);
-  const program = Effect6.gen(function* () {
+  const program = Effect7.gen(function* () {
     const fs = yield* FileSystem;
     const context = yield* collectFinalizerContextEffect({
       targetBase: options.targetBaseBranch,
@@ -5056,8 +5170,8 @@ function runFinalizerAgent(options) {
       reviewArtifactPath: options.reviewArtifactPath,
       logger: options.logger
     }).pipe(
-      Effect6.catchAll(
-        (error) => Effect6.fail(
+      Effect7.catchAll(
+        (error) => Effect7.fail(
           new FinalizerFailure({
             message: `Failed to collect finalizer context: ${error.message}`
           })
@@ -5102,7 +5216,7 @@ function runFinalizerAgent(options) {
   });
   const executionLayer = bridgeExecutionProvider2(executionProvider);
   return program.pipe(
-    Effect6.provide(
+    Effect7.provide(
       Layer3.mergeAll(executionLayer, FileSystemDefault, GitOperationsDefault)
     )
   );
@@ -5112,11 +5226,11 @@ function runPrDescriptionFinalizerCore(options) {
     options.worktreePath,
     options.artifactPathInWorktree
   );
-  return Effect6.gen(function* () {
+  return Effect7.gen(function* () {
     let parsed;
     let lastValidationError;
     for (let protocolAttempt = 1; protocolAttempt <= options.maxAttempts; protocolAttempt++) {
-      const retryResult = yield* Effect6.tryPromise({
+      const retryResult = yield* Effect7.tryPromise({
         try: () => executeWithMissingOrEmptyArtifactRetry({
           executionProvider: options.executionProvider,
           missingOrEmptyRetries: resolveMissingOrEmptyOutputRetries(
@@ -5153,7 +5267,7 @@ function runPrDescriptionFinalizerCore(options) {
       });
       const executionResult = retryResult.executionResult;
       if (!executionResult.success) {
-        return yield* Effect6.fail(
+        return yield* Effect7.fail(
           new FinalizerFailure({
             message: `Finalizer agent execution failed: ${executionResult.error}`
           })
@@ -5191,7 +5305,7 @@ function runPrDescriptionFinalizerCore(options) {
       }
     }
     if (!parsed) {
-      return yield* Effect6.fail(
+      return yield* Effect7.fail(
         new FinalizerFailure({
           message: lastValidationError?.message ?? "Finalizer validation failed"
         })
@@ -5206,20 +5320,20 @@ function runPrDescriptionFinalizerCore(options) {
   });
 }
 function loadFinalizerPromptEffect(repoRoot2, promptTemplate, fs) {
-  return Effect6.gen(function* () {
+  return Effect7.gen(function* () {
     const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
-    const exists = yield* fs.exists(promptPath).pipe(Effect6.orDie);
+    const exists = yield* fs.exists(promptPath).pipe(Effect7.orDie);
     if (exists) {
-      return yield* fs.readFile(promptPath).pipe(Effect6.orDie);
+      return yield* fs.readFile(promptPath).pipe(Effect7.orDie);
     }
     return promptTemplate;
   });
 }
 function persistGeneratedArtifactEffect(worktreePath, output, fs) {
-  return Effect6.gen(function* () {
+  return Effect7.gen(function* () {
     const dir = join11(worktreePath, ".pourkit", ".tmp", "finalizer");
-    yield* fs.mkdir(dir).pipe(Effect6.catchAll(() => Effect6.void));
-    yield* fs.writeFile(join11(dir, "generated.md"), output).pipe(Effect6.catchAll(() => Effect6.void));
+    yield* fs.mkdir(dir).pipe(Effect7.catchAll(() => Effect7.void));
+    yield* fs.writeFile(join11(dir, "generated.md"), output).pipe(Effect7.catchAll(() => Effect7.void));
   });
 }
 
@@ -5559,7 +5673,7 @@ function secondsRemaining(deadline, observedAt) {
 }
 
 // issues/merge-coordinator.ts
-import { Effect as Effect7, Either } from "effect";
+import { Effect as Effect8, Either } from "effect";
 import { UnknownException as UnknownException2 } from "effect/Cause";
 function unwrapError2(error) {
   if (error instanceof UnknownException2 && error.error !== void 0) {
@@ -5578,9 +5692,9 @@ function runMergeCoordinator(options) {
   } = options;
   const method = options.method ?? "squash";
   const waitForTargetGreen = options.waitForTargetGreen ?? true;
-  return Effect7.gen(function* () {
-    const checksEither = yield* Effect7.either(
-      Effect7.tryPromise(
+  return Effect8.gen(function* () {
+    const checksEither = yield* Effect8.either(
+      Effect8.tryPromise(
         () => prProvider.waitForPrChecks(prNumber, checkWaitOptions)
       )
     );
@@ -5593,8 +5707,8 @@ function runMergeCoordinator(options) {
         error: error instanceof Error ? error : new Error(String(error))
       };
     }
-    const mergeEither = yield* Effect7.either(
-      Effect7.tryPromise(
+    const mergeEither = yield* Effect8.either(
+      Effect8.tryPromise(
         () => prProvider.mergePr(prNumber, { method, matchHeadCommit })
       )
     );
@@ -5608,8 +5722,8 @@ function runMergeCoordinator(options) {
       };
     }
     if (waitForTargetGreen) {
-      const targetEither = yield* Effect7.either(
-        Effect7.tryPromise(
+      const targetEither = yield* Effect8.either(
+        Effect8.tryPromise(
           () => waitForBranchChecks(prProvider, logger, {
             branchName: targetBranch,
             checksFoundTimeoutMs: checkWaitOptions.checksFoundTimeoutMs,
@@ -5808,6 +5922,9 @@ function buildIssueFinalReviewPrComment(artifact) {
       `- **Required:** ${formatBoolean(artifact.verification.required)}`,
       `- **Passed:** ${formatBoolean(artifact.verification.passed)}`
     );
+    if (typeof artifact.verification.method === "string") {
+      lines.push(`- **Method:** ${formatLabel(artifact.verification.method)}`);
+    }
     const commands = Array.isArray(artifact.verification.commands) ? artifact.verification.commands.filter(
       (command) => typeof command === "string"
     ) : [];
@@ -6005,7 +6122,7 @@ function findSecretLikeContent(source, content) {
   ];
   for (const { kind, regex } of patterns) {
     for (const match of content.matchAll(regex)) {
-      if (isAllowedSecretPlaceholder(match[0])) {
+      if (isAllowedSecretPlaceholder(match[0]) || isAllowedDocumentationTokenReference(match[0])) {
         continue;
       }
       findings.push({ source, kind });
@@ -6026,6 +6143,9 @@ function isAllowedSecretPlaceholder(value) {
     "xxxxx"
   ].some((allowed) => normalized.includes(allowed));
 }
+function isAllowedDocumentationTokenReference(value) {
+  return /^token\s*:\s*["']?<verdict>/i.test(value);
+}
 
 // commands/issue-final-review-agent.ts
 import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
@@ -6055,7 +6175,9 @@ async function runIssueFinalReviewAgent(options) {
   const prompt = loadIssueFinalReviewPrompt({
     repoRoot: repoRoot2,
     promptTemplate: agent.promptTemplate,
-    validationCommand: `pourkit validate-artifact issue-final-review ${artifactPathInWorktree} --issue-number ${issue.number} --branch-name ${builderBranch} --base-ref origin/${target.baseBranch}`
+    validationCommand: `pourkit validate-artifact issue-final-review ${artifactPathInWorktree} --issue-number ${issue.number} --branch-name ${builderBranch} --base-ref origin/${target.baseBranch}`,
+    reviewArtifactPath: options.reviewArtifactPath,
+    reviewVerdict: options.reviewVerdict
   });
   const entry = await executeWithMissingOrEmptyArtifactRetry({
     executionProvider,
@@ -6151,10 +6273,16 @@ function extractChangedPaths(parsed) {
   ).filter((path9) => typeof path9 === "string") : [];
 }
 function loadIssueFinalReviewPrompt(options) {
-  const { repoRoot: repoRoot2, promptTemplate, validationCommand } = options;
+  const {
+    repoRoot: repoRoot2,
+    promptTemplate,
+    validationCommand,
+    reviewArtifactPath,
+    reviewVerdict
+  } = options;
   const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
   const promptBody = existsSync12(promptPath) ? readFileSync14(promptPath, "utf-8") : promptTemplate;
-  return appendProtectedWorkGuidance(`${promptBody}
+  let prompt = appendProtectedWorkGuidance(`${promptBody}
 
 ## Shared Run Context
 
@@ -6163,8 +6291,10 @@ Read the selected issue requirements, planning context (including plan and PRD c
 ## Initial Verification Pass
 
 - First read ${RUN_CONTEXT_PATH_IN_WORKTREE} only far enough to identify the configured verification commands.
-- Before reviewing code, diffs, artifacts, or prior findings, run each configured verification command yourself from the Worktree.
-- Run the commands exactly as configured. Do not substitute narrower commands unless the configured command cannot run.
+- Before reviewing code, diffs, artifacts, or prior findings, run the verification wrapper from the Worktree.
+- If the installed Pourkit CLI rejects the worktree config schemaVersion and the Run Context provides a Pourkit self-development fallback, build and run the worktree-local CLI wrapper exactly as instructed.
+- Do not substitute direct underlying commands unless neither wrapper path can run; if you must use direct commands, record degraded verification with \`verification.method: "commands"\` and explain why in \`verification.summary\`.
+- Record successful wrapper verification with \`verification.method: "wrapper"\`, or worktree-local CLI wrapper verification with \`verification.method: "local-wrapper"\`.
 - If a configured verification command fails because of fixable Issue work, self-retouch the Worktree, then rerun all configured verification commands.
 - Do not return \`pass\` while any configured verification command is failing.
 - If a command cannot run because the environment is missing required setup, dependencies, or scripts outside agent control, treat it as a human handoff blocker.
@@ -6186,6 +6316,19 @@ Read the selected issue requirements, planning context (including plan and PRD c
 - This validation checks both the artifact shape and \`changedFiles\` coverage against the canonical Git diff.
 - If validation fails, fix the artifact or safely retouch the worktree as needed, then rerun the same command.
 - Do not finish until the validation command passes.`);
+  if (reviewVerdict) {
+    prompt += `
+
+## Prior Review Context
+
+- Reviewer Artifact Path: ${reviewArtifactPath}
+- Prior Review Verdict: ${reviewVerdict}`;
+    if (reviewVerdict === "PASS_WITH_NOTES") {
+      prompt += `
+- This Issue passed the prior Reviewer with notes. Read the Reviewer Artifact and inspect its notes before making your final pass decision.`;
+    }
+  }
+  return prompt;
 }
 
 // issues/issue-worktree-resolution.ts
@@ -6375,6 +6518,7 @@ async function advanceIssueFinalReview(options) {
     repoRoot: repoRoot2,
     logger,
     reviewArtifactPath,
+    reviewVerdict,
     worktreeState
   } = options;
   const ifrFromState = worktreeState?.issueFinalReview;
@@ -6415,6 +6559,7 @@ async function advanceIssueFinalReview(options) {
     repoRoot: repoRoot2,
     logger,
     reviewArtifactPath,
+    reviewVerdict,
     ...options.memory ? { memory: options.memory } : {}
   });
   await assertCanonicalBaseAncestor2({
@@ -6580,7 +6725,7 @@ async function fetchParentPrdIssue(issue, issueProvider) {
 async function advanceIssueRunReview(options) {
   const accumulatedRefactorPaths = [];
   const reviewResult = await runEffectAndMapExit(
-    runReviewWithRefactorLoop({
+    runIssueReviewLoop({
       ...options,
       onRefactorProgress: (progress) => {
         if (progress.refactorArtifactPath) {
@@ -6603,16 +6748,29 @@ async function advanceIssueRunReview(options) {
     stageName: "Review/Refactor",
     logger: options.logger
   });
-  updateWorktreeRunState(options.worktreePath, {
-    review: {
-      lifetimeIterations: reviewResult.lifetimeIterations,
-      lastVerdict: reviewResult.verdict,
-      lastArtifactPath: reviewResult.artifactPath,
-      refactorCompletedForLastReview: reviewResult.refactorCompletedForLastReview,
-      exhaustedPreviousRun: reviewResult.exhaustedMaxIterations || reviewResult.verdict === "FAIL" || void 0,
-      refactorArtifactPaths: accumulatedRefactorPaths.length > 0 ? accumulatedRefactorPaths : void 0
-    }
-  });
+  const commonFields = {
+    lifetimeIterations: reviewResult.lifetimeIterations,
+    lastArtifactPath: reviewResult.reviewArtifactPath,
+    refactorCompletedForLastReview: reviewResult.refactorCompletedForLastReview,
+    refactorArtifactPaths: accumulatedRefactorPaths.length > 0 ? accumulatedRefactorPaths : void 0
+  };
+  if (reviewResult.status === "passed" || reviewResult.status === "needs_human") {
+    updateWorktreeRunState(options.worktreePath, {
+      review: {
+        ...commonFields,
+        lastVerdict: reviewResult.reviewVerdict,
+        exhaustedPreviousRun: void 0
+      }
+    });
+  } else {
+    updateWorktreeRunState(options.worktreePath, {
+      review: {
+        ...commonFields,
+        lastVerdict: reviewResult.reviewVerdict,
+        exhaustedPreviousRun: true
+      }
+    });
+  }
   return reviewResult;
 }
 async function completeIssueRun(options) {
@@ -6810,14 +6968,14 @@ async function transitionIssueToHumanHandoff(options) {
   const transitions = makeIssueTransitions2(issueProvider, config);
   await transitions.moveToReadyForHuman(issueNumber);
   const summary = extractHumanHandoffSummary(reviewResult.output);
-  const refactorDir = getRefactorArtifactDir(reviewResult.artifactPath);
+  const refactorDir = getRefactorArtifactDir(reviewResult.reviewArtifactPath);
   const comment = [
     "Pourkit stopped the review/refactor loop because human input is needed.",
     "",
     summary,
     "",
     "Artifacts:",
-    `- Review: ${reviewResult.artifactPath}`,
+    `- Review: ${reviewResult.reviewArtifactPath}`,
     `- Refactors: ${refactorDir}`
   ].join("\n");
   await issueProvider.commentIssue(issueNumber, comment);
@@ -7035,8 +7193,10 @@ async function runIssueLifecycle(options) {
     const startResult = await options.deps.startIssueRun(options.runOptions);
     const reviewAlreadyPassed = startResult.worktreeState?.review.lastVerdict && !startResult.worktreeState.review.exhaustedPreviousRun && (startResult.worktreeState.review.lastVerdict === "PASS" || startResult.worktreeState.review.lastVerdict === "PASS_WITH_NOTES");
     let reviewArtifactPath;
+    let reviewVerdict = void 0;
     if (reviewAlreadyPassed) {
       reviewArtifactPath = startResult.worktreeState.review.lastArtifactPath;
+      reviewVerdict = startResult.worktreeState.review.lastVerdict;
     } else {
       const reviewResult = await options.deps.advanceIssueRunReview({
         executionProvider: options.runOptions.executionProvider,
@@ -7053,28 +7213,34 @@ async function runIssueLifecycle(options) {
         serena: startResult.serena,
         memory: startResult.memory
       });
-      if (reviewResult.exhaustedMaxIterations) {
-        throw new Error(
-          "Review loop exhausted maximum iterations without passing"
-        );
-      }
-      if (reviewResult.verdict === "FAIL") {
-        const summary = reviewResult.output?.trim() || "no summary provided";
-        throw new Error(`Review loop failed: ${summary}`);
-      }
-      if (reviewResult.verdict === "NEEDS_HUMAN") {
-        await options.deps.transitionReviewNeedsHumanToHandoff({
-          issueProvider: options.issueProvider,
-          issueNumber: options.issueNumber,
-          config: options.config,
-          logger: options.logger,
-          reviewResult
-        });
-        throw new IssueRunHumanHandoffStop(
-          "Review requires human handoff: NEEDS_HUMAN verdict"
-        );
+      switch (reviewResult.status) {
+        case "passed":
+          reviewArtifactPath = reviewResult.reviewArtifactPath;
+          reviewVerdict = reviewResult.reviewVerdict;
+          break;
+        case "needs_human":
+          await options.deps.transitionReviewNeedsHumanToHandoff({
+            issueProvider: options.issueProvider,
+            issueNumber: options.issueNumber,
+            config: options.config,
+            logger: options.logger,
+            reviewResult
+          });
+          throw new IssueRunHumanHandoffStop(
+            "Review requires human handoff: NEEDS_HUMAN verdict"
+          );
+        case "exhausted_max_iterations":
+          await options.deps.transitionReviewNeedsHumanToHandoff({
+            issueProvider: options.issueProvider,
+            issueNumber: options.issueNumber,
+            config: options.config,
+            logger: options.logger,
+            reviewResult
+          });
+          throw new IssueRunHumanHandoffStop(
+            "Review exhausted maximum iterations - requires human handoff"
+          );
       }
-      reviewArtifactPath = reviewResult.artifactPath;
     }
     const finalReviewResult = await options.deps.advanceIssueFinalReview({
       executionProvider: options.runOptions.executionProvider,
@@ -7087,6 +7253,7 @@ async function runIssueLifecycle(options) {
       repoRoot: options.repoRoot,
       logger: options.logger,
       reviewArtifactPath,
+      reviewVerdict,
       worktreeState: startResult.worktreeState,
       memory: startResult.memory
     });
@@ -7458,7 +7625,7 @@ import { Match, pipe } from "effect";
 
 // commands/queue.ts
 init_common();
-import { Effect as Effect8 } from "effect";
+import { Effect as Effect9 } from "effect";
 
 // issues/select-issue.ts
 init_common();
@@ -7631,8 +7798,8 @@ function issueDataToCandidate(issue) {
 function selectNextQueueIssue(options) {
   const { config, issueProvider, logger, prdRef } = options;
   logger.step("info", "Loading candidate issues from provider");
-  return Effect8.gen(function* () {
-    const candidates = yield* Effect8.tryPromise({
+  return Effect9.gen(function* () {
+    const candidates = yield* Effect9.tryPromise({
       try: () => issueProvider.listCandidates(),
       catch: (e) => {
         if (e instanceof Error) {
@@ -7703,7 +7870,7 @@ function selectNextQueueIssue(options) {
       (c) => c.number === selection.issue.number
     );
     if (!selected) {
-      return yield* Effect8.die(
+      return yield* Effect9.die(
         new Error(
           `Selected issue #${selection.issue.number} not found in candidate list`
         )
@@ -7758,8 +7925,8 @@ function makeReconcileDeps(options) {
   };
 }
 function reconcileBlockedEffect(options) {
-  return Effect8.gen(function* () {
-    const blocked2 = yield* Effect8.tryPromise({
+  return Effect9.gen(function* () {
+    const blocked2 = yield* Effect9.tryPromise({
       try: () => options.issueProvider.listBlockedIssues(),
       catch: (e) => {
         if (e instanceof Error) {
@@ -7773,7 +7940,7 @@ function reconcileBlockedEffect(options) {
         "info",
         `Reconciling ${blocked2.length} blocked issue(s)`
       );
-      yield* Effect8.tryPromise({
+      yield* Effect9.tryPromise({
         try: () => reconcileBlockedIssues(blocked2, makeReconcileDeps(options)),
         catch: (e) => {
           if (e instanceof Error) {
@@ -7797,7 +7964,7 @@ function runOneQueueIssueEffect(options) {
     repoRoot: repoRoot2,
     prdRef
   } = options;
-  return Effect8.gen(function* () {
+  return Effect9.gen(function* () {
     const outcome = yield* selectNextQueueIssue({
       config,
       issueProvider,
@@ -7813,7 +7980,7 @@ function runOneQueueIssueEffect(options) {
     }
     const { issue: selected } = outcome;
     const baseBranchOverride = options.queueRunContext?.prdBranch;
-    const runResult = yield* Effect8.tryPromise({
+    const runResult = yield* Effect9.tryPromise({
       try: () => runIssueCommand({
         issueNumber: selected.number,
         targetName,
@@ -7853,7 +8020,7 @@ function runQueue(options) {
   return runOneQueueIssueEffect(options);
 }
 function runQueueLoopEffect(options, results) {
-  return Effect8.gen(function* () {
+  return Effect9.gen(function* () {
     yield* reconcileBlockedEffect(options);
     const outcome = yield* runOneQueueIssueEffect(options);
     if (outcome.selected === null) {
@@ -7870,7 +8037,7 @@ function runQueueLoopEffect(options, results) {
       };
     }
     const newResults = [...results, outcome];
-    const processedIssue = yield* Effect8.tryPromise({
+    const processedIssue = yield* Effect9.tryPromise({
       try: () => options.issueProvider.fetchIssue(outcome.selected.number),
       catch: (e) => {
         if (e instanceof Error) {
@@ -10225,8 +10392,7 @@ function generateConfigTemplate(options) {
           model: "opencode-go/qwen3.6-plus",
           promptTemplate: ".pourkit/managed/prompts/refactor.prompt.md"
         },
-        maxIterations: 3,
-        passWithNotesRefactorAttempts: 2
+        maxIterations: 3
       },
       issueFinalReview: {
         agent: "pourkit-reviewer",
@@ -10256,7 +10422,7 @@ function generateConfigTemplate(options) {
   }
   const config = {
     $schema: "./schema/pourkit.schema.json",
-    schemaVersion: 2,
+    schemaVersion: 3,
     targets: [target],
     workflowPack: {
       version: "1.0.0",
@@ -15454,11 +15620,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260621094003")) {
-    return "0.0.0-next-20260621094003";
+  if (isPackageVersion("0.0.0-next-20260621233457")) {
+    return "0.0.0-next-20260621233457";
   }
-  if (isReleaseVersion("0.0.0-next-20260621094003")) {
-    return "0.0.0-next-20260621094003";
+  if (isReleaseVersion("0.0.0-next-20260621233457")) {
+    return "0.0.0-next-20260621233457";
   }
   try {
     const root = repoRoot();