dev-loops 0.4.0 → 0.5.0

package/scripts/loop/run-watch-cycle.mjs

@@ -15,6 +15,7 @@ import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 const REMOVED_FLAGS = new Set([
   "--force-rerequest-review",
   "--probe-only",
@@ -46,9 +47,16 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   runtime failures:
     { "ok": false, "error": "..." }
+Concise mode:
+  --concise, --summary      Human-readable summary: loop state, copilot rounds,
+                            unresolved/actionable thread counts, round-cap-clean
+                            eligibility, CI status, next action, AND the current
+                            round's new Copilot comment bodies.
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or runtime failure`.trim();
+  1  Argument error or runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -202,6 +210,9 @@ export function parseWatchCycleCliArgs(argv) {
     help: false,
     repo: undefined,
     pr: undefined,
+    concise: false,
+    jq: undefined,
+    silent: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -209,6 +220,9 @@ export function parseWatchCycleCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      concise: { type: "boolean" },
+      summary: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -236,6 +250,18 @@ export function parseWatchCycleCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "concise" || token.name === "summary") {
+      options.concise = true;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -395,6 +421,46 @@ export async function runWatchCycle(
   });
   return result;
 }
+// Human-readable concise summary covering loop state, Copilot round count,
+// unresolved/actionable thread counts, round-cap-clean eligibility, CI status,
+// next action, AND the current round's new Copilot comment bodies (from the
+// embedded watch probe result). This is the field set the loop needs to read
+// without parsing the full JSON blob (issue #981).
+export function formatWatchCycleConcise(result) {
+  const snapshot = result.snapshot ?? {};
+  const lines = [
+    `Watch cycle: PR #${snapshot.prNumber ?? "?"}`,
+    `  loop state:          ${result.state}`,
+    `  handoff action:      ${result.handoffAction}`,
+    `  copilot rounds:      ${snapshot.copilotReviewRoundCount ?? 0}`,
+    `  unresolved threads:  ${snapshot.unresolvedThreadCount ?? 0}`,
+    `  actionable threads:  ${snapshot.actionableThreadCount ?? 0}`,
+    `  round-cap clean:     ${result.roundCapCleanEligible ? "yes" : "no"}`,
+    `  CI status:           ${snapshot.ciStatus ?? "none"}`,
+    `  loop disposition:    ${result.loopDisposition}`,
+    `  cycle disposition:   ${result.cycleDisposition}`,
+    `  watch status:        ${result.watchStatus ?? "(not watched)"}`,
+    `  terminal:            ${result.terminal ? "yes" : "no"}`,
+    `  next action:         ${result.nextAction}`,
+  ];
+  const watch = result.watch ?? {};
+  const bodies = [
+    ...(watch.newReviews ?? []).map((r) => ({ kind: "review", body: r.body })),
+    ...(watch.newComments ?? []).map((c) => ({ kind: "threadComment", body: c.body })),
+    ...(watch.newIssueComments ?? []).map((c) => ({ kind: "issueComment", body: c.body })),
+  ].filter((entry) => typeof entry.body === "string" && entry.body.trim().length > 0);
+  if (bodies.length > 0) {
+    lines.push("  new Copilot comment bodies this round:");
+    for (const entry of bodies) {
+      const indented = entry.body.trim().split("\n").map((l) => `      ${l}`).join("\n");
+      lines.push(`    [${entry.kind}]`);
+      lines.push(indented);
+    }
+  } else {
+    lines.push("  new Copilot comment bodies this round: (none)");
+  }
+  return lines.join("\n");
+}
 export async function runCli(
   argv = process.argv.slice(2),
   {
@@ -417,10 +483,18 @@ export async function runCli(
     watchCopilotReviewImpl,
     detectSessionActivity: true,
   });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  if (options.concise && options.jq === undefined && !options.silent) {
+    stdout.write(`${formatWatchCycleConcise(result)}\n`);
+    return result.ok === false ? 1 : 0;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

package/scripts/loop/slides-story-review-contract.mjs

@@ -0,0 +1,123 @@
+// Bounded slides content & storytelling reviewer mode behind `dev-loop`.
+// Sibling of scripts/loop/ui-designer-review-contract.mjs: this one judges a
+// deck's narrative, not its pixels. Pure module, no I/O.
+
+export const STORY_REVIEW_OUTCOMES = Object.freeze([
+  'story_review_satisfied',
+  'needs_iteration',
+]);
+
+export const STORY_REVIEW_SEVERITIES = Object.freeze(['high', 'medium', 'low']);
+
+export function validateSlidesStoryReviewInput(input = {}) {
+  // Coerce a null / non-object argument to {} so this validator always returns
+  // its structured status rather than throwing (the module's contract is a
+  // structured result, never an exception).
+  if (!input || typeof input !== 'object') input = {};
+  if (input.workType !== 'slides' || input.storyReviewRequested !== true) {
+    return {
+      ok: true,
+      status: 'skip_non_slides',
+      reason: 'non_slides_or_not_requested',
+      missing: [],
+    };
+  }
+  const missing = [];
+  const acceptanceCriteria = Array.isArray(input.acceptanceCriteria)
+    ? input.acceptanceCriteria.filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+    : [];
+  if (acceptanceCriteria.length === 0) {
+    missing.push('acceptanceCriteria');
+  }
+  if (typeof input.storytellingBrief !== 'string' || input.storytellingBrief.trim().length === 0) {
+    missing.push('storytellingBrief');
+  }
+  const deckBundle = input.deckBundle ?? {};
+  if (typeof deckBundle.deckSourcePath !== 'string' || deckBundle.deckSourcePath.trim().length === 0) {
+    missing.push('deckBundle.deckSourcePath');
+  }
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      status: 'blocked_missing_required_inputs',
+      reason: 'required_inputs_missing',
+      missing,
+    };
+  }
+  // Captured slide screenshots are optional, but if present each entry must be complete.
+  const incompleteArtifacts = [];
+  const slideScreenshots = Array.isArray(deckBundle.slideScreenshots) ? deckBundle.slideScreenshots : [];
+  slideScreenshots.forEach((rawShot, index) => {
+    const shot = rawShot && typeof rawShot === 'object' ? rawShot : {};
+    if (typeof shot.slideId !== 'string' || shot.slideId.trim().length === 0) {
+      incompleteArtifacts.push(`deckBundle.slideScreenshots[${index}].slideId`);
+    }
+    if (typeof shot.screenshotPath !== 'string' || shot.screenshotPath.trim().length === 0) {
+      incompleteArtifacts.push(`deckBundle.slideScreenshots[${index}].screenshotPath`);
+    }
+  });
+  if (incompleteArtifacts.length > 0) {
+    return {
+      ok: false,
+      status: 'blocked_incomplete_deck_bundle',
+      reason: 'deck_bundle_incomplete',
+      missing: incompleteArtifacts,
+    };
+  }
+  return {
+    ok: true,
+    status: 'ready_for_story_review',
+    reason: 'deck_bundle_complete',
+    missing: [],
+  };
+}
+
+export function validateSlidesStoryReviewResult(result = {}) {
+  // Coerce a null / non-object argument to {} so this validator returns its
+  // structured `invalid` result rather than throwing.
+  if (!result || typeof result !== 'object') result = {};
+  const invalid = [];
+  if (!STORY_REVIEW_OUTCOMES.includes(result.outcome)) {
+    invalid.push('outcome');
+  }
+  if (typeof result.summary !== 'string' || result.summary.trim().length === 0) {
+    invalid.push('summary');
+  }
+  const findings = Array.isArray(result.findings) ? result.findings : null;
+  if (findings === null) {
+    invalid.push('findings');
+  } else {
+    findings.forEach((rawFinding, index) => {
+      const finding = rawFinding && typeof rawFinding === 'object' ? rawFinding : {};
+      if (!STORY_REVIEW_SEVERITIES.includes(finding.severity)) {
+        invalid.push(`findings[${index}].severity`);
+      }
+      if (typeof finding.slideId !== 'string' || finding.slideId.trim().length === 0) {
+        invalid.push(`findings[${index}].slideId`);
+      }
+      if (typeof finding.problem !== 'string' || finding.problem.trim().length === 0) {
+        invalid.push(`findings[${index}].problem`);
+      }
+      if (typeof finding.correctiveAction !== 'string' || finding.correctiveAction.trim().length === 0) {
+        invalid.push(`findings[${index}].correctiveAction`);
+      }
+    });
+  }
+  if (result.outcome === 'needs_iteration' && findings !== null && findings.length === 0) {
+    invalid.push('findings');
+  }
+  if (invalid.length > 0) {
+    return {
+      ok: false,
+      status: 'invalid_result_shape',
+      reason: 'result_shape_invalid',
+      invalid,
+    };
+  }
+  return {
+    ok: true,
+    status: 'valid_result_shape',
+    reason: 'result_shape_valid',
+    invalid: [],
+  };
+}

