@nextcommerce/campaigns-os 1.61.0 → 1.63.0

package/src/doctor/ci.mjs

@@ -1,16 +1,47 @@
+import { worseChangeKind } from "../change-scope.mjs";
 import { assessEvidenceDebt } from "../evidence-debt.mjs";
+import { REFUSED_INVOCATION } from "../lifecycle.mjs";
 
 export const DOCTOR_CI_EXIT_CODES = Object.freeze({ current: 0, owed: 3, unknown: 4, usage: 2 });
 
 export function assessDoctorCi(inputs) {
   const debt = assessEvidenceDebt(inputs);
-  const stages = [debt.polish, debt.qa];
+  // Advisory Polish (a page-only change) is reported, never required.
+  const stages = [debt.polish, debt.qa].filter((stage) => !stage.advisory);
   // Any known debt is owed; otherwise incomplete evidence remains unknown.
   const status = stages.some((stage) => stage.status === "owed") ? "owed"
     : stages.some((stage) => stage.status === "unknown") ? "unknown" : "current";
   return { status, exit_code: DOCTOR_CI_EXIT_CODES[status], ...debt };
 }
 
+// What the change owes, from the stages it left owed: "pages" when the only
+// required stage is QA on the changed pages (Polish advisory or current),
+// "full" when a full stage is owed, null when nothing is owed. `kind` is the
+// worst change kind among the owed stages.
+export function ciChangeScope(ci) {
+  const owed = ["polish", "qa"].filter((stage) => ci[stage]?.status === "owed");
+  if (!owed.length) return { scope: null, kind: null };
+  const kind = owed.map((stage) => ci[stage].change?.kind || "unknown").reduce(worseChangeKind, "none");
+  const required = owed.filter((stage) => !ci[stage].advisory);
+  const scope = required.every((stage) => stage === "qa" && ci.qa.scope === "pages") ? "pages" : "full";
+  return { scope, kind };
+}
+
+// Page ids come from built routes ([A-Za-z0-9_-]); anything else is encoded.
+const pageArg = (id) => (/^[A-Za-z0-9_-]+$/.test(String(id)) ? String(id) : text(id));
+
+const commerceReasonText = new Map([
+  ["unmapped_file", "a file outside any page changed"],
+  ["page_added", "a page was added"],
+  ["page_removed", "a page was removed"],
+  ["checkout_page", "a checkout page changed"],
+  ["commerce_markup_changed", "package, offer, shipping, upsell, route or script markup changed"],
+  ["commerce_signature_unavailable", "the recorded build has no commerce signature to compare against"],
+  ["campaign_config_changed", "the campaign's Page Kit config (SDK pin, analytics ids, store fields) changed"],
+  ["campaign_config_unavailable", "the campaign's Page Kit config entry could not be read"],
+  ["change_history_unavailable", "the rebuilds since the reviewed build were not kept"],
+]);
+
 // Values can come from campaign files and will be rendered in a PR comment.
 // Encode punctuation as well as HTML: diagnostics are plain text, and may
 // contain Markdown, autolinks, code fences or line breaks from campaign files.
@@ -38,10 +69,10 @@ const requiredStageReasons = new Map([
   ["stage_required", "the lifecycle requires this stage again"],
 ]);
 
