@pourkit/cli 0.0.0-next-20260622055621 → 0.0.0-next-20260622235247

package/dist/cli.js

@@ -3740,10 +3740,6 @@ function shellQuote(value) {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 
-// commands/issue-run.ts
-import { existsSync as existsSync13, readFileSync as readFileSync15 } from "fs";
-import { isAbsolute as isAbsolute4, join as join15 } from "path";
-
 // pr/templates.ts
 init_common();
 function renderBranchName(template, issue) {
@@ -4960,9 +4956,9 @@ async function assertCanonicalBaseAncestor(options) {
   }
 }
 
-// commands/pr-description-agent.ts
-import { join as join11 } from "path";
-import { readFileSync as readFileSync12 } from "fs";
+// issues/pr-description-agent.ts
+import { existsSync as existsSync12, readFileSync as readFileSync13 } from "fs";
+import { isAbsolute as isAbsolute4, join as join12 } from "path";
 
 // pr/pr-description-context.ts
 init_common();
@@ -5084,204 +5080,323 @@ Write your finalizer output to: ${artifactPathInWorktree}
 Before handoff, run: pourkit validate-artifact finalizer ${artifactPathInWorktree}`;
 }
 
-// commands/pr-description-agent.ts
-import { Effect as Effect7, Layer as Layer3 } from "effect";
-function bridgeExecutionProvider2(ep) {
-  return Layer3.succeed(
-    ExecutionProvider,
-    ExecutionProvider.of({
-      execute: (opts) => Effect7.tryPromise({
-        try: () => ep.execute(opts),
-        catch: (e) => new Error(
-          e instanceof Error ? e.message : `Execution failed: ${String(e)}`
-        )
-      })
-    })
-  );
-}
-function runFinalizerAgent(options) {
-  const { executionProvider } = options;
-  const artifactPathInWorktree = join11(
-    ".pourkit",
-    ".tmp",
-    "finalizer",
-    "agent-output.md"
-  );
-  const artifactPath = join11(options.worktreePath, artifactPathInWorktree);
-  const program = Effect7.gen(function* () {
-    const fs = yield* FileSystem;
-    const context = yield* collectFinalizerContextEffect({
-      targetBase: options.targetBaseBranch,
-      branchName: options.builderBranch,
-      worktreePath: options.worktreePath,
-      reviewArtifactPath: options.reviewArtifactPath,
-      logger: options.logger
-    }).pipe(
-      Effect7.catchAll(
-        (error) => Effect7.fail(
-          new FinalizerFailure({
-            message: `Failed to collect finalizer context: ${error.message}`
-          })
-        )
-      )
-    );
-    const strategy = options.target.strategy;
-    const finalizer = strategy.finalize.prDescriptionAgent;
-    const resolvedPrompt = yield* loadFinalizerPromptEffect(
-      options.repoRoot,
-      finalizer.promptTemplate,
-      fs
-    );
-    const prompt = buildFinalizerPrompt(context, resolvedPrompt);
-    const result = yield* runPrDescriptionFinalizerCore({
-      executionProvider: options.executionProvider,
-      config: options.config,
-      target: options.target,
-      finalizer,
-      maxAttempts: strategy.finalize.maxAttempts,
+// issues/issue-final-review.ts
+import { existsSync as existsSync11, readFileSync as readFileSync12 } from "fs";
+import { isAbsolute as isAbsolute3, join as join11 } from "path";
+init_common();
+var ISSUE_FINAL_REVIEW_ARTIFACT_PATH = join11(
+  ".pourkit",
+  ".tmp",
+  "issue-final-review",
+  "agent-output.json"
+);
+async function runIssueFinalReview(options) {
+  const {
+    executionProvider,
+    target,
+    issue,
+    parentPrdIssue,
+    builderBranch,
+    worktreePath,
+    repoRoot: repoRoot2,
+    logger
+  } = options;
+  const artifactPathInWorktree = ISSUE_FINAL_REVIEW_ARTIFACT_PATH;
+  const artifactPath = join11(worktreePath, artifactPathInWorktree);
+  const ifrFromState = options.worktreeState?.issueFinalReview;
+  if (ifrFromState?.completed && ifrFromState.verdict === "pass") {
+    if (!ifrFromState.artifactPath) {
+      throw new Error(
+        "Issue Final Review state is incomplete: missing artifactPath"
+      );
+    }
+    const cachedArtifactPath = isAbsolute3(ifrFromState.artifactPath) ? ifrFromState.artifactPath : join11(worktreePath, ifrFromState.artifactPath);
+    const validation2 = validateAgentArtifact({
+      kind: "issue-final-review",
+      artifactPath: cachedArtifactPath,
+      issueNumber: issue.number,
+      branchName: builderBranch
+    });
+    if (!validation2.ok) {
+      throw new Error(
+        `Issue Final Review state artifact is invalid: ${validation2.reason}`
+      );
+    }
+    return {
+      status: "skipped",
+      verdict: "pass",
+      artifactPath: cachedArtifactPath,
+      selfRetouched: ifrFromState.selfRetouched ?? false,
+      changedPaths: ifrFromState.changedPaths ?? [],
+      verificationPassed: ifrFromState.verificationPassed ?? false
+    };
+  }
+  const strategy = target.strategy;
+  const issueFinalReview = strategy.issueFinalReview;
+  const agent = issueFinalReview;
+  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}`,
+    reviewArtifactPath: options.reviewArtifactPath,
+    reviewVerdict: options.reviewVerdict
+  });
+  const entry = await executeWithMissingOrEmptyArtifactRetry({
+    executionProvider,
+    missingOrEmptyRetries: resolveMissingOrEmptyOutputRetries(agent),
+    logger,
+    runningMessage: () => "Running Issue Final Review agent",
+    retryMessage: (attempt, total) => `Retrying Issue Final Review after empty output (${attempt}/${total})`,
+    executionOptions: {
+      stage: "issueFinalReview",
+      agent: agent.agent,
+      model: agent.model,
+      variant: agent.variant,
+      env: agent.env,
       prompt,
-      branchName: options.builderBranch,
-      repoRoot: options.repoRoot,
-      worktreePath: options.worktreePath,
-      artifactPathInWorktree,
-      commitSummaries: context.commits,
+      target,
+      repoRoot: repoRoot2,
+      branchName: builderBranch,
+      sandbox: options.config.sandbox,
+      autoApprove: true,
+      artifactPath: artifactPathInWorktree,
+      worktreePath,
       artifacts: [
         buildRunContextArtifact({
-          issue: options.issue,
-          target: options.target,
-          branchName: options.builderBranch,
+          issue,
+          parentPrdIssue,
+          target,
+          branchName: builderBranch,
+          repoRoot: repoRoot2,
           reviewerCriteria: strategy.review.reviewer.criteria,
-          sections: STAGE_SECTIONS.finalizer
+          sections: STAGE_SECTIONS.issueFinalReview
         })
       ],
-      logger: options.logger,
-      ...options.memory ? { memory: options.memory } : {}
-    });
-    const output = readFileSync12(artifactPath, "utf-8");
-    yield* persistGeneratedArtifactEffect(options.worktreePath, output, fs);
-    return result;
+      ...options.memory ? { memory: options.memory } : {},
+      logger
+    }
   });
