dev-loops 0.4.0 → 0.6.0

package/scripts/loop/resolve-pr-conflicts.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+
+const USAGE = `Usage: resolve-pr-conflicts.mjs [--base <branch>] [--repo-root <dir>] [--no-verify] [--push] [--json]
+
+Deterministic, conservative auto-resolve for a PR branch that is behind/CONFLICTING
+with its base. Merges \`origin/<base>\` into the current branch and resolves ONLY the
+safe additive case: a CHANGELOG.md conflict where both sides only ADD list/section
+entries (keep BOTH sides, in order). ANY other conflicted path — or a non-additive
+CHANGELOG edit — FAILS CLOSED, naming the conflicted paths. Never guesses.
+
+After a clean merge (or an auto-resolved additive CHANGELOG) it runs \`npm run test:docs\`
+(unless --no-verify) and, with --push, pushes the branch.
+
+Options:
+  --base <branch>     Base branch to merge from (default: derived from \`gh pr view\`
+                      base, falling back to "main").
+  --repo-root <dir>   Repo working tree to operate in (default: cwd).
+  --no-verify         Skip \`npm run test:docs\` after resolving.
+  --push              Push the resolved branch to origin after verify.
+  --json              Emit machine-readable JSON on stdout.
+
+Output (stdout, JSON with --json):
+  { "ok": true, "action": "clean_merge"|"resolved",
+    "base": "main", "resolvedFiles": ["CHANGELOG.md"], "pushed": false,
+    "verified": true }
+  ("clean_merge" covers an already-up-to-date branch; "resolved" is the
+   auto-resolved additive-CHANGELOG case. "verified" is true when post-resolve
+   verification ran; it is absent with --no-verify.)
+Error output:
+  { "ok": false, "error": "...", "conflictFiles": ["..."] }
+
+Exit codes:
+  0  Clean merge (incl. already up to date) or auto-resolved CHANGELOG
+  1  Argument error, git failure, or UNRESOLVABLE conflict (fail closed)`.trim();
+
+const parseError = buildParseError(USAGE);
+
+const SAFE_RESOLVABLE_PATH = "CHANGELOG.md";
+
+// Identity for merge/resolve commits so auto-resolve works on a clean runner
+// (CI / consumer) where no ambient git user is configured. Per-command via -c
+// so we never mutate the repo's config.
+const BOT_IDENTITY = [
+  "-c", "user.name=dev-loops[bot]",
+  "-c", "user.email=dev-loops[bot]@users.noreply.github.com",
+];
+
+export function parseResolvePrConflictsCliArgs(argv) {
+  const options = {
+    help: false,
+    base: null,
+    repoRoot: process.cwd(),
+    verify: true,
+    push: false,
+    json: false,
+  };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      base: { type: "string" },
+      "repo-root": { type: "string" },
+      "no-verify": { type: "boolean" },
+      push: { type: "boolean" },
+      json: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") throw parseError(`Unknown argument: ${token.value}`);
+    if (token.kind !== "option") continue;
+    switch (token.name) {
+      case "help":
+        options.help = true;
+        return options;
+      case "base": {
+        const value = requireTokenValue(token, parseError, { flagPattern: /^-/u }).trim();
+        options.base = value.length > 0 ? value : null;
+        break;
+      }
+      case "repo-root": {
+        const value = requireTokenValue(token, parseError, { flagPattern: /^-/u }).trim();
+        options.repoRoot = value.length > 0 ? value : process.cwd();
+        break;
+      }
+      case "no-verify":
+        options.verify = false;
+        break;
+      case "push":
+        options.push = true;
+        break;
+      case "json":
+        options.json = true;
+        break;
+      default:
+        throw parseError(`Unknown argument: ${token.rawName}`);
+    }
+  }
+  return options;
+}
+
+function run(command, args, { cwd, env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+    child.on("error", reject);
+    child.on("close", (code) => { resolve({ code, stdout, stderr }); });
+  });
+}
+
+async function listUnmergedFiles({ cwd, env }) {
+  const result = await run("git", ["diff", "--name-only", "--diff-filter=U"], { cwd, env });
+  if (result.code !== 0) {
+    return [];
+  }
+  return result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+/**
+ * Decide whether a single conflicted file is the safe additive CHANGELOG case
+ * and, if so, produce the merged content (keep BOTH sides, in order).
+ *
+ * Requires diff3-style conflict markers so each hunk carries its merge BASE:
+ *
+ *   <<<<<<< ours
+ *   ...ours...
+ *   ||||||| base
+ *   ...base...
+ *   =======
+ *   ...theirs...
+ *   >>>>>>> theirs
+ *
+ * STRUCTURAL additivity (not lexical): a hunk is safe to keep-both ONLY when its
+ * BASE section is EMPTY — a true insertion on both sides at a spot where base had
+ * nothing. A non-empty base means a shared line was MODIFIED or DELETED on at
+ * least one side → fail closed (a lexical "looks like a list item" check cannot
+ * tell an add from a modify, which silently duplicates/resurrects entries).
+ *
+ * Keep-both order: ours block then theirs block, preserving each side's order.
+ */
+export function resolveAdditiveChangelog(content) {
+  const lines = content.split("\n");
+  const out = [];
+  let i = 0;
+  let resolvedAnyHunk = false;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.startsWith("<<<<<<<")) {
+      out.push(line);
+      i += 1;
+      continue;
+    }
+    // Conflict hunk: <<<<<<< ours ... ||||||| base ... ======= ... >>>>>>> theirs
+    const ours = [];
+    const base = [];
+    const theirs = [];
+    i += 1; // skip <<<<<<<
+    while (i < lines.length && !lines[i].startsWith("|||||||") && !lines[i].startsWith("=======")) {
+      ours.push(lines[i]);
+      i += 1;
+    }
+    if (i >= lines.length) {
+      return { safe: false, reason: "malformed conflict markers (no ======= separator)" };
+    }
+    if (!lines[i].startsWith("|||||||")) {
+      // No base section ⇒ not diff3 style; we cannot tell add from modify.
+      return { safe: false, reason: "missing diff3 base section (||||||| marker)" };
+    }
+    i += 1; // skip |||||||
+    while (i < lines.length && !lines[i].startsWith("=======")) {
+      base.push(lines[i]);
+      i += 1;
+    }
+    if (i >= lines.length) {
+      return { safe: false, reason: "malformed conflict markers (no ======= separator)" };
+    }
+    i += 1; // skip =======
+    while (i < lines.length && !lines[i].startsWith(">>>>>>>")) {
+      theirs.push(lines[i]);
+      i += 1;
+    }
+    if (i >= lines.length) {
+      return { safe: false, reason: "malformed conflict markers (no >>>>>>> terminator)" };
+    }
+    i += 1; // skip >>>>>>>
+
+    // Additive ⇔ base had no line here (both sides inserted). Any non-empty base
+    // section is a modify/delete of a shared line → fail closed.
+    if (base.some((b) => b.trim().length > 0)) {
+      return { safe: false, reason: "CHANGELOG conflict modifies or deletes a shared line (non-empty merge base)" };
+    }
+    // Keep both sides, in order.
+    out.push(...ours, ...theirs);
+    resolvedAnyHunk = true;
+  }
+
+  if (!resolvedAnyHunk) {
+    return { safe: false, reason: "no conflict hunks found in CHANGELOG.md" };
+  }
+  return { safe: true, content: out.join("\n") };
+}
+
+async function abortMerge({ cwd, env }) {
+  await run("git", ["merge", "--abort"], { cwd, env });
+}
+
+export async function resolvePrConflicts(options, { env = process.env } = {}) {
+  const cwd = options.repoRoot;
+
+  // Resolve base branch: explicit flag, else `gh pr view`, else "main".
+  let base = options.base;
+  if (!base) {
+    const view = await run("gh", ["pr", "view", "--json", "baseRefName"], { cwd, env });
+    if (view.code === 0) {
+      try {
+        const parsed = JSON.parse(view.stdout);
+        if (typeof parsed?.baseRefName === "string" && parsed.baseRefName.trim().length > 0) {
+          base = parsed.baseRefName.trim();
+        }
+      } catch {
+        // fall through to default
+      }
+    }
+    if (!base) {
+      base = "main";
+    }
+  }
+
+  const fetch = await run("git", ["fetch", "origin", base], { cwd, env });
+  if (fetch.code !== 0) {
+    throw new Error(`git fetch origin ${base} failed: ${fetch.stderr.trim() || `exit ${fetch.code}`}`);
+  }
+
+  // diff3 conflict style so conflict hunks carry the merge BASE — the additive
+  // CHANGELOG resolver needs it to tell a true insertion from a modify/delete.
+  const merge = await run("git", [...BOT_IDENTITY, "-c", "merge.conflictStyle=diff3", "merge", "--no-edit", `origin/${base}`], { cwd, env });
+  if (merge.code === 0) {
+    const result = { ok: true, action: "clean_merge", base, resolvedFiles: [], pushed: false };
+    await afterResolve(result, options, { cwd, env });
+    return result;
+  }
+
+  // Merge failed — inspect conflicts.
+  const conflictFiles = await listUnmergedFiles({ cwd, env });
+  if (conflictFiles.length === 0) {
+    await abortMerge({ cwd, env });
+    throw new Error(`git merge origin/${base} failed without resolvable conflicts: ${merge.stderr.trim() || `exit ${merge.code}`}`);
+  }
+
+  // Fail closed on ANY conflicted path other than the single safe CHANGELOG case.
+  const nonSafe = conflictFiles.filter((file) => file !== SAFE_RESOLVABLE_PATH);
+  if (nonSafe.length > 0) {
+    await abortMerge({ cwd, env });
+    const err = new Error(
+      `Unresolvable merge conflict: only additive ${SAFE_RESOLVABLE_PATH} conflicts are auto-resolved. `
+      + `Conflicting paths: ${conflictFiles.join(", ")}. Resolve manually.`,
+    );
+    err.conflictFiles = conflictFiles;
+    throw err;
+  }
+
+  // Sole conflict is CHANGELOG.md — attempt the safe additive resolution.
+  const changelogPath = path.join(cwd, SAFE_RESOLVABLE_PATH);
+  const content = await readFile(changelogPath, "utf8");
+  const resolution = resolveAdditiveChangelog(content);
+  if (!resolution.safe) {
+    await abortMerge({ cwd, env });
+    const err = new Error(
+      `Unresolvable ${SAFE_RESOLVABLE_PATH} conflict (${resolution.reason}); not purely additive, so it fails closed. `
+      + `Conflicting paths: ${SAFE_RESOLVABLE_PATH}. Resolve manually.`,
+    );
+    err.conflictFiles = [SAFE_RESOLVABLE_PATH];
+    throw err;
+  }
+
+  await writeFile(changelogPath, resolution.content, "utf8");
+  const add = await run("git", ["add", SAFE_RESOLVABLE_PATH], { cwd, env });
+  if (add.code !== 0) {
+    await abortMerge({ cwd, env });
+    throw new Error(`git add ${SAFE_RESOLVABLE_PATH} failed: ${add.stderr.trim() || `exit ${add.code}`}`);
+  }
+  const commit = await run("git", [...BOT_IDENTITY, "commit", "--no-edit"], { cwd, env });
+  if (commit.code !== 0) {
+    await abortMerge({ cwd, env });
+    throw new Error(`git commit (merge) failed: ${commit.stderr.trim() || `exit ${commit.code}`}`);
+  }
+
+  const result = { ok: true, action: "resolved", base, resolvedFiles: [SAFE_RESOLVABLE_PATH], pushed: false };
+  await afterResolve(result, options, { cwd, env });
+  return result;
+}
+
+async function afterResolve(result, options, { cwd, env }) {
+  if (options.verify) {
+    const verify = await run("npm", ["run", "test:docs"], { cwd, env });
+    if (verify.code !== 0) {
+      const err = new Error(`Post-resolve verification (npm run test:docs) failed: ${verify.stderr.trim() || verify.stdout.trim() || `exit ${verify.code}`}`);
+      err.verifyFailed = true;
+      throw err;
+    }
+    result.verified = true;
+  }
+  if (options.push) {
+    const push = await run("git", ["push"], { cwd, env });
+    if (push.code !== 0) {
+      throw new Error(`git push failed: ${push.stderr.trim() || `exit ${push.code}`}`);
+    }
+    result.pushed = true;
+  }
+}
+
+export async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+  let options;
+  try {
+    options = parseResolvePrConflictsCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  try {
+    const result = await resolvePrConflicts(options, { env });
+    if (options.json) {
+      stdout.write(`${JSON.stringify(result)}\n`);
+    } else {
+      stdout.write(`${result.action} (base ${result.base}${result.resolvedFiles.length ? `, resolved ${result.resolvedFiles.join(", ")}` : ""}${result.pushed ? ", pushed" : ""})\n`);
+    }
+    return 0;
+  } catch (error) {
+    const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    if (Array.isArray(error?.conflictFiles)) {
+      payload.conflictFiles = error.conflictFiles;
+    }
+    stderr.write(`${JSON.stringify(payload)}\n`);
+    return 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

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

@@ -32,11 +32,16 @@ export const CHECKPOINT_ACTION_TO_CONDUCTOR_ACTION = Object.freeze({
   [PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY]: "merge",
   [PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL]: "await_approval",
   [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]: "resolve_conflicts",
+  [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]: "run_ui_e2e",
   [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]: "blocked",
   [PR_CHECKPOINT_ACTION.REPORT_DONE]: "done",
 });
 export const ACTION_PRIORITY = Object.freeze({
   merge: 100,
+  // UI e2e auto-scoping fix work (#976): a path-triggered, fail-closed
+  // precondition — surface it ahead of feedback/draft work so the rendered
+  // artifact gets registered + covered before the gate proceeds.
+  run_ui_e2e: 95,
   fix_threads: 90,
   run_pre_approval: 80,
   draft_gate: 70,

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: [],
+  };
+}