@pourkit/cli 0.0.0-next-20260714055657 → 0.0.0-next-20260715085442

package/dist/cli.js

@@ -370,10 +370,26 @@ function applyOutputRetriesDefaults(retries) {
 }
 function applyStageAgentDefaults(agent) {
   return {
-    ...agent,
+    agent: agent.agent,
+    model: agent.model,
+    variant: agent.variant,
+    env: agent.env,
+    promptTemplate: agent.promptTemplate,
     outputRetries: applyOutputRetriesDefaults(agent.outputRetries)
   };
 }
+var DEFAULT_POST_COMPLETION_FINAL_REVIEW_PROMPT = "post-completion-final-review.prompt.md";
+function applyPostCompletionFinalReviewDefaults(agent, issueFinalReview) {
+  if (agent) return applyStageAgentDefaults(agent);
+  return applyStageAgentDefaults({
+    agent: issueFinalReview.agent,
+    model: issueFinalReview.model,
+    variant: issueFinalReview.variant,
+    env: issueFinalReview.env,
+    promptTemplate: DEFAULT_POST_COMPLETION_FINAL_REVIEW_PROMPT,
+    outputRetries: issueFinalReview.outputRetries
+  });
+}
 function assertRepoRelativePath(value, location) {
   const normalized = normalize(value);
   if (isAbsolute(value) || isAbsolute(normalized) || normalized === ".." || normalized.startsWith(`..${sep}`)) {
@@ -432,6 +448,10 @@ function validateConfigSemantics(input) {
       target.strategy.issueFinalReview,
       `targets[${targetIndex}].strategy.issueFinalReview`
     );
+    assertStageAgentPath(
+      target.strategy.postCompletionFinalReview,
+      `targets[${targetIndex}].strategy.postCompletionFinalReview`
+    );
     assertStageAgentPath(
       target.strategy.finalize.prDescriptionAgent,
       `targets[${targetIndex}].strategy.finalize.prDescriptionAgent`
@@ -506,6 +526,10 @@ function normalizePourkitConfig(input) {
           ),
           maxAttempts: t.strategy.issueFinalReview.maxAttempts
         },
+        postCompletionFinalReview: applyPostCompletionFinalReviewDefaults(
+          t.strategy.postCompletionFinalReview,
+          t.strategy.issueFinalReview
+        ),
         finalize: {
           prDescriptionAgent: applyStageAgentDefaults(
             t.strategy.finalize.prDescriptionAgent
@@ -3772,7 +3796,7 @@ function validatePrdPlanWorkspace(options) {
     );
   }
   const children = [];
-  const CHILD_REF_PATTERN2 = /^\s*(I-0*\d+)\s*$/i;
+  const CHILD_REF_PATTERN = /^\s*(I-0*\d+)\s*$/i;
   const BLOCKED_BY_SECTION_REGEX2 = /## Blocked by\s*\n([\s\S]*?)(?=\n## |$)/i;
   const PARENT_SECTION_REGEX2 = /## Parent\s*\n([\s\S]*?)(?=\n## |$)/i;
   for (const childFile of childFiles) {
@@ -3810,7 +3834,7 @@ function validatePrdPlanWorkspace(options) {
         if (!line) continue;
         for (const part of line.split(",")) {
           const trimmed = part.trim();
-          const match = trimmed.match(CHILD_REF_PATTERN2);
+          const match = trimmed.match(CHILD_REF_PATTERN);
           if (match) {
             blockedByRefs.push(match[1].toUpperCase());
           }
@@ -4257,6 +4281,20 @@ var POST_COMPLETION_FINAL_REVIEW_ARTIFACT_PATH = join9(
   "post-completion-final-review",
   "agent-output.json"
 );
+var DEFAULT_POST_COMPLETION_FINAL_REVIEW_PROMPT2 = "post-completion-final-review.prompt.md";
+function resolvePostCompletionFinalReviewAgent(target) {
+  const configured = target.strategy.postCompletionFinalReview;
+  if (configured) return configured;
+  const fallback = target.strategy.issueFinalReview;
+  return {
+    agent: fallback.agent,
+    model: fallback.model,
+    variant: fallback.variant,
+    env: fallback.env,
+    outputRetries: fallback.outputRetries,
+    promptTemplate: DEFAULT_POST_COMPLETION_FINAL_REVIEW_PROMPT2
+  };
+}
 async function runPostCompletionFinalReview(options) {
   const {
     executionProvider,
@@ -4308,9 +4346,10 @@ async function runPostCompletionFinalReview(options) {
     };
   }
   const strategy = target.strategy;
-  const agent = strategy.issueFinalReview;
+  const agent = resolvePostCompletionFinalReviewAgent(target);
   const prompt = loadPostCompletionFinalReviewPrompt({
     repoRoot: repoRoot2,
+    promptTemplate: agent.promptTemplate,
     sourceDocumentPath,
     completedBranch,
     validationCommand: `pourkit validate-artifact post-completion-final-review ${artifactPathInWorktree}`,
@@ -4452,11 +4491,14 @@ Completed branch: ${completedBranch}`,
   );
 }
 function loadPostCompletionFinalReviewPrompt(options) {
-  const { repoRoot: repoRoot2, sourceDocumentPath, completedBranch, validationCommand } = options;
-  const promptPath = resolvePromptTemplatePath(
-    repoRoot2,
-    "post-completion-final-review.prompt.md"
-  );
+  const {
+    repoRoot: repoRoot2,
+    promptTemplate,
+    sourceDocumentPath,
+    completedBranch,
+    validationCommand
+  } = options;
+  const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
   const promptBody = existsSync9(promptPath) ? readFileSync8(promptPath, "utf-8") : `Review the completed branch against the source document.
 
 ## Source Document
@@ -8815,7 +8857,7 @@ import { isAbsolute as isAbsolute8, join as join22, relative as relative3, resol
 import { readFile as readFile5, readdir as readdir2 } from "fs/promises";
 import { join as join19 } from "path";
 var CHILD_FILE_PATTERN = /^I-0*(\d+)-.+\.md$/i;
-var CHILD_REF_PATTERN = /^\s*(?:[-*]|\d+[.)])?\s*(I-0*\d+)\s*$/i;
+var CHILD_REF_REGEX = /\bI-0*(\d+)\b/gi;
 var BLOCKED_BY_SECTION_REGEX = /## Blocked by\s*\n([\s\S]*?)(?=\n## |$)/i;
 var PARENT_SECTION_REGEX = /## Parent\s*\n([\s\S]*?)(?=\n## |$)/i;
 function escapeRegExp2(value) {
@@ -8840,19 +8882,10 @@ function parseChildRefsFromBody(body) {
   const section = body.match(BLOCKED_BY_SECTION_REGEX)?.[1];
   if (!section) return [];
   const refs = [];
-  for (const rawLine of section.split("\n")) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    const parts = line.split(",");
-    for (const part of parts) {
-      const trimmed = part.trim();
-      const match = trimmed.match(CHILD_REF_PATTERN);
-      if (match) {
-        refs.push(match[1].toUpperCase());
-      }
-    }
+  for (const match of section.matchAll(CHILD_REF_REGEX)) {
+    refs.push(`I-${match[1].padStart(2, "0")}`);
   }
-  return refs;
+  return Array.from(new Set(refs));
 }
 function extractTitleBody(content) {
   const firstLine = content.split("\n")[0];
@@ -11099,10 +11132,11 @@ async function runPrdPlanWorkspacePublishCommand(options) {
 
 // commands/prd-run.ts
 import { lstatSync, realpathSync } from "fs";
-import { join as join23 } from "path";
+import { join as join24 } from "path";
 
 // prd-run/coordinator.ts
 import { spawnSync as spawnSync2 } from "child_process";
+import { join as join23 } from "path";
 import { Match, pipe } from "effect";
 init_common();
 
@@ -11819,7 +11853,8 @@ function validatePrdRunTerminalEvidence(record, context) {
         humanReadableReason: `PRD Run ${context.prdRef} is missing proof that all child Issues finalized into ${context.prdBranch}.`,
         repairability: "operator-action",
         nextAction: "inspect-and-retry",
-        nextRecommendedCommand: "pourkit prd-run launch"
+        nextRecommendedCommand: "pourkit prd-run launch",
+        diagnostics: [...context.childFinalizationDiagnostics ?? []]
       })
     };
   }
@@ -11859,6 +11894,29 @@ async function claimReadyPrdChild(options) {
     }
   };
 }
+async function releaseClaimedPrdChild(options) {
+  const result = await runBdJson({
+    repoRoot: options.repoRoot,
+    args: ["update", options.childId, "--status", "open", "--json"],
+    logger: options.logger
+  });
+  const child = findReadyClaim(result);
+  if (!child?.id) {
+    return {
+      ok: false,
+      childId: options.childId,
+      reason: `bd update ${options.childId} --status open returned no child.`
+    };
+  }
+  return {
+    ok: true,
+    child: {
+      id: child.id,
+      title: child.title,
+      metadata: child.metadata
+    }
+  };
+}
 function findReadyClaim(value) {
   if (!value) return void 0;
   if (Array.isArray(value)) return value.find((entry) => Boolean(entry.id));
@@ -13051,6 +13109,32 @@ async function reconcileBlockedBeadsIssueProjection(options) {
   }
   return refreshed;
 }
+async function releaseSkippedBlockedBeadsChildren(options) {
+  for (const child of options.children) {
+    let result;
+    try {
+      result = await releaseClaimedPrdChild({
+        repoRoot: options.repoRoot,
+        childId: child.id,
+        logger: options.logger
+      });
+    } catch (error) {
+      logCoordinatorStep(
+        options.logger,
+        "warn",
+        `Failed to release skipped Beads child ${child.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      continue;
+    }
+    if (!result.ok) {
+      logCoordinatorStep(
+        options.logger,
+        "warn",
+        `Failed to release skipped Beads child ${child.id}: ${result.reason}`
+      );
+    }
+  }
+}
 function extractIssueFromQueueError(error) {
   if (!error || typeof error !== "object" || !("issue" in error)) {
     return void 0;
@@ -13199,6 +13283,105 @@ async function selectPrdRunCoordinatorMode(options) {
     })
   };
 }
+function escapeRegExp3(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeChildRef2(value) {
+  const match = value.match(/^I-0*(\d+)$/i);
+  if (!match) return null;
+  return `I-${match[1].padStart(2, "0")}`;
+}
+function issueChildRef(prdRef, issue) {
+  const match = issue.title.match(
+    new RegExp(`^${escapeRegExp3(prdRef)}\\s*/\\s*(I-0*\\d+)\\s*:`, "i")
+  );
+  return match ? normalizeChildRef2(match[1]) : null;
+}
+function issueSummary(issue) {
+  return `#${issue.number} ${issue.title}`;
+}
+async function readPlannedChildRefs(options) {
+  const sourceDocument = await resolvePrdPostCompletionSourceDocument(options);
+  if (!sourceDocument || sourceDocument.status !== "resolved") {
+    return {
+      ok: false,
+      diagnostics: sourceDocument && sourceDocument.status === "blocked" ? [...sourceDocument.diagnostics] : [
+        sourceDocument?.reason ?? `Unable to resolve source document for ${options.prdRef}.`
+      ]
+    };
+  }
+  const parsed = await parsePrdPlanWorkspace({
+    workspacePath: join23(options.repoRoot, sourceDocument.workspacePath),
+    prdRef: options.prdRef
+  });
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      diagnostics: parsed.diagnostics.map((diagnostic) => diagnostic.message)
+    };
+  }
+  return {
+    ok: true,
+    childRefs: parsed.workspace.children.map((child) => child.childRef)
+  };
+}
+async function verifyPrdChildFinalizationEvidence(options) {
+  const diagnostics = [];
+  const unfinalizedProcessed = options.processedResults.filter(
+    (result) => !result.noOp && result.publicationStatus !== "merged"
+  );
+  if (unfinalizedProcessed.length > 0) {
+    diagnostics.push(
+      `Processed child Issues missing PRD Branch merge/no-op evidence: ${unfinalizedProcessed.map((result) => `#${result.issueNumber}`).join(", ")}.`
+    );
+  }
+  let relatedIssues;
+  try {
+    relatedIssues = await options.issueProvider.listRelatedIssues(
+      options.prdRef
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      diagnostics: [
+        `Failed to list child Issues for ${options.prdRef}: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+  if (relatedIssues.length === 0) {
+    diagnostics.push(`No child Issue projections found for ${options.prdRef}.`);
+  }
+  const planned = await readPlannedChildRefs({
+    repoRoot: options.repoRoot,
+    prdRef: options.prdRef
+  });
+  if (!planned.ok) {
+    diagnostics.push(...planned.diagnostics);
+  } else if (planned.childRefs.length === 0) {
+    diagnostics.push(`No planned child Issues found for ${options.prdRef}.`);
+  } else {
+    const relatedRefs = new Set(
+      relatedIssues.map((issue) => issueChildRef(options.prdRef, issue)).filter((ref) => ref !== null)
+    );
+    const missingRefs = planned.childRefs.filter(
+      (ref) => !relatedRefs.has(ref)
+    );
+    if (missingRefs.length > 0) {
+      diagnostics.push(
+        `Planned child Issues without published Issue projections: ${missingRefs.join(", ")}.`
+      );
+    }
+  }
+  const openRelatedIssues = relatedIssues.filter(
+    (issue) => issue.state !== "closed"
+  );
+  if (openRelatedIssues.length > 0) {
+    diagnostics.push(
+      `Child Issues still open: ${openRelatedIssues.map(issueSummary).join(", ")}.`
+    );
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
 async function runPostCompletionAfterTerminal(options, prdRef, record, resumeFacts, startOutcome) {
   const receipt = record.postCompletionFinalReview;
   if (receipt?.status === "passed" || receipt?.status === "overridden") {
@@ -13758,17 +13941,25 @@ async function launchPrdRun(options) {
       logger: options.logger
     });
   }
-  if (currentRecord && startReceipt && activeRepairGuidance?.failureCode === "missing-child-finalization-evidence" && await prdParentIssueIsClosed({
-    issueProvider: options.issueProvider,
+  const parentClosureIssueProvider = options.issueProvider;
+  if (currentRecord && startReceipt && parentClosureIssueProvider && activeRepairGuidance?.failureCode === "missing-child-finalization-evidence" && await prdParentIssueIsClosed({
+    issueProvider: parentClosureIssueProvider,
     prdRef,
     logger: options.logger
   })) {
     const prdBranch = startReceipt.prdBranch ?? prdRef;
+    const childFinalizationEvidence = await verifyPrdChildFinalizationEvidence({
+      repoRoot: options.repoRoot,
+      prdRef,
+      issueProvider: parentClosureIssueProvider,
+      processedResults: []
+    });
     const terminalEvidence = validatePrdRunTerminalEvidence(currentRecord, {
       prdRef,
       baseBranch: startReceipt.startBaseBranch,
       prdBranch,
-      allChildIssuesFinalizedIntoPrdBranch: true
+      allChildIssuesFinalizedIntoPrdBranch: childFinalizationEvidence.ok,
+      childFinalizationDiagnostics: childFinalizationEvidence.diagnostics
     });
     if (!terminalEvidence.ok) {
       return buildLaunchBlockedOutcome(
@@ -14002,11 +14193,22 @@ async function launchGithubQueueDrain(options, prdRef, startReceipt, targetName,
       writeDrainedRecord(options.repoRoot, prdRef, startReceipt, targetName);
       const drainRecord = readPrdRun(options.repoRoot, prdRef).record;
       if (drainRecord) {
+        const childFinalizationEvidence = await verifyPrdChildFinalizationEvidence({
+          repoRoot: options.repoRoot,
+          prdRef,
+          issueProvider,
+          processedResults: outcome.results.map((result2) => ({
+            issueNumber: result2.selected.number,
+            noOp: result2.runResult.noOp,
+            publicationStatus: result2.runResult.publicationStatus
+          }))
+        });
         const drainContext = {
           prdRef,
           baseBranch: startReceipt.startBaseBranch,
           prdBranch,
-          allChildIssuesFinalizedIntoPrdBranch: outcome.allProcessedIssuesFinalizedIntoPrdBranch === true
+          allChildIssuesFinalizedIntoPrdBranch: childFinalizationEvidence.ok,
+          childFinalizationDiagnostics: childFinalizationEvidence.diagnostics
         };
         const terminalEvidence = validatePrdRunTerminalEvidence(
           drainRecord,
@@ -14267,6 +14469,7 @@ async function launchBeadsQueueDrain(options, prdRef, startReceipt, targetName,
   const executionProvider = options.executionProvider;
   const logger = options.logger;
   const processedResults = [];
+  const skippedBlockedBeadsChildren = [];
   const originalGuidance = readPrdRun(options.repoRoot, prdRef).record?.repairGuidance;
   logCoordinatorStep(
     logger,
@@ -14365,33 +14568,42 @@ async function launchBeadsQueueDrain(options, prdRef, startReceipt, targetName,
           prdRef,
           logger
         });
-        logCoordinatorStep(
-          logger,
-          "info",
-          `Running GitHub Issue #${issue.number} from Beads child ${contextResult.beads.childId}.`
-        );
-        const runResult = await runClaimedPrdIssueCommand({
-          targetName,
-          config: options.config,
-          issueProvider,
-          prProvider,
-          executionProvider,
-          force: false,
-          logger,
-          repoRoot: options.repoRoot,
-          issue,
-          queueRunContext: {
-            prdRef,
-            prdBranch: startReceipt.prdBranch,
-            beadsChild: contextResult.beads
-          }
-        });
-        processedResults.push({
-          beadsChildId: contextResult.beads.childId,
-          issueNumber: runResult.selected.number,
-          noOp: runResult.runResult.noOp,
-          publicationStatus: runResult.runResult.publicationStatus
-        });
+        if (issue.labels.includes(options.config.labels.blocked)) {
+          logCoordinatorStep(
+            logger,
+            "info",
+            `Skipping Beads child ${contextResult.beads.childId} because GitHub Issue #${issue.number} remains labeled ${options.config.labels.blocked}.`
+          );
+          skippedBlockedBeadsChildren.push(readResult.child);
+        } else {
+          logCoordinatorStep(
+            logger,
+            "info",
+            `Running GitHub Issue #${issue.number} from Beads child ${contextResult.beads.childId}.`
+          );
+          const runResult = await runClaimedPrdIssueCommand({
+            targetName,
+            config: options.config,
+            issueProvider,
+            prProvider,
+            executionProvider,
+            force: false,
+            logger,
+            repoRoot: options.repoRoot,
+            issue,
+            queueRunContext: {
+              prdRef,
+              prdBranch: startReceipt.prdBranch,
+              beadsChild: contextResult.beads
+            }
+          });
+          processedResults.push({
+            beadsChildId: contextResult.beads.childId,
+            issueNumber: runResult.selected.number,
+            noOp: runResult.runResult.noOp,
+            publicationStatus: runResult.runResult.publicationStatus
+          });
+        }
       } catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         const repair = buildQueueIssueRunRepairMetadata(
@@ -14469,30 +14681,52 @@ async function launchBeadsQueueDrain(options, prdRef, startReceipt, targetName,
         prdRef,
         logger
       });
-      const runResult = await runClaimedPrdIssueCommand({
-        targetName,
-        config: options.config,
-        issueProvider,
-        prProvider,
-        executionProvider,
-        force: false,
-        logger,
-        repoRoot: options.repoRoot,
-        issue: fetchedIssue,
-        queueRunContext: {
-          prdRef,
-          prdBranch: startReceipt.prdBranch,
-          ...resumeBeadsContext ? { beadsChild: resumeBeadsContext } : {}
+      if (fetchedIssue.labels.includes(options.config.labels.blocked)) {
+        logCoordinatorStep(
+          logger,
+          "info",
+          `Skipping resume issue #${fetchedIssue.number} because it remains labeled ${options.config.labels.blocked}; selecting another Beads-ready child.`
+        );
+        if (resumeBeadsContext) {
+          skippedBlockedBeadsChildren.push({
+            id: resumeBeadsContext.childId,
+            title: fetchedIssue.title,
+            metadata: {
+              pourkit: {
+                prdRef,
+                childRef: resumeBeadsContext.childRef,
+                githubIssueNumber: resumeIssueNumber
+              }
+            }
+          });
         }
-      });
-      processedResults.push({
-        beadsChildId: resumeIssue?.beadsChildId ?? "resumed",
-        issueNumber: runResult.selected.number,
-        noOp: runResult.runResult.noOp,
-        publicationStatus: runResult.runResult.publicationStatus
-      });
-      startReceipt.queueDrainedAt = (/* @__PURE__ */ new Date()).toISOString();
-      startReceipt.queueProcessedCount = processedResults.length;
+        resumeIssueNumber = void 0;
+      } else {
+        const runResult = await runClaimedPrdIssueCommand({
+          targetName,
+          config: options.config,
+          issueProvider,
+          prProvider,
+          executionProvider,
+          force: false,
+          logger,
+          repoRoot: options.repoRoot,
+          issue: fetchedIssue,
+          queueRunContext: {
+            prdRef,
+            prdBranch: startReceipt.prdBranch,
+            ...resumeBeadsContext ? { beadsChild: resumeBeadsContext } : {}
+          }
+        });
+        processedResults.push({
+          beadsChildId: resumeIssue?.beadsChildId ?? "resumed",
+          issueNumber: runResult.selected.number,
+          noOp: runResult.runResult.noOp,
+          publicationStatus: runResult.runResult.publicationStatus
+        });
+        startReceipt.queueDrainedAt = (/* @__PURE__ */ new Date()).toISOString();
+        startReceipt.queueProcessedCount = processedResults.length;
+      }
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       const repair = buildQueueIssueRunRepairMetadata(
@@ -14528,143 +14762,160 @@ async function launchBeadsQueueDrain(options, prdRef, startReceipt, targetName,
     }
   }
   let beadsClaimAttempted = false;
-  while (true) {
-    const claimResult = await claimReadyPrdChild({
-      repoRoot: options.repoRoot,
-      prdRef,
-      logger
-    });
-    if (!claimResult.ok) {
-      if (claimResult.reason === "no-ready-child") {
-        logCoordinatorStep(
-          logger,
-          "info",
-          `Beads-backed PRD queue drain for ${prdRef} found no additional ready child work.`
-        );
-        break;
-      }
-      return buildLaunchBlockedOutcome(
-        options.repoRoot,
-        prdRef,
-        buildPrdRunRepairGuidance({
-          blockedGate: "queue",
-          blockedStage: "queue-drain",
-          failureCode: "beads-claim-failed",
-          humanReadableReason: `Beads claim failed for PRD ${prdRef} epic ${claimResult.epicId}.`,
-          repairability: "operator-action",
-          nextAction: "inspect-and-retry",
-          nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
-          diagnostics: [`Beads claim error for epic ${claimResult.epicId}.`]
-        }),
-        plan,
-        startOutcome,
-        targetName,
-        startReceipt
-      );
-    }
-    beadsClaimAttempted = true;
-    logCoordinatorStep(
-      logger,
-      "info",
-      `Claimed Beads child ${claimResult.child.id} for ${prdRef}; mapping to GitHub Issue context.`
-    );
-    const contextResult = await buildIssueContextFromBeadsChild({
-      child: claimResult.child,
-      issueProvider,
-      expectedPrdRef: prdRef
-    });
-    if (!contextResult.ok) {
-      return buildLaunchBlockedOutcome(
-        options.repoRoot,
-        prdRef,
-        buildPrdRunRepairGuidance({
-          blockedGate: "queue",
-          blockedStage: "queue-drain",
-          failureCode: "beads-context-mapping-failed",
-          humanReadableReason: `Failed to map Beads child ${claimResult.child.id} to Issue context: ${contextResult.reason}`,
-          repairability: "operator-action",
-          nextAction: "inspect-and-retry",
-          nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
-          diagnostics: [contextResult.reason],
-          issue: claimedBeadsChildRepairIssue(claimResult.child)
-        }),
-        plan,
-        startOutcome,
-        targetName,
-        startReceipt
-      );
-    }
-    try {
-      const issue = await reconcileBlockedBeadsIssueProjection({
-        issue: contextResult.issue,
-        issueProvider,
-        config: options.config,
+  try {
+    while (true) {
+      const claimResult = await claimReadyPrdChild({
+        repoRoot: options.repoRoot,
         prdRef,
         logger
       });
+      if (!claimResult.ok) {
+        if (claimResult.reason === "no-ready-child") {
+          logCoordinatorStep(
+            logger,
+            "info",
+            `Beads-backed PRD queue drain for ${prdRef} found no additional ready child work.`
+          );
+          break;
+        }
+        return buildLaunchBlockedOutcome(
+          options.repoRoot,
+          prdRef,
+          buildPrdRunRepairGuidance({
+            blockedGate: "queue",
+            blockedStage: "queue-drain",
+            failureCode: "beads-claim-failed",
+            humanReadableReason: `Beads claim failed for PRD ${prdRef} epic ${claimResult.epicId}.`,
+            repairability: "operator-action",
+            nextAction: "inspect-and-retry",
+            nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
+            diagnostics: [`Beads claim error for epic ${claimResult.epicId}.`]
+          }),
+          plan,
+          startOutcome,
+          targetName,
+          startReceipt
+        );
+      }
       logCoordinatorStep(
         logger,
         "info",
-        `Running GitHub Issue #${issue.number} from Beads child ${contextResult.beads.childId}.`
+        `Claimed Beads child ${claimResult.child.id} for ${prdRef}; mapping to GitHub Issue context.`
       );
-      const runResult = await runClaimedPrdIssueCommand({
-        targetName,
-        config: options.config,
+      const contextResult = await buildIssueContextFromBeadsChild({
+        child: claimResult.child,
         issueProvider,
-        prProvider,
-        executionProvider,
-        force: false,
-        logger,
-        repoRoot: options.repoRoot,
-        issue,
-        queueRunContext: {
+        expectedPrdRef: prdRef
+      });
+      if (!contextResult.ok) {
+        return buildLaunchBlockedOutcome(
+          options.repoRoot,
           prdRef,
-          prdBranch: startReceipt.prdBranch,
-          beadsChild: contextResult.beads
+          buildPrdRunRepairGuidance({
+            blockedGate: "queue",
+            blockedStage: "queue-drain",
+            failureCode: "beads-context-mapping-failed",
+            humanReadableReason: `Failed to map Beads child ${claimResult.child.id} to Issue context: ${contextResult.reason}`,
+            repairability: "operator-action",
+            nextAction: "inspect-and-retry",
+            nextRecommendedCommand: `pourkit prd-run status ${prdRef}`,
+            diagnostics: [contextResult.reason],
+            issue: claimedBeadsChildRepairIssue(claimResult.child)
+          }),
+          plan,
+          startOutcome,
+          targetName,
+          startReceipt
+        );
+      }
+      try {
+        const issue = await reconcileBlockedBeadsIssueProjection({
+          issue: contextResult.issue,
+          issueProvider,
+          config: options.config,
+          prdRef,
+          logger
+        });
+        if (issue.labels.includes(options.config.labels.blocked)) {
+          logCoordinatorStep(
+            logger,
+            "info",
+            `Skipping Beads child ${contextResult.beads.childId} because GitHub Issue #${issue.number} remains labeled ${options.config.labels.blocked}.`
+          );
+          skippedBlockedBeadsChildren.push(claimResult.child);
+          continue;
         }
-      });
-      processedResults.push({
-        beadsChildId: claimResult.child.id,
-        issueNumber: runResult.selected.number,
-        noOp: runResult.runResult.noOp,
-        publicationStatus: runResult.runResult.publicationStatus
-      });
-    } catch (error) {
-      const msg = error instanceof Error ? error.message : String(error);
-      const repair = buildQueueIssueRunRepairMetadata(
-        msg,
-        "beads-issue-run-failed",
-        prdRef
-      );
-      const beadsChildClosed = msg.startsWith(
-        "Projection failure after Beads close"
-      );
-      return buildLaunchBlockedOutcome(
-        options.repoRoot,
-        prdRef,
-        buildPrdRunRepairGuidance({
-          blockedGate: "queue",
-          blockedStage: "queue-drain",
-          failureCode: repair.failureCode,
-          humanReadableReason: msg,
-          repairability: repair.repairability,
-          nextAction: repair.nextAction,
-          nextRecommendedCommand: repair.nextRecommendedCommand,
-          diagnostics: [msg],
-          issue: {
-            number: contextResult.issue.number,
-            title: contextResult.issue.title,
-            beadsChildId: contextResult.beads.childId,
-            beadsChildRef: contextResult.beads.childRef,
-            beadsChildClosed
+        beadsClaimAttempted = true;
+        logCoordinatorStep(
+          logger,
+          "info",
+          `Running GitHub Issue #${issue.number} from Beads child ${contextResult.beads.childId}.`
+        );
+        const runResult = await runClaimedPrdIssueCommand({
+          targetName,
+          config: options.config,
+          issueProvider,
+          prProvider,
+          executionProvider,
+          force: false,
+          logger,
+          repoRoot: options.repoRoot,
+          issue,
+          queueRunContext: {
+            prdRef,
+            prdBranch: startReceipt.prdBranch,
+            beadsChild: contextResult.beads
           }
-        }),
-        plan,
-        startOutcome,
-        targetName,
-        startReceipt
-      );
+        });
+        processedResults.push({
+          beadsChildId: claimResult.child.id,
+          issueNumber: runResult.selected.number,
+          noOp: runResult.runResult.noOp,
+          publicationStatus: runResult.runResult.publicationStatus
+        });
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        const repair = buildQueueIssueRunRepairMetadata(
+          msg,
+          "beads-issue-run-failed",
+          prdRef
+        );
+        const beadsChildClosed = msg.startsWith(
+          "Projection failure after Beads close"
+        );
+        return buildLaunchBlockedOutcome(
+          options.repoRoot,
+          prdRef,
+          buildPrdRunRepairGuidance({
+            blockedGate: "queue",
+            blockedStage: "queue-drain",
+            failureCode: repair.failureCode,
+            humanReadableReason: msg,
+            repairability: repair.repairability,
+            nextAction: repair.nextAction,
+            nextRecommendedCommand: repair.nextRecommendedCommand,
+            diagnostics: [msg],
+            issue: {
+              number: contextResult.issue.number,
+              title: contextResult.issue.title,
+              beadsChildId: contextResult.beads.childId,
+              beadsChildRef: contextResult.beads.childRef,
+              beadsChildClosed
+            }
+          }),
+          plan,
+          startOutcome,
+          targetName,
+          startReceipt
+        );
+      }
     }
+  } finally {
+    await releaseSkippedBlockedBeadsChildren({
+      repoRoot: options.repoRoot,
+      children: skippedBlockedBeadsChildren,
+      logger
+    });
   }
   if (processedResults.length === 0 && !beadsClaimAttempted) {
     const diagnostics = [
@@ -14712,13 +14963,18 @@ async function launchBeadsQueueDrain(options, prdRef, startReceipt, targetName,
   writeDrainedRecord(options.repoRoot, prdRef, startReceipt, targetName);
   const drainRecord = readPrdRun(options.repoRoot, prdRef).record;
   if (drainRecord) {
+    const childFinalizationEvidence = await verifyPrdChildFinalizationEvidence({
+      repoRoot: options.repoRoot,
+      prdRef,
+      issueProvider,
+      processedResults
+    });
     const drainContext = {
       prdRef,
       baseBranch: startReceipt.startBaseBranch,
       prdBranch,
-      allChildIssuesFinalizedIntoPrdBranch: processedResults.length > 0 && processedResults.every(
-        (r) => r.noOp || r.publicationStatus === "merged"
-      )
+      allChildIssuesFinalizedIntoPrdBranch: childFinalizationEvidence.ok,
+      childFinalizationDiagnostics: childFinalizationEvidence.diagnostics
     };
     const terminalEvidence = validatePrdRunTerminalEvidence(
       drainRecord,
@@ -15675,12 +15931,12 @@ icm --db .pourkit/icm/memories.db topics                                # list a
 var MANAGED_BLOCK_BEGIN = "<!-- BEGIN POURKIT MANAGED BLOCK -->";
 var MANAGED_BLOCK_END = "<!-- END POURKIT MANAGED BLOCK -->";
 var MANAGED_BLOCK_PATTERN = new RegExp(
-  `${escapeRegExp3(MANAGED_BLOCK_BEGIN)}\\r?\\n[\\s\\S]*?${escapeRegExp3(
+  `${escapeRegExp4(MANAGED_BLOCK_BEGIN)}\\r?\\n[\\s\\S]*?${escapeRegExp4(
     MANAGED_BLOCK_END
   )}[ \\t]*(?:\\r?\\n)?`,
   "g"
 );
-function escapeRegExp3(value) {
+function escapeRegExp4(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function buildManagedBlock(content) {
@@ -15895,6 +16151,12 @@ function generateConfigTemplate(options) {
         promptTemplate: ".pourkit/managed/prompts/issue-final-review.prompt.md",
         maxAttempts: 3
       },
+      postCompletionFinalReview: {
+        agent: "pourkit-reviewer",
+        model: "openai/gpt-5.5",
+        variant: "max",
+        promptTemplate: ".pourkit/managed/prompts/post-completion-final-review.prompt.md"
+      },
       finalize: {
         prDescriptionAgent: {
           agent: "pourkit-pr-description",
@@ -15915,7 +16177,7 @@ function generateConfigTemplate(options) {
   };
   const config = {
     $schema: "./schema/pourkit.schema.json",
-    schemaVersion: 3,
+    schemaVersion: 4,
     targets: [target],
     workflowPack: {
       version: "1.0.0",
@@ -17858,13 +18120,13 @@ Init applied: ${result.applied} operations applied, ${result.skipped} skipped.`
 // commands/memory-init.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync8, readFileSync as readFileSync19, writeFileSync as writeFileSync5 } from "fs";
 import { execFile as execFile3 } from "child_process";
-import { join as join24 } from "path";
+import { join as join25 } from "path";
 import { promisify as promisify3 } from "util";
 var execFileAsync3 = promisify3(execFile3);
 async function runMemoryInitCommand(options) {
   const cwd = options.cwd ?? process.cwd();
   const execCommand = options.execCommand ?? execFileAsync3;
-  const configPath = join24(cwd, ".pourkit", "config.json");
+  const configPath = join25(cwd, ".pourkit", "config.json");
   if (!existsSync20(configPath)) {
     return {
       ok: false,
@@ -17896,8 +18158,8 @@ async function runMemoryInitCommand(options) {
     const next = { ...raw, memory };
     writeFileSync5(configPath, JSON.stringify(next, null, 2) + "\n");
   }
-  const memoryDir = join24(cwd, ".pourkit", "icm");
-  const memoryDbPath = join24(memoryDir, "memories.db");
+  const memoryDir = join25(cwd, ".pourkit", "icm");
+  const memoryDbPath = join25(memoryDir, "memories.db");
   mkdirSync8(memoryDir, { recursive: true });
   let dbInitialized = false;
   let warning;
@@ -17911,7 +18173,7 @@ async function runMemoryInitCommand(options) {
   } catch {
     warning = "ICM is not available or could not initialize .pourkit/icm/memories.db. Install ICM and run `pourkit doctor` to verify repo-scoped memory setup.";
   }
-  const gitignorePath = join24(cwd, ".gitignore");
+  const gitignorePath = join25(cwd, ".gitignore");
   updateManagedBlockSync(gitignorePath, generateGitignoreBlock());
   const managed = await generateManagedAgentInstructions({
     sourceRoot: cwd,
@@ -17919,14 +18181,14 @@ async function runMemoryInitCommand(options) {
   });
   let updatedAgentFile = false;
   for (const fileName of ["AGENTS.md", "CLAUDE.md"]) {
-    const agentPath = join24(cwd, fileName);
+    const agentPath = join25(cwd, fileName);
     if (existsSync20(agentPath)) {
       updateManagedBlockSync(agentPath, managed);
       updatedAgentFile = true;
     }
   }
   if (!updatedAgentFile) {
-    updateManagedBlockSync(join24(cwd, "AGENTS.md"), managed);
+    updateManagedBlockSync(join25(cwd, "AGENTS.md"), managed);
   }
   return {
     ok: true,
@@ -20198,7 +20460,7 @@ init_common();
 
 // execution/sandcastle-execution.ts
 import { existsSync as existsSync24, mkdirSync as mkdirSync9, statSync as statSync2, writeFileSync as writeFileSync6 } from "fs";
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 import { createWorktree, opencode } from "@ai-hero/sandcastle";
 import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
@@ -20207,10 +20469,10 @@ init_common();
 import { mkdtempSync } from "fs";
 import { writeFile as writeFile5 } from "fs/promises";
 import { tmpdir } from "os";
-import { dirname as dirname8, join as join25 } from "path";
+import { dirname as dirname8, join as join26 } from "path";
 async function writeExecutionArtifacts(worktreePath, artifacts) {
   for (const artifact of artifacts) {
-    const filePath = join25(worktreePath, artifact.path);
+    const filePath = join26(worktreePath, artifact.path);
     await ensureDir(dirname8(filePath));
     await writeFile5(filePath, artifact.content, "utf-8");
   }
@@ -20272,7 +20534,7 @@ async function createSandboxFromExistingWorktree(options) {
 }
 
 // execution/sandbox-options.ts
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 var POURKIT_ICM_CONTAINER_DIR = "/home/agent/.pourkit/icm";
 function buildSandboxOptions(repoRoot2, sandbox, memory) {
   const mounts = [];
@@ -20281,12 +20543,12 @@ function buildSandboxOptions(repoRoot2, sandbox, memory) {
   }
   if (memory?.available) {
     mounts.push({
-      hostPath: join26(repoRoot2, ".pourkit", "icm"),
+      hostPath: join27(repoRoot2, ".pourkit", "icm"),
       sandboxPath: POURKIT_ICM_CONTAINER_DIR,
       readonly: false
     });
     mounts.push({
-      hostPath: join26(repoRoot2, ".pourkit", "icm", "cache"),
+      hostPath: join27(repoRoot2, ".pourkit", "icm", "cache"),
       sandboxPath: "/home/agent/.cache/icm",
       readonly: false
     });
@@ -20420,13 +20682,13 @@ var SandcastleExecutionSession = class {
             "Memory enabled but memory context is invalid. Run `pourkit memory init` or install ICM for host planning use."
           );
         }
-        const hostMemoryDir = join27(repoRoot2, ".pourkit", "icm");
+        const hostMemoryDir = join28(repoRoot2, ".pourkit", "icm");
         if (!existsSync24(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(join27(hostMemoryDir, "cache"), { recursive: true });
+        mkdirSync9(join28(hostMemoryDir, "cache"), { recursive: true });
       }
       const sandboxOptions = buildSandboxOptions(
         repoRoot2,
@@ -20585,7 +20847,7 @@ function sanitizeBranch(branchName) {
 }
 function safeCopyToWorktreePaths(paths, repoRoot2, worktreePath) {
   return paths.filter((relativePath) => {
-    const source = join27(repoRoot2, relativePath);
+    const source = join28(repoRoot2, relativePath);
     if (!existsSync24(source)) {
       return true;
     }
@@ -20596,7 +20858,7 @@ function safeCopyToWorktreePaths(paths, repoRoot2, worktreePath) {
     } catch {
       return true;
     }
-    const destination = join27(worktreePath, relativePath);
+    const destination = join28(worktreePath, relativePath);
     return !existsSync24(destination);
   });
 }
@@ -20661,12 +20923,12 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function savePromptToFile(repoRoot2, stage, iteration, prompt) {
-  const promptsDir = join27(repoRoot2, ".pourkit", ".tmp", "prompts");
+  const promptsDir = join28(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 = join27(promptsDir, filename);
+  const filePath = join28(promptsDir, filename);
   writeFileSync6(filePath, prompt, "utf-8");
 }
 
@@ -21450,11 +21712,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260714055657")) {
-    return "0.0.0-next-20260714055657";
+  if (isPackageVersion("0.0.0-next-20260715085442")) {
+    return "0.0.0-next-20260715085442";
   }
-  if (isReleaseVersion("0.0.0-next-20260714055657")) {
-    return "0.0.0-next-20260714055657";
+  if (isReleaseVersion("0.0.0-next-20260715085442")) {
+    return "0.0.0-next-20260715085442";
   }
   try {
     const root = repoRoot();