@mmerterden/multi-agent-pipeline 20.25.0 → 20.26.0

package/pipeline/scripts/jira-family.mjs

@@ -0,0 +1,947 @@
+#!/usr/bin/env node
+/**
+ * jira-family.mjs  -  the issue family of a run that started from a Jira link,
+ * and the writes the run owes it.
+ *
+ * A run can start from a development sub-task or from its parent story. Either
+ * way the work touches three issues: the story (whose description should be in
+ * the story format `/multi-agent:analysis-jira` writes), the development task
+ * (which gets the Phase 5 comment) and the test sub-task (which gets the test
+ * scenarios). This file is the deterministic half: it resolves the family from
+ * the issue JSON, checks and reformats the story description, builds the test
+ * comment and plans the writes. `lib/jira-family-write.sh` fetches and writes.
+ *
+ * A reformat never invents text. The existing lines are kept verbatim and only
+ * wrapped into panels and ordered: user story, acceptance criteria, the rest.
+ * A heading is added only to a block that had none, and `preserved` is false
+ * (and the write is dropped) if any original line would be lost. The author's
+ * lines are already Jira markup and pass through unescaped; only the text this
+ * file adds (macros, an added heading) is escaped, so the writer sends the body
+ * with `jira-publish.sh --raw`.
+ *
+ * Nothing here asks. An attended run shows every planned write in one grouped
+ * confirmation and drops the ones the person deselects (`--skip`); autopilot
+ * keeps them all and lists each choice it made in `decisions[]`. The one
+ * question left is which development sub-task, when a story has several.
+ *
+ * Every comment carries a `{anchor:...}` marker keyed on the run id. An anchor
+ * renders as nothing, and the writer skips a comment whose marker is already on
+ * the issue, so a re-run posts nothing twice.
+ *
+ * The settings this file consumes, by their full path:
+ *   issueTree.familyWrites      false keeps the single dev comment on the input issue
+ *   issueTree.storyIssueTypes   issue types that are stories (reformatted); empty = storyIssueType
+ *   issueTree.storyIssueType    the site's story type name, "Story" when unset
+ *   issueTree.testSubtaskTypes  sub-task type names that mean "test"; empty = discover
+ *   issueTree.devSubtaskTypes   sub-task type names that mean "development"; empty = match by name
+ *   issueTree.storyPanels       panel colours of the story format, or false for none
+ *   global.outputLanguage       tr or en: headings, questions and the confirmation line
+ *   global.hosts.jira           the host of the dev task link, when --host is not given
+ *
+ * Usage:
+ *   jira-family.mjs resolve --input F [--story F] [--site-types F] [--prefs F] [--lang tr|en]
+ *   jira-family.mjs plan --family F --dev-body F --run-id ID [--mode interactive|autopilot]
+ *                        [--pr-url URL] [--build TEXT] [--host HOST] [--skip id,id]
+ *                        [--dev-task KEY] [--test-task KEY] [--prefs F] [--lang tr|en]
+ *   jira-family.mjs check --description F [--prefs F]     exit 0 conforms, 1 does not
+ *
+ * Exit: 0 ok, 1 check: does not conform, 2 usage, 3 unreadable input.
+ *
+ * @module pipeline/scripts/jira-family
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { panelColours } from "./analysis-story-body.mjs";
+import { escapeJiraEmoticons, wikiLink } from "./jira-wiki-escape.mjs";
+
+const FAMILY_SETTINGS = [
+  "issueTree.familyWrites",
+  "issueTree.storyIssueTypes",
+  "issueTree.storyIssueType",
+  "issueTree.testSubtaskTypes",
+  "issueTree.devSubtaskTypes",
+  "issueTree.storyPanels",
+];
+
+const TEST_TYPE = /\btest\b/i;
+const NOT_TEST_TYPE = /\b(unit|bug|defect|automation)\b/i;
+const looksLikeTest = (name) => TEST_TYPE.test(name) && !NOT_TEST_TYPE.test(name);
+const DEV_TYPE = /\bdev(elop(ment)?)?\b|geliştirme/i;
+const CRITERIA_WORDS = /acceptance|criteria|kabul|kriter|\bAC\b/i;
+const STORY_WORDS = /user story|hikaye|\bstory\b|açıklama|description|amaç|purpose|özet|summary/i;
+const KIND_ORDER = { story: 0, criteria: 1, other: 2 };
+const IMPACT_EXCERPT_MAX = 8;
+const SUMMARY_EXCERPT_MAX = 5;
+
+const TEXT = {
+  tr: {
+    storyHeading: "Kullanıcı Hikayesi",
+    otherHeading: "Diğer",
+    summary: "Geliştirme Özeti",
+    scenarios: "Test Senaryoları",
+    impact: "Etki Analizi",
+    refs: "Bağlantılar",
+    devTask: "Geliştirme görevi",
+    writes: "yazma",
+    labels: {
+      story: "story açıklaması",
+      dev: "dev yorumu",
+      test: "test yorumu",
+      "story-tests": "story'ye test yorumu",
+    },
+    devQ: "Story'nin birden fazla geliştirme alt görevi var. Geliştirme yorumu hangisine gitsin?",
+    testQ: "Story'nin birden fazla test alt görevi var. Test yorumu hangisine gitsin?",
+  },
+  en: {
+    storyHeading: "User story",
+    otherHeading: "Details",
+    summary: "Development Summary",
+    scenarios: "Test Scenarios",
+    impact: "Impact Analysis",
+    refs: "References",
+    devTask: "Development task",
+    writes: "writes",
+    labels: {
+      story: "story description",
+      dev: "dev comment",
+      test: "test comment",
+      "story-tests": "test comment on the story",
+    },
+    devQ: "The story has more than one development sub-task. Which one gets the development comment?",
+    testQ: "The story has more than one test sub-task. Which one gets the test comment?",
+  },
+};
+
+const SUMMARY_HEADINGS = ["Geliştirme Özeti", "Development Summary"];
+const SCENARIO_HEADINGS = ["Test Senaryoları", "Test Scenarios"];
+const IMPACT_HEADINGS = ["Etki Analizi", "Impact Analysis"];
+
+/** tr or en; anything else reads as en. */
+export function language(value) {
+  return String(value || "").toLowerCase() === "tr" ? "tr" : "en";
+}
+
+function prefsPath() {
+  return (
+    process.env.MULTI_AGENT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json")
+  );
+}
+
+/** The family settings plus the output language, from a prefs file. Missing file: defaults. */
+export function readFamilyPrefs(path = prefsPath()) {
+  let g;
+  try {
+    g = JSON.parse(readFileSync(path, "utf8"))?.global || {};
+  } catch {
+    g = {};
+  }
+  const out = {};
+  for (const p of FAMILY_SETTINGS) {
+    const leaf = p.split(".")[1];
+    const v = g.issueTree?.[leaf];
+    if (v !== undefined) out[leaf] = v;
+  }
+  return {
+    familyWrites: out.familyWrites !== false,
+    storyIssueTypes:
+      Array.isArray(out.storyIssueTypes) && out.storyIssueTypes.length
+        ? out.storyIssueTypes
+        : [
+            typeof out.storyIssueType === "string" && out.storyIssueType
+              ? out.storyIssueType
+              : "Story",
+          ],
+    testSubtaskTypes: Array.isArray(out.testSubtaskTypes) ? out.testSubtaskTypes : [],
+    devSubtaskTypes: Array.isArray(out.devSubtaskTypes) ? out.devSubtaskTypes : [],
+    storyPanels: out.storyPanels,
+    lang: language(g.outputLanguage),
+    host: typeof g.hosts?.jira === "string" ? g.hosts.jira : null,
+  };
+}
+
+const lower = (list) => list.map((s) => String(s).toLowerCase());
+
+/**
+ * The type names that mean "test": the configured list, else the site's own
+ * sub-task types (createmeta) whose name carries the word test.
+ */
+export function testTypeNames(siteSubtaskTypes, configured) {
+  if (Array.isArray(configured) && configured.length) return configured;
+  return (siteSubtaskTypes || []).filter(looksLikeTest);
+}
+
+/** "test", "dev" or "other" for one sub-task type name. */
+export function classifySubtask(typeName, { testTypes = [], devTypes = [] } = {}) {
+  const name = String(typeName || "");
+  const isTest = testTypes.length
+    ? lower(testTypes).includes(name.toLowerCase())
+    : looksLikeTest(name);
+  if (isTest) return "test";
+  const isDev = devTypes.length
+    ? lower(devTypes).includes(name.toLowerCase())
+    : DEV_TYPE.test(name);
+  return isDev ? "dev" : "other";
+}
+
+// --- the story description -------------------------------------------------
+
+const WIKI_HEADING = /^\s*h[1-6]\.\s+(.*\S)\s*$/;
+const BOLD_HEADING = /^\s*\*([^*]{1,60})\*\s*:?\s*$/;
+const LABEL_HEADING = /^\s*([\p{L}][\p{L} ]{2,40}):\s*$/u;
+const WHOLE_PANEL = /^\s*\{panel(?::([^}]*))?\}\s*$/;
+const LITERAL_TOKEN = /\{(code|noformat)(?::[^}]*)?\}/g;
+const PAIRED_TOKEN = /\{(quote|color|panel)(:[^}]*)?\}/g;
+
+const knownSection = (text) => CRITERIA_WORDS.test(text) || STORY_WORDS.test(text);
+
+/**
+ * The heading text of a line, or null: an `hN.` heading, or a bold-only or
+ * `Label:` line that names a known section (user story, acceptance criteria).
+ */
+function headingText(line) {
+  const w = line.match(WIKI_HEADING);
+  if (w) return w[1].trim();
+  const b = line.match(BOLD_HEADING) || line.match(LABEL_HEADING);
+  if (b && knownSection(b[1])) return b[1].trim();
+  return null;
+}
+
+function kindOf(heading) {
+  if (CRITERIA_WORDS.test(heading)) return "criteria";
+  if (STORY_WORDS.test(heading)) return "story";
+  return "other";
+}
+
+function borderColour(params) {
+  const m = String(params || "").match(/borderColor=(#[0-9a-fA-F]{6})/);
+  return m ? m[1].toLowerCase() : null;
+}
+
+function panelTitle(params) {
+  const m = String(params || "").match(/(?:^|\|)\s*title=([^|]*)/);
+  return m && m[1].trim() ? m[1].trim() : null;
+}
+
+/**
+ * The description as lines, with what the rest of the file needs to know
+ * about each: whether it is literal text (`{code}` / `{noformat}` body, any
+ * parameters), how deep it sits inside `{quote}` / `{color}` / inline `{panel}`
+ * pairs, and whether it is a `{panel}` macro alone on its line outside every
+ * such pair. Only those whole-line panels are containers this file may
+ * replace; everything else is the author's text.
+ *
+ * `ok` is false when the line endings mix, a pair is left open, or a
+ * whole-line panel opens inside another one: then nothing can be proven about
+ * the text and it must not be rewritten.
+ */
+export function scanDescription(description) {
+  const text = String(description ?? "");
+  const crlf = text.includes("\r\n");
+  const strayCr = (crlf ? text.replace(/\r\n/g, "") : text).includes("\r");
+  const lines = text.split(crlf ? "\r\n" : "\n");
+  const rows = [];
+  let literal = null;
+  let depth = 0;
+  const open = { quote: 0, color: 0, panel: 0 };
+  let wholePanel = false;
+  let ok = !strayCr;
+  for (const line of lines) {
+    const row = { line, literal: literal !== null, depth, panel: null };
+    if (literal === null && depth === 0) {
+      const pm = line.match(WHOLE_PANEL);
+      if (pm) {
+        const closes = wholePanel && pm[1] === undefined;
+        if (!closes && wholePanel) ok = false;
+        row.panel = closes ? { close: true } : { open: true, params: pm[1] ?? "" };
+        wholePanel = !closes;
+        rows.push(row);
+        continue;
+      }
+    }
+    let i = 0;
+    while (i < line.length) {
+      if (literal !== null) {
+        const close = line.indexOf(`{${literal}}`, i);
+        if (close < 0) break;
+        i = close + literal.length + 2;
+        literal = null;
+        continue;
+      }
+      LITERAL_TOKEN.lastIndex = i;
+      PAIRED_TOKEN.lastIndex = i;
+      const lit = LITERAL_TOKEN.exec(line);
+      const pair = PAIRED_TOKEN.exec(line);
+      if (!lit && !pair) break;
+      if (lit && (!pair || lit.index < pair.index)) {
+        literal = lit[1];
+        i = lit.index + lit[0].length;
+        continue;
+      }
+      const [, name, params] = pair;
+      if (name === "quote") {
+        open.quote = open.quote ? 0 : 1;
+      } else if (params || !open[name]) {
+        open[name]++;
+      } else {
+        open[name]--;
+      }
+      depth = open.quote + open.color + open.panel;
+      i = pair.index + pair[0].length;
+    }
+    row.endLiteral = literal !== null;
+    row.endDepth = depth;
+    rows.push(row);
+  }
+  if (literal !== null || depth !== 0 || wholePanel) ok = false;
+  return { rows, eol: crlf ? "\r\n" : "\n", ok };
+}
+
+/** Whether a scanned row can start a section: a heading outside every literal block and pair. */
+function headingOf(row) {
+  return !row.literal && row.depth === 0 && !row.panel ? headingText(row.line) : null;
+}
+
+/**
+ * Whether a description is in the story format.
+ *
+ * With panels: every block sits in a whole-line panel whose border is one of
+ * the story colours, each panel opens with a heading, and the panels run user
+ * story, criteria, then the rest. A trailing `Sources:` line is allowed, as the
+ * analysis writer puts it there. Without panels (storyPanels false): no panel
+ * macros, and the text opens with a heading.
+ *
+ * @returns {{status: "conforms"|"nonconforming"|"empty", reasons: string[]}}
+ */
+export function checkStoryFormat(description, panelsSetting) {
+  const text = String(description ?? "");
+  if (!text.trim()) return { status: "empty", reasons: [] };
+  const colours = panelColours(panelsSetting);
+  const scan = scanDescription(text);
+  const reasons = [];
+  if (!scan.ok) reasons.push("unbalanced macros or mixed line endings");
+  const content = scan.rows.filter((r) => r.line.trim());
+  if (!colours) {
+    if (content.some((r) => r.panel)) reasons.push("panel macros present but panels are off");
+    if (!content.length || !headingOf(content[0])) reasons.push("content before the first heading");
+    const unique = [...new Set(reasons)];
+    return { status: unique.length ? "nonconforming" : "conforms", reasons: unique };
+  }
+  const kindByColour = {};
+  for (const k of ["other", "criteria", "story"]) kindByColour[colours[k].toLowerCase()] = k;
+  let inPanel = false;
+  let awaitingHeading = false;
+  let panels = 0;
+  let lastKind = -1;
+  for (const row of content) {
+    if (row.panel?.open) {
+      inPanel = true;
+      awaitingHeading = true;
+      panels++;
+      const kind = kindByColour[borderColour(row.panel.params)];
+      if (!kind) {
+        reasons.push("a panel colour that is not a story section colour");
+      } else {
+        if (KIND_ORDER[kind] < lastKind) reasons.push("sections out of order");
+        lastKind = Math.max(lastKind, KIND_ORDER[kind]);
+      }
+      continue;
+    }
+    if (row.panel?.close) {
+      if (awaitingHeading) reasons.push("an empty panel");
+      inPanel = false;
+      continue;
+    }
+    if (!inPanel) {
+      if (!/^Sources:/.test(row.line.trim())) reasons.push("text outside the panels");
+    } else if (awaitingHeading) {
+      if (!headingOf(row)) reasons.push("a panel without a heading");
+      awaitingHeading = false;
+    }
+  }
+  if (!panels) reasons.push("no panels");
+  const unique = [...new Set(reasons)];
+  return { status: unique.length ? "nonconforming" : "conforms", reasons: unique };
+}
+
+/**
+ * The description cut into sections at its own headings and at its
+ * whole-line panels. A heading inside a literal block or a pair never cuts.
+ * A panel's `title=` becomes the heading of its section; a section with no
+ * heading of its own gets one added (`added: true`).
+ */
+function sectionsOf(scan) {
+  const sections = [];
+  let current = null;
+  const start = (heading) => {
+    current = { heading, headingLine: null, lines: [] };
+    sections.push(current);
+  };
+  for (const row of scan.rows) {
+    if (row.panel?.open) {
+      start(panelTitle(row.panel.params));
+      continue;
+    }
+    if (row.panel?.close) {
+      current = null;
+      continue;
+    }
+    const h = headingOf(row);
+    if (h !== null) {
+      start(h);
+      current.headingLine = row.line;
+      continue;
+    }
+    if (!current) {
+      if (!row.line.trim()) continue;
+      start(null);
+    }
+    current.lines.push(row.line);
+  }
+  return sections
+    .map((s) => {
+      const lines = [...s.lines];
+      while (lines.length && !lines[0].trim()) lines.shift();
+      while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+      return { ...s, lines };
+    })
+    .filter((s) => s.heading !== null || s.lines.length);
+}
+
+/** The non-blank lines of a description that are the author's text: everything but whole-line panels. */
+function authorLines(description) {
+  return scanDescription(description)
+    .rows.filter((r) => !r.panel && r.line.trim())
+    .map((r) => r.line);
+}
+
+/**
+ * Whether every line of the author's text in `before` is in `after`, exactly
+ * and as many times as it was. Only whole-line panel macros may go.
+ */
+export function preservesContent(before, after) {
+  const have = new Map();
+  for (const l of String(after ?? "").split(/\r?\n/)) have.set(l, (have.get(l) || 0) + 1);
+  for (const l of authorLines(before)) {
+    const n = have.get(l) || 0;
+    if (!n) return false;
+    have.set(l, n - 1);
+  }
+  return true;
+}
+
+/**
+ * The description in the story format, built from its own lines.
+ *
+ * Each line of the author's text is kept as it is, headings included at their
+ * own level; sections move as whole blocks into story, criteria, rest order.
+ * `preserved` is false, and the caller must not write, when the text cannot be
+ * proven to survive: unbalanced macros, mixed line endings, a lost line.
+ *
+ * @returns {{body: string, sections: {heading: string, kind: string, added: boolean}[], preserved: boolean}}
+ */
+export function reformatStory(description, { panels, lang = "en" } = {}) {
+  const T = TEXT[language(lang)];
+  const colours = panelColours(panels);
+  const scan = scanDescription(description);
+  const sections = sectionsOf(scan).map((s, i) => {
+    const added = s.heading === null;
+    const heading = added ? (i === 0 ? T.storyHeading : T.otherHeading) : s.heading;
+    const kind = added ? (i === 0 ? "story" : "other") : kindOf(heading);
+    const headingLine = s.headingLine ?? `h3. ${escapeJiraEmoticons(heading)}`;
+    return { ...s, heading, kind, added, headingLine };
+  });
+  const ordered = [...sections].sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]);
+  const out = [];
+  for (const s of ordered) {
+    const block = [s.headingLine, ...s.lines];
+    if (colours) out.push(`{panel:borderColor=${colours[s.kind]}}`, ...block, "{panel}", "");
+    else out.push(...block, "");
+  }
+  while (out.length && !out[out.length - 1]) out.pop();
+  const body = out.join(scan.eol);
+  return {
+    body,
+    sections: sections.map((s) => ({ heading: s.heading, kind: s.kind, added: s.added })),
+    preserved: scan.ok && preservesContent(description, body),
+  };
+}
+
+// --- the family ------------------------------------------------------------
+
+function subtaskRow(s) {
+  return {
+    key: s.key,
+    summary: s.fields?.summary ?? "",
+    type: s.fields?.issuetype?.name ?? "",
+    status: s.fields?.status?.name ?? "",
+  };
+}
+
+/**
+ * The family of the input issue.
+ *
+ * @param {object} input       the input issue JSON (fields: issuetype, parent, subtasks, description)
+ * @param {object|null} story  the parent's issue JSON when the input is a sub-task
+ * @param {{siteSubtaskTypes?: string[], prefs?: object}} [opts]
+ */
+export function resolveFamily(input, story, opts = {}) {
+  const prefs = opts.prefs || readFamilyPrefs("/nonexistent");
+  const f = input?.fields || {};
+  const isSub = f.issuetype?.subtask === true;
+  const storyIssue = isSub
+    ? story || { key: f.parent?.key, fields: f.parent?.fields || {} }
+    : input;
+  const sf = storyIssue?.fields || {};
+  const testTypes = testTypeNames(opts.siteSubtaskTypes, prefs.testSubtaskTypes);
+  const types = { testTypes, devTypes: prefs.devSubtaskTypes };
+  const subtasks = (sf.subtasks || []).map(subtaskRow);
+  for (const s of subtasks) s.role = classifySubtask(s.type, types);
+  const tests = subtasks.filter((s) => s.role === "test");
+  const devs = subtasks.filter((s) => s.role === "dev");
+
+  let devTaskKey = null;
+  if (isSub) devTaskKey = input.key;
+  else if (devs.length === 1) devTaskKey = devs[0].key;
+
+  const known = typeof sf.description === "string" || sf.description === null;
+  const description = typeof sf.description === "string" ? sf.description : "";
+  const storyType = sf.issuetype?.name ?? "";
+  const storyTypes = lower(prefs.storyIssueTypes || ["Story"]);
+  let format;
+  if (storyType && !storyTypes.includes(storyType.toLowerCase())) {
+    format = { status: "not-a-story", reasons: [`${storyType} is not a story issue type`] };
+  } else if (known) {
+    format = checkStoryFormat(description, prefs.storyPanels);
+  } else {
+    format = { status: "unknown", reasons: ["the story was not fetched"] };
+  }
+  const reformat =
+    format.status === "nonconforming"
+      ? reformatStory(description, { panels: prefs.storyPanels, lang: prefs.lang })
+      : null;
+
+  return {
+    inputKey: input?.key ?? null,
+    inputRole: isSub ? "subtask" : "story",
+    story: { key: storyIssue?.key ?? null, summary: sf.summary ?? "", description },
+    subtasks,
+    testTypes,
+    format: {
+      ...format,
+      reformatted: reformat?.body ?? null,
+      preserved: reformat?.preserved ?? null,
+    },
+    stateEntry: {
+      inputKey: input?.key ?? null,
+      inputRole: isSub ? "subtask" : "story",
+      storyKey: storyIssue?.key ?? null,
+      devTaskKey,
+      devCandidates: devs.map((d) => d.key),
+      testTaskKey: tests.length === 1 ? tests[0].key : null,
+      testCandidates: tests.map((t) => t.key),
+      storyFormat: { status: format.status, reasons: format.reasons },
+    },
+  };
+}
+
+// --- the comments ----------------------------------------------------------
+
+const slug = (s) =>
+  String(s || "run")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "run";
+
+/** The hidden marker a comment of `role` carries for `runId`. */
+export function marker(runId, role) {
+  return `{anchor:ma-family-${slug(role)}-${slug(runId)}}`;
+}
+
+// Wiki markup uses `#` for list items, markdown for headings, so the dialect
+// decides which lines are headings: a body with any `hN.` heading is wiki.
+function headingPatterns(lines) {
+  const wiki = lines.some((l) => /^\s*h[1-6]\.\s/.test(l));
+  return wiki
+    ? { h2: /^\s*h2\.\s+(.*\S)\s*$/, stop: /^\s*h[12]\.\s/ }
+    : { h2: /^\s*##\s+(.*\S)\s*$/, stop: /^\s*#{1,2}\s/ };
+}
+
+/** The lines under the first `##` / `h2.` heading named one of `names`, up to the next heading. */
+export function sectionOf(body, names) {
+  const want = names.map((n) => n.toLowerCase());
+  const lines = String(body ?? "").split("\n");
+  const re = headingPatterns(lines);
+  const start = lines.findIndex((l) => {
+    const m = l.match(re.h2);
+    return Boolean(m && want.includes(m[1].toLowerCase()));
+  });
+  if (start < 0) return null;
+  const out = [];
+  for (const l of lines.slice(start + 1)) {
+    if (re.stop.test(l)) break;
+    out.push(l);
+  }
+  while (out.length && !out[0].trim()) out.shift();
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+/** Whether the scenarios section holds at least one step a tester can follow. */
+export function hasScenarios(devBody) {
+  const s = sectionOf(devBody, SCENARIO_HEADINGS);
+  return Boolean(s && s.some((l) => /^\s*(#+|\d+\.)\s+\S/.test(l)));
+}
+
+/** The first paragraph of the dev comment's summary: what changed, in its own words. */
+function summaryExcerpt(devBody) {
+  const s = sectionOf(devBody, SUMMARY_HEADINGS) || [];
+  const end = s.findIndex((l) => !l.trim());
+  return s.slice(0, end < 0 ? SUMMARY_EXCERPT_MAX : Math.min(end, SUMMARY_EXCERPT_MAX));
+}
+
+/** Part 3 of the impact section (where to test), else its first lines. */
+function impactExcerpt(devBody) {
+  const s = sectionOf(devBody, IMPACT_HEADINGS);
+  if (!s) return [];
+  const part = (n) => (l) => new RegExp(`^\\s*\\*{0,2}${n}\\s*-`).test(l);
+  const from = s.findIndex(part(3));
+  if (from >= 0) {
+    const to = s.findIndex((l, i) => i > from && part(4)(l));
+    return s.slice(from, to < 0 ? undefined : to).filter((l, i, a) => l.trim() || i < a.length - 1);
+  }
+  return s.slice(0, IMPACT_EXCERPT_MAX);
+}
+
+/**
+ * The test sub-task comment, in the dev comment's format: the same four
+ * sections in the same order. The summary's first paragraph (what changed),
+ * the test scenarios verbatim, part 3 of the impact analysis (where to look),
+ * and links to the development task, the PR and the build to test. Null
+ * without scenarios.
+ */
+export function buildTestComment({ devBody, lang, prUrl, build, devKey, host, runId, role }) {
+  if (!hasScenarios(devBody)) return null;
+  const T = TEXT[language(lang)];
+  const out = [];
+  const summary = summaryExcerpt(devBody);
+  if (summary.length) out.push(`h2. ${T.summary}`, ...summary, "");
+  out.push(`h2. ${T.scenarios}`, ...sectionOf(devBody, SCENARIO_HEADINGS), "");
+  const impact = impactExcerpt(devBody);
+  if (impact.length) out.push(`h2. ${T.impact}`, ...impact, "");
+  const refs = [];
+  if (devKey) {
+    const url = host
+      ? `https://${String(host)
+          .replace(/^https?:\/\//, "")
+          .replace(/\/$/, "")}/browse/${devKey}`
+      : null;
+    refs.push(`* ${T.devTask}: ${url ? wikiLink(devKey, url) : devKey}`);
+  }
+  if (prUrl) refs.push(`* PR: ${wikiLink(prUrl, prUrl)}`);
+  if (build) refs.push(`* Build: ${String(build).replace(/\s+/g, " ").trim()}`);
+  if (refs.length) out.push(`h2. ${T.refs}`, ...refs, "");
+  out.push(marker(runId, role || "test"));
+  return out.join("\n");
+}
+
+// --- the plan --------------------------------------------------------------
+
+/**
+ * The writes the run owes the family, the questions an interactive run still
+ * has to ask before them, and the decisions an autopilot run took instead.
+ *
+ * @param {object} family  resolveFamily output
+ * @param {{devBody: string, lang?: string, mode?: string, runId?: string, prUrl?: string,
+ *          build?: string, host?: string, skip?: string[],
+ *          devTask?: string, familyWrites?: boolean}} o
+ */
+export function planWrites(family, o) {
+  const lang = language(o.lang);
+  const T = TEXT[lang];
+  const autopilot = o.mode === "autopilot";
+  const st = family.stateEntry;
+  const writes = [];
+  const skipped = [];
+  const questions = [];
+  const decisions = [];
+  if (!o.runId) throw new Error("planWrites needs a run id: the comment markers are keyed on it");
+  const runId = o.runId;
+  const devBody = String(o.devBody ?? "").replace(/\s+$/, "");
+  const dev = (issue) => ({
+    id: "dev",
+    kind: "comment",
+    issue,
+    label: T.labels.dev,
+    marker: marker(runId, "dev"),
+    body: `${devBody}\n\n${marker(runId, "dev")}`,
+  });
+
+  if (o.familyWrites === false) {
+    writes.push(dev(st.inputKey));
+    return finish();
+  }
+
+  if (st.storyFormat.status === "not-a-story") {
+    skipped.push({ id: "story", reason: `not applicable: ${st.storyFormat.reasons.join("; ")}` });
+    if (autopilot) {
+      decisions.push({
+        writeId: null,
+        what: `Left the description of ${st.storyKey} as it is`,
+        why: `${st.storyFormat.reasons.join("; ")}; only a story is reformatted into the story format`,
+        costIfWrong:
+          "If this issue should follow the story format, it has to be reformatted by hand",
+        phase: 5,
+      });
+    }
+  }
+  if (st.storyFormat.status === "nonconforming") {
+    if (family.format.preserved !== true) {
+      skipped.push({
+        id: "story",
+        reason: "the reformat would not keep every line; left as it is",
+      });
+    } else {
+      writes.push({
+        id: "story",
+        kind: "description",
+        issue: st.storyKey,
+        label: T.labels.story,
+        body: family.format.reformatted,
+        original: family.story.description,
+        raw: true,
+      });
+      if (autopilot) {
+        decisions.push({
+          writeId: "story",
+          what: `Reformatted the description of ${st.storyKey} into the story format`,
+          why: `It did not follow the story format (${st.storyFormat.reasons.join("; ")}); the lines were kept verbatim and only wrapped into panels`,
+          costIfWrong:
+            "The story reads differently than its author left it; the previous description is backed up under jira-backups and can be put back",
+          phase: 5,
+        });
+      }
+    }
+  }
+
+  let devTarget = st.devTaskKey;
+  if (!devTarget && o.devTask && st.devCandidates.includes(o.devTask)) devTarget = o.devTask;
+  if (!devTarget && st.devCandidates.length > 1) {
+    if (autopilot) {
+      devTarget = st.inputKey;
+      decisions.push({
+        writeId: "dev",
+        what: `Posted the development comment on ${st.inputKey} instead of one of its development sub-tasks`,
+        why: `The story has ${st.devCandidates.length} development sub-tasks (${st.devCandidates.join(", ")}) and none is the run's own`,
+        costIfWrong:
+          "The developer looks for the comment on the sub-task and finds it on the story",
+        phase: 5,
+      });
+    } else {
+      questions.push({ id: "dev-task", question: T.devQ, options: st.devCandidates });
+    }
+  }
+  if (!devTarget && !questions.some((q) => q.id === "dev-task")) devTarget = st.inputKey;
+  if (devTarget) writes.push(dev(devTarget));
+
+  if (!hasScenarios(devBody)) {
+    skipped.push({ id: "test", reason: "no test scenarios" });
+    return finish();
+  }
+  const testArgs = {
+    devBody,
+    lang,
+    prUrl: o.prUrl,
+    build: o.build,
+    devKey: devTarget && devTarget !== st.storyKey ? devTarget : null,
+    host: o.host,
+    runId,
+  };
+  let testTarget = st.testTaskKey;
+  const testCandidates = st.testCandidates || [];
+  if (!testTarget && o.testTask && testCandidates.includes(o.testTask)) testTarget = o.testTask;
+  if (!testTarget && testCandidates.length > 1) {
+    if (!autopilot) {
+      questions.push({ id: "test-task", question: T.testQ, options: testCandidates });
+      return finish();
+    }
+    const exact = (family.subtasks || []).find(
+      (x) => testCandidates.includes(x.key) && String(x.type).toLowerCase() === "test",
+    );
+    testTarget = exact ? exact.key : testCandidates[0];
+    if (!exact) {
+      decisions.push({
+        writeId: "test",
+        what: `Posted the test comment on ${testTarget}, the first of ${testCandidates.length} test sub-tasks`,
+        why: `The story has ${testCandidates.length} test sub-tasks (${testCandidates.join(", ")}) and none is of the type Test`,
+        costIfWrong: "The tester looks on another test sub-task and does not find the scenarios",
+        phase: 5,
+      });
+    }
+  }
+  if (testTarget) {
+    writes.push({
+      id: "test",
+      kind: "comment",
+      issue: testTarget,
+      label: T.labels.test,
+      marker: marker(runId, "test"),
+      body: buildTestComment({ ...testArgs, role: "test" }),
+    });
+    return finish();
+  }
+  writes.push({
+    id: "story-tests",
+    kind: "comment",
+    issue: st.storyKey,
+    label: T.labels["story-tests"],
+    marker: marker(runId, "story-tests"),
+    body: buildTestComment({ ...testArgs, role: "story-tests" }),
+  });
+  if (autopilot) {
+    decisions.push({
+      writeId: "story-tests",
+      what: `Posted the test scenarios on ${st.storyKey}, which has no test sub-task`,
+      why: "Autopilot does not drop scenarios a tester needs, and the story is the issue a tester can find",
+      costIfWrong:
+        "The scenarios sit on the story until a test sub-task is opened and they are moved there",
+      phase: 5,
+    });
+  }
+  return finish();
+
+  function finish() {
+    const drop = new Set(o.skip || []);
+    for (const w of writes.filter((x) => drop.has(x.id))) {
+      skipped.push({ id: w.id, reason: "deselected" });
+    }
+    const kept = writes.filter((w) => !drop.has(w.id));
+    const keptDecisions = decisions.filter((d) => d.writeId === null || !drop.has(d.writeId));
+    const labels = kept.map((w) => w.label);
+    return {
+      version: 1,
+      lang,
+      mode: autopilot ? "autopilot" : "interactive",
+      runId,
+      storyPanels: o.storyPanels ?? null,
+      ready: questions.length === 0,
+      confirm: `${kept.length} ${T.writes}: ${labels.join(", ")}`,
+      writes: kept,
+      skipped,
+      questions,
+      decisions: keptDecisions,
+    };
+  }
+}
+
+// --- CLI -------------------------------------------------------------------
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) throw new UsageError(`unexpected argument ${a}`);
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith("--")) throw new UsageError(`${a} needs a value`);
+    opts[a.slice(2)] = v;
+    i++;
+  }
+  return opts;
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function readLines(path) {
+  try {
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+const ENUMS = {
+  mode: ["interactive", "autopilot"],
+  lang: ["tr", "en"],
+};
+
+const HELP = `usage:
+  jira-family.mjs resolve --input F [--story F] [--site-types F] [--prefs F] [--lang tr|en]
+  jira-family.mjs plan --family F --dev-body F --run-id ID [--mode interactive|autopilot]
+                       [--pr-url URL] [--build TEXT] [--host HOST] [--skip id,id]
+                       [--dev-task KEY] [--test-task KEY] [--prefs F] [--lang tr|en]
+  jira-family.mjs check --description F [--prefs F]
+Contract: multi-agent-refs/features/jira-family.md`;
+
+function main(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === "help" || argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${HELP}\n`);
+    return cmd ? 0 : 2;
+  }
+  const o = parseArgs(argv.slice(1));
+  for (const [k, allowed] of Object.entries(ENUMS)) {
+    if (o[k] !== undefined && !allowed.includes(o[k])) {
+      throw new UsageError(`--${k} must be one of ${allowed.join(", ")}`);
+    }
+  }
+  const prefs = readFamilyPrefs(o.prefs || prefsPath());
+  if (o.lang) prefs.lang = o.lang;
+  if (cmd === "check") {
+    if (!o.description) throw new UsageError("check needs --description FILE");
+    const r = checkStoryFormat(readFileSync(o.description, "utf8"), prefs.storyPanels);
+    process.stdout.write(`${JSON.stringify(r)}\n`);
+    return r.status === "conforms" ? 0 : 1;
+  }
+  if (cmd === "resolve") {
+    if (!o.input) throw new UsageError("resolve needs --input FILE");
+    const input = readJson(o.input);
+    const story = o.story ? readJson(o.story) : null;
+    const fam = resolveFamily(input, story, {
+      siteSubtaskTypes: o["site-types"] ? readLines(o["site-types"]) : [],
+      prefs,
+    });
+    process.stdout.write(`${JSON.stringify({ ...fam, lang: prefs.lang }, null, 2)}\n`);
+    return 0;
+  }
+  if (cmd === "plan") {
+    if (!o.family || !o["dev-body"] || !o["run-id"]) {
+      throw new UsageError("plan needs --family FILE --dev-body FILE --run-id ID");
+    }
+    const plan = planWrites(readJson(o.family), {
+      devBody: readFileSync(o["dev-body"], "utf8"),
+      lang: prefs.lang,
+      mode: o.mode,
+      runId: o["run-id"],
+      prUrl: o["pr-url"],
+      build: o.build,
+      host: o.host || prefs.host,
+      skip: o.skip ? o.skip.split(",").map((x) => x.trim()) : [],
+      devTask: o["dev-task"],
+      testTask: o["test-task"],
+      storyPanels: prefs.storyPanels,
+      familyWrites: prefs.familyWrites,
+    });
+    process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+    return 0;
+  }
+  throw new UsageError("usage: jira-family.mjs resolve|plan|check ...");
+}
+
+if (invokedDirectly(import.meta.url)) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`jira-family: ${err.message}\n`);
+    process.exitCode = err instanceof UsageError ? 2 : 3;
+  }
+}