package/scripts/pages/build-site.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Assembles the GitHub Pages publishable dir deterministically. The landing
+// page (index.html) is the "Introducing dev-loops" article; the deep-dive
+// article and the deep-dive deck are published alongside it and reached through
+// a shared navigation bar injected into the article pages. The source HTML files
+// under docs/ are the source of truth; site/ is assembled, never hand-maintained.
+// Usage: node scripts/pages/build-site.mjs [--out <dir>] [--repo-root <dir>]
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve, parse as parsePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT_DEFAULT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// The landing page: the intro article, published as index.html. file is
+// relative to docs/articles/.
+export const LANDING = { file: 'introducing-dev-loops.html' };
+
+// The deep-dive article published alongside the landing page. file is relative
+// to docs/articles/; navLabel is how the nav refers to it.
+export const ARTICLES = [
+  { file: 'dev-loops-deep-dive.html', navLabel: 'Deep dive' },
+];
+
+// The decks to publish. file is relative to docs/presentations/; outFile is the
+// published name (defaults to file). The deep-dive article and deck share the
+// source basename dev-loops-deep-dive.html under different docs/ dirs, so the
+// deck publishes under a distinct name to avoid clobbering the article in site/.
+export const DECKS = [
+  {
+    file: 'introducing-dev-loops.html',
+    title: 'Introducing dev-loops',
+    subtitle: 'A coordination runtime for AI-assisted development',
+    description: 'The concept, the data behind it, and how to run the loop on your own project.',
+    navLabel: 'Intro (deck)',
+  },
+  {
+    file: 'dev-loops-deep-dive.html',
+    outFile: 'dev-loops-deep-dive-deck.html',
+    title: 'dev-loops: A Deep Dive',
+    subtitle: 'Coordination delay and the waiting between actions',
+    description: 'How explicit handoffs on a state graph and measuring the wait between actions cut delivery delay.',
+    navLabel: 'Deep dive (deck)',
+  },
+];
+
+// Resolve a deck's published filename: distinct outFile when set, else file.
+const deckOut = (deck) => deck.outFile ?? deck.file;
+
+// The other resources linked from the navigation, in order.
+export const NAV_LINKS = [
+  ...ARTICLES.map((a) => ({ file: a.file, label: a.navLabel })),
+  ...DECKS.map((d) => ({ file: deckOut(d), label: d.navLabel })),
+];
+
+// Nav styling, appended to each article page's own <style> block so it reuses
+// the article design-system variables (--heading/--kicker/--accent-soft).
+const NAV_CSS = `
+  .site-nav { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.5rem 1.1rem; max-width: 64rem; margin: 0 auto; padding: 0.9rem clamp(1.1rem, 5vw, 2rem); border-bottom: 1px solid rgba(148, 163, 184, 0.16); }
+  .site-nav-brand { font-weight: 700; letter-spacing: -0.01em; color: var(--heading); text-decoration: none; border: 0; margin-right: auto; }
+  .site-nav-links { display: flex; flex-wrap: wrap; gap: 0.5rem 1.1rem; }
+  .site-nav a { color: var(--kicker); text-decoration: none; font-size: 0.9rem; border: 0; }
+  .site-nav a:hover { color: var(--accent-soft); }`;
+
+function navMarkup() {
+  const links = NAV_LINKS.map((l) => `        <a href="${l.file}">${l.label}</a>`).join('\n');
+  return `<nav class="site-nav" aria-label="dev-loops resources">
+      <a class="site-nav-brand" href="index.html">dev-loops</a>
+      <div class="site-nav-links">
+${links}
+      </div>
+    </nav>`;
+}
+
+// Inject the shared nav into an article page: nav CSS before </style>, nav
+// markup right after <body>. Idempotent enough for assembly (each source file
+// is read once). Throws if the page lacks the expected anchors so a structural
+// drift fails the build rather than publishing an un-navigable page.
+export function injectNav(html) {
+  if (!html.includes('</style>') || !/<body[^>]*>/.test(html)) {
+    throw new Error('cannot inject nav: page is missing a <style> block or <body> tag');
+  }
+  return html
+    .replace('</style>', `${NAV_CSS}\n</style>`)
+    .replace(/<body([^>]*)>/, `<body$1>\n    ${navMarkup()}`);
+}
+
+export async function buildSite({ repoRoot = REPO_ROOT_DEFAULT, outDir } = {}) {
+  const out = outDir ? resolve(outDir) : join(repoRoot, 'site');
+  const articlesDir = join(repoRoot, 'docs', 'articles');
+  const decksDir = join(repoRoot, 'docs', 'presentations');
+
+  // Guard: out is wiped before assembly. Refuse paths that would nuke the
+  // filesystem root, the repo itself, or an ancestor of the repo.
+  const root = resolve(repoRoot);
+  const isAncestorOf = (a, b) => b === a || b.startsWith(a + '/');
+  if (out === parsePath(out).root || out === root || isAncestorOf(out, root)) {
+    throw new Error(`refusing to wipe unsafe output dir ${out}`);
+  }
+
+  await rm(out, { recursive: true, force: true });
+  await mkdir(out, { recursive: true });
+
+  // Landing page: the intro article, navigable, published as index.html.
+  const landingHtml = await readFile(join(articlesDir, LANDING.file), 'utf8');
+  await writeFile(join(out, 'index.html'), injectNav(landingHtml), 'utf8');
+
+  // Deep-dive article: published with the same nav so the set is navigable.
+  for (const article of ARTICLES) {
+    const html = await readFile(join(articlesDir, article.file), 'utf8');
+    await writeFile(join(out, article.file), injectNav(html), 'utf8');
+  }
+
+  // Decks: self-contained slide renders, copied as-is (no nav injection).
+  for (const deck of DECKS) {
+    await cp(join(decksDir, deck.file), join(out, deckOut(deck)));
+  }
+
+  return {
+    out,
+    files: ['index.html', ...ARTICLES.map((a) => a.file), ...DECKS.map((d) => deckOut(d))],
+  };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const getArg = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const result = await buildSite({
+    repoRoot: getArg('--repo-root') ? resolve(getArg('--repo-root')) : undefined,
+    outDir: getArg('--out'),
+  });
+  console.log(`Built site at ${result.out}: ${result.files.join(', ')}`);
+}

