@nextcommerce/campaigns-os 1.41.2 → 1.43.1

package/src/cli.mjs

@@ -1,3 +1,4 @@
+import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { withHtmlScanSnapshot, readHtmlScanText, htmlScanDigest } from "./html-scan.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { createDemo, demoArguments } from "./demo.mjs";
@@ -28,7 +29,7 @@ import { observeProgress, PROGRESS_OBSERVATION } from "./progress-node.mjs";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { HIDDEN_EAGER_MEDIA_ACTIONS, requiredActionText, substitutePacket } from "./gate-actions.mjs";
 import { ORDER_PATH_DEPTH_DRIFT_CODE, orderPathDepthDriftText, orderPathDepthReconcileAction, orderPathDepthsDisagree, parseOrderPathDepthFlag } from "./proof-policy.mjs";
-import { specMaterialHash } from "./spec-identity.mjs";
+import { specMaterialHash, specHashesMatch } from "./spec-identity.mjs";
 // The same predicate stage-ledger.mjs judges a mutator's result with, imported
 // rather than re-stated so the waive preview and the commit agree by identity.
 import { isPlainObject } from "./repo-scan.mjs";
@@ -98,7 +99,7 @@ import { campaignSidecarPaths, resolveCampaignWorkspace, targetRepoFor } from ".
 import { canonicalPath, sameFile } from "./fs-identity.mjs";
 import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
 import { writeMapSdkPin } from "./map-pin-writeback.mjs";
-import { discoverQaVerdicts, iterateQaVerdicts, qaVerdictCandidateScore, qaVerdictCandidateTime, qaVerdictPathHints } from "./qa-verdict-discovery.mjs";
+import { qaVerdictIdentityMatch, discoverQaVerdicts, iterateQaVerdicts, qaVerdictCandidateScore, qaVerdictCandidateTime, qaVerdictPathHints } from "./qa-verdict-discovery.mjs";
 import { assertFetchAvailable, assertSecureProxyBase, boundedResponseText, DEFAULT_RUNS_ENDPOINT, describeRemitBaseKind, isLoopbackHostname, REMIT_RESULTS, remitRunRecord } from "./remit.mjs";
 import {
   aggregateLifecycleForRun,
@@ -485,12 +486,13 @@ Usage:
   campaigns-os readback --example [--json]                                # project the bundled synthetic sample; freshness is not computable for it by design
   campaigns-os validate-assembly-report --report <json> [--json]
   campaigns-os install-skills [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--dry-run] [--json]
+  campaigns-os tooling setup --target <campaign-directory> [--platform claude] [--dry-run] [--json]   # after installing the pinned project dependencies, install skills, connect Claude's context and install the QA browser; preserve existing pages and instructions, then restart the agent
   campaigns-os login [--store <subdomain>]
   campaigns-os logout [--store <subdomain>]
   campaigns-os tooling status [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--skills-revision <bundle-revision|skill-id@version>] [--packet <campaign-runtime.build.json>] [--force] [--json]   # install-mode, git, skill freshness, and local gateway login/store/expiry/reported version. --skills-revision checks the bundle revision the skill you loaded states on its first body line (or that one skill's <skill-id>@<version>) against the bundle THIS CLI ships: revision_check is match, mismatch or unchecked, and a mismatch prints the full status and exits 2 because skill text already in context cannot be refreshed by re-running — start a fresh session. The pin check reports one executable per project: the project pin first — the first exact spec for this package (x.y.z, =x.y.z or vx.y.z) on the walk up from the nearest package.json, devDependencies then dependencies in each, entering a workspace root and stopping there, never peerDependencies or optionalDependencies — then the Build Packet's campaigns_os_version (the project's campaign-runtime.build.json, or --packet <path>); the Pin: line names the key and manifest (or packet) each version came from; pin.status is match, stale_pin (the pin is not the running version), conflicting_pin (the two sources disagree) or unpinned (neither, or only a range; exit 0). stale_pin and conflicting_pin exit 2 with the file to change; --force (bare) overrides them, is reported as pin.forced and lands on the lifecycle journal entry. See docs/skills-revision.md
   campaigns-os tooling diagnose [--packet <packet>] [--platform <claude|codex|agents|all>] [--json]   # read-only redacted support summary
   campaigns-os install-agent-context --target <page-kit-dir> [--dry-run]
-  campaigns-os next --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
+  campaigns-os next [${NEXT_STAGE_ORDER.join("|")}] --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]   # no stage self-decides; returns gates[] + next_actions[] alongside the prompt
   campaigns-os next setup --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next build --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next polish --packet <json> --report <json> [--json]
@@ -654,6 +656,18 @@ export async function main(argv, { authentication } = {}) {
       return;
     }
 
