@pourkit/cli 0.0.0-next-20260611235559 → 0.0.0-next-20260613012953

package/dist/cli.js

@@ -1041,7 +1041,7 @@ async function cleanupRepository(options) {
 // commands/artifact-validation.ts
 import { createHash } from "crypto";
 import { execSync } from "child_process";
-import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync6 } from "fs";
 import { isAbsolute, join as join6, resolve } from "path";
 
 // pr/review-verdict.ts
@@ -2938,6 +2938,194 @@ function parseConflictResolutionArtifact(output) {
   };
 }
 
+// prd-run/final-review-validation.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+function parseFinalReviewArtifact(artifactPath) {
+  if (!existsSync5(artifactPath)) {
+    return {
+      ok: false,
+      reason: "Final Review artifact not found.",
+      diagnostics: [`Artifact path: ${artifactPath}`]
+    };
+  }
+  let content;
+  try {
+    content = readFileSync5(artifactPath, "utf-8");
+  } catch (error) {
+    return {
+      ok: false,
+      reason: "Final Review artifact could not be read.",
+      diagnostics: [
+        error instanceof Error ? error.message : String(error),
+        `Artifact path: ${artifactPath}`
+      ]
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return {
+      ok: false,
+      reason: "Final Review artifact is not valid JSON.",
+      diagnostics: [`Artifact path: ${artifactPath}`]
+    };
+  }
+  const verdict = parsed.verdict;
+  if (!verdict || typeof verdict !== "string") {
+    return {
+      ok: false,
+      reason: "Final Review artifact is missing a verdict field.",
+      diagnostics: [`Artifact content preview: ${content.slice(0, 300)}`]
+    };
+  }
+  const allowedVerdicts = [
+    "pass_no_changes",
+    "pass_with_retouch",
+    "needs_human_review",
+    "blocked"
+  ];
+  if (!allowedVerdicts.includes(verdict)) {
+    return {
+      ok: false,
+      reason: `Final Review artifact has unsupported verdict "${verdict}".`,
+      diagnostics: [`Allowed verdicts: ${allowedVerdicts.join(", ")}`]
+    };
+  }
+  const summary = typeof parsed.summary === "string" ? parsed.summary : typeof parsed.reason === "string" ? parsed.reason : String(verdict);
+  const diagnostics = Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [];
+  const changedPaths = Array.isArray(parsed.changedPaths) ? parsed.changedPaths : void 0;
+  const isAutoSummary = !parsed.summary && !parsed.reason;
+  if (verdict === "pass_with_retouch" && (!changedPaths || changedPaths.length === 0) && isAutoSummary) {
+    return {
+      ok: false,
+      reason: 'Final Review artifact with "pass_with_retouch" verdict requires changed paths.',
+      diagnostics: [
+        "pass_with_retouch verdict must include a changedPaths array in the artifact or provide a summary/reason with enough context for git diff fallback.",
+        "Provide changedPaths or a descriptive summary in the artifact."
+      ]
+    };
+  }
+  const prdRef = typeof parsed.prdRef === "string" && parsed.prdRef.trim() ? parsed.prdRef.trim() : void 0;
+  const stage = typeof parsed.stage === "string" && parsed.stage.trim() ? parsed.stage.trim() : void 0;
+  const checkoutBase = typeof parsed.checkoutBase === "string" && parsed.checkoutBase.trim() ? parsed.checkoutBase.trim() : void 0;
+  const reviewBase = typeof parsed.reviewBase === "string" && parsed.reviewBase.trim() ? parsed.reviewBase.trim() : void 0;
+  return {
+    ok: true,
+    verdict,
+    summary,
+    diagnostics,
+    changedPaths,
+    prdRef,
+    stage,
+    checkoutBase,
+    reviewBase
+  };
+}
+function validateFinalReviewArtifactSemanticIds(artifact, context) {
+  const errors = [];
+  if (!artifact.prdRef) {
+    errors.push("Final Review artifact is missing prdRef.");
+  } else if (artifact.prdRef !== context.prdRef) {
+    errors.push(
+      `Final Review artifact prdRef "${artifact.prdRef}" does not match active PRD Run "${context.prdRef}".`
+    );
+  }
+  if (!artifact.stage) {
+    errors.push("Final Review artifact is missing stage field.");
+  } else if (artifact.stage !== "prdFinalReview") {
+    errors.push(
+      `Final Review artifact stage "${artifact.stage}" is not "prdFinalReview".`
+    );
+  }
+  if (!artifact.checkoutBase) {
+    errors.push("Final Review artifact is missing checkoutBase.");
+  } else if (artifact.checkoutBase !== context.prdBranch) {
+    errors.push(
+      `Final Review artifact checkoutBase "${artifact.checkoutBase}" does not match active PRD Branch "${context.prdBranch}".`
+    );
+  }
+  if (!artifact.reviewBase) {
+    errors.push("Final Review artifact is missing reviewBase.");
+  } else if (artifact.reviewBase !== context.mergeBase) {
+    errors.push(
+      `Final Review artifact reviewBase "${artifact.reviewBase}" does not match active merge base "${context.mergeBase}".`
+    );
+  }
+  if (errors.length > 0) {
+    return { ok: false, errors, blockedGate: "final-review" };
+  }
+  return { ok: true };
+}
+function validateFinalReviewRetouchScope(changedPaths) {
+  if (!changedPaths || changedPaths.length === 0) {
+    return {
+      ok: false,
+      reason: "Final Review retouch scope validation failed. No changed paths available. Provide changed paths or run Final Review with a summary that includes changed paths.",
+      diagnostics: ["Changed paths list is empty or undefined."],
+      offendingPaths: []
+    };
+  }
+  const offendingPaths = changedPaths.filter((p) => !isRetouchScopePath(p));
+  const allowedPaths = changedPaths.filter((p) => isRetouchScopePath(p));
+  if (allowedPaths.length === 0) {
+    return {
+      ok: false,
+      reason: "Final Review retouch scope validation failed. No implementation, test, or Changeset paths found for retouch.",
+      diagnostics: [
+        "All changed paths are prohibited for retouch.",
+        ...changedPaths.map((p) => `  - ${p}`)
+      ],
+      offendingPaths
+    };
+  }
+  if (offendingPaths.length > 0) {
+    return {
+      ok: false,
+      reason: "Final Review retouch scope validation failed. Prohibited paths cannot be included in retouch PR.",
+      diagnostics: [
+        "Prohibited paths found:",
+        ...offendingPaths.map((p) => `  - ${p}`)
+      ],
+      offendingPaths
+    };
+  }
+  return { ok: true, changedPaths };
+}
+function validateFinalReviewAgentOutputs(options) {
+  const artifact = parseFinalReviewArtifact(options.artifactPath);
+  if (!artifact.ok) {
+    return { ...artifact, offendingPaths: [] };
+  }
+  const semanticResult = validateFinalReviewArtifactSemanticIds(
+    artifact,
+    options.context
+  );
+  if (!semanticResult.ok) {
+    return {
+      ok: false,
+      reason: "Final Review artifact has mismatched semantic IDs.",
+      diagnostics: semanticResult.errors,
+      offendingPaths: []
+    };
+  }
+  if (artifact.verdict !== "pass_with_retouch") {
+    return { ok: true, artifact };
+  }
+  const changedPaths = options.changedPaths && options.changedPaths.length > 0 ? options.changedPaths : artifact.changedPaths;
+  const retouch = validateFinalReviewRetouchScope(changedPaths ?? []);
+  if (!retouch.ok) {
+    return retouch;
+  }
+  return { ok: true, artifact, retouch };
+}
+function isRetouchScopePath(path9) {
+  if (path9.startsWith(".pourkit/architecture/") || path9 === ".pourkit/CONTEXT.md" || path9.startsWith(".pourkit/docs/adr/") || /^\.pourkit\/prd-runs\/[^/]+\.json$/.test(path9)) {
+    return false;
+  }
+  return true;
+}
+
 // commands/artifact-validation.ts
 var CONFLICT_MARKER_PATTERN = /<<<<<<<|=======|>>>>>>>/m;
 function invalid(options, reason, diagnostics = []) {
@@ -2958,14 +3146,14 @@ function valid(options, diagnostics = []) {
   };
 }
 function readArtifact(options) {
-  if (!existsSync5(options.artifactPath)) {
+  if (!existsSync6(options.artifactPath)) {
     return {
       ok: false,
       result: invalid(options, `Artifact missing at ${options.artifactPath}`)
     };
   }
   try {
-    const content = readFileSync5(options.artifactPath, "utf-8");
+    const content = readFileSync6(options.artifactPath, "utf-8");
     if (!content.trim()) {
       return { ok: false, result: invalid(options, "Artifact is empty") };
     }
@@ -2998,7 +3186,7 @@ function validateAgentArtifact(options) {
       case "refactor": {
         let findingIds = options.findingIds ?? [];
         if (findingIds.length === 0 && options.latestReviewArtifactPath) {
-          const latestReview = readFileSync5(
+          const latestReview = readFileSync6(
             options.latestReviewArtifactPath,
             "utf-8"
           );
@@ -3024,7 +3212,7 @@ function validateAgentArtifact(options) {
             const filePath = resolve(base, file);
             try {
               return CONFLICT_MARKER_PATTERN.test(
-                readFileSync5(filePath, "utf-8")
+                readFileSync6(filePath, "utf-8")
               );
             } catch {
               return false;
@@ -3040,6 +3228,26 @@ function validateAgentArtifact(options) {
         }
         return valid(options, [`status: ${parsed.status}`]);
       }
+      case "final-review": {
+        if (!options.prdRef || !options.checkoutBase || !options.reviewBase) {
+          return invalid(
+            options,
+            "Final Review artifact validation requires --prd-ref, --checkout-base, and --review-base."
+          );
+        }
+        const result = validateFinalReviewAgentOutputs({
+          artifactPath: options.artifactPath,
+          context: {
+            prdRef: options.prdRef,
+            prdBranch: options.checkoutBase,
+            mergeBase: options.reviewBase
+          }
+        });
+        if (!result.ok) {
+          return invalid(options, result.reason, result.diagnostics);
+        }
+        return valid(options, [`verdict: ${result.artifact.verdict}`]);
+      }
       case "failure-resolution": {
         const parsed = parseRecoveryArtifact(
           artifact.content,
@@ -3145,7 +3353,7 @@ function runLocalValidateArtifactCommand(options) {
 }
 function readLocalArtifact(path9, failureCode) {
   try {
-    const raw = readFileSync5(path9, "utf-8");
+    const raw = readFileSync6(path9, "utf-8");
     const parsed = JSON.parse(raw);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {
@@ -3844,7 +4052,7 @@ function validateLocalTriage(prdPath, issuePaths) {
 }
 
 // commands/issue-run.ts
-import { existsSync as existsSync9, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
 import { join as join13 } from "path";
 
 // pr/templates.ts
@@ -3980,7 +4188,7 @@ function runEffectAndMapExit(program) {
 }
 
 // shared/attempt-log.ts
-import { appendFileSync, existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync6 } from "fs";
+import { appendFileSync, existsSync as existsSync7, mkdirSync as mkdirSync6, readFileSync as readFileSync7 } from "fs";
 import { dirname as dirname3, join as join7 } from "path";
 var ATTEMPT_LOG_PATH = ".pourkit/attempt-log.jsonl";
 function writeAttemptLog(worktreePath, entry) {
@@ -3990,10 +4198,10 @@ function writeAttemptLog(worktreePath, entry) {
 }
 function readAttemptLog(worktreePath) {
   const logPath = join7(worktreePath, ATTEMPT_LOG_PATH);
-  if (!existsSync6(logPath)) {
+  if (!existsSync7(logPath)) {
     return [];
   }
-  const raw = readFileSync6(logPath, "utf-8");
+  const raw = readFileSync7(logPath, "utf-8");
   const lines = raw.split("\n").filter((l) => l.length > 0);
   const entries = [];
   for (const line of lines) {
@@ -4112,7 +4320,7 @@ async function runBaseRefreshAttempt(options) {
 }
 
 // commands/conflict-resolution.ts
-import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
 import { join as join8 } from "path";
 init_common();
 var CONFLICT_MARKER_PATTERN2 = /<<<<<<<|=======|>>>>>>>/m;
@@ -4120,7 +4328,7 @@ async function hasUnresolvedConflictMarkers(worktreePath, files) {
   for (const file of files) {
     const filePath = join8(worktreePath, file);
     try {
-      const content = readFileSync7(filePath, "utf-8");
+      const content = readFileSync8(filePath, "utf-8");
       if (CONFLICT_MARKER_PATTERN2.test(content)) {
         return true;
       }
@@ -4451,7 +4659,7 @@ async function prepareSerenaForTarget(options) {
 }
 
 // failure-resolution/failure-resolution-agent.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { join as join9 } from "path";
 
 // failure-resolution/recovery-policy.ts
@@ -4605,7 +4813,7 @@ async function runFailureResolutionAgent(options) {
   }
   let artifact;
   try {
-    const md = readFileSync8(fullArtifactPath, "utf-8");
+    const md = readFileSync9(fullArtifactPath, "utf-8");
     const validation2 = validateAgentArtifact({
       kind: "failure-resolution",
       artifactPath: fullArtifactPath,
@@ -4699,7 +4907,7 @@ async function writeRecoveryAttempt(worktreePath, outcome, fingerprint, summary,
 
 // commands/pr-description-agent.ts
 import { join as join11 } from "path";
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 
 // pr/pr-description-context.ts
 init_common();
@@ -4893,7 +5101,7 @@ function runFinalizerAgent(options) {
       ],
       logger: options.logger
     });
-    const output = readFileSync9(artifactPath, "utf-8");
+    const output = readFileSync10(artifactPath, "utf-8");
     yield* persistGeneratedArtifactEffect(options.worktreePath, output, fs);
     return result;
   });
@@ -5021,7 +5229,7 @@ function persistGeneratedArtifactEffect(worktreePath, output, fs) {
 
 // prd-run/local-merge-coordinator.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync9, mkdirSync as mkdirSync7, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "fs";
 import { join as join12 } from "path";
 
 // prd-run/local-branches.ts
@@ -5122,9 +5330,9 @@ function getIssueArtifactPath(repoRoot2, prdId, issueId) {
 }
 function readIssueBranchName(repoRoot2, prdId, issueId) {
   const issuePath = getIssueArtifactPath(repoRoot2, prdId, issueId);
-  if (!existsSync8(issuePath)) return null;
+  if (!existsSync9(issuePath)) return null;
   try {
-    const content = readFileSync10(issuePath, "utf-8");
+    const content = readFileSync11(issuePath, "utf-8");
     const parsed = JSON.parse(content);
     return typeof parsed.branchName === "string" && parsed.branchName ? parsed.branchName : null;
   } catch {
@@ -5134,9 +5342,9 @@ function readIssueBranchName(repoRoot2, prdId, issueId) {
 async function hasLocalIssueMergeReceipt(prdId, issueId, repoRoot2) {
   const root = repoRoot2 ?? process.cwd();
   const receiptPath = getMergeReceiptPath(root, prdId, issueId);
-  if (!existsSync8(receiptPath)) return null;
+  if (!existsSync9(receiptPath)) return null;
   try {
-    const content = readFileSync10(receiptPath, "utf-8");
+    const content = readFileSync11(receiptPath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.prdId === "string" && typeof parsed.issueId === "string" && typeof parsed.stage === "string" && typeof parsed.sourceBranch === "string" && typeof parsed.localPrdBranch === "string" && typeof parsed.mergeCommit === "string" && typeof parsed.completedAt === "string") {
       return parsed;
@@ -5149,10 +5357,10 @@ async function hasLocalIssueMergeReceipt(prdId, issueId, repoRoot2) {
 async function squashMergeLocalIssue(prdId, issueId, input, repoRoot2) {
   const root = repoRoot2 ?? process.cwd();
   const receiptPath = getMergeReceiptPath(root, prdId, issueId);
-  if (existsSync8(receiptPath)) {
+  if (existsSync9(receiptPath)) {
     try {
       const existing = JSON.parse(
-        readFileSync10(receiptPath, "utf-8")
+        readFileSync11(receiptPath, "utf-8")
       );
       if (existing.prdId === prdId && existing.issueId === issueId && existing.mergeCommit) {
         return {
@@ -6047,12 +6255,12 @@ async function completeIssueRun(options) {
           prTitle = finalizerFromState.title;
           prBody = finalizerFromState.body;
         } else if (finalizerFromState.artifactPath) {
-          if (!existsSync9(finalizerFromState.artifactPath)) {
+          if (!existsSync10(finalizerFromState.artifactPath)) {
             throw new FinalizerFailure({
               message: `Finalizer artifact missing at ${finalizerFromState.artifactPath}`
             });
           }
-          const artifactContent = readFileSync11(
+          const artifactContent = readFileSync12(
             finalizerFromState.artifactPath,
             "utf-8"
           );
@@ -6749,7 +6957,7 @@ async function syncTargetBranch(root, baseBranch, logger) {
 }
 function loadBuilderPrompt(repoRoot2, promptTemplate) {
   const promptPath = resolvePromptTemplatePath(repoRoot2, promptTemplate);
-  const promptBody = existsSync9(promptPath) ? readFileSync11(promptPath, "utf-8") : promptTemplate;
+  const promptBody = existsSync10(promptPath) ? readFileSync12(promptPath, "utf-8") : promptTemplate;
   return appendProtectedWorkGuidance(`${promptBody}
 
 ## Shared Run Context
@@ -7207,9 +7415,9 @@ import { Match, pipe } from "effect";
 
 // prd-run/state.ts
 import {
-  existsSync as existsSync10,
+  existsSync as existsSync11,
   mkdirSync as mkdirSync8,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   readdirSync as readdirSync3,
   writeFileSync as writeFileSync5
 } from "fs";
@@ -7245,6 +7453,7 @@ var PrdRunRecordSchema = z2.object({
     status: z2.enum(["started", "succeeded", "adopted", "reused"]),
     targetName: z2.string().min(1),
     prdBranch: z2.string().min(1),
+    startBaseBranch: z2.string().min(1),
     startBaseCommit: z2.string().min(1).optional(),
     branchAction: z2.enum(["created", "reused", "adopted"]).optional(),
     startedAt: z2.string().min(1).optional(),
@@ -7303,15 +7512,26 @@ function normalizePrdRunRef(ref) {
 function readPrdRun(repoRoot2, prdRef) {
   const normalized = normalizePrdRunRef(prdRef);
   const recordPath = getRecordPath(repoRoot2, normalized);
-  if (!existsSync10(recordPath)) {
+  if (!existsSync11(recordPath)) {
     return { record: null, diagnostics: [] };
   }
   try {
-    const parsed = PrdRunRecordSchema.parse(
-      JSON.parse(readFileSync12(recordPath, "utf-8"))
-    );
+    const raw = JSON.parse(readFileSync13(recordPath, "utf-8"));
+    const parsed = PrdRunRecordSchema.parse(raw);
     return { record: parsed, diagnostics: [] };
   } catch (error) {
+    try {
+      const raw = JSON.parse(readFileSync13(recordPath, "utf-8"));
+      if (raw && typeof raw === "object" && raw.start && typeof raw.start === "object" && raw.start.startBaseBranch === void 0) {
+        return {
+          record: raw,
+          diagnostics: [
+            `Legacy PRD Run record at ${recordPath} is missing startBaseBranch.`
+          ]
+        };
+      }
+    } catch {
+    }
     return {
       record: null,
       diagnostics: [
@@ -7323,7 +7543,7 @@ function readPrdRun(repoRoot2, prdRef) {
 }
 function listPrdRuns(repoRoot2) {
   const stateDir = join14(repoRoot2, PRD_RUN_STATE_DIR);
-  if (!existsSync10(stateDir)) {
+  if (!existsSync11(stateDir)) {
     return { records: [], diagnostics: [] };
   }
   const records = [];
@@ -7335,7 +7555,7 @@ function listPrdRuns(repoRoot2) {
     const recordPath = join14(stateDir, entry.name);
     try {
       const record = PrdRunRecordSchema.parse(
-        JSON.parse(readFileSync12(recordPath, "utf-8"))
+        JSON.parse(readFileSync13(recordPath, "utf-8"))
       );
       records.push(record);
     } catch (error) {
@@ -7403,7 +7623,7 @@ function getLocalStorePath2(repoRoot2, prdId) {
 async function readLocalPrdRun(repoRoot2, prdId) {
   const normalized = normalizePrdRunRef(prdId);
   const recordPath = getLocalStorePath2(repoRoot2, normalized);
-  if (!existsSync10(recordPath)) {
+  if (!existsSync11(recordPath)) {
     return null;
   }
   try {
@@ -7512,191 +7732,30 @@ function buildEvidencePacket(input) {
     prdBranch: input.prdBranch.trim(),
     mergeBase,
     planningManifestPath: input.planningManifestPath.trim(),
-    planningManifestFacts: {
-      parentPrdIssueUrl: input.planningManifestFacts.parentPrdIssueUrl.trim(),
-      childIssueCount: input.planningManifestFacts.childIssueCount
-    },
-    stage: stageResult.data,
-    stageReceipts: input.stageReceipts
-  };
-  return packet;
-}
-var TOKEN_LIKE_PATTERNS = [
-  /gh[ps]_[A-Za-z0-9]{20,}/g,
-  /token[=:_\s][A-Za-z0-9_-]{20,}/gi,
-  /secret[=:_\s][A-Za-z0-9_-]{20,}/gi,
-  /credential[=:_\s][A-Za-z0-9_-]{20,}/gi,
-  /key[=:_\s][A-Za-z0-9_-]{20,}/gi,
-  /-----BEGIN (RSA |EC )?PRIVATE KEY-----/g,
-  /xox[baprs]-[A-Za-z0-9_-]{10,}/g
-];
-function redactSensitiveValues(input) {
-  let redacted = input;
-  for (const pattern of TOKEN_LIKE_PATTERNS) {
-    redacted = redacted.replace(pattern, "[REDACTED]");
-  }
-  return redacted;
-}
-
-// prd-run/final-review-validation.ts
-import { existsSync as existsSync11, readFileSync as readFileSync13 } from "fs";
-function parseFinalReviewArtifact(artifactPath) {
-  if (!existsSync11(artifactPath)) {
-    return {
-      ok: false,
-      reason: "Final Review artifact not found.",
-      diagnostics: [`Artifact path: ${artifactPath}`]
-    };
-  }
-  let content;
-  try {
-    content = readFileSync13(artifactPath, "utf-8");
-  } catch (error) {
-    return {
-      ok: false,
-      reason: "Final Review artifact could not be read.",
-      diagnostics: [
-        error instanceof Error ? error.message : String(error),
-        `Artifact path: ${artifactPath}`
-      ]
-    };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    return {
-      ok: false,
-      reason: "Final Review artifact is not valid JSON.",
-      diagnostics: [`Artifact path: ${artifactPath}`]
-    };
-  }
-  const verdict = parsed.verdict;
-  if (!verdict || typeof verdict !== "string") {
-    return {
-      ok: false,
-      reason: "Final Review artifact is missing a verdict field.",
-      diagnostics: [`Artifact content preview: ${content.slice(0, 300)}`]
-    };
-  }
-  const allowedVerdicts = [
-    "pass_no_changes",
-    "pass_with_retouch",
-    "needs_human_review",
-    "blocked"
-  ];
-  if (!allowedVerdicts.includes(verdict)) {
-    return {
-      ok: false,
-      reason: `Final Review artifact has unsupported verdict "${verdict}".`,
-      diagnostics: [`Allowed verdicts: ${allowedVerdicts.join(", ")}`]
-    };
-  }
-  const summary = typeof parsed.summary === "string" ? parsed.summary : typeof parsed.reason === "string" ? parsed.reason : String(verdict);
-  const diagnostics = Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [];
-  const changedPaths = Array.isArray(parsed.changedPaths) ? parsed.changedPaths : void 0;
-  const isAutoSummary = !parsed.summary && !parsed.reason;
-  if (verdict === "pass_with_retouch" && (!changedPaths || changedPaths.length === 0) && isAutoSummary) {
-    return {
-      ok: false,
-      reason: 'Final Review artifact with "pass_with_retouch" verdict requires changed paths.',
-      diagnostics: [
-        "pass_with_retouch verdict must include a changedPaths array in the artifact or provide a summary/reason with enough context for git diff fallback.",
-        "Provide changedPaths or a descriptive summary in the artifact."
-      ]
-    };
-  }
-  const prdRef = typeof parsed.prdRef === "string" && parsed.prdRef.trim() ? parsed.prdRef.trim() : void 0;
-  const stage = typeof parsed.stage === "string" && parsed.stage.trim() ? parsed.stage.trim() : void 0;
-  const checkoutBase = typeof parsed.checkoutBase === "string" && parsed.checkoutBase.trim() ? parsed.checkoutBase.trim() : void 0;
-  const reviewBase = typeof parsed.reviewBase === "string" && parsed.reviewBase.trim() ? parsed.reviewBase.trim() : void 0;
-  return {
-    ok: true,
-    verdict,
-    summary,
-    diagnostics,
-    changedPaths,
-    prdRef,
-    stage,
-    checkoutBase,
-    reviewBase
-  };
-}
-function validateFinalReviewArtifactSemanticIds(artifact, context) {
-  const errors = [];
-  if (!artifact.prdRef) {
-    errors.push("Final Review artifact is missing prdRef.");
-  } else if (artifact.prdRef !== context.prdRef) {
-    errors.push(
-      `Final Review artifact prdRef "${artifact.prdRef}" does not match active PRD Run "${context.prdRef}".`
-    );
-  }
-  if (!artifact.stage) {
-    errors.push("Final Review artifact is missing stage field.");
-  } else if (artifact.stage !== "prdFinalReview") {
-    errors.push(
-      `Final Review artifact stage "${artifact.stage}" is not "prdFinalReview".`
-    );
-  }
-  if (!artifact.checkoutBase) {
-    errors.push("Final Review artifact is missing checkoutBase.");
-  } else if (artifact.checkoutBase !== context.prdBranch) {
-    errors.push(
-      `Final Review artifact checkoutBase "${artifact.checkoutBase}" does not match active PRD Branch "${context.prdBranch}".`
-    );
-  }
-  if (!artifact.reviewBase) {
-    errors.push("Final Review artifact is missing reviewBase.");
-  } else if (artifact.reviewBase !== context.mergeBase) {
-    errors.push(
-      `Final Review artifact reviewBase "${artifact.reviewBase}" does not match active merge base "${context.mergeBase}".`
-    );
-  }
-  if (errors.length > 0) {
-    return { ok: false, errors, blockedGate: "final-review" };
-  }
-  return { ok: true };
-}
-function validateFinalReviewRetouchScope(changedPaths) {
-  if (!changedPaths || changedPaths.length === 0) {
-    return {
-      ok: false,
-      reason: "Final Review retouch scope validation failed. No changed paths available. Provide changed paths or run Final Review with a summary that includes changed paths.",
-      diagnostics: ["Changed paths list is empty or undefined."],
-      offendingPaths: []
-    };
-  }
-  const offendingPaths = changedPaths.filter((p) => !isRetouchScopePath(p));
-  const allowedPaths = changedPaths.filter((p) => isRetouchScopePath(p));
-  if (allowedPaths.length === 0) {
-    return {
-      ok: false,
-      reason: "Final Review retouch scope validation failed. No implementation, test, or Changeset paths found for retouch.",
-      diagnostics: [
-        "All changed paths are prohibited for retouch.",
-        ...changedPaths.map((p) => `  - ${p}`)
-      ],
-      offendingPaths
-    };
-  }
-  if (offendingPaths.length > 0) {
-    return {
-      ok: false,
-      reason: "Final Review retouch scope validation failed. Prohibited paths cannot be included in retouch PR.",
-      diagnostics: [
-        "Prohibited paths found:",
-        ...offendingPaths.map((p) => `  - ${p}`)
-      ],
-      offendingPaths
-    };
-  }
-  return { ok: true, changedPaths };
+    planningManifestFacts: {
+      parentPrdIssueUrl: input.planningManifestFacts.parentPrdIssueUrl.trim(),
+      childIssueCount: input.planningManifestFacts.childIssueCount
+    },
+    stage: stageResult.data,
+    stageReceipts: input.stageReceipts
+  };
+  return packet;
 }
-function isRetouchScopePath(path9) {
-  if (path9.startsWith(".pourkit/architecture/") || path9 === ".pourkit/CONTEXT.md" || path9.startsWith(".pourkit/docs/adr/") || /^\.pourkit\/prd-runs\/[^/]+\.json$/.test(path9)) {
-    return false;
+var TOKEN_LIKE_PATTERNS = [
+  /gh[ps]_[A-Za-z0-9]{20,}/g,
+  /token[=:_\s][A-Za-z0-9_-]{20,}/gi,
+  /secret[=:_\s][A-Za-z0-9_-]{20,}/gi,
+  /credential[=:_\s][A-Za-z0-9_-]{20,}/gi,
+  /key[=:_\s][A-Za-z0-9_-]{20,}/gi,
+  /-----BEGIN (RSA |EC )?PRIVATE KEY-----/g,
+  /xox[baprs]-[A-Za-z0-9_-]{10,}/g
+];
+function redactSensitiveValues(input) {
+  let redacted = input;
+  for (const pattern of TOKEN_LIKE_PATTERNS) {
+    redacted = redacted.replace(pattern, "[REDACTED]");
   }
-  return true;
+  return redacted;
 }
 
 // commands/prd-run.ts
@@ -8886,6 +8945,7 @@ function buildStartReceipt(options) {
     status: options.status,
     targetName: options.targetName,
     prdBranch: options.prdBranch,
+    startBaseBranch: options.startBaseBranch,
     startBaseCommit: options.startBaseCommit,
     branchAction: options.branchAction,
     startedAt: options.startedAt,
@@ -8914,7 +8974,7 @@ function buildFinalReviewPrompt(options) {
     `Worktree checkout base: ${options.evidencePacket.prdBranch}`,
     `Review only this range: ${options.evidencePacket.mergeBase}..HEAD`,
     "Do not compare against current target branch HEAD; the merge base is the review baseline.",
-    `Before handoff, run: pourkit prd-run validate-final-review ${options.evidencePacket.prdRef} --checkout-base ${options.evidencePacket.prdBranch} --review-base ${options.evidencePacket.mergeBase}`,
+    `Before handoff, run: pourkit validate-artifact final-review .pourkit/final-review-artifact.json --prd-ref ${options.evidencePacket.prdRef} --checkout-base ${options.evidencePacket.prdBranch} --review-base ${options.evidencePacket.mergeBase}`,
     "Fix any validation failures before handing off.",
     "",
     "## Verification",
@@ -8941,40 +9001,6 @@ function finalReviewWorktreePath(repoRoot2, branchName) {
     branchName.replace(/\//g, "-")
   );
 }
-function computeFinalReviewMergeBase(repoRoot2, prdRef) {
-  const result = spawnSync3(
-    "git",
-    ["merge-base", "origin/dev", `origin/${prdRef}`],
-    {
-      cwd: repoRoot2,
-      encoding: "utf8"
-    }
-  );
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      gate: "final-review",
-      reason: `Unable to fetch refs and compute Final Review merge-base for ${prdRef}.`,
-      diagnostics: collectSpawnDiagnostics(result, "git merge-base failed")
-    };
-  }
-  return { ok: true, mergeBase: result.stdout.trim(), diagnostics: [] };
-}
-function computeLocalFinalReviewMergeBase(repoRoot2, localPrdBranch) {
-  const result = spawnSync3("git", ["merge-base", "HEAD", localPrdBranch], {
-    cwd: repoRoot2,
-    encoding: "utf8"
-  });
-  if (result.status !== 0) {
-    return {
-      ok: false,
-      gate: "final-review",
-      reason: `Unable to compute Final Review merge-base for ${localPrdBranch}.`,
-      diagnostics: collectSpawnDiagnostics(result, "git merge-base failed")
-    };
-  }
-  return { ok: true, mergeBase: result.stdout.trim(), diagnostics: [] };
-}
 function collectSpawnDiagnostics(result, fallback) {
   const diagnostics = [];
   const stderr = result.stderr?.toString?.().trim();
@@ -9411,7 +9437,7 @@ async function runPrdRunFinalReviewCommand(options) {
     options.repoRoot,
     prdRef
   );
-  if (readDiagnostics.length > 0) {
+  if (readDiagnostics.length > 0 && !record) {
     const reason = `PRD Run ${prdRef} has a malformed record and cannot proceed to Final Review.`;
     writePrdRunRecord(options.repoRoot, {
       prdRef,
@@ -9617,7 +9643,33 @@ async function runPrdRunFinalReviewCommand(options) {
     );
   } else {
     prdBranch = record.prdBranch ?? prdRef;
-    mergeBaseResult = computeFinalReviewMergeBase(options.repoRoot, prdRef);
+    const startBaseBranch = record.start?.startBaseBranch;
+    if (!startBaseBranch) {
+      const reason = `PRD Run ${prdRef} has a start receipt without startBaseBranch. This record predates target-owned PRD Run base branches and cannot proceed to Final Review.`;
+      writePrdRunRecord(options.repoRoot, {
+        ...record,
+        status: "blocked",
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        blockedGate: "final-review",
+        blockedReason: reason,
+        diagnostics: [reason],
+        targetName,
+        offendingPaths: []
+      });
+      return {
+        prdRef,
+        status: "blocked",
+        blockedGate: "final-review",
+        blockedReason: reason,
+        diagnostics: [reason],
+        offendingPaths: []
+      };
+    }
+    mergeBaseResult = computeFinalReviewMergeBase(
+      options.repoRoot,
+      prdRef,
+      startBaseBranch
+    );
   }
   if (!mergeBaseResult.ok) {
     writePrdRunRecord(options.repoRoot, {
@@ -9666,7 +9718,10 @@ async function runPrdRunFinalReviewCommand(options) {
       childIssueCount: relatedIssues.length
     },
     stage: "prdFinalReview",
-    stageReceipts: { mergeBase: mergeBaseResult.mergeBase }
+    stageReceipts: {
+      mergeBase: mergeBaseResult.mergeBase,
+      startBaseBranch: record.start?.startBaseBranch
+    }
   });
   const startReceipt = {
     status: "started",
@@ -10502,6 +10557,99 @@ async function runPrdRunFinalReviewCommand(options) {
     offendingPaths: []
   };
 }
+function computeFinalReviewMergeBase(repoRoot2, prdRef, baseBranch) {
+  const normalized = normalizePrdRunRef(prdRef);
+  const fetchResult = spawnSync3(
+    "git",
+    ["fetch", "origin", baseBranch, normalized],
+    {
+      cwd: repoRoot2,
+      encoding: "utf8"
+    }
+  );
+  const fetchDiagnostics = [];
+  if (fetchResult.status !== 0) {
+    const stderr = fetchResult.stderr?.toString?.() ?? "";
+    const stdout = fetchResult.stdout?.toString?.() ?? "";
+    if (stderr.trim()) fetchDiagnostics.push(stderr.trim());
+    if (stdout.trim()) fetchDiagnostics.push(stdout.trim());
+    return {
+      ok: false,
+      gate: "final-review",
+      reason: `Final Review failed to fetch origin/${baseBranch} and origin/${normalized}.`,
+      diagnostics: fetchDiagnostics.length > 0 ? fetchDiagnostics : ["git fetch failed"]
+    };
+  }
+  if (fetchResult.stderr?.toString?.()?.trim()) {
+    fetchDiagnostics.push(fetchResult.stderr.toString().trim());
+  }
+  const mergeBaseResult = spawnSync3(
+    "git",
+    ["merge-base", `origin/${baseBranch}`, `origin/${normalized}`],
+    {
+      cwd: repoRoot2,
+      encoding: "utf8"
+    }
+  );
+  const mergeBaseDiagnostics = [];
+  if (mergeBaseResult.status !== 0) {
+    if (mergeBaseResult.stderr?.toString?.()?.trim()) {
+      mergeBaseDiagnostics.push(mergeBaseResult.stderr.toString().trim());
+    }
+    if (mergeBaseResult.stdout?.toString?.()?.trim()) {
+      mergeBaseDiagnostics.push(mergeBaseResult.stdout.toString().trim());
+    }
+    return {
+      ok: false,
+      gate: "final-review",
+      reason: `Final Review merge-base computation failed for origin/${baseBranch} and origin/${normalized}.`,
+      diagnostics: mergeBaseDiagnostics.length > 0 ? mergeBaseDiagnostics : ["git merge-base returned non-zero exit status"]
+    };
+  }
+  const mergeBase = mergeBaseResult.stdout?.toString?.()?.trim();
+  if (!mergeBase) {
+    return {
+      ok: false,
+      gate: "final-review",
+      reason: `Final Review merge-base returned empty result for origin/${baseBranch} and origin/${normalized}.`,
+      diagnostics: [
+        `merge-base stdout was empty for origin/${baseBranch}..origin/${normalized}`
+      ]
+    };
+  }
+  return { ok: true, mergeBase, diagnostics: fetchDiagnostics };
+}
+function computeLocalFinalReviewMergeBase(repoRoot2, prdBranch) {
+  const mergeBaseResult = spawnSync3("git", ["merge-base", "dev", prdBranch], {
+    cwd: repoRoot2,
+    encoding: "utf8"
+  });
+  if (mergeBaseResult.status !== 0) {
+    const diagnostics = [];
+    if (mergeBaseResult.stderr?.toString?.()?.trim()) {
+      diagnostics.push(mergeBaseResult.stderr.toString().trim());
+    }
+    if (mergeBaseResult.stdout?.toString?.()?.trim()) {
+      diagnostics.push(mergeBaseResult.stdout.toString().trim());
+    }
+    return {
+      ok: false,
+      gate: "final-review",
+      reason: `Final Review merge-base computation failed for dev and ${prdBranch}.`,
+      diagnostics: diagnostics.length > 0 ? diagnostics : ["git merge-base returned non-zero exit status"]
+    };
+  }
+  const mergeBase = mergeBaseResult.stdout?.toString?.()?.trim();
+  if (!mergeBase) {
+    return {
+      ok: false,
+      gate: "final-review",
+      reason: `Final Review merge-base returned empty result for dev and ${prdBranch}.`,
+      diagnostics: [`merge-base stdout was empty for dev..${prdBranch}`]
+    };
+  }
+  return { ok: true, mergeBase, diagnostics: [] };
+}
 async function runPrdRunLaunchCommand(options) {
   const prdRef = normalizePrdRunRef(options.prdRef);
   const attempted = [];
@@ -10576,7 +10724,8 @@ async function runPrdRunLaunchCommand(options) {
       prProvider: options.prProvider,
       executionProvider: options.executionProvider,
       logger: options.logger,
-      adoptExistingBranch: options.adoptExistingBranch
+      adoptExistingBranch: options.adoptExistingBranch,
+      baseBranchOverride: options.baseBranchOverride
     });
     const skippedAfterStart = [
       "queue",
@@ -10738,7 +10887,7 @@ async function runPrdRunLaunchCommand(options) {
     skipped,
     resumed,
     diagnostics: [
-      "Integration Gate is not implemented. PRD Run is waiting for manual integration."
+      `Integration Gate is not implemented. PRD Run is waiting for manual integration back to ${currentRecord?.start?.startBaseBranch ?? "(missing startBaseBranch)"}.`
     ],
     start: startResult,
     finalReview: finalReviewResult
@@ -10777,8 +10926,52 @@ async function runPrdRunStartCommand(options) {
     });
     return buildBlockedStartResult(prdRef, failure);
   }
+  const resolvedTarget = options.config ? resolveTarget(options.config, targetName) : null;
+  const targetBaseBranch = resolvedTarget?.baseBranch ?? "main";
+  const baseResolution = resolvePrdRunBaseBranch({
+    targetBaseBranch,
+    baseBranchOverride: options.baseBranchOverride
+  });
+  if (!baseResolution.ok) {
+    persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, baseResolution, {
+      targetName
+    });
+    return buildBlockedStartResult(prdRef, baseResolution);
+  }
   if (existingRecord.record?.start) {
-    const fetchResult2 = fetchOriginDev(options.repoRoot);
+    const recordedBaseBranch = existingRecord.record.start.startBaseBranch;
+    if (!recordedBaseBranch) {
+      const failure = {
+        ok: false,
+        gate: "branch-state",
+        reason: `PRD Run ${prdRef} has a start receipt without startBaseBranch. Run prd-run start to create a fresh start receipt.`,
+        diagnostics: [
+          `Recorded start: ${JSON.stringify(existingRecord.record.start)}`
+        ],
+        offendingPaths: []
+      };
+      persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, failure, {
+        targetName
+      });
+      return buildBlockedStartResult(prdRef, failure);
+    }
+    if (recordedBaseBranch !== baseResolution.baseBranch) {
+      const failure = {
+        ok: false,
+        gate: "branch-state",
+        reason: `PRD Run ${prdRef} start receipt records startBaseBranch "${recordedBaseBranch}" but current base resolution resolves to "${baseResolution.baseBranch}". Use --base with the matching value or create a fresh start receipt.`,
+        diagnostics: [
+          `Recorded startBaseBranch: ${recordedBaseBranch}`,
+          `Current base resolution: ${baseResolution.baseBranch} (source: ${baseResolution.source})`
+        ],
+        offendingPaths: []
+      };
+      persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, failure, {
+        targetName
+      });
+      return buildBlockedStartResult(prdRef, failure);
+    }
+    const fetchResult2 = fetchOriginBranch(options.repoRoot, recordedBaseBranch);
     if (!fetchResult2.ok) {
       persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, fetchResult2, {
         targetName
@@ -10831,7 +11024,7 @@ async function runPrdRunStartCommand(options) {
             `Existing remote branch: ${prdRef}`,
             `Recorded start branch: ${existingRecord.record.start.prdBranch}`,
             `Recorded start base commit: ${existingRecord.record.start.startBaseCommit}`,
-            `Current origin/dev head: ${fetchResult2.startBaseCommit}`
+            `Current origin/${recordedBaseBranch} head: ${fetchResult2.startBaseCommit}`
           ],
           offendingPaths: []
         };
@@ -10852,15 +11045,41 @@ async function runPrdRunStartCommand(options) {
         );
         return buildBlockedStartResult(prdRef, fetchPrdResult);
       }
-      const adoptedStart = {
+      const ancestryResult = spawnSync3(
+        "git",
+        [
+          "merge-base",
+          "--is-ancestor",
+          `origin/${recordedBaseBranch}`,
+          `origin/${prdRef}`
+        ],
+        { cwd: options.repoRoot, encoding: "utf8" }
+      );
+      if (ancestryResult.status !== 0) {
+        const failure = {
+          ok: false,
+          gate: "branch-state",
+          reason: `PRD Branch ${prdRef} base ancestry check failed: origin/${recordedBaseBranch} is not an ancestor of origin/${prdRef}. Cannot adopt.`,
+          diagnostics: [
+            `Base branch: origin/${recordedBaseBranch}`,
+            `PRD branch: origin/${prdRef}`
+          ],
+          offendingPaths: []
+        };
+        persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, failure, {
+          targetName
+        });
+        return buildBlockedStartResult(prdRef, failure);
+      }
+      const adoptedStart = buildStartReceipt({
         status: "adopted",
         targetName,
         prdBranch: prdRef,
+        startBaseBranch: recordedBaseBranch,
         startBaseCommit: fetchResult2.startBaseCommit,
         branchAction: "adopted",
-        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        refreshReceipts: []
-      };
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
       persistStartingPrdRunRecord(
         options.repoRoot,
         prdRef,
@@ -10884,7 +11103,10 @@ async function runPrdRunStartCommand(options) {
       );
     }
   }
-  const fetchResult = fetchOriginDev(options.repoRoot);
+  const fetchResult = fetchOriginBranch(
+    options.repoRoot,
+    baseResolution.baseBranch
+  );
   if (!fetchResult.ok) {
     persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, fetchResult, {
       targetName
@@ -10928,6 +11150,7 @@ async function runPrdRunStartCommand(options) {
       status: "started",
       targetName,
       prdBranch: localBranchName,
+      startBaseBranch: baseResolution.baseBranch,
       startBaseCommit: fetchResult.startBaseCommit,
       branchAction: localBranchResult.created ? "created" : "reused",
       startedAt: updatedAt2
@@ -10969,7 +11192,7 @@ async function runPrdRunStartCommand(options) {
           `Existing remote branch: ${prdRef}`,
           `Recorded start branch: ${existingRecord.record?.start?.prdBranch ?? "(missing)"}`,
           `Recorded start base commit: ${existingRecord.record?.start?.startBaseCommit ?? "(missing)"}`,
-          `Current origin/dev head: ${fetchResult.startBaseCommit}`
+          `Current origin/${baseResolution.baseBranch} head: ${fetchResult.startBaseCommit}`
         ],
         offendingPaths: []
       };
@@ -10990,15 +11213,41 @@ async function runPrdRunStartCommand(options) {
       );
       return buildBlockedStartResult(prdRef, fetchPrdResult);
     }
-    const adoptedStart = {
+    const ancestryResult = spawnSync3(
+      "git",
+      [
+        "merge-base",
+        "--is-ancestor",
+        `origin/${baseResolution.baseBranch}`,
+        `origin/${prdRef}`
+      ],
+      { cwd: options.repoRoot, encoding: "utf8" }
+    );
+    if (ancestryResult.status !== 0) {
+      const failure = {
+        ok: false,
+        gate: "branch-state",
+        reason: `PRD Branch ${prdRef} base ancestry check failed: origin/${baseResolution.baseBranch} is not an ancestor of origin/${prdRef}. Cannot adopt.`,
+        diagnostics: [
+          `Base branch: origin/${baseResolution.baseBranch}`,
+          `PRD branch: origin/${prdRef}`
+        ],
+        offendingPaths: []
+      };
+      persistBlockedPrdRunStartRecord(options.repoRoot, prdRef, failure, {
+        targetName
+      });
+      return buildBlockedStartResult(prdRef, failure);
+    }
+    const adoptedStart = buildStartReceipt({
       status: "adopted",
       targetName,
       prdBranch: prdRef,
+      startBaseBranch: baseResolution.baseBranch,
       startBaseCommit: fetchResult.startBaseCommit,
       branchAction: "adopted",
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      refreshReceipts: []
-    };
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
     persistStartingPrdRunRecord(
       options.repoRoot,
       prdRef,
@@ -11047,6 +11296,7 @@ async function runPrdRunStartCommand(options) {
     status: "started",
     targetName,
     prdBranch: prdRef,
+    startBaseBranch: baseResolution.baseBranch,
     startBaseCommit: fetchResult.startBaseCommit,
     branchAction: "created",
     startedAt: updatedAt
@@ -11367,8 +11617,98 @@ function inspectRemotePrdBranch(repoRoot2, prdRef) {
   }
   return { ok: true, exists: true, headSha };
 }
-function fetchOriginDev(repoRoot2) {
-  const fetchResult = spawnSync3("git", ["fetch", "origin", "dev"], {
+function resolvePrdRunBaseBranch(options) {
+  const raw = options.baseBranchOverride ?? options.targetBaseBranch;
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: value is empty after trimming.`,
+      diagnostics: [`Provided branch value: "${raw}"`],
+      offendingPaths: []
+    };
+  }
+  if (trimmed.startsWith("origin/")) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: "${trimmed}" must not include "origin/" prefix. Use just the branch lane name (e.g. "dev" instead of "origin/dev").`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  if (/^(refs\/|heads\/|remotes\/|tags\/)/.test(trimmed)) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: "${trimmed}" must be a simple branch lane name, not a ref specification.`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  if (/^[0-9a-f]{7,40}$/i.test(trimmed)) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: value looks like a commit SHA rather than a branch lane name.`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  const segments = trimmed.split("/");
+  for (const segment of segments) {
+    if (segment === "." || segment === ".." || segment === "") {
+      return {
+        ok: false,
+        gate: "branch-state",
+        reason: `Invalid PRD Run base branch: "${trimmed}" must not contain ".", "..", or empty segments.`,
+        diagnostics: [`Provided branch value: "${trimmed}"`],
+        offendingPaths: []
+      };
+    }
+  }
+  if (/[~^:?*\[\\]/.test(trimmed)) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: "${trimmed}" contains invalid characters (~ ^ : ? * [ \\).`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  if (/[\x00-\x1f\x7f]/.test(trimmed)) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: value contains control characters.`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  if (trimmed.endsWith("/")) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: "${trimmed}" must not end with a trailing slash.`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  if (trimmed.endsWith(".lock")) {
+    return {
+      ok: false,
+      gate: "branch-state",
+      reason: `Invalid PRD Run base branch: "${trimmed}" must not end with ".lock" suffix.`,
+      diagnostics: [`Provided branch value: "${trimmed}"`],
+      offendingPaths: []
+    };
+  }
+  const source = options.baseBranchOverride !== void 0 ? "override" : "target";
+  return { ok: true, baseBranch: trimmed, source };
+}
+function fetchOriginBranch(repoRoot2, baseBranch) {
+  const fetchResult = spawnSync3("git", ["fetch", "origin", baseBranch], {
     cwd: repoRoot2,
     encoding: "utf8"
   });
@@ -11376,7 +11716,7 @@ function fetchOriginDev(repoRoot2) {
     return {
       ok: false,
       gate: "git",
-      reason: "PRD Run start failed while fetching origin/dev.",
+      reason: `PRD Run start failed while fetching origin/${baseBranch}.`,
       diagnostics: [
         fetchResult.error instanceof Error ? fetchResult.error.message : void 0,
         fetchResult.stderr?.toString?.() ?? String(fetchResult.stderr ?? ""),
@@ -11385,15 +11725,19 @@ function fetchOriginDev(repoRoot2) {
       offendingPaths: []
     };
   }
-  const revParseResult = spawnSync3("git", ["rev-parse", "origin/dev"], {
-    cwd: repoRoot2,
-    encoding: "utf8"
-  });
+  const revParseResult = spawnSync3(
+    "git",
+    ["rev-parse", `origin/${baseBranch}`],
+    {
+      cwd: repoRoot2,
+      encoding: "utf8"
+    }
+  );
   if (revParseResult.status !== 0) {
     return {
       ok: false,
       gate: "git",
-      reason: "PRD Run start failed while resolving origin/dev.",
+      reason: `PRD Run start failed while resolving origin/${baseBranch}.`,
       diagnostics: [
         revParseResult.error instanceof Error ? revParseResult.error.message : void 0,
         revParseResult.stderr?.toString?.() ?? String(revParseResult.stderr ?? ""),
@@ -14979,7 +15323,7 @@ function createCliProgram(version) {
   });
   program.command("validate-artifact").description("Validate an agent handoff artifact").argument(
     "<kind>",
-    "artifact kind: reviewer, refactor, finalizer, conflict-resolution, failure-resolution, local-prd, local-issue, or local-triage"
+    "artifact kind: reviewer, refactor, finalizer, conflict-resolution, final-review, failure-resolution, local-prd, local-issue, or local-triage"
   ).argument("<artifactPath>", "artifact path to validate").argument("[extraPaths...]", "additional artifact paths (for local-triage)").option("--iteration <number>", "review/refactor iteration", (value) => {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) || parsed < 1) {
@@ -15012,6 +15356,12 @@ function createCliProgram(version) {
       return previous;
     },
     []
+  ).option("--prd-ref <ref>", "PRD ref for final-review artifacts").option(
+    "--checkout-base <ref>",
+    "checkout base / PRD branch for final-review artifacts"
+  ).option(
+    "--review-base <ref>",
+    "review merge base for final-review artifacts"
   ).option("--no-check-conflict-markers", "skip conflict marker scan").option("--cwd <path>", "target repository directory").action(
     (kind, artifactPath, extraPaths, options) => {
       const allowedKinds = /* @__PURE__ */ new Set([
@@ -15019,6 +15369,7 @@ function createCliProgram(version) {
         "refactor",
         "finalizer",
         "conflict-resolution",
+        "final-review",
         "failure-resolution",
         "local-prd",
         "local-issue",
@@ -15051,6 +15402,9 @@ function createCliProgram(version) {
         findingIds: options.findingId,
         latestReviewArtifactPath: options.latestReviewArtifact,
         allowedDecisions: options.allowedDecision,
+        prdRef: options.prdRef,
+        checkoutBase: options.checkoutBase,
+        reviewBase: options.reviewBase,
         checkConflictMarkers: options.checkConflictMarkers
       });
       console.log(JSON.stringify(result, null, 2));
@@ -15263,7 +15617,7 @@ function createCliProgram(version) {
     }
   );
   const prdRun = program.command("prd-run").description("PRD Run commands");
-  prdRun.command("start").argument("<prdRef>", "PRD ref").requiredOption("--target <name>", "target name").option("--adopt-existing-branch", "adopt an existing PRD branch").option("--cwd <path>", "target repository directory").action(
+  prdRun.command("start").argument("<prdRef>", "PRD ref").requiredOption("--target <name>", "target name").option("--base <branch>", "override target baseBranch for this PRD Run").option("--adopt-existing-branch", "adopt an existing PRD branch").option("--cwd <path>", "target repository directory").action(
     async (prdRef, options) => {
       const targetRepoRoot = options.cwd ? repoRoot(options.cwd) : repoRoot();
       const normalizedPrdRef = normalizePrdRef(prdRef);
@@ -15288,6 +15642,7 @@ function createCliProgram(version) {
           repoRoot: targetRepoRoot,
           prdRef: normalizedPrdRef,
           targetName: options.target,
+          baseBranchOverride: options.base,
           adoptExistingBranch: options.adoptExistingBranch ?? false,
           config,
           issueProvider,
@@ -15308,7 +15663,7 @@ function createCliProgram(version) {
       }
     }
   );
-  prdRun.command("launch").argument("<prdRef>", "PRD ref").requiredOption("--target <name>", "target name").option("--cwd <path>", "target repository directory").option("--no-auto-merge", "skip auto-merge for manual review").option("--adopt-existing-branch", "adopt an existing PRD branch").action(
+  prdRun.command("launch").argument("<prdRef>", "PRD ref").requiredOption("--target <name>", "target name").option("--base <branch>", "override target baseBranch for this PRD Run").option("--cwd <path>", "target repository directory").option("--no-auto-merge", "skip auto-merge for manual review").option("--adopt-existing-branch", "adopt an existing PRD branch").action(
     async (prdRef, options) => {
       const targetRepoRoot = options.cwd ? repoRoot(options.cwd) : repoRoot();
       const normalizedPrdRef = normalizePrdRef(prdRef);
@@ -15335,6 +15690,7 @@ function createCliProgram(version) {
           repoRoot: targetRepoRoot,
           prdRef: normalizedPrdRef,
           targetName: options.target,
+          baseBranchOverride: options.base,
           autoMerge: options.autoMerge ?? true,
           adoptExistingBranch: options.adoptExistingBranch ?? false,
           config,
@@ -15530,11 +15886,11 @@ function createCliProgram(version) {
   return program;
 }
 async function resolveCliVersion() {
-  if (isPackageVersion("0.0.0-next-20260611235559")) {
-    return "0.0.0-next-20260611235559";
+  if (isPackageVersion("0.0.0-next-20260613012953")) {
+    return "0.0.0-next-20260613012953";
   }
-  if (isReleaseVersion("0.0.0-next-20260611235559")) {
-    return "0.0.0-next-20260611235559";
+  if (isReleaseVersion("0.0.0-next-20260613012953")) {
+    return "0.0.0-next-20260613012953";
   }
   try {
     const root = repoRoot();