-export function doctorCiFailure(error, { usage = false } = {}) {
+export function doctorCiFailure(error, { usage = false, code = usage ? "doctor.ci.packet" : "doctor.ci.failed" } = {}) {
   return {
     ok: false, status: "blocked",
-    errors: [{ code: usage ? "doctor.ci.packet" : "doctor.ci.failed", message: String(error?.message ?? error) }],
+    errors: [{ code, message: String(error?.message ?? error) }],
     warnings: [], exit_code: usage ? DOCTOR_CI_EXIT_CODES.usage : DOCTOR_CI_EXIT_CODES.unknown,
   };
 }
@@ -54,7 +85,8 @@ export async function withDoctorCiReport(args, invoke) {
     return await invoke(args);
   } catch (error) {
     if (command !== "doctor" || args.ci !== true) throw error;
-    const result = doctorCiFailure(error);
+    // A flag refused up front (such as --packet=<path>) is a usage error.
+    const result = error?.code === REFUSED_INVOCATION ? doctorCiFailure(error, { usage: true, code: "doctor.ci.usage" }) : doctorCiFailure(error);
     console.log(args.json ? JSON.stringify(result, null, 2) : formatDoctorCi(result));
     process.exitCode = result.exit_code;
   }
@@ -66,22 +98,51 @@ export function formatDoctorCi(result) {
     return [
       `## Campaign evidence: could not evaluate (exit ${result.exit_code ?? DOCTOR_CI_EXIT_CODES.usage})`, "",
       ...(result.errors || []).map((issue) => `- ${code(issue.code)}: ${text(issue.message)}`), "",
-      "Remedy: correct the packet or inspection failure and re-run `campaigns-os doctor --packet <packet> --ci --no-live-refs`.",
+      result.errors?.[0]?.code === "doctor.ci.usage"
+        ? "Remedy: correct the command's flags (each value as the next argument, `--flag value`) and re-run `campaigns-os doctor --packet <packet> --ci --no-live-refs`."
+        : "Remedy: correct the packet or inspection failure and re-run `campaigns-os doctor --packet <packet> --ci --no-live-refs`.",
     ].join("\n");
   }
   const lines = [`## Campaign evidence: ${text(ci.status)} (exit ${ci.exit_code})`, ""];
-  const owed = ["polish", "qa"].filter((stage) => ci[stage].status === "owed");
-  lines.push(`Owed stages: ${owed.length ? owed.join(", ") : "none"}.`);
+  const advisory = ["polish", "qa"].filter((stage) => ci[stage].status === "owed" && ci[stage].advisory);
+  const owed = ["polish", "qa"].filter((stage) => ci[stage].status === "owed" && !ci[stage].advisory);
+  const change = ciChangeScope(ci);
+  const pageScoped = change.scope === "pages";
+  if (pageScoped) {
+    lines.push(`Change found: page-only. ${owed.length ? `It owes QA on ${ci.qa.owed_pages.map((page) => code(page.page_id)).join(", ")}` : "QA is current"}; Polish is advisory.`);
+  } else if (change.scope === "full") {
+    const reasons = [...new Set((ci.polish.change?.reasons || []).concat(ci.qa.change?.reasons || [])
+      .map((reason) => commerceReasonText.get(reason.code)).filter(Boolean))];
+    const found = change.kind === "commerce_affecting" ? "commerce-affecting"
+      : change.kind === "page_only" ? "page-only, but an input change or a Polish or QA that did not complete requires the full stages" : "not classified";
+    // Name only the stages that count, each at the scope it is owed: an
+    // advisory Polish is not owed, and QA can still be owed on pages only.
+    const qaPages = ci.qa.scope === "pages" ? `QA on ${ci.qa.owed_pages.map((page) => code(page.page_id)).join(", ")}` : null;
+    const owes = owed.length === 2 ? (qaPages ? `the full Polish, and ${qaPages}` : "the full Polish and QA")
+      : owed[0] === "polish" ? "the full Polish" : qaPages || "a full QA run";
+    lines.push(`Change found: ${found}${reasons.length ? ` (${reasons.join("; ")})` : ""}. It owes ${owes}${advisory.includes("polish") ? "; Polish is advisory" : ""}.`);
+  }
+  lines.push(`Owed stages: ${owed.length ? owed.map((stage) => stage === "qa" && ci.qa.scope === "pages" ? "qa (changed pages only)" : stage).join(", ") : "none"}.`);
   for (const stage of owed) {
     const reason = ci[stage].reason === "build_fingerprint_changed"
       ? "the recorded build fingerprint differs from the current build"
       : requiredStageReasons.get(ci[stage].reason) ?? "the recorded stage evidence is owed";
     lines.push(`- Owed ${stage}: ${reason}.`);
   }
-  for (const page of ci.changes.changed_pages) {
+  for (const stage of advisory) {
+    lines.push(`- Advisory ${stage}: the change since its last review is page-only, so it is reported and not required.`);
+  }
+  // The pages changed since the builds the owed stages reviewed, which
+  // record build keeps; without them, the drift from the assembly manifest.
+  const sincePages = new Map();
+  for (const stage of [...owed, ...advisory]) {
+    for (const page of ci[stage].change?.changed_pages || []) sincePages.set(page.built_path, page);
+  }
+  const changedPages = sincePages.size ? [...sincePages.values()] : ci.changes.changed_pages;
+  for (const page of changedPages) {
     lines.push(`- Changed page: ${code(page.page_id)} (${code(page.built_path)})`);
   }
-  if (!ci.changes.changed_pages.length && (owed.length || ci.changes.status === "unknown")) {
+  if (!changedPages.length && (owed.length || ci.changes.status === "unknown")) {
     lines.push(ci.changes.status === "unknown"
       ? `Changed pages unavailable: ${unavailablePageChanges.get(ci.changes.reason) ?? "the page-change reason is unrecognized."}`
       : "Changed page ids unavailable: the retained assembly manifest may already describe the rebuilt output.");
@@ -90,7 +151,11 @@ export function formatDoctorCi(result) {
     if (ci[stage].status === "unknown") lines.push(`- Unknown ${stage}: ${code(ci[stage].reason)}`);
   }
   if (ci.changes.status === "unknown") lines.push(`- Unknown page changes: ${code(ci.changes.reason)}`);
-  if (ci.status === "owed" || ci.status === "unknown") {
+  if (ci.status === "owed" && pageScoped && owed.length) {
+    const pages = ci.qa.owed_pages.map((page) => ` --page ${pageArg(page.page_id)}`).join("");
+    const recorded = ci.changes.recorded_build_fingerprint && ci.changes.recorded_build_fingerprint === ci.changes.current_build_fingerprint;
+    lines.push("", `Remedy: ${recorded ? "" : "run `campaigns-os record build --packet <packet>` for the rebuilt output, then "}run \`campaigns-os qa run --packet <packet>${pages}\` against that build. Polish capture is optional for a page-only change.`);
+  } else if (ci.status === "owed" || ci.status === "unknown") {
     const matchingRequired = owed.length > 0
       && owed.every((stage) => requiredStageReasons.has(ci[stage].reason) && ci[stage].matches_current_build === true)
       && ["polish", "qa"].every((stage) => ci[stage].status !== "unknown");

package/src/doctor/inspect.mjs

@@ -1,7 +1,8 @@
 // Doctor entry points: the doctor command, packet inspection and built-output inspection.
 import { resolveCampaignIdentity } from "../spec-source-identity.mjs";
 import { assessDoctorCi, doctorCiFailure } from "./ci.mjs";
-import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
+import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, applyPageOnlyChangeToCheckpoint, applyPageOnlyChangeToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
+import { assessEvidenceDebt } from "../evidence-debt.mjs";
 import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -11,7 +12,7 @@ import { commitAssemblyReport, recordProducerStageOutcome } from "../stage-ledge
 import { annotateDoctorIssueCauses } from "../finding-cause.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "../doctor-sidecar.mjs";
 import { recordQcResults } from "../qc-results.mjs";
-import { resolveCampaignWorkspace } from "../campaign-workspace.mjs";
+import { packetRuntimeRelPath, resolveCampaignWorkspace } from "../campaign-workspace.mjs";
 import { normalizePublicRouteSlug } from "../route-identity.mjs";
 import { DEFAULT_PROXY_BASE } from "../spec-fetch.mjs";
 import { disabledLiveRead, liveRefsDisabled, readLiveCampaignForPacket } from "../live-campaign-refs.mjs";
@@ -458,6 +459,16 @@ export function doctorBuiltOutput(args) {
   };
 }
 
+// Inspection already refused a packet whose runtime directory is unreadable;
+// the history lookup then falls back to the project-level directory.
+function packetRuntimeRelPathOrDefault(packetPath) {
+  try {
+    return packetRuntimeRelPath(JSON.parse(readFileSync(resolve(packetPath), "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
 export function doctorPacket(packetPath, options = {}) {
   const result = withHtmlScanSnapshot(() => inspectDoctorPacket(packetPath, options));
   // Per-finding cause classification lives HERE, at the single production
@@ -487,6 +498,7 @@ export function doctorPacket(packetPath, options = {}) {
     errors: result.errors,
     warnings: result.warnings,
     baseDir: comparableIdentity ? dirname(resolve(packetPath)) : null,
+    runtimeRelPath: comparableIdentity ? packetRuntimeRelPathOrDefault(packetPath) : undefined,
     mapId: result.derived?.map_id || null,
     localSpecId: result.derived?.local_spec_id || null,
   });
@@ -587,16 +599,21 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
 
   // The local preview policy (local-preview-policy.mjs) carries missing
   // polish and page-load evidence forward as warnings on a local-serve packet.
-  const polishCheckpointGate = applyLocalPreviewToCheckpoint(
+  // A page-only change since Polish last reviewed the campaign carries its
+  // stale evidence on any target: Polish is advisory for it (#720). The
+  // evidence debt is the one readback and doctor --ci assess.
+  const evidenceDebt = assessEvidenceDebt({ packet, packetPath, report });
+  derived.evidence_debt = evidenceDebt;
+  const polishCheckpointGate = applyPageOnlyChangeToCheckpoint(applyLocalPreviewToCheckpoint(
     evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report }),
     { packet, report },
-  );
+  ), evidenceDebt);
   derived.polish_checkpoint_gate = polishCheckpointGate;
-  const polishGate = applyLocalPreviewToPolishGate(evaluatePolishGate({
+  const polishGate = applyPageOnlyChangeToPolishGate(applyLocalPreviewToPolishGate(evaluatePolishGate({
     report,
     hiddenEagerMediaGate: polishCheckpointGate,
     currentOutputFingerprint: derived.build_output_fingerprint?.value || null,
-  }), { packet, checkpointGate: polishCheckpointGate });
+  }), { packet, checkpointGate: polishCheckpointGate }), { debt: evidenceDebt, checkpointGate: polishCheckpointGate });
   derived.polish_gate = polishGate;
   if (polishGate.status === "blocked" && !polishGate.owned_checkpoint_only) {
     pushGateIssue({ errors, warnings }, gateIssue("polish_gate", polishGate));

package/src/doctor/next-step.mjs

@@ -503,6 +503,13 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     }
     if (cliStage === "qa" && qaRecordedBuildFingerprint(report) && currentBuildFingerprint(report)
       && !qaRecordedForCurrentBuild(report, currentBuildFingerprint(report))) {
+      // A page-only change since the build QA reviewed owes QA on the
+      // changed pages only (#720); qa run --page pays it.
+      const qaDebt = derived?.evidence_debt?.qa;
+      if (qaDebt?.scope === "pages" && qaDebt.owed_pages?.length) {
+        const pages = qaDebt.owed_pages.map((page) => `--page ${page.page_id}`).join(" ");
+        return { stage: "qa", reason: `QA was recorded for a different build, and the change since then is page-only: run QA on the changed pages with ${cmd("qa")} run --packet <packet> ${pages}.` };
+      }
       return { stage: "qa", reason: "QA was recorded for a different build; run QA against the current build." };
     }
     // A terminal QA status is not the same claim as purchase proof. QA finalizes

package/src/doctor-sidecar.mjs

@@ -73,8 +73,9 @@ export function writeDoctorSidecar(path, doctor, { command, targetRepo = null }
 // qa policy set) stamp the retained snapshot stale instead of leaving a green
 // lie on disk, while commands that DO recompute (doctor, prepare-build/start,
 // next) rewrite the sidecar wholesale — which clears any stale stamp.
-export function markDoctorSidecarStale(targetBaseDir, { command = null, reason = null } = {}) {
-  const path = doctorSidecarPath(targetBaseDir);
+// `path` is the funnel's own sidecar (campaign-workspace.mjs doctorOutPath);
+// without it, the project-level one under `targetBaseDir`.
+export function markDoctorSidecarStale(targetBaseDir, { command = null, reason = null, path = doctorSidecarPath(targetBaseDir) } = {}) {
   if (!existsSync(path)) return null;
   let sidecar;
   try {

package/src/evidence-debt.mjs

@@ -9,9 +9,10 @@ import {
   resolveBuiltSiteScope,
   routeForFile,
 } from "./built-site-scope.mjs";
+import { changeSince, classifyDrift } from "./change-scope.mjs";
 import { normalizePublicRouteSlug } from "./route-identity.mjs";
 import { isFileReadFailure } from "./cart-placeholders.mjs";
-import { qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
+import { polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
 
 export const EVIDENCE_DEBT_STATUSES = Object.freeze(["current", "owed", "unknown"]);
 
@@ -24,6 +25,12 @@ const portable = (value) => value.split(sep).join("/");
  * the build an older stage reviewed. We cannot reconstruct an older manifest.
  * Missing build inputs remain unknown; lifecycle-required stages are owed
  * even without a stage binding. A matching binding alone is not a verdict.
+ *
+ * Each owed stage also carries `change`: what changed since the build that
+ * stage reviewed (change-scope.mjs), read from the rebuilds `record build`
+ * kept plus the drift on disk. A page-only change makes owed Polish
+ * `advisory` and owed QA `scope: "pages"` on `owed_pages`; anything else
+ * owes the full stage.
  */
 export function assessEvidenceDebt({ packet = null, packetPath = null, report = null } = {}) {
   const assembly = report?.stages?.assembly;
@@ -38,12 +45,13 @@ export function assessEvidenceDebt({ packet = null, packetPath = null, report =
   let outputRoot = null;
   let reason = null;
   let scopeReason = null;
+  let targetRepo = null;
   const target = fingerprint(packet?.assembly?.target_repo);
   const slug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   if (!packet || !packetPath) reason = "packet_unavailable";
   else if (!target || !slug) reason = "build_output_location_unknown";
   else {
-    const targetRepo = resolve(dirname(resolve(packetPath)), target);
+    targetRepo = resolve(dirname(resolve(packetPath)), target);
     outputRoot = join(targetRepo, "_site", slug);
     try {
       current = computeBuildFingerprint(outputRoot);
@@ -111,9 +119,41 @@ export function assessEvidenceDebt({ packet = null, packetPath = null, report =
       else changes.unmapped_files.push(path);
     }
   }
-  return {
-    polish: stage(report?.stages?.polish, polishBuild, Boolean(polishBuild && currentBuild && polishBuild === currentBuild)),
-    qa: stage(report?.stages?.qa, qaBuild, qaRecordedForCurrentBuild(report, currentBuild)),
-    changes,
-  };
+  const driftClassification = classifyDrift({ changes, baseline: assembly, outputRoot, targetRepo, publicRouteSlug: slug });
+  changes.kind = driftClassification.kind;
+  changes.reasons = driftClassification.reasons;
+  const changeFor = (anchor) => changeSince(anchor, { assembly, drift: changes, driftClassification });
+
+  // Polish reviewed the build a terminal record is bound to; once `record
+  // build` has made it required, the build it reviewed is kept as
+  // owed_since_build_fingerprint (polishReviewedBuild). Only a Polish that
+  // reviewed a build can be advisory: a blocked or pending one, or one a
+  // brief or spec change made required, owes the full stage, before and
+  // after record build alike.
+  const polishRecord = report?.stages?.polish;
+  const polish = stage(polishRecord, polishBuild, Boolean(polishBuild && currentBuild && polishBuild === currentBuild));
+  if (polish.status === "owed") {
+    const reviewed = polishReviewedBuild(polishRecord);
+    polish.change = changeFor(reviewed || polishBuild || fingerprint(polishRecord?.owed_since_build_fingerprint));
+    polish.advisory = Boolean(reviewed) && polish.change.kind === "page_only";
+  } else {
+    polish.change = null;
+    polish.advisory = false;
+  }
+  // QA on the changed pages only extends a completed QA: the change is read
+  // from the build that QA checked (qaExtendedBuildFingerprint). A blocked,
+  // pending or skipped full run extends nothing and owes the full stage.
+  const qaRecord = report?.stages?.qa;
+  const qa = stage(qaRecord, qaBuild, qaRecordedForCurrentBuild(report, currentBuild));
+  if (qa.status === "owed") {
+    const extended = qaExtendedBuildFingerprint(report);
+    qa.change = changeFor(extended || qaBuild);
+    qa.scope = extended && qaRecord?.status !== "required" && qa.change.kind === "page_only" ? "pages" : "full";
+    qa.owed_pages = qa.scope === "pages" ? qa.change.changed_pages : [];
+  } else {
+    qa.change = null;
+    qa.scope = null;
+    qa.owed_pages = [];
+  }
+  return { polish, qa, changes };
 }

package/src/finding-cause.mjs

@@ -330,7 +330,8 @@ import { iterateQaVerdicts } from "./qa-verdict-discovery.mjs";
 import { readRunRecordsForTarget } from "./run-record.mjs";
 
 /**
- * The most recent Run Record for the same campaign identity under `baseDir`,
+ * The most recent Run Record for the same campaign identity under `baseDir`
+ * (in the packet's runtime directory, `runtimeRelPath`, when one is given),
  * or null. Records are discovered newest-first, and the current run's record
  * does not exist yet at classification time (both `qa run` and `doctor`
  * complete before `run-record` assembles anything), so the first identity
@@ -341,9 +342,9 @@ import { readRunRecordsForTarget } from "./run-record.mjs";
  * against a non-adjacent one and report findings introduced in between as
  * pre-existing.
  */
-export function findPriorRunRecord({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+export function findPriorRunRecord({ baseDir, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   if (!text(baseDir)) return null;
-  for (const entry of readRunRecordsForTarget(baseDir)) {
+  for (const entry of readRunRecordsForTarget(baseDir, runtimeRelPath)) {
     const record = entry?.record;
     if (!record || typeof record !== "object" || Array.isArray(record)) continue;
     if (currentRunId && record.run_id === currentRunId) continue;
@@ -448,8 +449,8 @@ function locateExternalPriorVerdict({ targetRepo, record, ref }) {
  * The single-record boundary is unchanged: this still reads the final attempt
  * of exactly one earlier run, never a merged view across runs.
  */
-export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
+export function loadPriorQaVerdict({ baseDir, runtimeRelPath = undefined, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId });
   if (!record) return { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const ref = (Array.isArray(record.artifacts) ? record.artifacts : []).findLast((artifact) => artifact?.kind === "qa_verdict");
   const refPath = text(ref?.path);
@@ -472,8 +473,8 @@ export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, l
  * carries these, so doctor cause labels work against existing history with no
  * upgrade window. Returns `{ prior, record, reason }`.
  */
-function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
+function loadPriorDoctorFindings({ baseDir, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId });
   if (!record) return { prior: null, record: null, reason: "no_prior_run" };
   const prior = priorSetFromRunRecordDoctor(record);
   if (!prior) return { prior: null, record, reason: "prior_run_without_doctor_observations" };
@@ -496,9 +497,9 @@ function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, cu
  * raw map id) have no Run Record home, so they get `unknown` / `no_prior_run`
  * throughout — which is the truth, not a silence.
  */
-export function annotateQaAssertionCauses(assertions, { baseDir = null, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
+export function annotateQaAssertionCauses(assertions, { baseDir = null, runtimeRelPath = undefined, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
   const lookup = baseDir
-    ? loadPriorQaVerdict({ baseDir, targetRepo, mapId, localSpecId, currentRunId })
+    ? loadPriorQaVerdict({ baseDir, runtimeRelPath, targetRepo, mapId, localSpecId, currentRunId })
     : { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const prior = lookup.verdict ? priorSetFromVerdict(lookup.verdict, { isFinding }) : null;
   const noPriorReason = lookup.reason || "no_prior_run";
@@ -532,9 +533,9 @@ const CAUSE_SUMMARY_SCHEMA = "campaigns-os-finding-cause/v0";
  * The doctor twin. `errors` and `warnings` are the doctor output's own arrays;
  * both are stamped in place. Returns the same summary shape.
  */
-export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   const lookup = baseDir
-    ? loadPriorDoctorFindings({ baseDir, mapId, localSpecId, currentRunId })
+    ? loadPriorDoctorFindings({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId })
     : { prior: null, record: null, reason: "no_prior_run" };
   const noPriorReason = lookup.reason || "no_prior_run";
   const findings = [];