dev-loops 0.5.0 → 0.7.1

package/scripts/refine/promote-plan.mjs

@@ -17,6 +17,7 @@ import {
   writeLinkedPrNumber,
   PLAN_FILE_PROMOTE_ACTION,
 } from "@dev-loops/core/loop/plan-file-promote-contract";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const CREATE_PR_PATH = fileURLToPath(new URL("../github/create-pr.mjs", import.meta.url));
 
@@ -42,9 +43,14 @@ Optional:
   --branch <name>     Branch name to commit the plan on (default: derived from the plan path)
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Promotion succeeded (or idempotent no-op for an already-linked plan)
-  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created`.trim();
+  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -57,6 +63,7 @@ export function parsePromotePlanCliArgs(argv) {
       base: { type: "string" },
       branch: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -88,6 +95,7 @@ export function parsePromotePlanCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,14 @@ function parsePrNumberFromGhOutput(text) {
   return match ? Number.parseInt(match[1], 10) : null;
 }
 
-function emit(stdout, json, summary, humanLines) {
-  if (json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+// Sets process.exitCode from `summary.ok` (0/1), or the shared --jq/--silent
+// contract's exit code (0/1/2) when --json + --jq/--silent are in play.
+function emit(stdout, options, summary, humanLines) {
+  if (options.json) {
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(`${humanLines.join("\n")}\n`);
+    process.exitCode = summary.ok ? 0 : 1;
   }
 }
 
@@ -161,8 +172,7 @@ export async function runCli(argv = process.argv.slice(2), {
   if (!decision.ok) {
     // Fail closed: no git, no gh, no issue — surface the reason and stop.
     const summary = { ok: false, reason: decision.reason, planFileIntakeState: decision.planFileIntakeState ?? null };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${decision.reason})`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${decision.reason})`]);
     return summary;
   }
 
@@ -174,7 +184,7 @@ export async function runCli(argv = process.argv.slice(2), {
       planFile: planPath,
       prNumber: decision.existingPrNumber,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       "promote-plan: PASS (already promoted)",
       `  plan: ${planPath}`,
       `  pr: #${decision.existingPrNumber} (existing; opened nothing)`,