package/scripts/projects/add-queue-item.mjs

@@ -2,6 +2,7 @@
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: dev-loops queue add --repo <owner/name> --project <number|id> --item <number>
        dev-loops project add … (back-compat alias for "queue add")
@@ -19,10 +20,12 @@ Options:
 Output (stdout):
   JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent } }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — success (or no-op when already present)
   1 — usage or argument error
-  2 — GitHub API error
+  2 — GitHub API error / invalid --jq filter
   3 — project, field, column, or issue/PR not found
 `.trim();
 
@@ -46,6 +49,7 @@ function parseCliArgs(argv) {
       column: { type: "string" },
       status: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -93,6 +97,12 @@ function parseCliArgs(argv) {
         // resolved by argv order.
         args.status = requireValue(token, "--status requires a value");
         break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
       default:
         throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
     }
@@ -543,7 +553,7 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
   }
   try {
     const result = await main(args, { env });
-    stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
     process.exitCode = classifyExitCode(err);

package/scripts/projects/list-queue-items.mjs

@@ -2,6 +2,7 @@
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: dev-loops queue list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
        (dev-loops project list … is a back-compat alias)
@@ -19,10 +20,12 @@ Options:
 Output (stdout):
   JSON: { ok: true, items: [{ issueNumber, prNumber, title, url, itemId, contentId, status }, ...] }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — success
   1 — usage or argument error
-  2 — GitHub API error
+  2 — GitHub API error / invalid --jq filter
   3 — project, field, or column not found
 `.trim();
 