+    // Project setup must not recover campaign sessions, read gateway bindings,
+    // or emit lifecycle/telemetry evidence before a campaign is selected.
+    if (command === "tooling" && args._[1] === "setup") {
+      const { setupArguments, setupTooling, setupTextLines } = await import("./tooling-setup.mjs");
+      setupArguments(args, argv);
+      const { installQaBrowser } = await import("./qa-node.mjs");
+      const result = setupTooling(args, { packageRoot: ROOT, installSkills, installAgentContext, installBrowser: installQaBrowser });
+      console.log(args.json ? JSON.stringify(result, null, 2) : setupTextLines(result).join("\n"));
+      if (!result.ok) process.exitCode = 2;
+      return;
+    }
+
     // Ambient run session (Tier 3): when `run start` is active, every command
     // shares its run_id WITHOUT --run-id. Explicit --run-id still wins. Resolved
     // ONCE here and threaded through dispatch + persistence so the run_id a
@@ -959,31 +973,38 @@ export function recordQaStageOutcome(args, result) {
     if (!existsSync(reportPath)) return false;
 
     const verdict = result.verdict;
+    const hasLocalIdentity = packet.spec?.local_spec_id != null || verdict?.local_spec_id != null;
+    if (hasLocalIdentity && !qaVerdictIdentityMatch(verdict, packet)) return false;
     const failed = (Array.isArray(verdict.assertions) ? verdict.assertions : [])
       .filter((assertion) => assertion?.status === "fail")
       .map((assertion) => `${assertion.id}: ${assertion.actual || "assertion failed"}`);
-    const committed = commitAssemblyReport(workspace, (report) => recordProducerStageOutcome(report, {
-      stage: "qa",
-      disposition: verdict.disposition,
-      timestamp: verdict.completed_at,
-      command: `campaigns-os ${QA_RUN_PRODUCER}`,
-      outputs: [result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString),
-      blockers: verdict.disposition === "blocked" ? failed : [],
-      warnings: verdict.disposition === "ready_with_exceptions"
-        ? ["QA completed with explicitly attributed exceptions; inspect the verdict artifact."]
-        : [],
-      // The producer knows its own run id and must restate it, or the stage
-      // keeps a previous run's identity beside this run's status and outputs.
-      identity: { verdict_run_id: optionalString(verdict.run_id) },
-      // Which build this verdict judged, and the gates whose browser outcome
-      // the doctor's static scan defers to (qaGatePassedForCurrentBuild). A
-      // gate that never ran is left out, so silence never reads as a pass.
-      evidence: qaStageGateEvidence(verdict, report),
-      // Counts-only: never order ids, refs, emails or URLs (see
-      // summarizePurchaseProof). This is what lets `next` tell a real purchase
-      // path from a `--test-order off` diagnostic.
-      proof: summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
-    }), {
+    const committed = commitAssemblyReport(workspace, (report) => {
+      if (hasLocalIdentity && !specHashesMatch(verdict.spec_hash, report.identity?.spec_material_hash)) {
+        throw new Error("Local-spec QA verdict belongs to a different material revision; report evidence was not changed.");
+      }
+      return recordProducerStageOutcome(report, {
+        stage: "qa",
+        disposition: verdict.disposition,
+        timestamp: verdict.completed_at,
+        command: `campaigns-os ${QA_RUN_PRODUCER}`,
+        outputs: [result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString),
+        blockers: verdict.disposition === "blocked" ? failed : [],
+        warnings: verdict.disposition === "ready_with_exceptions"
+          ? ["QA completed with explicitly attributed exceptions; inspect the verdict artifact."]
+          : [],
+        // The producer knows its own run id and must restate it, or the stage
+        // keeps a previous run's identity beside this run's status and outputs.
+        identity: { verdict_run_id: optionalString(verdict.run_id) },
+        // Which build this verdict judged, and the gates whose browser outcome
+        // the doctor's static scan defers to (qaGatePassedForCurrentBuild). A
+        // gate that never ran is left out, so silence never reads as a pass.
+        evidence: qaStageGateEvidence(verdict, report),
+        // Counts-only: never order ids, refs, emails or URLs (see
+        // summarizePurchaseProof). This is what lets `next` tell a real purchase
+        // path from a `--test-order off` diagnostic.
+        proof: summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
+      });
+    }, {
       stage: "qa",
       // The sidecar names this refresh as its producer (generated_by, #312).
       // This function is the `qa run` stage record, whichever token dispatch
@@ -1167,6 +1188,23 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // them from this function's source.
     const mode = PREPARE_MODES[command];
     if (!mode) throw new Error(`No intake mode registered for "${command}"; add it to PREPARE_MODES.`);
+    // Validate argv before --spec is inspected or --map-id fetches and caches.
+    // Preserve resolveSpecPath's missing-input and map-id/target diagnostics.
+    for (const flag of ["spec", "map-id", "source", "target", "source-kind", "proxy-base"]) {
+      if (Object.hasOwn(args, flag)) requireArg(args, flag);
+    }
+    if (args.spec || (args["map-id"] && args.target)) requireArg(args, "source");
+    if (args.spec) requireArg(args, "target");
+    const sourceKind = optionalString(args["source-kind"], "html_funnel");
+    if (sourceKind !== "html_funnel") {
+      throw refused(`Unsupported source adapter "${sourceKind}". Use html_funnel for the current prepared-HTML flow.`);
+    }
+    if (Object.hasOwn(args, "wrapper-policy") && !isNonEmptyString(args["wrapper-policy"])) {
+      throw refused(`--wrapper-policy needs a value. Accepted values: ${ADAPTER_WRAPPER_POLICIES.join(", ")}.`);
+    }
+    const wrapperPolicyFlag = refusing(() => parseWrapperPolicyFlag(args));
+    refusing(() => requireDesignManifestValue(args));
+    const orderPathDepthFlag = refusing(() => parseOrderPathDepthFlag(args, { command: "prepare-build" }));
     // Tier 2: mark sub-phases so the lifecycle journal entry carries per-phase
     // timings (spec resolve vs the prepare+doctor+install build), which Tier 1
     // aggregates into `start:resolve-spec` / `start:prepare-build` stages.
@@ -1178,7 +1216,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     args.spec = resolved.specPath;
     // `command` rides along for the doctor sidecar's generated_by stamp when
     // the mode runs doctor (#312): threaded from here, not re-read from argv.
-    const result = await recorder.time("prepare-build", () => prepareBuild(args, { ...mode, command, specInput }));
+    const result = await recorder.time("prepare-build", () => prepareBuild(args, { ...mode, command, specInput, sourceKind, wrapperPolicyFlag, orderPathDepthFlag }));
     result.spec_source = resolved;
     autoStartRunSession(result, args, ambient, sessionHolder);
     printPrepareResult(result, args);
@@ -1346,7 +1384,9 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // command a QA run prints has to agree with the run_id this session will
     // later close and remit under.
     const result = await runQaCli(args, { ambient });
-    if (args._[1] === "run" && result?.verdict && recordQaStageOutcome(args, result)) {
+    // nextStage requires a packet. Guard its optional, swallowed progress
+    // probe explicitly so it cannot construct a refusal in that try block.
+    if (args._[1] === "run" && result?.verdict && isNonEmptyString(args.packet) && recordQaStageOutcome(args, result)) {
       // Observe committed QA before the existing closeout; this cannot close
       // a run or change the QA disposition. Reuse the canonical picker.
       try {
@@ -1364,6 +1404,9 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
   }
 
   if (command === "run-record") {
+    // These are the operator's own argv. Internal closeouts call
+    // runRecordCommand directly and retain their pre-1.43.1 flag handling.
+    validateRunRecordArgv(args);
     await runRecordCommand(args, ambient);
     return;
   }
@@ -1675,7 +1718,7 @@ function campaignIdentity(spec, args) {
     || optionalString(spec.spec_identity?.public_route_slug)
     || optionalString(spec.campaign?.slug)
     || optionalString(spec.campaign?.id);
-  return { mapId, publicRouteSlug };
+  return { mapId, publicRouteSlug, localSpecId: spec.spec_identity?.local_spec_id ?? null };
 }
 
 function preferredTemplateFamily(spec) {
@@ -2288,11 +2331,8 @@ function parseWrapperPolicyFlag(args) {
 // directory are errors: the operator named the file, so silently falling back
 // to filesystem matching would discard the declaration they made.
 function parseDesignManifestFlag(args) {
-  const raw = args["design-manifest"];
+  const raw = requireDesignManifestValue(args);
   if (raw == null) return null;
-  if (raw === true || !isNonEmptyString(raw)) {
-    throw new Error("--design-manifest needs a value: the path of a source-html-manifest/v0 JSON file.");
-  }
   const path = resolve(raw);
   if (!existsSync(path) || !statSync(path).isFile()) {
     throw new Error(`Design manifest does not exist or is not a file: ${path}`);
@@ -2300,6 +2340,14 @@ function parseDesignManifestFlag(args) {
   return path;
 }
 
+function requireDesignManifestValue(args) {
+  const raw = args["design-manifest"];
+  if (raw != null && (raw === true || !isNonEmptyString(raw))) {
+    throw new Error("--design-manifest needs a value: the path of a source-html-manifest/v0 JSON file.");
+  }
+  return raw;
+}
+
 // Same precedence the template family uses (docs/build-packet.md
 // "Authoring-Time Hints"): an explicit CLI flag beats a declared file hint,
 // and with neither the default stands. The vocabulary is the adapter
@@ -2350,21 +2398,18 @@ function prepareBuild(args, options = {}) {
   assertDistinctPrepareBuildOutputPaths(prepareBuildCollisionPaths);
   guardAssemblyReportOverwrite(reportPath, args);
   const spec = readJson(specPath);
-  const { mapId, publicRouteSlug } = campaignIdentity(spec, args);
-  if (!mapId) throw new Error("CampaignSpec has no map ID. Re-export a saved Map Builder spec with spec_identity.map_id before assembly; use --map-id only for legacy diagnostics.");
-  if (!publicRouteSlug) throw new Error("CampaignSpec has no public route slug. Re-export a saved Map Builder spec with spec_identity.public_route_slug or set campaign.slug.");
-
-  const sourceKind = optionalString(args["source-kind"], "html_funnel");
-  if (sourceKind !== "html_funnel") {
-    throw new Error(`Unsupported source adapter "${sourceKind}". Use html_funnel for the current prepared-HTML flow.`);
-  }
-  // Validated here, with the other argv checks, rather than where the policy
-  // is consumed: prepare-build publishes an immutable Design Source Package
-  // partway through, so a flag that throws later would leave persistent state
-  // behind for a bad argument.
-  const wrapperPolicyFlag = parseWrapperPolicyFlag(args);
+  const { mapId, publicRouteSlug, localSpecId } = campaignIdentity(spec, args);
+  if (!resolveCampaignIdentity({ map_id: mapId, local_spec_id: localSpecId })) {
+    throw new Error("CampaignSpec requires exactly one identity: a saved spec_identity.map_id, or an agent-authored spec_identity.local_spec_id (1–64 letters, digits, underscores or hyphens). Keep the local ID stable across revisions; do not invent a Map ID.");
+  }
+  if (!publicRouteSlug) throw new Error("CampaignSpec has no public route slug. Set spec_identity.public_route_slug or campaign.slug.");
+
+  // Dispatch validated the argv-only flags before spec resolution. Only the
+  // manifest's filesystem check remains here, before preparation writes.
+  const sourceKind = options.sourceKind;
+  const wrapperPolicyFlag = options.wrapperPolicyFlag;
   const designManifestPath = parseDesignManifestFlag(args);
-  const orderPathDepthFlag = parseOrderPathDepthFlag(args, { command: "prepare-build" });
+  const orderPathDepthFlag = options.orderPathDepthFlag;
 
   const activePages = activeSpecPages(spec);
   const htmlFiles = collectHtmlFiles(sourceRoot);
@@ -2600,7 +2645,8 @@ function prepareBuild(args, options = {}) {
     },
     spec: {
       map_id: mapId,
-      spec_url: spec.spec_identity?.spec_url || null,
+      ...(localSpecId ? { local_spec_id: localSpecId } : {}),
+      spec_url: localSpecId ? null : spec.spec_identity?.spec_url || null,
       local_path: relFromFile(packetPath, specPath),
     },
     design_source_package: designSourcePackage.referenceFor(packetPath),
@@ -2965,6 +3011,7 @@ function createAssemblyReport({
     status: "prepared",
     identity: {
       map_id: packet.spec.map_id,
+      ...localSpecIdentityFields(packet.spec),
       public_route_slug: packet.campaign.public_route_slug,
       campaign_directory: packet.campaign.campaign_directory,
       live_url_path: packet.campaign.live_url_path,
@@ -3860,11 +3907,17 @@ export function doctorPacket(packetPath, options = {}) {
   // to go by first. Code granularity, because that is the granularity the
   // record stores. baseDir is the packet directory, the same root the Run
   // Record writes under.
+  // An invalid identity cannot select history. In particular, withholding a
+  // malformed local ID from derived must not turn it into an unfiltered or
+  // Map-only lookup of another campaign's findings.
+  const comparableIdentity = resolveCampaignIdentity(result.derived)
+    && !result.errors.some(issue => issue.code === "spec.local_identity" || issue.code === "spec.map_id");
   result.cause_summary = annotateDoctorIssueCauses({
     errors: result.errors,
     warnings: result.warnings,
-    baseDir: dirname(resolve(packetPath)),
+    baseDir: comparableIdentity ? dirname(resolve(packetPath)) : null,
     mapId: result.derived?.map_id || null,
+    localSpecId: result.derived?.local_spec_id || null,
   });
   return result;
 }
@@ -3884,6 +3937,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
   const errors = [];
   const warnings = [];
   const ready = [];
+  const packetIdentity = resolveCampaignIdentity(packet?.spec);
   const derived = {
     packet_path: packetPath,
     // The report this inspection read (null when the caller switched the
@@ -3891,6 +3945,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
     // different file.
     assembly_report_path: typeof resolvedReportPath === "string" ? resolvedReportPath : null,
     map_id: packet?.spec?.map_id || null,
+    ...(packetIdentity?.kind === "local_spec" ? { local_spec_id: packetIdentity.id } : {}),
     public_route_slug: packet?.campaign?.public_route_slug || null,
     template_family: packet?.assembly?.template_family || null,
     source_root: null,
@@ -4324,7 +4379,10 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
 
   requireString(packet, errors, "campaign.public_route_slug");
   requireBoolean(packet, errors, "campaign.allowed_domains_confirmed");
-  requireString(packet, errors, "spec.map_id");
+  if (!resolveCampaignIdentity(packet.spec)) addIssue(errors, packet.spec?.local_spec_id != null ? "spec.local_identity" : "spec.map_id", "Packet spec requires exactly one valid map_id or local_spec_id.", { kind: packet.spec?.local_spec_id != null ? "local_spec" : "saved_map" });
+  if (packet.spec?.local_spec_id != null && (packet.spec.spec_url != null || !isNonEmptyString(packet.spec.local_path))) {
+    addIssue(errors, "spec.local_identity", "Local-spec packets require a local_path and no saved-Map spec_url.");
+  }
   if (!synthesizedBuiltSite) {
     requireString(packet, errors, "source_html.root");
     requireArray(packet, errors, "source_html.pages");
@@ -4510,8 +4568,11 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     buildState.specStatus = specStatus;
     if (specStatus === "ok") {
       const specMapId = spec.spec_identity?.map_id || spec.map_id;
-      if (specMapId && specMapId !== packet.spec.map_id) {
-        addIssue(errors, "spec.map_id", `Packet map_id "${packet.spec.map_id}" does not match CampaignSpec map_id "${specMapId}".`);
+      if ((specMapId && specMapId !== packet.spec.map_id)
+        || ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+          && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec))) {
+        const localIdentity = spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null;
+        addIssue(errors, localIdentity ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: localIdentity ? "local_spec" : "saved_map" });
       }
       ready.push("Local CampaignSpec parsed");
       runDoctorChecks(SPEC_DOCTOR_CHECKS, { packet, packetPath, spec, targetRepo, errors, warnings, ready, derived, buildState });
@@ -5006,6 +5067,9 @@ export function pageKitSyncCommand(args) {
       addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", `CampaignSpec identifies route "${singleLineField(specSlug)}" but the packet's campaign.public_route_slug is "${publicRouteSlug}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
     } else if (specMapId && packetMapId && specMapId !== packetMapId) {
       addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", `CampaignSpec spec_identity.map_id "${singleLineField(specMapId)}" does not match the packet's spec.map_id "${singleLineField(packetMapId)}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
+    } else if ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+      && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec)) {
+      addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", "CampaignSpec identity (spec_identity.map_id/local_spec_id) does not match the packet identity. Point spec.local_path at this campaign's spec (or re-run prepare-build from it); nothing was written.");
     }
   }
 
@@ -5349,6 +5413,9 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
       addIssue(result.errors, "spec.derive.spec_identity_mismatch", `CampaignSpec identifies route "${singleLineField(specSlug)}" but the packet's campaign.public_route_slug is "${publicRouteSlug}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
     } else if (specMapId && packetMapId && specMapId !== packetMapId) {
       addIssue(result.errors, "spec.derive.spec_identity_mismatch", `CampaignSpec spec_identity.map_id "${singleLineField(specMapId)}" does not match the packet's spec.map_id "${singleLineField(packetMapId)}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
+    } else if ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+      && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec)) {
+      addIssue(result.errors, "spec.derive.spec_identity_mismatch", "CampaignSpec identity (spec_identity.map_id/local_spec_id) does not match the packet identity. Point spec.local_path at this campaign's spec (or re-run prepare-build from it); nothing was written.");
     }
   }
 
@@ -6133,15 +6200,15 @@ function validateSpecPackageAvailability(spec, warnings, ready) {
 
 function validateSpecIdentityExport(spec, warnings, ready) {
   const identity = spec?.spec_identity;
-  if (isObject(identity) && isNonEmptyString(identity.map_id) && isNonEmptyString(identity.public_route_slug)) {
-    ready.push("CampaignSpec spec_identity includes map_id and public_route_slug");
+  if (isObject(identity) && resolveCampaignIdentity(identity) && isNonEmptyString(identity.public_route_slug)) {
+    ready.push(`CampaignSpec spec_identity includes ${identity.local_spec_id ? "local_spec_id" : "map_id"} and public_route_slug`);
     return;
   }
 
   addIssue(
     warnings,
     "spec_identity.export",
-    "CampaignSpec is missing complete spec_identity.map_id/public_route_slug. Prefer re-exporting from a saved Map Builder map; CLI identity overrides should stay diagnostic-only."
+    "CampaignSpec is missing complete spec_identity: declare map_id for a saved Map or local_spec_id for a local spec, plus public_route_slug. CLI identity overrides should stay diagnostic-only."
   );
 }
 
@@ -9024,7 +9091,12 @@ function validateAssemblyReport(report, { checkSourcePackageFreshness = true } =
   if (report.schema_version !== REPORT_SCHEMA) addIssue(errors, "schema_version", `Expected ${REPORT_SCHEMA}.`);
   else ready.push(`Assembly report schema ${REPORT_SCHEMA}`);
   for (const path of ["run_id", "generated_at", "status", "identity.map_id", "identity.public_route_slug", "inputs.packet_path", "template_family.value"]) {
-    requireString(report, errors, path);
+    if (path === "identity.map_id") {
+      if (!resolveCampaignIdentity(report.identity)) addIssue(errors, "identity.map_id", "Assembly Report requires exactly one valid map_id or local_spec_id.");
+    } else requireString(report, errors, path);
+  }
+  if (report.identity?.local_spec_id != null && !/^sha256:[0-9a-f]{64}$/.test(report.identity.spec_material_hash || "")) {
+    addIssue(errors, "identity.spec_material_hash", "Local-spec reports require a current SHA-256 material spec hash.");
   }
   const stages = report.stages;
   if (!isObject(stages)) {
@@ -9274,13 +9346,14 @@ function nextPrepareBuildBindingIssues({
   const expectedSlug = optionalString(packet.campaign?.public_route_slug);
   const recordedMapId = optionalString(report.identity?.map_id);
   const recordedSlug = optionalString(report.identity?.public_route_slug);
-  if (recordedMapId !== expectedMapId || recordedSlug !== expectedSlug) {
+  if (!campaignIdentitiesMatch(packet.spec, report.identity) || recordedSlug !== expectedSlug) {
     push(
       "next.prepare_build.report_campaign_mismatch",
       "Assembly Report campaign identity does not match the current Build Packet.",
       {
-        expected: { map_id: expectedMapId, public_route_slug: expectedSlug },
-        recorded: { map_id: recordedMapId, public_route_slug: recordedSlug },
+        // Failed identity fields are diagnostic data, never adopted evidence.
+        expected: { map_id: expectedMapId, local_spec_id: packet.spec?.local_spec_id ?? null, public_route_slug: expectedSlug },
+        recorded: { map_id: recordedMapId, local_spec_id: report.identity?.local_spec_id ?? null, public_route_slug: recordedSlug },
       },
     );
   }
@@ -9689,6 +9762,9 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
 }
 
 export function nextStage(stage, args, ambient = null) {
+  if (stage !== null && !NEXT_STAGE_ORDER.includes(stage)) {
+    throw refused(`Unknown next stage: ${stage}. Accepted stages: ${NEXT_STAGE_ORDER.join(", ")}.`);
+  }
   const packetPath = resolve(requireArg(args, "packet"));
   // A custom prepare-build report is recorded on the Build Context relative
   // to the target repo. Packet-only `next` must follow that durable pointer;
@@ -9894,8 +9970,6 @@ export function nextStage(stage, args, ambient = null) {
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "qa");
     addThemeGateErrors(errors, themeGate, "qa");
     prompt = qaPrompt(packetPath, reportPath, packet);
-  } else {
-    throw new Error(`Unknown next stage: ${stage}`);
   }
   const status = errors.length
     ? "blocked"
@@ -10602,7 +10676,7 @@ function qaPrompt(packetPath, reportPath, packet) {
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
   return `Use next-campaigns-qa for this deployed campaign.
 
-Map ID: ${packet.spec.map_id}
+${packet.spec.local_spec_id ? "Local spec ID" : "Map ID"}: ${packet.spec.local_spec_id || packet.spec.map_id}
 Base URL: ${url}
 Build Packet: ${packetPath}
 Assembly Report: ${reportPath}
@@ -12609,6 +12683,12 @@ function runSessionProgress(found) {
 }
 
 async function runSessionEnd(args, ambient = null, sessionHolder = null) {
+  // The closer reads a session, but its own argv refusals still belong to the
+  // invoking command. Check them before entering closeRunSession's nested scope.
+  if (Object.hasOwn(args, "new-run") || Object.hasOwn(args, "run-id")) {
+    throw refused("run end uses the saved session's run ID; --new-run and --run-id are not accepted.");
+  }
+  validateRunRecordArgv(args);
   // Use the session resolved once in main() (single source of truth).
   const found = ambient;
   if (!found) {
@@ -12643,11 +12723,15 @@ async function runSessionEnd(args, ambient = null, sessionHolder = null) {
 // invoking command implements the flag; a closer invoked by a command that
 // does not (the QA auto-end) drops it from extraArgs before calling — see
 // DRY_RUN_COMMANDS and autoEndRunSessionAfterTerminalQa.
-const RUN_RECORD_INHERITABLE_FLAGS = Object.freeze([
+export const RUN_RECORD_INHERITABLE_FLAGS = Object.freeze([
   "context", "report", "qa-verdict", "journal", "surfaces", "primary-surface", "surface-confidence",
   "agent-input-tokens", "agent-output-tokens", "agent-tool-output-tokens", "agent-total-tokens", "agent-elapsed-ms", "agent-model", "agent-usage-source",
   "no-remit", "no-write", "proxy-base", "dry-run", "json",
 ]);
+const RUN_RECORD_BOOLEAN_INHERITABLE_FLAGS = new Set(["no-remit", "no-write", "dry-run", "json"]);
+const RUN_RECORD_INTEGER_INHERITABLE_FLAGS = new Set([
+  "agent-input-tokens", "agent-output-tokens", "agent-tool-output-tokens", "agent-total-tokens", "agent-elapsed-ms",
+]);
 
 // The run-record argv that closes `session`: its run_id and journal, the
 // packet the closer resolved, and only the inheritable flags of `extraArgs`.
@@ -12674,15 +12758,23 @@ export function runSessionEndArgs(session, packet, extraArgs = {}) {
 async function closeRunSession(found, { packet, extraArgs = {}, silent = false, promptForConsent = true, onError = null } = {}) {
   const endArgs = runSessionEndArgs(found.session, packet, extraArgs);
   try {
-    const summary = await runRecordCommand(endArgs, found, { silent, promptForConsent });
+    // No internal closeout currently constructs a refusal before its invoking
+    // command journals: the sweep forwards only remit controls tolerated by
+    // run-record, run end validates its own argv first, and QA auto-end runs
+    // after QA persistence. Keep the scope at this boundary so a future
+    // closeout refusal swallowed by onError cannot mark the outer invocation.
+    const summary = await runWithRefusalScope(() => runRecordCommand(endArgs, found, { silent, promptForConsent }));
     // Clearing the session is a write like any other, so a closer carrying
     // --dry-run leaves it open: the operator sees the record the close would
     // assemble and can still close for real afterwards.
     if (endArgs["dry-run"] !== true) clearRunSession(found.path);
     return summary;
   } catch (error) {
-    if (!onError) throw error;
-    onError(error);
+    // A nested run-record refusal is a failure of the invoking closer, which
+    // has already read session state. Do not pass its tag to outer persistence.
+    const failure = error?.code === REFUSED_INVOCATION ? new Error(error.message, { cause: error }) : error;
+    if (!onError) throw failure;
+    onError(failure);
     return null;
   }
 }
@@ -12892,6 +12984,10 @@ export function describeCampaignKeyRejection(rejected) {
 // docs/workflow-findings-sidecar.md.
 async function runRecordCommand(args, ambient = null, { silent = false, promptForConsent = true } = {}) {
   const packetPath = resolve(requireArg(args, "packet"));
+  if (args["new-run"] === true && optionalString(args["run-id"])) {
+    throw refused("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
+  }
+  const agentUsage = refusing(() => parseAgentUsageArgs(args));
   // --dry-run assembles the record and shows it, then writes and sends
   // nothing. It differs from --no-write, which skips the assembly's reads
   // as well; combining the two is allowed and still writes nothing.
@@ -12919,10 +13015,12 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     : inferQaVerdictPath({ packet, report, reportPath: reportExists ? reportPath : null, targetRepo, baseDir });
   const qaVerdictExists = qaVerdictPath != null && existsSync(qaVerdictPath);
   const qaVerdict = qaVerdictExists ? readJson(qaVerdictPath) : null;
+  if (qaVerdict && (packet.spec?.local_spec_id != null || qaVerdict.local_spec_id != null) && !qaVerdictIdentityMatch(qaVerdict, packet)) {
+    throw new Error("run-record: QA verdict does not match this packet's local_spec_id; foreign evidence cannot be recorded as this local campaign.");
+  }
 
   const journalPath = resolveJournalPath(args);
   const journal = readJournal(journalPath);
-  const agentUsage = parseAgentUsageArgs(args);
 
   // run_id: explicit flag > --new-run (mint) > active run session > the most
   // recent Run Record on disk for this packet's campaign > freshly minted.
@@ -12935,9 +13033,6 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   // record for this campaign exists, or when --new-run asks for it. The
   // source travels on the stdout envelope only: the record's schema is
   // hashed surface and does not carry it.
-  if (args["new-run"] === true && optionalString(args["run-id"])) {
-    throw new Error("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
-  }
   const listOnly = args.list === true;
   // The directory is scanned only when something reads it: --list, or an id
   // that nothing else names. An explicit --run-id, --new-run or an open
@@ -13134,6 +13229,7 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     consent: { state: consent.state, source: consent.source },
     identity: {
       map_id: optionalString(packet.spec?.map_id),
+      ...localSpecIdentityFields(packet.spec),
       campaign_slug: optionalString(packet.campaign?.public_route_slug),
       template_family: optionalString(packet.assembly?.template_family),
       entry_point_shape: "packet",
@@ -13467,7 +13563,8 @@ function inferQaVerdictPath({ packet, report, reportPath = null, targetRepo = nu
     report,
     reportPath: reportPath || (targetRepo ? campaignSidecarPaths(targetRepo).reportPath : null),
     roots: [targetRepo, baseDir],
-  }).filter((candidate) => candidate.verdict && candidate.trusted);
+  }).filter((candidate) => candidate.verdict && candidate.trusted
+    && ((packet?.spec?.local_spec_id == null && candidate.verdict.local_spec_id == null) || candidate.identityMatch));
   eligible.sort((a, b) => {
     const scoreDelta = qaVerdictCandidateScore(b, packet) - qaVerdictCandidateScore(a, packet);
     if (scoreDelta !== 0) return scoreDelta;
@@ -13508,6 +13605,26 @@ function parseRunRecordSurfaces(value) {
   return surfaces;
 }
 
+function validateRunRecordArgv(args) {
+  for (const flag of RUN_RECORD_INHERITABLE_FLAGS) {
+    // The integer flags are checked below by parseAgentUsageArgs, which keeps
+    // their non-negative-integer diagnostics for bare and blank values.
+    if (!RUN_RECORD_BOOLEAN_INHERITABLE_FLAGS.has(flag) && !RUN_RECORD_INTEGER_INHERITABLE_FLAGS.has(flag) && Object.hasOwn(args, flag)) requireArg(args, flag);
+  }
+  if (Object.hasOwn(args, "run-id")) requireArg(args, "run-id");
+  if (Object.hasOwn(args, "new-run") && args["new-run"] !== true) {
+    throw refused("--new-run takes no value.");
+  }
+  if (args["new-run"] === true && optionalString(args["run-id"])) {
+    throw refused("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
+  }
+  return {
+    agentUsage: refusing(() => parseAgentUsageArgs(args)),
+    dryRun: isDryRun(args),
+    parsedSurfaces: parseRunRecordSurfaces(args.surfaces),
+  };
+}
+
 function parseAgentUsageArgs(args) {
   const fields = {
     "agent-input-tokens": "input_tokens",

package/src/finding-cause.mjs

@@ -1,3 +1,4 @@
+import { campaignIdentitiesMatch } from "./spec-source-identity.mjs";
 // Per-finding cause class — "did the change under test cause this?"
 //
 // A run that surfaces eleven findings, none of them caused by the change being
@@ -340,12 +341,13 @@ 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, currentRunId = null } = {}) {
+export function findPriorRunRecord({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   if (!text(baseDir)) return null;
   for (const entry of readRunRecordsForTarget(baseDir)) {
     const record = entry?.record;
     if (!record || typeof record !== "object" || Array.isArray(record)) continue;
     if (currentRunId && record.run_id === currentRunId) continue;
+    if (localSpecId && !campaignIdentitiesMatch(record.identity, { local_spec_id: localSpecId })) continue;
     if (text(mapId) && text(record.identity?.map_id) !== text(mapId)) continue;
     return record;
   }
@@ -376,7 +378,9 @@ function readPriorVerdictFile(path) {
 // verdicts are filed and matched under the names the record itself stores.
 function recordIdentityForDiscovery(record) {
   return {
-    spec: { map_id: text(record?.identity?.map_id) || null },
+    // This is a read-side comparison, not an artifact writer. Preserve even an
+    // invalid local marker so discovery rejects it instead of using its Map ID.
+    spec: { map_id: text(record?.identity?.map_id) || null, local_spec_id: record?.identity?.local_spec_id ?? null },
     campaign: { public_route_slug: text(record?.identity?.campaign_slug) || null },
   };
 }
@@ -444,8 +448,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, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, currentRunId });
+export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, 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);
@@ -468,8 +472,8 @@ export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, c
  * carries these, so doctor cause labels work against existing history with no
  * upgrade window. Returns `{ prior, record, reason }`.
  */
-function loadPriorDoctorFindings({ baseDir, mapId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, currentRunId });
+function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, 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" };
@@ -492,9 +496,9 @@ function loadPriorDoctorFindings({ baseDir, mapId = null, currentRunId = null }
  * 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, currentRunId = null, isFinding } = {}) {
+export function annotateQaAssertionCauses(assertions, { baseDir = null, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
   const lookup = baseDir
-    ? loadPriorQaVerdict({ baseDir, targetRepo, mapId, currentRunId })
+    ? loadPriorQaVerdict({ baseDir, 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";
@@ -528,9 +532,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, currentRunId = null } = {}) {
+export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   const lookup = baseDir
-    ? loadPriorDoctorFindings({ baseDir, mapId, currentRunId })
+    ? loadPriorDoctorFindings({ baseDir, mapId, localSpecId, currentRunId })
     : { prior: null, record: null, reason: "no_prior_run" };
   const noPriorReason = lookup.reason || "no_prior_run";
   const findings = [];