@@ -207,8 +217,7 @@ export async function runCli(argv = process.argv.slice(2), {
 
   const fail = (reason, detail) => {
     const summary = { ok: false, reason, detail: detail ?? null, planFile: planPath };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
     return summary;
   };
 
@@ -294,11 +303,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `gh pr create failed, so no PR was opened, but the plan is committed and branch ${branch} is pushed. Re-run promote-plan to recover: the commit step is idempotent (skips when nothing is staged) and the push is idempotent, so a clean re-run will retry opening the PR.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_create_failed)${detail ? `: ${detail}` : ""}`,
       `  branch: ${branch} (committed and pushed; no PR opened — re-run promote-plan to recover, it is idempotent and will retry opening the PR)`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
   const prNumber = parsePrNumberFromGhOutput(prCreate.stdout);
@@ -315,11 +323,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `A draft PR was opened on branch ${branch} but its number could not be parsed from gh output. Find it with: gh pr list --head "${branch}" --json number,url. Then record the link with: node scripts/refine/promote-plan.mjs is idempotent only once the front-matter prNumber is set, so add it manually (prNumber: <n>) and commit ${planDocRelPath}.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_number_unparseable)`,
       `  branch: ${branch} (a draft PR is open; its number could not be parsed — recover via 'gh pr list --head "${branch}"')`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
 
@@ -340,11 +347,10 @@ export async function runCli(argv = process.argv.slice(2), {
       prNumber,
       recovery: `PR #${prNumber} is open but the plan->PR link commit failed. ${planDocRelPath} now carries prNumber: ${prNumber} in its front-matter; record the link with: git add -- "${planDocRelPath}" && git commit -m "docs(plan): link to PR #${prNumber}" && git push.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`,
       `  pr: #${prNumber} (open; plan->PR link NOT committed — recover manually)`,
     ]);
-    process.exitCode = 1;
     return summary;
   };
   const linkedMarkdown = writeLinkedPrNumber(markdownText, prNumber);
@@ -370,7 +376,7 @@ export async function runCli(argv = process.argv.slice(2), {
     branch,
     prNumber,
   };
-  emit(stdout, options.json, summary, [
+  emit(stdout, options, summary, [
     "promote-plan: PASS",
     `  plan: ${planPath}`,
     `  branch: ${branch}`,

package/scripts/refine/prose-linkage-detector.mjs

@@ -80,7 +80,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runProseLinkageDetector(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/refine-plan-file.mjs

@@ -13,6 +13,7 @@ import {
 } from "@dev-loops/core/loop/plan-file-refine-contract";
 import { PLAN_FILE_REFINEMENT_SECTIONS } from "@dev-loops/core/loop/plan-file-intake-contract";
 import { classifyDocsGrillFinding } from "../loop/docs-grill-contract.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   refine-plan-file.mjs --plan-file <path> --payload <path> [--json]
@@ -31,9 +32,14 @@ Required:
 Optional:
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Refinement succeeded; plan written in place; stop for local human review
-  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)`.trim();
+  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -45,6 +51,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       "plan-file": { type: "string" },
       payload: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -72,6 +79,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,12 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   if (!result.ok) {
     // Fail closed: surface the reason, do not write, do not advance, do not promote.
     if (options.json) {
-      stdout.write(`${JSON.stringify({ ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null })}\n`);
+      const failurePayload = { ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null };
+      process.exitCode = emitResult(failurePayload, { jq: options.jq, silent: options.silent, stdout });
     } else {
       stdout.write(`refine-plan-file: FAIL (${result.reason})\n`);
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return result;
   }
 
@@ -142,7 +151,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     grillDispositions: result.grillDispositions,
   };
   if (options.json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(
       [

package/scripts/refine/refinement-completeness-checker.mjs

@@ -76,7 +76,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runRefinementCompletenessChecker(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/scaffold-spike-file.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Scaffold a STARTABLE spike findings artifact from an inline question (#988 P2).
+//
+// `/start-spike <question>` needs a findings artifact that passes
+// `validateSpikeExplorationSections` (non-empty Question/Approach/Findings) so
+// `resolve-dev-loop-startup --spike <path>` accepts it. This is the only new
+// piece behind /start-spike: a pure section builder + a thin file writer. The
+// Recommendation is left for the spike to fill in (the exit marker), matching
+// the spike-mode contract — so this scaffolds an in-progress spike, not a
+// ready-for-exit one. No new spike behavior; the intake/gate/exit machinery is
+// the shipped #964/#965/#966 surface.
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { SPIKE_FILE_EXPLORATION_SECTIONS } from "./validate-spike-file.mjs";
+
+// Placeholder bodies the operator fills in during the spike. Non-empty so the
+// exploration scaffold validates; explicitly marked TBD so they are obviously
+// stubs, not findings. (`Recommendation` is intentionally omitted — it is the
+// exit marker, written when the spike concludes.)
+const PLACEHOLDER = "TBD — filled in during the spike.";
+
+const USAGE = `Usage:
+  scaffold-spike-file.mjs --question <text> --out <path>
+
+Scaffold a startable spike findings artifact from an inline question. Writes a
+file carrying the exploration scaffold (## Question filled from --question,
+## Approach/## Findings stubbed) so \`resolve-dev-loop-startup --spike <path>\`
+accepts it. The ## Recommendation is left for the spike to fill in.
+
+Options:
+  --question <text>   Required. The question the spike investigates.
+  --out <path>        Required. Where to write the findings artifact.
+  --help, -h          Show this help.
+
+Output (stdout):
+  JSON: { ok: true, path: "<abs>", question: "<text>" }
+
+${JQ_OUTPUT_USAGE}
+`.trim();
+
+// Pure builder: question text -> a findings-artifact markdown body carrying the
+// exploration scaffold. Question gets the operator's text; Approach/Findings get
+// non-empty placeholder bodies so the exploration scaffold validates.
+export function buildSpikeScaffold(question) {
+  const trimmed = String(question ?? "").trim();
+  if (trimmed.length === 0) {
+    throw Object.assign(new Error("--question must be non-empty"), { code: "INVALID_ARGS" });
+  }
+  const bodies = { Question: trimmed, Approach: PLACEHOLDER, Findings: PLACEHOLDER };
+  const sections = SPIKE_FILE_EXPLORATION_SECTIONS.map(
+    (heading) => `## ${heading}\n\n${bodies[heading]}\n`,
+  );
+  return `# Spike\n\n${sections.join("\n")}`;
+}
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+  // The question is free text embedded in the artifact body, never forwarded as
+  // a CLI option — so unlike --out/--jq it may legitimately begin with `-`
+  // (e.g. "- should we ...?"). Only require a non-empty value, matching the
+  // core free-text parser; leave the leading-`-` guard to the path/filter flags.
+  const requireQuestion = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      question: { type: "string" },
+      out: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        args.help = true;
+        break;
+      case "json":
+        // Output is JSON by default; accepted as a no-op for callers that pass it.
+        break;
+      case "question":
+        args.question = requireQuestion(token, "--question requires a value");
+        break;
+      case "out":
+        args.out = requireValue(token, "--out requires a value (path)");
+        break;
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
+        throw parseError(`Unknown flag: ${token.rawName}`);
+      }
+    }
+  }
+  return args;
+}
+
+export async function main(args, { writeFileImpl = writeFile, mkdirImpl = mkdir } = {}) {
+  if (!args.question) {
+    throw Object.assign(new Error("--question is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  if (!args.out) {
+    throw Object.assign(new Error("--out is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  const body = buildSpikeScaffold(args.question);
+  const outPath = path.resolve(args.out);
+  await mkdirImpl(path.dirname(outPath), { recursive: true });
+  // Fail closed on an existing file: the slash-command picks a fresh path and
+  // must never clobber a spike already in progress. `wx` makes write+exclusive
+  // atomic, so a concurrent create still loses (no overwrite).
+  try {
+    await writeFileImpl(outPath, body, { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      throw Object.assign(new Error(`--out already exists, refusing to overwrite: ${outPath}`), {
+        usage: USAGE,
+        code: "INVALID_ARGS",
+      });
+    }
+    throw err;
+  }
+  return { ok: true, path: outPath, question: String(args.question).trim() };
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await main(args);
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = err.code === "INVALID_ARGS" ? 1 : 2;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 2;
+  });
+}

package/scripts/refine/scope-boundary-cross-checker.mjs

@@ -151,7 +151,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runScopeBoundaryCrossChecker(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/tree-integrity-validator.mjs

@@ -199,7 +199,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runTreeIntegrityValidator(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/validate-plan-file.mjs

@@ -52,7 +52,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const markdownText = await readFile(options.input, "utf8");
   const result = validatePlanFile(markdownText);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/validate-spike-file.mjs

@@ -75,7 +75,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const markdownText = await readFile(options.input, "utf8");
   const result = validateSpikeFile(markdownText);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/verify.mjs

@@ -9,6 +9,7 @@ import { runProseLinkageDetector } from "./prose-linkage-detector.mjs";
 import { runScopeBoundaryCrossChecker } from "./scope-boundary-cross-checker.mjs";
 import { runRefinementCompletenessChecker } from "./refinement-completeness-checker.mjs";
 import { runTreeIntegrityValidator } from "./tree-integrity-validator.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   dev-loops refine verify --issue <number> [--repo <owner/name>] [--json]
@@ -26,7 +27,10 @@ Required (exactly one mode):
 Optional:
   --repo <owner/name>       Repository slug for online mode
   --json                    Machine-readable JSON output (default: human-readable summary)
-  --help                    Show this help`.trim();
+  --help                    Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -39,6 +43,7 @@ export function parseRefineVerifyCliArgs(argv) {
       repo: { type: "string" },
       input: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -79,6 +84,7 @@ export function parseRefineVerifyCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
@@ -177,13 +183,12 @@ export async function runCli(
   };
 
   if (options.json) {
-    stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout });
   } else {
     writeHumanOutput(result, tree, { stdout });
-  }
-
-  if (!result.ok) {
-    process.exitCode = 1;
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
   }
   return payload;
 }

package/scripts/release/assert-core-dependency-version.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Release-time guard: fail closed when the published `dev-loops` package's
+ * `@dev-loops/core` dependency does not resolve to the same major.minor as the
+ * version being released. This is the check that would have caught #1033
+ * (`dev-loops@0.6.2` shipping `@dev-loops/core@^0.2.6`).
+ *
+ * Runs in release.yml BEFORE the GitHub Release is created, so a mismatched
+ * manifest never becomes a release (and never fires npm-publish). release.yml
+ * has no `npm ci`, so this script imports only `node:` builtins — a workspace
+ * import here would ERR_MODULE_NOT_FOUND and skip the guard entirely (same
+ * constraint as extract-changelog-section.mjs).
+ *
+ * Usage:
+ *   node scripts/release/assert-core-dependency-version.mjs [--release-version <v>] [--manifest <path>]
+ *
+ * --release-version defaults to the manifest `version`. Pass the tag-derived
+ * version in release.yml so a manifest that forgot its own bump is also caught.
+ * Exits 0 on lockstep, 1 on mismatch, 2 on usage/parse errors.
+ */
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const CORE_DEP = "@dev-loops/core";
+
+function isDirectCliRun(importMetaUrl, argv1 = process.argv[1]) {
+  if (typeof argv1 !== "string" || argv1.length === 0) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(importMetaUrl));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract the `major.minor` token from a semver version or npm range.
+ * Handles leading range operators (^, ~, >=, >, <=, <, =, v) and compound
+ * ranges by taking the first `<digits>.<digits>` occurrence.
+ * @param {string} spec
+ * @returns {string} e.g. "0.6"
+ */
+export function extractMajorMinor(spec) {
+  const match = String(spec).match(/(\d+)\.(\d+)/);
+  if (!match) {
+    throw new Error(`cannot parse a major.minor version from "${spec}"`);
+  }
+  return `${match[1]}.${match[2]}`;
+}
+
+/**
+ * Assert the `@dev-loops/core` dependency range is in lockstep (same
+ * major.minor) with the release version. Throws on mismatch (fail closed).
+ * @param {{releaseVersion: string, coreRange: string}} input
+ * @returns {{releaseVersion: string, coreRange: string, majorMinor: string}}
+ */
+export function assertCoreDependencyInLockstep({ releaseVersion, coreRange } = {}) {
+  if (!releaseVersion) throw new Error("releaseVersion is required");
+  if (!coreRange) {
+    throw new Error(`root package must declare a "${CORE_DEP}" dependency`);
+  }
+  const releaseMajorMinor = extractMajorMinor(releaseVersion);
+  const coreMajorMinor = extractMajorMinor(coreRange);
+  if (releaseMajorMinor !== coreMajorMinor) {
+    throw new Error(
+      `${CORE_DEP} dependency "${coreRange}" (major.minor ${coreMajorMinor}) does not match ` +
+        `the release version ${releaseVersion} (major.minor ${releaseMajorMinor}). ` +
+        `Bump the ${CORE_DEP} range to ^${releaseMajorMinor}.0 before releasing (root cause of #1033).`,
+    );
+  }
+  return { releaseVersion, coreRange, majorMinor: releaseMajorMinor };
+}
+
+function usageError(message) {
+  const err = new Error(message);
+  err.usage = true;
+  return err;
+}
+
+function parseArgs(argv) {
+  const out = { manifest: "package.json", releaseVersion: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--release-version" || arg === "--manifest") {
+      const value = argv[++i];
+      // Fail closed like extract-changelog-section.mjs: a flag missing its value
+      // is a usage error (exit 2), not a silent fallback that defeats the guard.
+      if (value === undefined) throw usageError(`${arg} requires a value`);
+      if (arg === "--release-version") out.releaseVersion = value;
+      else out.manifest = value;
+    } else {
+      throw usageError(`unknown argument: ${arg}`);
+    }
+  }
+  return out;
+}
+
+async function main(argv) {
+  const { manifest, releaseVersion } = parseArgs(argv);
+  // An unreadable or invalid manifest is a usage/parse error (exit 2), not a
+  // lockstep mismatch (exit 1) — matches the header contract and extract-changelog-section.mjs.
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(manifest, "utf8"));
+  } catch (err) {
+    throw usageError(`cannot read or parse manifest "${manifest}": ${err.message}`);
+  }
+  const coreRange = pkg.dependencies?.[CORE_DEP];
+  const result = assertCoreDependencyInLockstep({
+    releaseVersion: releaseVersion ?? pkg.version,
+    coreRange,
+  });
+  process.stdout.write(
+    `${CORE_DEP} ${result.coreRange} is in lockstep with release ${result.releaseVersion} (major.minor ${result.majorMinor}).\n`,
+  );
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`::error::${err.message}\n`);
+    process.exit(err.usage ? 2 : 1);
+  });
+}