@@ -45,6 +48,7 @@ function parseCliArgs(argv) {
       column: { type: "string" },
       limit: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +87,12 @@ function parseCliArgs(argv) {
         args.limit = val;
         break;
       }
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
       default:
         throw parseError(`Unknown flag: ${token.rawName}`);
     }
@@ -474,7 +484,7 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
   }
   try {
     const result = await main(args, { env });
-    stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
     process.exitCode = classifyExitCode(err);

package/scripts/projects/move-queue-item.mjs

@@ -2,6 +2,7 @@
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: dev-loops queue move --repo <owner/name> --project <number|id> --item <number|node-id> --to-column <name>
        (dev-loops project move … is a back-compat alias)
@@ -18,10 +19,12 @@ Options:
 Output (stdout):
   JSON: { ok: true, item: { itemId, issueNumber, prNumber, previousColumn, newColumn } }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — success
   1 — usage or argument error
-  2 — GitHub API error
+  2 — GitHub API error / invalid --jq filter
   3 — project, field, column, or item not found
 `.trim();
 
@@ -44,6 +47,7 @@ function parseCliArgs(argv) {
       item: { type: "string" },
       "to-column": { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -76,6 +80,12 @@ function parseCliArgs(argv) {
       case "to-column":
         args.toColumn = requireValue(token, "--to-column requires a value");
         break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
       default:
         throw parseError(`Unknown flag: ${token.rawName}`);
     }
@@ -532,7 +542,7 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
   }
   try {
     const result = await main(args, { env });
-    stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
     process.exitCode = classifyExitCode(err);

package/scripts/refine/_refine-helpers.mjs

@@ -233,6 +233,26 @@ export function extractSection(body, headingText) {
   return body.slice(start, end).trim();
 }
 
+/**
+ * Shared base-section checker for the phase-doc-format validators (plan + spike).
+ * For each heading, reports its distinct missing_* code when the section is
+ * absent or has an empty body. Pure; no side effects.
+ *
+ * @param {string} markdownText
+ * @param {string} checker  checker name echoed back in the result
+ * @param {Record<string,string>} sectionCodes  heading → missing_* code (key order = section order)
+ * @returns {{ checker: string, ok: boolean, errors: { code: string, message: string }[] }}
+ */
+export function checkBaseSections(markdownText, checker, sectionCodes) {
+  const errors = [];
+  for (const [heading, code] of Object.entries(sectionCodes)) {
+    if (!extractSection(markdownText, heading)) {
+      errors.push({ code, message: `Missing or empty ## ${heading} section.` });
+    }
+  }
+  return { checker, ok: errors.length === 0, errors };
+}
+
 export function normalizeScopeToken(value) {
   return String(value ?? "")
     .trim()