-  const executionLayer = bridgeExecutionProvider2(executionProvider);
-  return program.pipe(
-    Effect7.provide(
-      Layer3.mergeAll(executionLayer, FileSystemDefault, GitOperationsDefault)
-    )
+  const executionResult = entry.executionResult;
+  if (!executionResult.success) {
+    throw new Error(
+      `Issue Final Review agent execution failed: ${executionResult.error}`
+    );
+  }
+  let content;
+  if (entry.artifact._tag === "content") {
+    content = entry.artifact.value;
+  } else if (entry.artifact._tag === "empty") {
+    throw new Error(
+      `Issue Final Review agent produced empty output at ${artifactPath}`
+    );
+  } else {
+    throw new Error(
+      `Issue Final Review agent did not produce output at ${artifactPath}`
+    );
+  }
+  const validation = validateAgentArtifact({
+    kind: "issue-final-review",
+    artifactPath,
+    issueNumber: issue.number,
+    branchName: builderBranch
+  });
+  if (!validation.ok) {
+    throw new Error(
+      `Issue Final Review artifact validation failed: ${validation.reason}`
+    );
+  }
+  const parsed = JSON.parse(content);
+  const verdict = parsed.verdict;
+  const baseRef = `origin/${target.baseBranch}`;
+  await assertCanonicalBaseAncestor2({
+    worktreePath,
+    baseRef,
+    stageName: "Issue Final Review",
+    logger
+  });
+  if (verdict === "pass") {
+    const changedPaths = await completeIssueFinalReviewChangedPaths({
+      worktreePath,
+      baseRef,
+      declaredChangedPaths: extractChangedPaths(parsed),
+      logger
+    });
+    updateWorktreeRunState(worktreePath, {
+      issueFinalReview: {
+        completed: true,
+        verdict: "pass",
+        artifactPath,
+        selfRetouched: parsed.selfRetouched === true,
+        changedPaths,
+        verificationPassed: parsed.verification?.passed === true
+      }
+    });
+    return {
+      status: "passed",
+      verdict: "pass",
+      artifactPath,
+      selfRetouched: parsed.selfRetouched === true,
+      changedPaths,
+      verificationPassed: parsed.verification?.passed === true
+    };
+  }
+  if (verdict === "needs_human_review") {
+    return {
+      status: "needs_human_review",
+      verdict: "needs_human_review",
+      artifactPath,
+      needsHumanReason: parsed.needsHumanReason,
+      selfRetouched: parsed.selfRetouched === true,
+      changedPaths: extractChangedPaths(parsed)
+    };
+  }
+  throw new Error(
+    `Unknown Issue Final Review verdict: ${JSON.stringify(verdict)}`
   );
 }
