@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/research-gate.mjs

@@ -0,0 +1,704 @@
+#!/usr/bin/env node
+/**
+ * research-gate.mjs  -  which gaps a research pass actually closed.
+ *
+ * A research pass (/multi-agent:research, multi-agent-refs/research/engine.md)
+ * looks for the answer to a gap before anybody is asked: a maturity blocker
+ * such as an empty description, or a Section 20 question the analysis left
+ * open. It writes what it found to <run state dir>/research/research.json
+ * (schemas/research-output.schema.json), the fetched tracker context beside
+ * it (context.json: the issue-fetcher descriptor plus fetched documents), and
+ * a self-contained research.md for the dev run.
+ *
+ * The pass is an agent, so none of its conclusions are taken on its word. This
+ * script decides, by rules:
+ *
+ *   - The gaps are the run's, read from the state: `state.maturity` blockers
+ *     and warnings, or `state.analysis.openQuestions[]`. A finding for a gap
+ *     the run does not have is ignored.
+ *   - `evidence` counts when its `ref` is a source present in context.json and
+ *     its quote is found in that source's text.
+ *   - `repo` counts when `file:line` resolves in the checkout with the quote on
+ *     that line (verify-citations.mjs resolveOne), or when the commit exists
+ *     and its message or diff carries the quote.
+ *   - `inference` never counts. A gap backed only by reasoning is a candidate.
+ *   - Acceptance-criteria and business-rule gaps only ever yield candidates:
+ *     what "done" means and what the business wants belong to a person. The
+ *     writer's category can only make a gap stricter, never looser.
+ *   - Status gaps (closed, already resolved) stay open: the tracker decides.
+ *
+ * Then the check re-runs and its verdict is the decision. For maturity, the
+ * verified quotes are appended to the descriptor's description and
+ * `issue-fetcher.sh --rescore` scores it with the one maturity formula; no
+ * blocker left means proceed. For open questions, the closed rows leave
+ * `analysis.openQuestions[]` and the open-questions check is evaluated on what
+ * remains; an empty list means proceed.
+ *
+ * Gate mode (the default) runs only while the quality gates are active
+ * (lib/unattended.mjs gatesActive); otherwise it prints a not-applicable
+ * verdict, exits 0 and writes nothing. Active, it records `state.research`,
+ * a `research` ledger entry, and either the re-entry point (proceed) or a
+ * parked question a person answers through answer-question.mjs (ask).
+ *
+ * Usage:
+ *   node research-gate.mjs --state <agent-state.json> [--dir <research dir>] [--repo <dir>]
+ *                          [--kind maturity|open-questions] [--json]
+ *   node research-gate.mjs --state <p> --evaluate [--json]      pure: print, write nothing
+ *   node research-gate.mjs --state <p> --recheck --descriptor <fresh.json> [--json]
+ *        pure: re-apply the recorded verified findings to a freshly fetched
+ *        descriptor and re-score it (the maturity step on re-entry); prints the
+ *        maturity and the working description with the verified quotes in it
+ *
+ * Exit: 0 proceed or not-applicable · 1 ask (parked in gate mode) · 2 usage · 3 no state
+ *
+ * @module pipeline/scripts/research-gate
+ */
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { attendedVerdict } from "../lib/unattended.mjs";
+import { messages, outputLanguage } from "../lib/user-facing.mjs";
+import { gateContext, recordQuietly, updateState } from "./gate-ledger.mjs";
+import { evaluateOpenQuestions, pendingQuestionFor } from "./open-questions-gate.mjs";
+import { resolveOne } from "./verify-citations.mjs";
+
+const GATE = "research";
+export const MATURITY_STEP = "phase-0/maturity";
+export const OPEN_QUESTIONS_STEP = "phase-1/open-questions";
+
+const FETCHER =
+  process.env.MA_ISSUE_FETCHER || join(import.meta.dirname, "..", "lib", "issue-fetcher.sh");
+
+/** Categories research can never close on its own. */
+const CANDIDATE_ONLY = new Set(["acceptance-criteria", "business-rule"]);
+const TRACKER_OWNED = new Set(["status"]);
+
+/** Maturity gap codes (lib/issue-fetcher.sh) and what kind of gap each is. */
+const CODE_CATEGORY = {
+  status_closed: "status",
+  already_resolved: "status",
+  description_empty: "description",
+  description_empty_parent_available: "description",
+  description_empty_sibling_available: "description",
+  short_description: "description",
+  short_title: "description",
+  no_repro_steps: "reproduction",
+  no_acceptance_criteria: "acceptance-criteria",
+};
+
+const AC_RE = /acceptance criteria|kabul kriter|definition of done|\bDoD\b|done when|bitti say/i;
+const BR_RE = /business[- ]rule|i[sş] kural|\bpolicy\b|politika|regulat|compliance|mevzuat|legal/i;
+
+/** A quote shorter than this matches too much text to prove anything. */
+const MIN_QUOTE = 8;
+const TEXT_MAX = 2000;
+
+const MATURITY_OPTIONS = (() => {
+  try {
+    const q = JSON.parse(
+      readFileSync(join(import.meta.dirname, "..", "schemas", "run-questions.json"), "utf8"),
+    ).questions.find((x) => x.id === "maturity");
+    if (q && Array.isArray(q.options) && q.options.length >= 2) return q.options;
+  } catch {
+    // An install without the schemas tree still parks on the same three ids.
+  }
+  return [
+    { id: "fix", label: "Open the item and fix it" },
+    { id: "continue", label: "Continue without it" },
+    { id: "abort", label: "Abort" },
+  ];
+})();
+
+const HEAD = {
+  maturity: {
+    en: (n) => `Research could not close ${n} maturity blocker(s); development has not started.`,
+    tr: (n) => `Araştırma ${n} olgunluk engelini kapatamadı; geliştirme başlamadı.`,
+  },
+  candidates: {
+    en: "Candidates research found but could not verify or may not decide:",
+    tr: "Araştırmanın bulduğu ama doğrulayamadığı ya da karar veremeyeceği adaylar:",
+  },
+};
+
+const collapse = (s) =>
+  String(s ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+const lower = (s) => collapse(s).toLowerCase();
+const normRef = (r) =>
+  String(r ?? "")
+    .trim()
+    .replace(/\/+$/, "");
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every source the fetched context holds, by each name it can be cited by.
+ *
+ * @param {{descriptor?: object, documents?: object[]}|null} context
+ * @returns {Map<string, string[]>} ref -> texts
+ */
+export function contextIndex(context) {
+  const map = new Map();
+  const add = (ref, ...texts) => {
+    const k = normRef(ref);
+    if (!k) return;
+    const text = texts.filter((t) => typeof t === "string" && t).join("\n");
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(text);
+  };
+  const d = context?.descriptor && typeof context.descriptor === "object" ? context.descriptor : {};
+  add(d.url, d.title, d.description);
+  add(d.key, d.title, d.description);
+  for (const c of Array.isArray(d.comments) ? d.comments : []) {
+    if (!c || typeof c !== "object") continue;
+    add(c.url, c.body);
+    add(c.id, c.body);
+    if (d.key && c.id) add(`${d.key}#comment-${c.id}`, c.body);
+  }
+  for (const l of Array.isArray(d.links) ? d.links : []) {
+    if (!l || typeof l !== "object") continue;
+    add(l.key, l.summary, l.status);
+    add(l.url, l.summary, l.status);
+  }
+  for (const r of Array.isArray(d.relatedIssues) ? d.relatedIssues : []) {
+    if (r && typeof r === "object") add(r.key, r.summary, r.description);
+  }
+  if (d.parentKey) add(d.parentKey, d.parentDescription);
+  for (const doc of Array.isArray(context?.documents) ? context.documents : []) {
+    if (!doc || typeof doc !== "object") continue;
+    add(doc.id, doc.title, doc.text);
+    add(doc.url, doc.title, doc.text);
+  }
+  return map;
+}
+
+function commitCarries(repo, sha, quote) {
+  const t = spawnSync("git", ["-C", repo, "cat-file", "-t", sha], { encoding: "utf8" });
+  if (t.status !== 0 || t.stdout.trim() !== "commit") return `no commit ${sha} in ${repo}`;
+  const show = spawnSync("git", ["-C", repo, "show", "--format=%B", sha], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (show.status !== 0) return `commit ${sha} could not be read`;
+  return lower(show.stdout).includes(lower(quote)) ? null : `quote not in commit ${sha}`;
+}
+
+/**
+ * One source, checked. Returns the source with `verified` and, when it failed,
+ * `reason`.
+ */
+export function verifySource(src, index, repo, lineCache = new Map()) {
+  const out = { ...src, verified: false };
+  if (!src || typeof src !== "object") return { verified: false, reason: "not a source" };
+  const quote = typeof src.quote === "string" ? src.quote : "";
+  if (src.label === "inference") return { ...out, reason: "inference is reasoning, not a source" };
+  if (src.label === "evidence") {
+    if (collapse(quote).length < MIN_QUOTE) {
+      return { ...out, reason: `evidence needs a quote of at least ${MIN_QUOTE} characters` };
+    }
+    const texts = index.get(normRef(src.ref));
+    if (!texts) return { ...out, reason: `${src.ref} is not in the fetched context` };
+    if (!texts.some((t) => lower(t).includes(lower(quote)))) {
+      return { ...out, reason: `quote not found in ${src.ref}` };
+    }
+    return { ...out, verified: true };
+  }
+  if (src.label === "repo") {
+    if (!repo || !existsSync(repo)) return { ...out, reason: "no checkout to resolve against" };
+    if (typeof src.commit === "string") {
+      if (!/^[0-9a-f]{7,40}$/.test(src.commit)) return { ...out, reason: "not a commit sha" };
+      if (collapse(quote).length < MIN_QUOTE) {
+        return { ...out, reason: `a commit needs a quote of at least ${MIN_QUOTE} characters` };
+      }
+      const why = commitCarries(repo, src.commit, quote);
+      return why ? { ...out, reason: why } : { ...out, verified: true };
+    }
+    if (typeof src.file === "string" && Number.isInteger(src.line)) {
+      if (!collapse(quote)) return { ...out, reason: "file:line needs the quoted line" };
+      const why = resolveOne(repo, null, { file: src.file, line: src.line, quote }, lineCache);
+      return why ? { ...out, reason: why } : { ...out, verified: true };
+    }
+    return { ...out, reason: "repo source needs file+line or commit" };
+  }
+  return { ...out, reason: `unknown label ${src.label}` };
+}
+
+const STRICTNESS = ["status", "acceptance-criteria", "business-rule"];
+
+/** The stricter of two categories; a non-strict one never replaces the other. */
+function stricter(a, b) {
+  const ra = STRICTNESS.indexOf(a);
+  const rb = STRICTNESS.indexOf(b);
+  if (rb === -1) return a;
+  if (ra === -1) return b;
+  return ra <= rb ? a : b;
+}
+
+function textCategory(text) {
+  if (AC_RE.test(text || "")) return "acceptance-criteria";
+  if (BR_RE.test(text || "")) return "business-rule";
+  return null;
+}
+
+/** The run's own gaps, never the research writer's list. */
+export function gapsFor(kind, state) {
+  if (kind === "open-questions") {
+    const list = Array.isArray(state?.analysis?.openQuestions) ? state.analysis.openQuestions : [];
+    return list.map((q, i) => {
+      const text =
+        typeof q === "string" ? q : q?.question || q?.title || q?.id || JSON.stringify(q);
+      const id = (typeof q === "object" && q && q.id) || `Q${i + 1}`;
+      return { id: String(id), text, category: textCategory(text) || "other", raw: q };
+    });
+  }
+  const m = state?.maturity || {};
+  const codes = [
+    ...(Array.isArray(m.blockers) ? m.blockers : []),
+    ...(Array.isArray(m.warnings) ? m.warnings : []),
+  ];
+  return [...new Set(codes)].map((code) => ({
+    id: code,
+    text: code,
+    category: CODE_CATEGORY[code] || "other",
+    blocker: Array.isArray(m.blockers) && m.blockers.includes(code),
+  }));
+}
+
+/** Which gap list this run is waiting on. */
+export function inferKind(state, research) {
+  if (state?.pendingQuestion?.stepId === OPEN_QUESTIONS_STEP) return "open-questions";
+  if (state?.waitingFor === "maturity") return "maturity";
+  const oq = state?.analysis?.openQuestions;
+  if (state?.waitingFor === "question" && Array.isArray(oq) && oq.length) return "open-questions";
+  if (Array.isArray(state?.maturity?.blockers) && state.maturity.blockers.length) {
+    return "maturity";
+  }
+  return research?.kind === "open-questions" ? "open-questions" : "maturity";
+}
+
+function sourceRef(s) {
+  if (s.label === "evidence") return s.ref;
+  if (s.commit) return `commit ${s.commit}`;
+  return `${s.file}:${s.line}`;
+}
+
+/** Re-score a descriptor with the fetcher's own maturity formula. */
+export function rescore(descriptor) {
+  const r = spawnSync("bash", [FETCHER, "--rescore"], {
+    input: JSON.stringify(descriptor),
+    encoding: "utf8",
+    timeout: 60000,
+  });
+  if (r.status !== 0) return null;
+  try {
+    return JSON.parse(r.stdout).maturity || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The whole decision, from its inputs. No writes.
+ *
+ * @param {{kind?: string, state: object, research: object|null, context: object|null,
+ *          repo?: string|null, rescoreWith?: (d: object) => object|null}} args
+ */
+export function evaluate({ kind, state, research, context, repo = null, rescoreWith = rescore }) {
+  const k = kind || inferKind(state, research);
+  const gaps = gapsFor(k, state);
+  const byId = new Map(gaps.map((g) => [g.id, { ...g, findings: [], sources: [] }]));
+  const index = contextIndex(context);
+  const lineCache = new Map();
+  const ignored = [];
+
+  for (const f of Array.isArray(research?.findings) ? research.findings : []) {
+    if (!f || typeof f !== "object") continue;
+    const g = byId.get(String(f.gap));
+    if (!g) {
+      if (!ignored.includes(String(f.gap))) ignored.push(String(f.gap));
+      continue;
+    }
+    if (typeof f.category === "string") g.category = stricter(g.category, f.category);
+    const checked = (Array.isArray(f.sources) ? f.sources : []).map((s) =>
+      verifySource(s, index, repo, lineCache),
+    );
+    g.findings.push({ answer: String(f.answer ?? ""), sources: checked });
+    g.sources.push(...checked);
+  }
+
+  for (const g of byId.values()) {
+    const textCat = textCategory(g.findings.map((f) => f.answer).join(" "));
+    if (k === "open-questions" && textCat) g.category = stricter(g.category, textCat);
+    const verified = g.sources.some((s) => s.verified && s.label !== "inference");
+    if (TRACKER_OWNED.has(g.category) || !g.findings.length) g.status = "open";
+    else if (verified && !CANDIDATE_ONLY.has(g.category)) g.status = "closed";
+    else g.status = "candidate";
+  }
+
+  const all = [...byId.values()];
+  const pick = (st) => all.filter((g) => g.status === st).map((g) => g.id);
+  const result = {
+    gate: GATE,
+    kind: k,
+    gaps: all.map(({ raw: _raw, ...g }) => g),
+    closed: pick("closed"),
+    candidates: pick("candidate"),
+    open: pick("open"),
+    ignored,
+  };
+
+  if (!research) return { ...result, decision: "ask", reason: "no research/research.json" };
+
+  if (k === "open-questions") {
+    const closed = new Set(result.closed);
+    const remaining = all.filter((g) => !closed.has(g.id)).map((g) => g.raw);
+    const check = evaluateOpenQuestions({ analysis: { openQuestions: remaining } });
+    return {
+      ...result,
+      remaining,
+      resolved: all
+        .filter((g) => closed.has(g.id))
+        .map((g) => ({
+          id: g.id,
+          question: g.text,
+          answer: g.findings.map((f) => f.answer).join(" / "),
+          sources: g.sources.filter((s) => s.verified).map(compactSource),
+        })),
+      check: { gate: check.gate, verdict: check.verdict, open: check.open },
+      decision: check.verdict === "pass" ? "proceed" : "ask",
+      reason:
+        check.verdict === "pass"
+          ? "every open question is answered by a verified source"
+          : `${check.open} open question(s) remain after research`,
+    };
+  }
+
+  const descriptor = context?.descriptor;
+  if (!descriptor || typeof descriptor !== "object") {
+    return { ...result, decision: "ask", reason: "no fetched descriptor in research/context.json" };
+  }
+  const closed = new Set(result.closed);
+  const quotes = [];
+  for (const g of all) {
+    if (!closed.has(g.id)) continue;
+    for (const s of g.sources) {
+      if (s.verified) quotes.push(`- "${collapse(s.quote)}" (${sourceRef(s)})`);
+    }
+  }
+  const own = typeof descriptor.description === "string" ? descriptor.description : "";
+  const augmentedDescription = quotes.length
+    ? `${own}${own.trim() ? "\n\n" : ""}Research findings, verified against their sources:\n${[...new Set(quotes)].join("\n")}`
+    : own;
+  const maturityAfter = rescoreWith({ ...descriptor, description: augmentedDescription });
+  if (!maturityAfter) {
+    return {
+      ...result,
+      augmentedDescription,
+      decision: "ask",
+      reason: "the maturity check could not be re-run (issue-fetcher.sh --rescore)",
+    };
+  }
+  const left = Array.isArray(maturityAfter.blockers) ? maturityAfter.blockers : [];
+  return {
+    ...result,
+    augmentedDescription,
+    maturityBefore: state?.maturity || descriptor.maturity || null,
+    maturityAfter,
+    decision: left.length ? "ask" : "proceed",
+    reason: left.length
+      ? `the maturity check still reports ${left.join(", ")}`
+      : "the maturity check reports no blocker once the verified findings are applied",
+  };
+}
+
+function compactSource(s) {
+  const out = { label: s.label };
+  for (const k of ["ref", "file", "line", "commit", "quote"]) if (s[k] !== undefined) out[k] = s[k];
+  return out;
+}
+
+function candidateLines(result) {
+  const lines = [];
+  for (const g of result.gaps) {
+    if (g.status === "closed" || !g.findings.length) continue;
+    for (const f of g.findings) {
+      const labels = [...new Set(f.sources.map((s) => s.label))].join("+");
+      lines.push(`- ${g.id}: ${collapse(f.answer).slice(0, 200)} (${labels || "no source"})`);
+    }
+  }
+  return lines;
+}
+
+function appendWithin(head, lines) {
+  let text = head;
+  for (const l of lines) {
+    const next = `\n${l}`;
+    if (text.length + next.length > TEXT_MAX) break;
+    text += next;
+  }
+  return text;
+}
+
+/** The question a research pass that could not close its gaps parks on. */
+export function pendingQuestionForResearch(result, lang = outputLanguage()) {
+  const cand = candidateLines(result);
+  const candHead = cand.length ? [messages(HEAD.candidates, lang), ...cand] : [];
+  if (result.kind === "open-questions") {
+    const base = pendingQuestionFor(
+      (result.remaining || []).map((q) =>
+        typeof q === "string" ? q : q?.question || q?.title || q?.id || JSON.stringify(q),
+      ),
+    );
+    return { ...base, text: appendWithin(base.text, candHead) };
+  }
+  const blockers = result.maturityAfter?.blockers || result.open;
+  const summary = String(result.maturityAfter?.summary || "")
+    .split("\n")
+    .filter(Boolean);
+  const head = messages(HEAD.maturity, lang)(blockers.length || result.open.length);
+  return {
+    id: "maturity",
+    stepId: MATURITY_STEP,
+    text: appendWithin(head, [...summary, ...candHead]),
+    kind: "single-select",
+    options: MATURITY_OPTIONS.map((o) => ({ id: o.id, label: o.label })),
+  };
+}
+
+function researchRecord(result, { round, dir, at }) {
+  const rec = {
+    round,
+    kind: result.kind,
+    decision: result.decision,
+    reason: result.reason,
+    dir,
+    json: join(dir, "research.json"),
+    context: join(dir, "context.json"),
+    md: join(dir, "research.md"),
+    gaps: result.gaps.map((g) => ({
+      id: g.id,
+      category: g.category,
+      status: g.status,
+      sources: g.sources.filter((s) => s.verified).map(compactSource),
+    })),
+    closed: result.closed,
+    candidates: result.candidates,
+    open: result.open,
+    ignored: result.ignored,
+    at,
+  };
+  if (result.maturityBefore) rec.maturityBefore = result.maturityBefore;
+  if (result.maturityAfter) rec.maturityAfter = result.maturityAfter;
+  if (result.resolved) rec.resolved = result.resolved;
+  return rec;
+}
+
+/** Load research.json / context.json, and refuse a pass that wrote no story. */
+function loadInputs(dir) {
+  const jsonPath = join(dir, "research.json");
+  const research = existsSync(jsonPath) ? readJson(jsonPath) : null;
+  const context = readJson(join(dir, "context.json"));
+  let missing = null;
+  if (!research) missing = `no readable ${jsonPath}`;
+  else if (!existsSync(join(dir, "research.md")) || !statSync(join(dir, "research.md")).size) {
+    missing = `no research.md in ${dir}`;
+  }
+  return { research, context, missing };
+}
+
+function repoFor(state, opt) {
+  if (opt) return opt;
+  for (const p of [state?.worktreePath, state?.projectRoot]) {
+    if (typeof p === "string" && existsSync(p)) return p;
+  }
+  return process.cwd();
+}
+
+function out(json, result) {
+  if (json) {
+    const { gaps, ...rest } = result;
+    const shown = gaps
+      ? {
+          ...rest,
+          gaps: gaps.map((g) => ({ id: g.id, category: g.category, status: g.status })),
+        }
+      : rest;
+    delete shown.augmentedDescription;
+    writeFileSync(1, `${JSON.stringify(shown, null, 2)}\n`);
+    return;
+  }
+  if (result.verdict === "not-applicable") {
+    writeFileSync(1, `research-gate: not-applicable (${result.reason})\n`);
+    return;
+  }
+  writeFileSync(
+    1,
+    `research-gate: ${result.decision} - ${result.reason}\n` +
+      `  closed: ${result.closed?.join(", ") || "none"}\n` +
+      `  candidates: ${result.candidates?.join(", ") || "none"}\n` +
+      `  open: ${result.open?.join(", ") || "none"}\n`,
+  );
+}
+
+function parseArgs(argv) {
+  const opts = { json: false, evaluate: false, recheck: false };
+  const VALUE = new Set(["--state", "--dir", "--repo", "--kind", "--descriptor"]);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--evaluate") opts.evaluate = true;
+    else if (a === "--recheck") opts.recheck = true;
+    else if (VALUE.has(a)) {
+      if (argv[i + 1] === undefined) return { error: `${a} needs a value` };
+      opts[a.slice(2)] = argv[++i];
+    } else return { error: `unexpected argument ${a}` };
+  }
+  if (opts.kind && !["maturity", "open-questions"].includes(opts.kind)) {
+    return { error: `--kind must be maturity or open-questions, got ${opts.kind}` };
+  }
+  if (opts.recheck && !opts.descriptor) return { error: "--recheck needs --descriptor <file>" };
+  return { opts };
+}
+
+async function main(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.error) {
+    process.stderr.write(`research-gate: ${parsed.error}\n`);
+    return 2;
+  }
+  const { opts } = parsed;
+  const pure = opts.evaluate || opts.recheck;
+  const ctx = gateContext({ statePath: opts.state || null, repo: opts.repo || process.cwd() });
+  if (!pure && !ctx.active) {
+    out(opts.json, attendedVerdict(GATE));
+    return 0;
+  }
+  const path = ctx.statePath;
+  if (!path || !existsSync(path)) {
+    process.stderr.write("research-gate: no run state found; there is no gap list to research\n");
+    return 3;
+  }
+  const state = readJson(path);
+  if (!state || typeof state !== "object") {
+    process.stderr.write(`research-gate: ${path} is not a JSON object\n`);
+    return 3;
+  }
+  const repo = repoFor(state, opts.repo);
+
+  if (opts.recheck) {
+    const dir = state.research?.dir || opts.dir || join(dirname(path), "research");
+    const research = readJson(state.research?.json || join(dir, "research.json"));
+    const prior = readJson(state.research?.context || join(dir, "context.json")) || {};
+    const descriptor = readJson(opts.descriptor);
+    if (!descriptor) {
+      process.stderr.write(`research-gate: ${opts.descriptor} is not a descriptor\n`);
+      return 2;
+    }
+    const before = state.research?.maturityBefore || descriptor.maturity;
+    const result = evaluate({
+      kind: "maturity",
+      state: { maturity: before },
+      research,
+      context: { descriptor, documents: prior.documents || [] },
+      repo,
+    });
+    const maturity = result.maturityAfter || descriptor.maturity || null;
+    const shown = {
+      gate: GATE,
+      mode: "recheck",
+      decision: result.decision,
+      reason: result.reason,
+      closed: result.closed,
+      maturity,
+      description: result.augmentedDescription ?? descriptor.description ?? "",
+    };
+    if (opts.json) writeFileSync(1, `${JSON.stringify(shown, null, 2)}\n`);
+    else writeFileSync(1, `research-gate recheck: ${result.decision} - ${result.reason}\n`);
+    return result.decision === "proceed" ? 0 : 1;
+  }
+
+  const dir = opts.dir || join(dirname(path), "research");
+  const { research, context, missing } = loadInputs(dir);
+  let result = evaluate({ kind: opts.kind, state, research, context, repo });
+  if (missing && result.decision === "proceed") {
+    result = { ...result, decision: "ask", reason: missing };
+  } else if (missing && !research) {
+    result = { ...result, reason: missing };
+  }
+
+  if (opts.evaluate) {
+    out(opts.json, result);
+    return result.decision === "proceed" ? 0 : 1;
+  }
+
+  const at = new Date().toISOString();
+  const round = (Number.isInteger(state.research?.round) ? state.research.round : 0) + 1;
+  const rec = researchRecord(result, { round, dir, at });
+  const proceed = result.decision === "proceed";
+  const pending = proceed ? null : { ...pendingQuestionForResearch(result), askedAt: at };
+
+  await updateState(path, (s) => {
+    const next = { ...s, research: rec };
+    if (result.maturityAfter) {
+      const accepted = s.maturity?.accepted;
+      next.maturity = { ...result.maturityAfter, ...(accepted ? { accepted } : {}) };
+    }
+    if (result.kind === "open-questions") {
+      next.analysis = { ...(s.analysis || {}), openQuestions: result.remaining || [] };
+    }
+    if (proceed && result.kind === "open-questions") {
+      delete next.waitingFor;
+      delete next.pendingQuestion;
+      delete next.haltReason;
+      next.status = "in_progress";
+    } else if (proceed) {
+      delete next.pendingQuestion;
+      next.waitingFor = "maturity";
+      next.status = "awaiting_input";
+      next.haltReason = `research closed ${result.closed.join(", ") || "no gap"}; resume re-enters the maturity step`;
+    } else {
+      next.waitingFor = "question";
+      next.pendingQuestion = pending;
+      next.status = "awaiting_input";
+      next.haltReason = `research: ${result.reason}`;
+    }
+    return next;
+  });
+
+  await recordQuietly(
+    GATE,
+    proceed ? "pass" : "fail",
+    {
+      kind: result.kind,
+      round,
+      closed: result.closed,
+      candidates: result.candidates,
+      open: result.open,
+    },
+    { repo, statePath: path },
+  );
+  if (result.kind === "open-questions" && result.check) {
+    await recordQuietly(
+      "open-questions",
+      result.check.verdict,
+      { open: result.check.open, via: "research" },
+      { repo, statePath: path },
+    );
+  }
+  out(opts.json, { ...result, round });
+  return proceed ? 0 : 1;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}