-function runPrDescriptionFinalizerCore(options) {
-  const artifactPath = join11(
-    options.worktreePath,
-    options.artifactPathInWorktree
-  );
-  return Effect7.gen(function* () {
-    let parsed;
-    let lastValidationError;
-    for (let protocolAttempt = 1; protocolAttempt <= options.maxAttempts; protocolAttempt++) {
-      const retryResult = yield* Effect7.tryPromise({
-        try: () => executeWithMissingOrEmptyArtifactRetry({
-          executionProvider: options.executionProvider,
-          missingOrEmptyRetries: resolveMissingOrEmptyOutputRetries(
-            options.finalizer
-          ),
-          logger: options.logger,
-          runningMessage: () => `Running finalizer agent (${protocolAttempt}/${options.maxAttempts})`,
-          retryMessage: (attempt, total) => `Retrying finalizer after empty output (${attempt}/${total})`,
-          executionOptions: {
-            stage: "finalizer",
-            agent: options.finalizer.agent,
-            model: options.finalizer.model,
-            variant: options.finalizer.variant,
-            env: options.finalizer.env,
-            prompt: options.prompt,
-            target: options.target,
-            repoRoot: options.repoRoot,
-            branchName: options.branchName,
-            sandbox: options.config.sandbox,
-            autoApprove: true,
-            artifactPath: options.artifactPathInWorktree,
-            worktreePath: options.worktreePath,
-            artifacts: options.artifacts,
-            baseRef: options.baseRef,
-            checkoutBase: options.checkoutBase,
-            reviewBase: options.reviewBase,
-            ...options.memory ? { memory: options.memory } : {},
-            logger: options.logger
-          }
-        }),
-        catch: (error) => new FinalizerFailure({
-          message: error instanceof Error ? error.message : String(error)
-        })
-      });
-      const executionResult = retryResult.executionResult;
-      if (!executionResult.success) {
-        return yield* Effect7.fail(
-          new FinalizerFailure({
-            message: `Finalizer agent execution failed: ${executionResult.error}`
-          })
-        );
-      }
-      if (retryResult.artifact._tag === "content") {
-        const validation = validateAgentArtifact({
-          kind: "finalizer",
-          artifactPath
-        });
-        if (validation.ok) {
-          try {
-            parsed = parsePrDescription(retryResult.artifact.value);
-            lastValidationError = void 0;
-            break;
-          } catch (error) {
-            lastValidationError = error instanceof PrDescriptionProtocolError ? new Error(`Finalizer protocol error: ${error.message}`) : error instanceof Error ? error : new Error(String(error));
-          }
-        } else {
-          lastValidationError = new Error(
-            `Finalizer protocol error: ${validation.reason}`
-          );
-          if (protocolAttempt === options.maxAttempts) break;
-        }
-      } else if (retryResult.artifact._tag === "empty") {
-        lastValidationError = new Error(
-          `Finalizer agent produced empty output at ${artifactPath}`
-        );
-        break;
-      } else {
-        lastValidationError = new Error(
-          `Finalizer agent did not produce output at ${artifactPath}`
-        );
-        break;
-      }
-    }
-    if (!parsed) {
-      return yield* Effect7.fail(
-        new FinalizerFailure({
-          message: lastValidationError?.message ?? "Finalizer validation failed"
-        })
-      );
-    }
-    options.logger.step("info", "Finalizer output generated successfully");
-    return {
-      title: ensureConventionalPrTitle(parsed.title, options.commitSummaries),
-      body: parsed.body,
-      artifactPath
-    };
+async function assertCanonicalBaseAncestor2(options) {
+  const { worktreePath, baseRef, stageName, logger } = options;
+  await syncRemoteBaseRef2(worktreePath, baseRef, logger);
+  try {
+    await execCapture("git", ["merge-base", "--is-ancestor", baseRef, "HEAD"], {
+      cwd: worktreePath,
+      logger,
+      label: "git merge-base --is-ancestor"
+    });
+  } catch {
+    throw new Error(
+      `Cannot continue after ${stageName}: ${baseRef} is not an ancestor of HEAD. An agent may have moved the issue branch behind the canonical base; refresh the branch onto the latest target base before continuing.`
+    );
+  }
+}
+async function syncRemoteBaseRef2(worktreePath, baseRef, logger) {
+  const remoteBase = parseRemoteBaseRef2(baseRef);
+  if (!remoteBase) {
+    return;
+  }
+  await execCapture("git", ["fetch", remoteBase.remote, remoteBase.branch], {
+    cwd: worktreePath,
+    logger,
+    label: "git fetch target"
   });
 }
-function loadFinalizerPromptEffect(repoRoot2, promptTemplate, fs) {
-  return Effect7.gen(function* () {
-    const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
-    const exists = yield* fs.exists(promptPath).pipe(Effect7.orDie);
-    if (exists) {
-      return yield* fs.readFile(promptPath).pipe(Effect7.orDie);
+function parseRemoteBaseRef2(baseRef) {
+  const [remote, ...branchParts] = baseRef.split("/");
+  const branch = branchParts.join("/");
+  if (!remote || !branch) {
+    return null;
+  }
+  return { remote, branch };
+}
+async function completeIssueFinalReviewChangedPaths(options) {
+  const actualChangedPaths = await listIssueFinalReviewChangedPaths2(options);
+  const declared = new Set(options.declaredChangedPaths.map(normalizeGitPath2));
+  const missing = actualChangedPaths.filter((path9) => !declared.has(path9));
+  if (missing.length === 0) {
+    return actualChangedPaths;
+  }
+  options.logger.step(
+    "warn",
+    `Issue Final Review pass omitted ${missing.length} changed file(s) from changedFiles; using git inventory for finalization state.`
+  );
+  options.logger.kv("MISSING_CHANGED_FILES", missing.join(", "));
+  return actualChangedPaths;
+}
+async function listIssueFinalReviewChangedPaths2(options) {
+  const trackedDiff = await execCapture(
+    "git",
+    ["diff-index", "--name-only", options.baseRef, "--"],
+    {
+      cwd: options.worktreePath,
+      logger: options.logger,
+      label: "git diff-index Issue Final Review paths"
     }
-    return promptTemplate;
-  });
+  );
+  const untrackedFiles = await execCapture(
+    "git",
+    ["ls-files", "--others", "--exclude-standard"],
+    {
+      cwd: options.worktreePath,
+      logger: options.logger,
+      label: "git ls-files Issue Final Review paths"
+    }
+  );
+  return Array.from(
+    /* @__PURE__ */ new Set([
+      ...parseGitPathList2(trackedDiff.stdout),
+      ...parseGitPathList2(untrackedFiles.stdout)
+    ])
+  ).filter(isIssueFinalReviewAuditedPath2);
 }
-function persistGeneratedArtifactEffect(worktreePath, output, fs) {
-  return Effect7.gen(function* () {
-    const dir = join11(worktreePath, ".pourkit", ".tmp", "finalizer");
-    yield* fs.mkdir(dir).pipe(Effect7.catchAll(() => Effect7.void));
-    yield* fs.writeFile(join11(dir, "generated.md"), output).pipe(Effect7.catchAll(() => Effect7.void));
-  });
+function parseGitPathList2(output) {
+  return output.split(/\r?\n/).map(normalizeGitPath2).filter((path9) => path9.length > 0);
+}
+function normalizeGitPath2(path9) {
+  return path9.replace(/^"|"$/g, "").replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
+}
+function isIssueFinalReviewAuditedPath2(path9) {
+  return path9 !== "" && path9 !== WORKTREE_RUN_STATE_PATH && !path9.startsWith(".pourkit/.tmp/") && !path9.startsWith(".pourkit/logs/");
+}
+function extractChangedPaths(parsed) {
+  return Array.isArray(parsed.changedFiles) ? parsed.changedFiles.map(
+    (file) => file && typeof file === "object" ? file.path : void 0
+  ).filter((path9) => typeof path9 === "string") : [];
+}
+function loadIssueFinalReviewPrompt(options) {
+  const {
+    repoRoot: repoRoot2,
+    promptTemplate,
+    validationCommand,
+    reviewArtifactPath,
+    reviewVerdict
+  } = options;
+  const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
+  const promptBody = existsSync11(promptPath) ? readFileSync12(promptPath, "utf-8") : promptTemplate;
+  let prompt = appendProtectedWorkGuidance(`${promptBody}
+
+## 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}
+
+## 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 verification wrapper from the Worktree.
+- Do not substitute direct underlying commands unless no wrapper path can run; if you must use direct commands, explain why in \`verification.summary\`.
+- 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.
+- If no verification commands are configured, note that and proceed with normal review.
+
+## Changed Files Audit
+
+- Read the Branch section of ${RUN_CONTEXT_PATH_IN_WORKTREE} and use its Canonical Base Ref for the changed-file inventory.
+- Before writing \`changedFiles\`, run \`git diff-index --name-only <canonical-base-ref> --\` from the Worktree to enumerate tracked files changed by the Issue.
+- Also run \`git ls-files --others --exclude-standard\` from the Worktree to enumerate untracked files changed by the Issue.
+- Treat the union of those command outputs, excluding only \`.pourkit/.tmp/**\`, \`.pourkit/logs/**\`, and \`.pourkit/state.json\`, as the required \`changedFiles\` inventory.
+- Include every file from that inventory in \`changedFiles\`, including generated files, managed operating assets, docs, prompts, schema files, and large batches.
+- If any file from the inventory is out-of-scope, mark it \`out-of-scope\` and either self-retouch it away or return \`needs_human_review\`; do not omit it.
+- Do not return \`pass\` until \`changedFiles\` covers the full inventory.
+
+## Required Artifact Validation
+
+- Before handoff, run exactly: \`${validationCommand}\`
+- 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;
 }
 
 // pr/pr-body.ts
@@ -5352,10 +5467,281 @@ function extractClosingRefs(body) {
   return refs;
 }
 
+// issues/pr-description-agent.ts
+import { Effect as Effect7, Layer as Layer3 } from "effect";
+function bridgeExecutionProvider2(ep) {
+  return Layer3.succeed(
+    ExecutionProvider,
+    ExecutionProvider.of({
+      execute: (opts) => Effect7.tryPromise({
+        try: () => ep.execute(opts),
+        catch: (e) => new Error(
+          e instanceof Error ? e.message : `Execution failed: ${String(e)}`
+        )
+      })
+    })
+  );
+}
+function loadFinalizerPromptEffect(repoRoot2, promptTemplate, fs) {
+  return Effect7.gen(function* () {
+    const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
+    const exists = yield* fs.exists(promptPath).pipe(Effect7.orDie);
+    if (exists) {
+      return yield* fs.readFile(promptPath).pipe(Effect7.orDie);
+    }
+    return promptTemplate;
+  });
+}
+function persistGeneratedArtifactEffect(worktreePath, output, fs) {
+  return Effect7.gen(function* () {
+    const dir = join12(worktreePath, ".pourkit", ".tmp", "finalizer");
+    yield* fs.mkdir(dir).pipe(Effect7.catchAll(() => Effect7.void));
+    yield* fs.writeFile(join12(dir, "generated.md"), output).pipe(Effect7.catchAll(() => Effect7.void));
+  });
+}
+function runPrDescriptionAgent(options) {
+  const { executionProvider } = options;
+  const artifactPathInWorktree = join12(
+    ".pourkit",
+    ".tmp",
+    "finalizer",
+    "agent-output.md"
+  );
+  const artifactPath = join12(options.worktreePath, artifactPathInWorktree);
+  const finalizerFromState = options.worktreeState?.finalizer?.completed ? options.worktreeState.finalizer : null;
+  if (finalizerFromState) {
+    return Effect7.gen(function* () {
+      if (!finalizerFromState.artifactPath) {
+        return yield* Effect7.fail(
+          new FinalizerFailure({
+            message: "Finalizer artifact missing: artifactPath not set in completed finalizer state"
+          })
+        );
+      }
+      const resolvedArtifactPath = isAbsolute4(finalizerFromState.artifactPath) ? finalizerFromState.artifactPath : join12(options.worktreePath, finalizerFromState.artifactPath);
+      if (!existsSync12(resolvedArtifactPath)) {
+        return yield* Effect7.fail(
+          new FinalizerFailure({
+            message: `Finalizer artifact missing: the artifact does not exist at \`${resolvedArtifactPath}\``
+          })
+        );
+      }
+      const validation = validateAgentArtifact({
+        kind: "finalizer",
+        artifactPath: resolvedArtifactPath
+      });
+      if (!validation.ok) {
+        return yield* Effect7.fail(
+          new FinalizerFailure({
+            message: `Finalizer state artifact is invalid: ${validation.reason}`
+          })
+        );
+      }
+      if (!finalizerFromState.title || !finalizerFromState.body) {
+        return yield* Effect7.fail(
+          new FinalizerFailure({
+            message: "Finalizer state is incomplete: missing stored title or body"
+          })
+        );
+      }
+      return {
+        status: "skipped",
+        title: finalizerFromState.title,
+        body: finalizerFromState.body,
+        artifactPath: resolvedArtifactPath
+      };
+    });
+  }
+  const program = Effect7.gen(function* () {
+    const fs = yield* FileSystem;
+    const context = yield* collectFinalizerContextEffect({
+      targetBase: options.targetBaseBranch,
+      branchName: options.builderBranch,
+      worktreePath: options.worktreePath,
+      reviewArtifactPath: options.reviewArtifactPath,
+      logger: options.logger
+    }).pipe(
+      Effect7.catchAll(
+        (error) => Effect7.fail(
+          new FinalizerFailure({
+            message: `Failed to collect finalizer context: ${error.message}`
+          })
+        )
+      )
+    );
+    const strategy = options.target.strategy;
+    const finalizer = strategy.finalize.prDescriptionAgent;
+    const resolvedPrompt = yield* loadFinalizerPromptEffect(
+      options.repoRoot,
+      finalizer.promptTemplate,
+      fs
+    );
+    const prompt = buildFinalizerPrompt(context, resolvedPrompt);
+    const result = yield* runPrDescriptionFinalizerCore({
+      executionProvider: options.executionProvider,
+      config: options.config,
+      target: options.target,
+      finalizer,
+      maxAttempts: strategy.finalize.maxAttempts,
+      prompt,
+      branchName: options.builderBranch,
+      repoRoot: options.repoRoot,
+      worktreePath: options.worktreePath,
+      artifactPathInWorktree,
+      commitSummaries: context.commits,
+      artifacts: [
+        buildRunContextArtifact({
+          issue: options.issue,
+          target: options.target,
+          branchName: options.builderBranch,
+          reviewerCriteria: strategy.review.reviewer.criteria,
+          sections: STAGE_SECTIONS.finalizer
+        })
+      ],
+      logger: options.logger,
+      ...options.memory ? { memory: options.memory } : {}
+    });
+    const output = readFileSync13(artifactPath, "utf-8");
+    yield* persistGeneratedArtifactEffect(options.worktreePath, output, fs);
+    const body = ensureClosingRefs(result.body, options.issue.number);
+    yield* Effect7.tryPromise({
+      try: () => assertCanonicalBaseAncestor2({
+        worktreePath: options.worktreePath,
+        baseRef: `origin/${options.targetBaseBranch}`,
+        stageName: "Finalizer",
+        logger: options.logger
+      }),
+      catch: (error) => new FinalizerFailure({
+        message: error instanceof Error ? error.message : String(error)
+      })
+    });
+    yield* Effect7.sync(() => {
+      updateWorktreeRunState(options.worktreePath, {
+        finalizer: {
+          completed: true,
+          artifactPath: result.artifactPath,
+          title: result.title,
+          body
+        }
+      });
+    });
+    return {
+      status: "completed",
+      title: result.title,
+      body,
+      artifactPath: result.artifactPath
+    };
+  });
+  const executionLayer = bridgeExecutionProvider2(executionProvider);
+  return program.pipe(
+    Effect7.provide(
+      Layer3.mergeAll(executionLayer, FileSystemDefault, GitOperationsDefault)
+    )
+  );
+}
+function runPrDescriptionFinalizerCore(options) {
+  const artifactPath = join12(
+    options.worktreePath,
+    options.artifactPathInWorktree
+  );
+  return Effect7.gen(function* () {
+    let parsed;
+    let lastValidationError;
+    for (let protocolAttempt = 1; protocolAttempt <= options.maxAttempts; protocolAttempt++) {
+      const retryResult = yield* Effect7.tryPromise({
+        try: () => executeWithMissingOrEmptyArtifactRetry({
+          executionProvider: options.executionProvider,
+          missingOrEmptyRetries: resolveMissingOrEmptyOutputRetries(
+            options.finalizer
+          ),
+          logger: options.logger,
+          runningMessage: () => `Running finalizer agent (${protocolAttempt}/${options.maxAttempts})`,
+          retryMessage: (attempt, total) => `Retrying finalizer after empty output (${attempt}/${total})`,
+          executionOptions: {
+            stage: "finalizer",
+            agent: options.finalizer.agent,
+            model: options.finalizer.model,
+            variant: options.finalizer.variant,
+            env: options.finalizer.env,
+            prompt: options.prompt,
+            target: options.target,
+            repoRoot: options.repoRoot,
+            branchName: options.branchName,
+            sandbox: options.config.sandbox,
+            autoApprove: true,
+            artifactPath: options.artifactPathInWorktree,
+            worktreePath: options.worktreePath,
+            artifacts: options.artifacts,
+            baseRef: options.baseRef,
+            checkoutBase: options.checkoutBase,
+            reviewBase: options.reviewBase,
+            ...options.memory ? { memory: options.memory } : {},
+            logger: options.logger
+          }
+        }),
+        catch: (error) => new FinalizerFailure({
+          message: error instanceof Error ? error.message : String(error)
+        })
+      });
+      const executionResult = retryResult.executionResult;
+      if (!executionResult.success) {
+        return yield* Effect7.fail(
+          new FinalizerFailure({
+            message: `Finalizer agent execution failed: ${executionResult.error}`
+          })
+        );
+      }
+      if (retryResult.artifact._tag === "content") {
+        const validation = validateAgentArtifact({
+          kind: "finalizer",
+          artifactPath
+        });
+        if (validation.ok) {
+          try {
+            parsed = parsePrDescription(retryResult.artifact.value);
+            lastValidationError = void 0;
+            break;
+          } catch (error) {
+            lastValidationError = error instanceof PrDescriptionProtocolError ? new Error(`Finalizer protocol error: ${error.message}`) : error instanceof Error ? error : new Error(String(error));
+          }
+        } else {
+          lastValidationError = new Error(
+            `Finalizer protocol error: ${validation.reason}`
+          );
+          if (protocolAttempt === options.maxAttempts) break;
+        }
+      } else if (retryResult.artifact._tag === "empty") {
+        lastValidationError = new Error(
+          `Finalizer agent produced empty output at ${artifactPath}`
+        );
+        break;
+      } else {
+        lastValidationError = new Error(
+          `Finalizer agent did not produce output at ${artifactPath}`
+        );
+        break;
+      }
+    }
+    if (!parsed) {
+      return yield* Effect7.fail(
+        new FinalizerFailure({
+          message: lastValidationError?.message ?? "Finalizer validation failed"
+        })
+      );
+    }
+    options.logger.step("info", "Finalizer output generated successfully");
+    return {
+      title: ensureConventionalPrTitle(parsed.title, options.commitSummaries),
+      body: parsed.body,
+      artifactPath
+    };
+  });
+}
+
 // issues/github-issue-publication.ts
 init_common();
-import { existsSync as existsSync11, readFileSync as readFileSync13 } from "fs";
-import { isAbsolute as isAbsolute3, join as join12 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "fs";
+import { isAbsolute as isAbsolute5, join as join13 } from "path";
 
 // issues/issue-transitions.ts
 function createIssueTransitions(deps, labels) {
@@ -5830,11 +6216,11 @@ function readIssueFinalReviewArtifact(worktreeState, worktreePath) {
   if (!configuredPath) {
     return null;
   }
-  const artifactPath = isAbsolute3(configuredPath) ? configuredPath : join12(worktreePath, configuredPath);
-  if (!existsSync11(artifactPath)) return null;
+  const artifactPath = isAbsolute5(configuredPath) ? configuredPath : join13(worktreePath, configuredPath);
+  if (!existsSync13(artifactPath)) return null;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync13(artifactPath, "utf-8"));
+    parsed = JSON.parse(readFileSync14(artifactPath, "utf-8"));
   } catch {
     return null;
   }
@@ -6034,243 +6420,61 @@ function assertNoSecretLikeContent(inputs) {
   }
   const summary = findings.slice(0, 5).map((finding) => `${finding.source}: ${finding.kind}`).join("; ");
   throw new Error(
-    `Secret-like content detected before finalization (${summary}). Redact it before committing, pushing, or creating a PR.`
-  );
-}
-function findSecretLikeContent(source, content) {
-  const findings = [];
-  const patterns = [
-    {
-      kind: "private key block",
-      regex: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/gi
-    },
-    {
-      kind: "GitHub token",
-      regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/g
-    },
-    {
-      kind: "GitHub fine-grained token",
-      regex: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g
-    },
-    { kind: "npm token", regex: /\bnpm_[A-Za-z0-9]{20,}\b/g },
-    { kind: "OpenAI key", regex: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g },
-    { kind: "AWS access key", regex: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g },
-    {
-      kind: "authorization bearer token",
-      regex: /\bAuthorization\s*:\s*Bearer\s+[^\s`'\"]{12,}/gi
-    },
-    {
-      kind: "secret assignment",
-      regex: /\b[A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|DATABASE[_-]?URL)[A-Z0-9_]*\s*[:=]\s*["']?[^\s"'`]{8,}/gi
-    }
-  ];
-  for (const { kind, regex } of patterns) {
-    for (const match of content.matchAll(regex)) {
-      if (isAllowedSecretPlaceholder(match[0]) || isAllowedDocumentationTokenReference(match[0])) {
-        continue;
-      }
-      findings.push({ source, kind });
-      break;
-    }
-  }
-  return findings;
-}
-function isAllowedSecretPlaceholder(value) {
-  const normalized = value.toLowerCase();
-  return [
-    "<redacted>",
-    "<example",
-    "example-",
-    "dummy-",
-    "test-",
-    "placeholder",
-    "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";
-import { join as join13 } from "path";
-var ISSUE_FINAL_REVIEW_ARTIFACT_PATH = join13(
-  ".pourkit",
-  ".tmp",
-  "issue-final-review",
-  "agent-output.json"
-);
-async function runIssueFinalReviewAgent(options) {
-  const {
-    executionProvider,
-    target,
-    issue,
-    parentPrdIssue,
-    builderBranch,
-    worktreePath,
-    repoRoot: repoRoot2,
-    logger
-  } = options;
-  const artifactPathInWorktree = ISSUE_FINAL_REVIEW_ARTIFACT_PATH;
-  const artifactPath = join13(worktreePath, artifactPathInWorktree);
-  const strategy = target.strategy;
-  const issueFinalReview = strategy.issueFinalReview;
-  const agent = issueFinalReview;
-  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}`,
-    reviewArtifactPath: options.reviewArtifactPath,
-    reviewVerdict: options.reviewVerdict
-  });
-  const entry = await executeWithMissingOrEmptyArtifactRetry({
-    executionProvider,
-    missingOrEmptyRetries: resolveMissingOrEmptyOutputRetries(agent),
-    logger,
-    runningMessage: () => "Running Issue Final Review agent",
-    retryMessage: (attempt, total) => `Retrying Issue Final Review after empty output (${attempt}/${total})`,
-    executionOptions: {
-      stage: "issueFinalReview",
-      agent: agent.agent,
-      model: agent.model,
-      variant: agent.variant,
-      env: agent.env,
-      prompt,
-      target,
-      repoRoot: repoRoot2,
-      branchName: builderBranch,
-      sandbox: options.config.sandbox,
-      autoApprove: true,
-      artifactPath: artifactPathInWorktree,
-      worktreePath,
-      artifacts: [
-        buildRunContextArtifact({
-          issue,
-          parentPrdIssue,
-          target,
-          branchName: builderBranch,
-          repoRoot: repoRoot2,
-          reviewerCriteria: strategy.review.reviewer.criteria,
-          sections: STAGE_SECTIONS.issueFinalReview
-        })
-      ],
-      ...options.memory ? { memory: options.memory } : {},
-      logger
-    }
-  });
-  const executionResult = entry.executionResult;
-  if (!executionResult.success) {
-    throw new Error(
-      `Issue Final Review agent execution failed: ${executionResult.error}`
-    );
-  }
-  let content;
-  if (entry.artifact._tag === "content") {
-    content = entry.artifact.value;
-  } else if (entry.artifact._tag === "empty") {
-    throw new Error(
-      `Issue Final Review agent produced empty output at ${artifactPath}`
-    );
-  } else {
-    throw new Error(
-      `Issue Final Review agent did not produce output at ${artifactPath}`
-    );
-  }
-  const validation = validateAgentArtifact({
-    kind: "issue-final-review",
-    artifactPath,
-    issueNumber: issue.number,
-    branchName: builderBranch
-  });
-  if (!validation.ok) {
-    throw new Error(
-      `Issue Final Review artifact validation failed: ${validation.reason}`
-    );
-  }
-  const parsed = JSON.parse(content);
-  const verdict = parsed.verdict;
-  if (verdict === "pass") {
-    return {
-      verdict: "pass",
-      artifactPath,
-      selfRetouched: parsed.selfRetouched === true,
-      changedPaths: extractChangedPaths(parsed),
-      verificationPassed: parsed.verification?.passed === true
-    };
-  }
-  if (verdict === "needs_human_review") {
-    return {
-      verdict: "needs_human_review",
-      artifactPath,
-      needsHumanReason: parsed.needsHumanReason,
-      selfRetouched: parsed.selfRetouched === true,
-      changedPaths: extractChangedPaths(parsed)
-    };
-  }
-  throw new Error(
-    `Unknown Issue Final Review verdict: ${JSON.stringify(verdict)}`
-  );
-}
-function extractChangedPaths(parsed) {
-  return Array.isArray(parsed.changedFiles) ? parsed.changedFiles.map(
-    (file) => file && typeof file === "object" ? file.path : void 0
-  ).filter((path9) => typeof path9 === "string") : [];
-}
-function loadIssueFinalReviewPrompt(options) {
-  const {
-    repoRoot: repoRoot2,
-    promptTemplate,
-    validationCommand,
-    reviewArtifactPath,
-    reviewVerdict
-  } = options;
-  const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
-  const promptBody = existsSync12(promptPath) ? readFileSync14(promptPath, "utf-8") : promptTemplate;
-  let prompt = appendProtectedWorkGuidance(`${promptBody}
-
-## 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}
-
-## 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 verification wrapper from the Worktree.
-- Do not substitute direct underlying commands unless no wrapper path can run; if you must use direct commands, explain why in \`verification.summary\`.
-- 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.
-- If no verification commands are configured, note that and proceed with normal review.
-
-## Changed Files Audit
-
-- Read the Branch section of ${RUN_CONTEXT_PATH_IN_WORKTREE} and use its Canonical Base Ref for the changed-file inventory.
-- Before writing \`changedFiles\`, run \`git diff-index --name-only <canonical-base-ref> --\` from the Worktree to enumerate tracked files changed by the Issue.
-- Also run \`git ls-files --others --exclude-standard\` from the Worktree to enumerate untracked files changed by the Issue.
-- Treat the union of those command outputs, excluding only \`.pourkit/.tmp/**\`, \`.pourkit/logs/**\`, and \`.pourkit/state.json\`, as the required \`changedFiles\` inventory.
-- Include every file from that inventory in \`changedFiles\`, including generated files, managed operating assets, docs, prompts, schema files, and large batches.
-- If any file from the inventory is out-of-scope, mark it \`out-of-scope\` and either self-retouch it away or return \`needs_human_review\`; do not omit it.
-- Do not return \`pass\` until \`changedFiles\` covers the full inventory.
-
-## Required Artifact Validation
-
-- Before handoff, run exactly: \`${validationCommand}\`
-- 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.`;
+    `Secret-like content detected before finalization (${summary}). Redact it before committing, pushing, or creating a PR.`
+  );
+}
+function findSecretLikeContent(source, content) {
+  const findings = [];
+  const patterns = [
+    {
+      kind: "private key block",
+      regex: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/gi
+    },
+    {
+      kind: "GitHub token",
+      regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/g
+    },
+    {
+      kind: "GitHub fine-grained token",
+      regex: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g
+    },
+    { kind: "npm token", regex: /\bnpm_[A-Za-z0-9]{20,}\b/g },
+    { kind: "OpenAI key", regex: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g },
+    { kind: "AWS access key", regex: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g },
+    {
+      kind: "authorization bearer token",
+      regex: /\bAuthorization\s*:\s*Bearer\s+[^\s`'\"]{12,}/gi
+    },
+    {
+      kind: "secret assignment",
+      regex: /\b[A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|DATABASE[_-]?URL)[A-Z0-9_]*\s*[:=]\s*["']?[^\s"'`]{8,}/gi
+    }
+  ];
+  for (const { kind, regex } of patterns) {
+    for (const match of content.matchAll(regex)) {
+      if (isAllowedSecretPlaceholder(match[0]) || isAllowedDocumentationTokenReference(match[0])) {
+        continue;
+      }
+      findings.push({ source, kind });
+      break;
     }
   }
-  return prompt;
+  return findings;
+}
+function isAllowedSecretPlaceholder(value) {
+  const normalized = value.toLowerCase();
+  return [
+    "<redacted>",
+    "<example",
+    "example-",
+    "dummy-",
+    "test-",
+    "placeholder",
+    "xxxxx"
+  ].some((allowed) => normalized.includes(allowed));
+}
+function isAllowedDocumentationTokenReference(value) {
+  return /^token\s*:\s*["']?<verdict>/i.test(value);
 }
 
 // issues/issue-worktree-resolution.ts
@@ -6449,90 +6653,7 @@ function assertIssueFinalReviewPassed(worktreeState) {
   }
 }
 async function advanceIssueFinalReview(options) {
-  const {
-    executionProvider,
-    config,
-    target,
-    issue,
-    parentPrdIssue,
-    builderBranch,
-    worktreePath,
-    repoRoot: repoRoot2,
-    logger,
-    reviewArtifactPath,
-    reviewVerdict,
-    worktreeState
-  } = options;
-  const ifrFromState = worktreeState?.issueFinalReview;
-  if (ifrFromState?.completed && ifrFromState.verdict === "pass") {
-    if (!ifrFromState.artifactPath) {
-      throw new Error(
-        "Issue Final Review state is incomplete: missing artifactPath"
-      );
-    }
-    const artifactPath = isAbsolute4(ifrFromState.artifactPath) ? ifrFromState.artifactPath : join15(worktreePath, ifrFromState.artifactPath);
-    const validation = validateAgentArtifact({
-      kind: "issue-final-review",
-      artifactPath,
-      issueNumber: issue.number,
-      branchName: builderBranch
-    });
-    if (!validation.ok) {
-      throw new Error(
-        `Issue Final Review state artifact is invalid: ${validation.reason}`
-      );
-    }
-    return {
-      verdict: "pass",
-      artifactPath,
-      selfRetouched: ifrFromState.selfRetouched ?? false,
-      changedPaths: ifrFromState.changedPaths ?? [],
-      verificationPassed: ifrFromState.verificationPassed ?? false
-    };
-  }
-  const result = await runIssueFinalReviewAgent({
-    executionProvider,
-    config,
-    target,
-    issue,
-    parentPrdIssue,
-    builderBranch,
-    worktreePath,
-    repoRoot: repoRoot2,
-    logger,
-    reviewArtifactPath,
-    reviewVerdict,
-    ...options.memory ? { memory: options.memory } : {}
-  });
-  await assertCanonicalBaseAncestor2({
-    worktreePath,
-    baseRef: `origin/${target.baseBranch}`,
-    stageName: "Issue Final Review",
-    logger
-  });
-  if (result.verdict === "pass") {
-    const changedPaths = await completeIssueFinalReviewChangedPaths({
-      worktreePath,
-      baseRef: `origin/${target.baseBranch}`,
-      declaredChangedPaths: result.changedPaths,
-      logger
-    });
-    updateWorktreeRunState(worktreePath, {
-      issueFinalReview: {
-        completed: true,
-        verdict: "pass",
-        artifactPath: result.artifactPath,
-        selfRetouched: result.selfRetouched,
-        changedPaths,
-        verificationPassed: result.verificationPassed
-      }
-    });
-    return {
-      ...result,
-      changedPaths
-    };
-  }
-  return result;
+  return runIssueFinalReview(options);
 }
 async function startIssueRun(options) {
   const {
@@ -6734,9 +6855,11 @@ async function completeIssueRun(options) {
     checksCompletionTimeoutMs: config.checks.checksCompletionTimeoutSeconds * 1e3,
     pollIntervalMs: config.checks.pollIntervalSeconds * 1e3
   };
-  const ifrState = executionResult.worktreePath ? readWorktreeRunState(executionResult.worktreePath) ?? worktreeState : worktreeState;
+  const readCurrentWorktreeState = () => executionResult.worktreePath ? readWorktreeRunState(executionResult.worktreePath) ?? worktreeState : worktreeState;
+  const ifrState = readCurrentWorktreeState();
   assertIssueFinalReviewPassed(ifrState);
-  if (executionResult.worktreePath && !worktreeState?.finalCommit?.completed && !worktreeState?.pr?.created && !await hasWorktreeChanges(
+  const stateBeforeCompletion = readCurrentWorktreeState();
+  if (executionResult.worktreePath && !stateBeforeCompletion?.finalCommit?.completed && !stateBeforeCompletion?.pr?.created && !await hasWorktreeChanges(
     executionResult.worktreePath,
     `origin/${effectiveBaseBranch}`,
     logger
@@ -6753,92 +6876,33 @@ async function completeIssueRun(options) {
       noOp: true
     };
   }
-  let prTitle = issue.title;
-  let prBody;
-  let finalizerResult;
-  const finalizerFromState = worktreeState?.finalizer?.completed ? worktreeState.finalizer : null;
-  if (finalizerFromState) {
-    try {
-      if (finalizerFromState.title && finalizerFromState.body) {
-        prTitle = finalizerFromState.title;
-        prBody = finalizerFromState.body;
-      } else if (finalizerFromState.artifactPath) {
-        if (!existsSync13(finalizerFromState.artifactPath)) {
-          throw new FinalizerFailure({
-            message: `Finalizer artifact missing at ${finalizerFromState.artifactPath}`
-          });
-        }
-        const artifactContent = readFileSync15(
-          finalizerFromState.artifactPath,
-          "utf-8"
-        );
-        const parsed = parsePrDescription(artifactContent);
-        prTitle = parsed.title;
-        prBody = parsed.body;
-      } else {
-        throw new FinalizerFailure({
-          message: "Finalizer state is incomplete: missing title, body, and artifactPath"
-        });
-      }
-    } catch (error) {
-      throw error;
-    }
-  } else {
-    try {
-      finalizerResult = await runEffectAndMapExit(
-        runFinalizerAgent({
-          executionProvider,
-          config,
-          target,
-          issue,
-          builderBranch: branchName,
-          targetBaseBranch: effectiveBaseBranch,
-          worktreePath: executionResult.worktreePath,
-          reviewArtifactPath,
-          repoRoot: ROOT,
-          logger,
-          ...startResult.memory ? { memory: startResult.memory } : {}
-        })
-      );
-    } catch (error) {
-      throw error;
-    }
-    prTitle = finalizerResult.title;
-    prBody = finalizerResult.body;
-    if (executionResult.worktreePath) {
-      await assertCanonicalBaseAncestor2({
-        worktreePath: executionResult.worktreePath,
-        baseRef: `origin/${effectiveBaseBranch}`,
-        stageName: "Finalizer",
-        logger
-      });
-    }
-  }
-  prTitle = ensureConventionalPrTitle(
-    prTitle,
-    executionResult.commits.join("\n")
-  );
-  const finalBody = ensureClosingRefs(
-    prBody ?? `Closes #${issue.number}`,
-    issue.number
+  const currentWorktreeState = readCurrentWorktreeState();
+  const prDescriptionAgentResult = await runEffectAndMapExit(
+    runPrDescriptionAgent({
+      executionProvider,
+      config,
+      target,
+      issue,
+      builderBranch: branchName,
+      targetBaseBranch: effectiveBaseBranch,
+      worktreePath: executionResult.worktreePath,
+      reviewArtifactPath,
+      repoRoot: ROOT,
+      logger,
+      worktreeState: currentWorktreeState,
+      ...startResult.memory ? { memory: startResult.memory } : {}
+    })
   );
-  if (!finalizerFromState && executionResult.worktreePath) {
-    updateWorktreeRunState(executionResult.worktreePath, {
-      finalizer: {
-        completed: true,
-        artifactPath: finalizerResult.artifactPath,
-        title: prTitle,
-        body: prBody
-      }
-    });
-  }
-  const finalCommitFromState = worktreeState?.finalCommit?.completed;
+  const prTitle = prDescriptionAgentResult.title;
+  const prBody = prDescriptionAgentResult.body;
+  const stateBeforeFinalCommit = readCurrentWorktreeState();
+  const finalCommitFromState = stateBeforeFinalCommit?.finalCommit?.completed;
   if (!finalCommitFromState) {
     await finalizeWorktreeCommit({
       worktreePath: executionResult.worktreePath,
       baseRef: `origin/${effectiveBaseBranch}`,
       title: prTitle,
-      body: finalBody,
+      body: prBody,
       logger
     });
     if (executionResult.worktreePath) {
@@ -6866,9 +6930,9 @@ async function completeIssueRun(options) {
     baseBranch: effectiveBaseBranch,
     autoMerge: target.autoMerge !== false,
     worktreePath: executionResult.worktreePath,
-    worktreeState,
+    worktreeState: readCurrentWorktreeState(),
     prTitle,
-    prBody: finalBody,
+    prBody,
     issueProvider,
     prProvider,
     logger,
@@ -6968,89 +7032,6 @@ async function finalizeWorktreeCommit(options) {
     label: "git commit"
   });
 }
-async function assertCanonicalBaseAncestor2(options) {
-  const { worktreePath, baseRef, stageName, logger } = options;
-  await syncRemoteBaseRef2(worktreePath, baseRef, logger);
-  try {
-    await execCapture("git", ["merge-base", "--is-ancestor", baseRef, "HEAD"], {
-      cwd: worktreePath,
-      logger,
-      label: "git merge-base --is-ancestor"
-    });
-  } catch {
-    throw new Error(
-      `Cannot continue after ${stageName}: ${baseRef} is not an ancestor of HEAD. An agent may have moved the issue branch behind the canonical base; refresh the branch onto the latest target base before continuing.`
-    );
-  }
-}
-async function completeIssueFinalReviewChangedPaths(options) {
-  const actualChangedPaths = await listIssueFinalReviewChangedPaths2(options);
-  const declared = new Set(options.declaredChangedPaths.map(normalizeGitPath2));
-  const missing = actualChangedPaths.filter((path9) => !declared.has(path9));
-  if (missing.length === 0) {
-    return actualChangedPaths;
-  }
-  options.logger.step(
-    "warn",
-    `Issue Final Review pass omitted ${missing.length} changed file(s) from changedFiles; using git inventory for finalization state.`
-  );
-  options.logger.kv("MISSING_CHANGED_FILES", missing.join(", "));
-  return actualChangedPaths;
-}
-async function listIssueFinalReviewChangedPaths2(options) {
-  const trackedDiff = await execCapture(
-    "git",
-    ["diff-index", "--name-only", options.baseRef, "--"],
-    {
-      cwd: options.worktreePath,
-      logger: options.logger,
-      label: "git diff-index Issue Final Review paths"
-    }
-  );
-  const untrackedFiles = await execCapture(
-    "git",
-    ["ls-files", "--others", "--exclude-standard"],
-    {
-      cwd: options.worktreePath,
-      logger: options.logger,
-      label: "git ls-files Issue Final Review paths"
-    }
-  );
-  return Array.from(
-    /* @__PURE__ */ new Set([
-      ...parseGitPathList2(trackedDiff.stdout),
-      ...parseGitPathList2(untrackedFiles.stdout)
-    ])
-  ).filter(isIssueFinalReviewAuditedPath2);
-}
-function parseGitPathList2(output) {
-  return output.split(/\r?\n/).map(normalizeGitPath2).filter((path9) => path9.length > 0);
-}
-function normalizeGitPath2(path9) {
-  return path9.replace(/^"|"$/g, "").replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
-}
-function isIssueFinalReviewAuditedPath2(path9) {
-  return path9 !== "" && path9 !== WORKTREE_RUN_STATE_PATH && !path9.startsWith(".pourkit/.tmp/") && !path9.startsWith(".pourkit/logs/");
-}
-async function syncRemoteBaseRef2(worktreePath, baseRef, logger) {
-  const remoteBase = parseRemoteBaseRef2(baseRef);
-  if (!remoteBase) {
-    return;
-  }
-  await execCapture("git", ["fetch", remoteBase.remote, remoteBase.branch], {
-    cwd: worktreePath,
-    logger,
-    label: "git fetch target"
-  });
-}
-function parseRemoteBaseRef2(baseRef) {
-  const [remote, ...branchParts] = baseRef.split("/");
-  const branch = branchParts.join("/");
-  if (!remote || !branch) {
-    return null;
-  }
-  return { remote, branch };
-}
 function makeIssueTransitions2(provider, config) {
   return createIssueTransitions(
     {
@@ -7199,7 +7180,7 @@ async function runIssueLifecycle(options) {
       worktreeState: startResult.worktreeState,
       memory: startResult.memory
     });
-    if (finalReviewResult.verdict === "needs_human_review") {
+    if (finalReviewResult.status === "needs_human_review") {
       await options.deps.transitionIssueFinalReviewNeedsHumanToHandoff({
         issueNumber: options.issueNumber,
         finalReviewResult
@@ -7393,17 +7374,17 @@ async function runIssueCreateCommand(args, issueProvider, logger) {
 
 // commands/prd-run.ts
 import { lstatSync, realpathSync } from "fs";
-import { join as join17 } from "path";
+import { join as join16 } from "path";
 
 // prd-run/state.ts
 import {
   existsSync as existsSync14,
   mkdirSync as mkdirSync7,
-  readFileSync as readFileSync16,
+  readFileSync as readFileSync15,
   readdirSync as readdirSync3,
   writeFileSync as writeFileSync4
 } from "fs";
-import { join as join16 } from "path";
+import { join as join15 } from "path";
 import { z } from "zod";
 var PRD_RUN_STATE_DIR = ".pourkit/prd-runs";
 var PrdRunRecordSchema = z.object({
@@ -7492,12 +7473,12 @@ function readPrdRun(repoRoot2, prdRef) {
     return { record: null, diagnostics: [] };
   }
   try {
-    const raw = JSON.parse(readFileSync16(recordPath, "utf-8"));
+    const raw = JSON.parse(readFileSync15(recordPath, "utf-8"));
     const parsed = PrdRunRecordSchema.parse(raw);
     return { record: parsed, diagnostics: [] };
   } catch (error) {
     try {
-      const raw = JSON.parse(readFileSync16(recordPath, "utf-8"));
+      const raw = JSON.parse(readFileSync15(recordPath, "utf-8"));
       if (raw && typeof raw === "object" && raw.start && typeof raw.start === "object" && raw.start.startBaseBranch === void 0) {
         return {
           record: raw,
@@ -7518,7 +7499,7 @@ function readPrdRun(repoRoot2, prdRef) {
   }
 }
 function listPrdRuns(repoRoot2) {
-  const stateDir = join16(repoRoot2, PRD_RUN_STATE_DIR);
+  const stateDir = join15(repoRoot2, PRD_RUN_STATE_DIR);
   if (!existsSync14(stateDir)) {
     return { records: [], diagnostics: [] };
   }
@@ -7528,10 +7509,10 @@ function listPrdRuns(repoRoot2) {
     (left, right) => left.name.localeCompare(right.name)
   )) {
     if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
-    const recordPath = join16(stateDir, entry.name);
+    const recordPath = join15(stateDir, entry.name);
     try {
       const record = PrdRunRecordSchema.parse(
-        JSON.parse(readFileSync16(recordPath, "utf-8"))
+        JSON.parse(readFileSync15(recordPath, "utf-8"))
       );
       records.push(record);
     } catch (error) {
@@ -7544,7 +7525,7 @@ function listPrdRuns(repoRoot2) {
 }
 function writePrdRunRecord(repoRoot2, record) {
   const normalized = normalizePrdRunRef(record.prdRef);
-  const stateDir = join16(repoRoot2, PRD_RUN_STATE_DIR);
+  const stateDir = join15(repoRoot2, PRD_RUN_STATE_DIR);
   const recordPath = getRecordPath(repoRoot2, normalized);
   mkdirSync7(stateDir, { recursive: true });
   writeFileSync4(
@@ -7554,7 +7535,7 @@ function writePrdRunRecord(repoRoot2, record) {
   );
 }
 function getRecordPath(repoRoot2, prdRef) {
-  return join16(
+  return join15(
     repoRoot2,
     PRD_RUN_STATE_DIR,
     `${normalizePrdRunRef(prdRef)}.json`
@@ -9314,7 +9295,7 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
 }
 
 // prd-run/final-review-validation.ts
-import { existsSync as existsSync15, readFileSync as readFileSync17 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync16 } from "fs";
 
 // commands/prd-run.ts
 async function runPrdRunLaunchCommand(options) {
@@ -12324,18 +12305,18 @@ Init applied: ${result.applied} operations applied, ${result.skipped} skipped.`
 }
 
 // commands/memory-init.ts
-import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync18, writeFileSync as writeFileSync5 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync17, writeFileSync as writeFileSync5 } from "fs";
+import { join as join17 } from "path";
 async function runMemoryInitCommand(options) {
   const cwd = options.cwd ?? process.cwd();
-  const configPath = join18(cwd, ".pourkit", "config.json");
+  const configPath = join17(cwd, ".pourkit", "config.json");
   if (!existsSync17(configPath)) {
     return {
       ok: false,
       message: "No .pourkit/config.json found. Run `pourkit init` first to initialize Pourkit, then run `pourkit memory init`."
     };
   }
-  const raw = JSON.parse(readFileSync18(configPath, "utf8"));
+  const raw = JSON.parse(readFileSync17(configPath, "utf8"));
   let alreadyEnabled = false;
   if (Object.prototype.hasOwnProperty.call(raw, "memory")) {
     const m = raw.memory;
@@ -12360,8 +12341,8 @@ async function runMemoryInitCommand(options) {
     const next = { ...raw, memory };
     writeFileSync5(configPath, JSON.stringify(next, null, 2) + "\n");
   }
-  mkdirSync8(join18(cwd, ".pourkit", "icm"), { recursive: true });
-  const gitignorePath = join18(cwd, ".gitignore");
+  mkdirSync8(join17(cwd, ".pourkit", "icm"), { recursive: true });
+  const gitignorePath = join17(cwd, ".gitignore");
   updateManagedBlockSync(gitignorePath, generateGitignoreBlock());
   const managed = await generateManagedAgentInstructions({
     sourceRoot: cwd,
@@ -12369,14 +12350,14 @@ async function runMemoryInitCommand(options) {
   });
   let updatedAgentFile = false;
   for (const fileName of ["AGENTS.md", "CLAUDE.md"]) {
-    const agentPath = join18(cwd, fileName);
+    const agentPath = join17(cwd, fileName);
     if (existsSync17(agentPath)) {
       updateManagedBlockSync(agentPath, managed);
       updatedAgentFile = true;
     }
   }
   if (!updatedAgentFile) {
-    updateManagedBlockSync(join18(cwd, "AGENTS.md"), managed);
+    updateManagedBlockSync(join17(cwd, "AGENTS.md"), managed);
   }
   return {
     ok: true,
@@ -12392,7 +12373,7 @@ ${content}${MANAGED_BLOCK_END}
     writeFileSync5(filePath, blockContent);
     return;
   }
-  const existing = readFileSync18(filePath, "utf8");
+  const existing = readFileSync17(filePath, "utf8");
   const beginIdx = existing.indexOf(MANAGED_BLOCK_BEGIN);
   const endIdx = existing.indexOf(MANAGED_BLOCK_END);
   if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
@@ -12521,7 +12502,7 @@ async function runSerenaStatusCommand(options) {
 }
 
 // commands/config-schema.ts
-import { readFileSync as readFileSync19, existsSync as existsSync18 } from "fs";
+import { readFileSync as readFileSync18, existsSync as existsSync18 } from "fs";
 import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile2, readdir as readdir2 } from "fs/promises";
 import { resolve as resolve3, dirname as dirname5, relative as relative2 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -12542,7 +12523,7 @@ var _schemaValidator = null;
 var _schemaErrors = null;
 function getSchemaValidator() {
   if (!_schemaValidator) {
-    const schema = JSON.parse(readFileSync19(PACKAGED_SCHEMA_PATH, "utf-8"));
+    const schema = JSON.parse(readFileSync18(PACKAGED_SCHEMA_PATH, "utf-8"));
     const ajv = new Ajv2({ strict: true });
     ajv.addKeyword("x-pourkit-schema-version");
     const validate = ajv.compile(schema);
@@ -12556,7 +12537,7 @@ function getSchemaValidator() {
   return _schemaValidator;
 }
 function readPackagedHash() {
-  return readFileSync19(PACKAGED_HASH_PATH, "utf-8");
+  return readFileSync18(PACKAGED_HASH_PATH, "utf-8");
 }
 function localSchemaDir(repoRoot2) {
   return resolve3(repoRoot2, ".pourkit/schema");
@@ -13112,7 +13093,7 @@ async function validateMemoryHealth(cwd, memoryConfig) {
     detail: icmPath !== null ? icmPath : "icm not found on PATH"
   });
   const gitignorePath = resolve3(cwd, ".gitignore");
-  const gitignoreContent = existsSync18(gitignorePath) ? readFileSync19(gitignorePath, "utf-8") : "";
+  const gitignoreContent = existsSync18(gitignorePath) ? readFileSync18(gitignorePath, "utf-8") : "";
   const hasGitignoreEntry = gitignoreContent.includes(".pourkit/icm/");
   checks.push({
     name: "icm-gitignore",
@@ -13161,7 +13142,7 @@ async function runDoctorCommand(options) {
   let rawMemoryConfig;
   if (existsSync18(configPath)) {
     try {
-      const raw = JSON.parse(readFileSync19(configPath, "utf-8"));
+      const raw = JSON.parse(readFileSync18(configPath, "utf-8"));
       rawMemoryConfig = raw.memory;
       const validate = getSchemaValidator();
       const valid2 = validate(raw);
@@ -14373,7 +14354,7 @@ init_common();
 
 // execution/sandcastle-execution.ts
 import { existsSync as existsSync21, mkdirSync as mkdirSync9, statSync as statSync2, writeFileSync as writeFileSync6 } from "fs";
-import { join as join21 } from "path";
+import { join as join20 } from "path";
 import { createWorktree, opencode } from "@ai-hero/sandcastle";
 import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
@@ -14382,10 +14363,10 @@ init_common();
 import { mkdtempSync } from "fs";
 import { writeFile as writeFile4 } from "fs/promises";
 import { tmpdir } from "os";
-import { dirname as dirname7, join as join19 } from "path";
+import { dirname as dirname7, join as join18 } from "path";
 async function writeExecutionArtifacts(worktreePath, artifacts) {
   for (const artifact of artifacts) {
-    const filePath = join19(worktreePath, artifact.path);
+    const filePath = join18(worktreePath, artifact.path);
     await ensureDir(dirname7(filePath));
     await writeFile4(filePath, artifact.content, "utf-8");
   }
@@ -14400,7 +14381,7 @@ import path7 from "path";
 
 // execution/sandbox-image.ts
 import { createHash as createHash2 } from "crypto";
-import { existsSync as existsSync20, readFileSync as readFileSync20 } from "fs";
+import { existsSync as existsSync20, readFileSync as readFileSync19 } from "fs";
 import path6 from "path";
 function sandboxImageName(repoRoot2, installIcm) {
   const dirName = path6.basename(repoRoot2.replace(/[\\/]+$/, "")) || "local";
@@ -14411,7 +14392,7 @@ function sandboxImageName(repoRoot2, installIcm) {
     const base2 = `sandcastle:${baseName}`;
     return installIcm ? `${base2}-icm` : base2;
   }
-  const fingerprint = createHash2("sha256").update(readFileSync20(dockerfilePath)).digest("hex").slice(0, 8);
+  const fingerprint = createHash2("sha256").update(readFileSync19(dockerfilePath)).digest("hex").slice(0, 8);
   const base = `sandcastle:${baseName}-${fingerprint}`;
   return installIcm ? `${base}-icm` : base;
 }
@@ -14447,7 +14428,7 @@ async function createSandboxFromExistingWorktree(options) {
 }
 
 // execution/sandbox-options.ts
-import { join as join20 } from "path";
+import { join as join19 } from "path";
 var POURKIT_ICM_CONTAINER_DIR = "/home/agent/.pourkit/icm";
 function buildSandboxOptions(repoRoot2, sandbox, memory) {
   const mounts = [];
@@ -14456,12 +14437,12 @@ function buildSandboxOptions(repoRoot2, sandbox, memory) {
   }
   if (memory?.available) {
     mounts.push({
-      hostPath: join20(repoRoot2, ".pourkit", "icm"),
+      hostPath: join19(repoRoot2, ".pourkit", "icm"),
       sandboxPath: POURKIT_ICM_CONTAINER_DIR,
       readonly: false
     });
     mounts.push({
-      hostPath: join20(repoRoot2, ".pourkit", "icm", "cache"),
+      hostPath: join19(repoRoot2, ".pourkit", "icm", "cache"),
       sandboxPath: "/home/agent/.cache/icm",
       readonly: false
     });
@@ -14595,13 +14576,13 @@ var SandcastleExecutionSession = class {
             "Memory enabled but memory context is invalid. Run `pourkit memory init` or install ICM for host planning use."
           );
         }
-        const hostMemoryDir = join21(repoRoot2, ".pourkit", "icm");
+        const hostMemoryDir = join20(repoRoot2, ".pourkit", "icm");
         if (!existsSync21(hostMemoryDir) || !statSync2(hostMemoryDir).isDirectory()) {
           throw new MissingHostMemoryDirError(
             "Memory enabled but host .pourkit/icm/ directory is missing. Run `pourkit memory init` to create the repo-scoped memory store."
           );
         }
-        mkdirSync9(join21(hostMemoryDir, "cache"), { recursive: true });
+        mkdirSync9(join20(hostMemoryDir, "cache"), { recursive: true });
       }
       const sandboxOptions = buildSandboxOptions(
         repoRoot2,
@@ -14760,7 +14741,7 @@ function sanitizeBranch(branchName) {
 }
 function safeCopyToWorktreePaths(paths, repoRoot2, worktreePath) {
   return paths.filter((relativePath) => {
-    const source = join21(repoRoot2, relativePath);
+    const source = join20(repoRoot2, relativePath);
     if (!existsSync21(source)) {
       return true;
     }
@@ -14771,7 +14752,7 @@ function safeCopyToWorktreePaths(paths, repoRoot2, worktreePath) {
     } catch {
       return true;
     }
-    const destination = join21(worktreePath, relativePath);
+    const destination = join20(worktreePath, relativePath);
     return !existsSync21(destination);
   });
 }
@@ -14836,12 +14817,12 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function savePromptToFile(repoRoot2, stage, iteration, prompt) {
-  const promptsDir = join21(repoRoot2, ".pourkit", ".tmp", "prompts");
+  const promptsDir = join20(repoRoot2, ".pourkit", ".tmp", "prompts");
   mkdirSync9(promptsDir, { recursive: true });
   const timestamp2 = Date.now();
   const iterationSuffix = iteration !== void 0 ? `-iteration-${iteration}` : "";
   const filename = `${stage}${iterationSuffix}-${timestamp2}.md`;
-  const filePath = join21(promptsDir, filename);
+  const filePath = join20(promptsDir, filename);
   writeFileSync6(filePath, prompt, "utf-8");
 }
 
@@ -15562,11 +15543,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260622055621")) {
-    return "0.0.0-next-20260622055621";
+  if (isPackageVersion("0.0.0-next-20260622235247")) {
+    return "0.0.0-next-20260622235247";
   }
-  if (isReleaseVersion("0.0.0-next-20260622055621")) {
-    return "0.0.0-next-20260622055621";
+  if (isReleaseVersion("0.0.0-next-20260622235247")) {
+    return "0.0.0-next-20260622235247";
   }
   try {
     const root = repoRoot();