@mmerterden/multi-agent-pipeline 16.28.0 → 16.29.0

package/pipeline/schemas/prefs.schema.json

@@ -555,8 +555,8 @@
             },
             "fableEnabled": {
               "type": "boolean",
-              "default": true,
-              "description": "Whether the fable rung is available at all on Claude Code. false makes every persona that declares preferredModel: fable dispatch on opus from the first call, with no dispatch attempt on fable and no error to recover from  -  a cost control, not a fallback. Claude Code only: Copilot CLI does not offer Fable 5, and on Codex CLI the fable rung means gpt-5.6 @ xhigh, which this switch deliberately does not touch. Turning it off also collapses the Phase 4 Claude Code reviewer panel from three to two (Reviewer 1 lands on opus, which Reviewer 2 already holds), and consensus.reviewerCount records 2."
+              "default": false,
+              "description": "Whether the fable rung is available at all on Claude Code. Ships OFF: the top rung is the most expensive thing a run can reach, and a cost control that is on by default is not a control. false makes every persona that declares preferredModel: fable dispatch on opus from the first call, with no dispatch attempt on fable and no error to recover from  -  a cost control, not a fallback. Claude Code only: Copilot CLI does not offer Fable 5, and on Codex CLI the fable rung means gpt-5.6 @ xhigh, which this switch deliberately does not touch. Turning it off also collapses the Phase 4 Claude Code reviewer panel from three to two (Reviewer 1 lands on opus, which Reviewer 2 already holds), and consensus.reviewerCount records 2."
             },
             "onDispatchError": {
               "type": "boolean",
@@ -1868,6 +1868,64 @@
               "description": "Recording cap. A flow needing longer is a debugging session, not a review artefact."
             }
           }
+        },
+        "issueTree": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "v16.29+  -  how /multi-agent:analysis-jira turns an analysis document into a Jira story tree. Every site-specific NAME lives in a free-form map value here, never as a schema key: a key is a published literal and this file ships to everyone, so a site's component, team and issue-type names must be values the site fills in. subtaskRoles ships EMPTY on purpose - an empty list is an instruction to go and look at how this board actually splits work, while a ready-made list would be the guess we most want to avoid. subtaskIssueType null means discover it: createmeta returns whichever type carries subtask:true, under whatever name the site gave it. Same rule as features/jira-context.md - the type travels as it comes from Jira and is never a matching criterion in code.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "projectKey": {
+              "type": ["string", "null"],
+              "default": null,
+              "description": "Where the tree is created. Null means ask at preview time."
+            },
+            "epicIssueType": {
+              "type": "string",
+              "default": "Epic"
+            },
+            "storyIssueType": {
+              "type": "string",
+              "default": "Story"
+            },
+            "subtaskIssueType": {
+              "type": ["string", "null"],
+              "default": null,
+              "description": "Null means discover from createmeta rather than assume a name."
+            },
+            "subtaskRoles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "The roles each story is split into. Ships empty: mine the board, do not guess."
+            },
+            "channelComponents": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "default": {},
+              "description": "channel -> this site's component name. Free-form: the key is the channel, the value is the site's own vocabulary."
+            },
+            "channelTeams": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "default": {},
+              "description": "channel -> this site's team name. Free-form, same reason."
+            },
+            "labelPrefix": {
+              "type": "string",
+              "default": "ma-analysis",
+              "description": "Prefix of the identity label a created issue carries. The label is how a second run, on a second machine or by a second analyst, finds the tree it already made instead of opening a duplicate."
+            }
+          }
         }
       }
     },

package/pipeline/scripts/analysis-story-tree.mjs

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+/**
+ * @file analysis-story-tree.mjs  -  an analysis document, read as a work breakdown.
+ *
+ * WHAT THIS IS
+ *
+ * It plans a Jira tree from a rendered analysis document and prints the plan.
+ * It never writes to Jira; `analysis-jira-write.sh` does that, from this output.
+ * The split is the point: planning is deterministic and testable with no network,
+ * and the thing that can create issues is small enough to read in one sitting.
+ *
+ * THE COVERAGE CHECK IS TWO-WAY, AND THE SECOND DIRECTION IS THE USEFUL ONE
+ *
+ * Forward: every atom in the document (`BR-<slug>-NN` globally, `FG-NN` in the
+ * corporate profile) appears in some story, or is listed as uncovered. That
+ * catches a dropped requirement.
+ *
+ * Backward: every id a story cites is actually defined in the document. That
+ * catches an INVENTED story - a node with no requirement behind it - which no
+ * forward check can see, and which is the failure mode of building a tree from a
+ * model's reading rather than from the document's own ids.
+ *
+ * AN UNVERIFIABLE RUN MUST NOT LOOK VERIFIED
+ *
+ * A lite global document may carry no `BR` ids at all. Then coverage cannot run,
+ * and the verdict is `unverifiable` - not `ok`. It gets its own line in the
+ * preview, its own approval option, and its own heading in any write-back. A run
+ * that could not be checked is allowed; one that looks checked when it was not
+ * is the defect.
+ *
+ * IDENTITY IS A LABEL, NOT A TITLE
+ *
+ * Each planned node carries a label derived from a fingerprint of the document
+ * id plus the node's source ids. A second run finds its own tree back through
+ * JQL on that label. Titles were the obvious key and are the wrong one: they get
+ * edited, and matching on them breaks exactly when someone has improved the
+ * wording. The label lives server-side, so it also works from a second machine,
+ * after `~/.claude` is deleted, and for a SECOND ANALYST - who is precisely the
+ * person positioned to open a duplicate tree.
+ *
+ * Usage:
+ *   analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]
+ *
+ * Exit: 0 planned, 2 nothing to plan, 3 usage, 4 the document is not issue-ready.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const argv = process.argv.slice(2);
+const JSON_OUT = argv.includes("--json");
+const prefsFlag = argv.indexOf("--prefs");
+const PREFS_PATH =
+  prefsFlag !== -1
+    ? argv[prefsFlag + 1]
+    : join(homedir(), ".claude", "multi-agent-preferences.json");
+const file = argv.find((a) => !a.startsWith("--") && a !== PREFS_PATH);
+
+function die(msg, code) {
+  process.stderr.write(`${msg}\n`);
+  process.exitCode = code;
+  return null;
+}
+
+const ATOM_GLOBAL = /\bBR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+\b/gi;
+const ATOM_CORP = /\bFG-\d{2,3}\b/g;
+const GROUP_CORP = /\bUC-\d{2,3}\b/g;
+
+function frontMatter(text) {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() !== "---") return {};
+  const end = lines.indexOf("---", 1);
+  if (end < 0) return {};
+  const fm = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^([a-z_]+):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return fm;
+}
+
+/** Headings with their bodies, so a story can be scoped to a section. */
+function sections(text) {
+  const out = [];
+  let cur = null;
+  for (const line of text.split("\n")) {
+    const h = line.match(/^(#{2,3})\s+(\d+(?:\.\d+)*)\.?\s+(.*)$/);
+    if (h) {
+      if (cur) out.push(cur);
+      cur = { number: h[2], title: h[3].trim(), body: [] };
+      continue;
+    }
+    if (cur) cur.body.push(line);
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/**
+ * The identity label. Derived from the document id, the node's own group and
+ * its source ids, so it is stable across re-runs and distinct per node - and it
+ * is NOT derived from the title, which is the thing people edit.
+ *
+ * The group is in the hash because the source ids alone are not an identity:
+ * two groups can legitimately cite the same atoms, and a shared label collapses
+ * both nodes onto one issue the next time the tree is searched by label.
+ */
+export function identityLabel(prefix, docId, sourceIds) {
+  const h = createHash("sha256")
+    .update(`${docId}${[...sourceIds].sort().join(",")}`)
+    .digest("hex")
+    .slice(0, 10);
+  return `${prefix}-${h}`;
+}
+
+/**
+ * The settings this file consumes, by their full `parent.leaf` path.
+ *
+ * Written out rather than destructured because a bare leaf (`enabled`,
+ * `projectKey`) is also an ordinary word: a reader cannot tell which settings a
+ * file actually reads, and neither can `smoke-prefs-consumed.sh`. Naming the
+ * path is what makes "declared" and "consumed" the same list.
+ *
+ *   issueTree.enabled            refuse to run when the site turned this off
+ *   issueTree.projectKey         where the tree is created
+ *   issueTree.epicIssueType      the type name for an epic on this site
+ *   issueTree.storyIssueType     the type name for a story
+ *   issueTree.subtaskIssueType   null = discover from createmeta
+ *   issueTree.subtaskRoles       how a story is split; ships empty on purpose
+ *   issueTree.channelComponents  channel -> this site's component name
+ *   issueTree.channelTeams       channel -> this site's team name
+ *   issueTree.labelPrefix        prefix of the identity label
+ */
+const ISSUE_TREE_SETTINGS = [
+  "issueTree.enabled",
+  "issueTree.projectKey",
+  "issueTree.epicIssueType",
+  "issueTree.storyIssueType",
+  "issueTree.subtaskIssueType",
+  "issueTree.subtaskRoles",
+  "issueTree.channelComponents",
+  "issueTree.channelTeams",
+  "issueTree.labelPrefix",
+];
+
+function readPrefs() {
+  try {
+    const j = JSON.parse(readFileSync(PREFS_PATH, "utf8"));
+    const g = j?.global || {};
+    const out = {};
+    for (const path of ISSUE_TREE_SETTINGS) {
+      const leaf = path.split(".")[1];
+      const v = g.issueTree?.[leaf];
+      if (v !== undefined) out[leaf] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** Every open placeholder that makes a document unfit to become work. */
+export function openItems(text) {
+  const found = [];
+  for (const [i, line] of text.split("\n").entries()) {
+    if (/\bEKLENECEK\b/.test(line)) found.push(`line ${i + 1}: EKLENECEK`);
+    else if (/\bTBD\b/.test(line)) found.push(`line ${i + 1}: TBD`);
+    else if (/^\s*\|/.test(line) && /(Açık \/ Open|Acik \/ Open|Girdi bekleniyor)/i.test(line))
+      found.push(`line ${i + 1}: an open Section 20 row`);
+  }
+  return found;
+}
+
+/**
+ * Coverage, in both directions, over a set of defined ids and a set of nodes.
+ *
+ * Extracted so the backward direction can be tested against ITS OWN code rather
+ * than against a re-implementation in a test. The planner cannot produce an
+ * invented id - it derives every `sourceIds` from `defined` - so a test that
+ * builds one by hand and re-checks it with hand-written logic proves nothing
+ * about this function. Calling this with a fabricated node does.
+ *
+ * The backward direction guards the boundary where a plan arrives from
+ * somewhere else: hand-edited, resumed from an older format, or written by
+ * something that read the document rather than its ids.
+ */
+export function coverageOf(defined, nodes, corporate = false) {
+  const covered = new Set(nodes.flatMap((n) => n.sourceIds || []));
+  const uncovered = [...defined].filter((id) => !covered.has(id)).sort();
+  const invented = [...covered].filter((id) => !defined.has(id)).sort();
+  let verdict;
+  if (defined.size === 0) {
+    // Nothing to check against. Saying "ok" here would be the lie this tool is
+    // built to avoid: no atoms means the check did not run, not that it passed.
+    verdict = "unverifiable";
+  } else if (uncovered.length || invented.length) {
+    verdict = "incomplete";
+  } else {
+    verdict = "ok";
+  }
+  return {
+    verdict,
+    atomsDefined: defined.size,
+    atomsCovered: covered.size,
+    uncovered,
+    invented,
+    reason:
+      verdict === "unverifiable"
+        ? `no ${corporate ? "FG-NN" : "BR-<slug>-NN"} ids in the document, so coverage could not be checked`
+        : null,
+  };
+}
+
+export function plan(text, prefs) {
+  const fm = frontMatter(text);
+  const profile = (fm.profile || "global").toLowerCase();
+  const corporate = profile === "corporate";
+  const secs = sections(text);
+
+  const atomRe = corporate ? ATOM_CORP : ATOM_GLOBAL;
+  const defined = new Set((text.match(atomRe) || []).map((x) => x.toUpperCase()));
+
+  // The document's own identity. `evidence_digest` is what changes when the
+  // evidence changes, which is exactly when a re-plan should produce new nodes.
+  const docId = fm.evidence_digest || fm.feature || "unidentified";
+  const prefix = prefs.labelPrefix || "ma-analysis";
+
+  const groups = corporate
+    ? [...new Set(text.match(GROUP_CORP) || [])].sort()
+    : [...new Set([...defined].map((id) => id.replace(/-\d+$/, "")))].sort();
+
+  // One story per group, scoped to the section that defines the most of its
+  // atoms. A story with no section is still a story - the atoms are the claim,
+  // the heading is only the label.
+  //
+  // A lite document may carry no ids at all, and its user-story sub-sections are
+  // still real work. Deriving from those keeps such a run useful AND makes
+  // `unverifiable` a state that actually occurs: without this fallback the
+  // no-atom document produced no stories, exited "nothing to plan", and the
+  // unverifiable branch below was unreachable - a case the code claimed to
+  // handle and never could.
+  //
+  // Corporate atoms are attributed ROW-WISE, never section-wise. The template
+  // states the mapping in a column - the functional-requirement table carries a
+  // source-UC cell, and the traceability matrix repeats the chain - so both of
+  // those sections necessarily name EVERY use case. Reading attribution from
+  // section containment therefore handed every group every atom: three stories
+  // with identical sources, identical titles, and, since the label hashes the
+  // sources, one identical label, which collapsed the whole tree onto a single
+  // issue on the second run while coverage still reported `ok`.
+  //
+  // No column name is hardcoded. An atom and a group sharing one table row IS
+  // the mapping, in whatever language the site writes its headers.
+  const rowAtoms = new Map();
+  if (corporate) {
+    for (const line of text.split("\n")) {
+      const gs = line.match(GROUP_CORP);
+      if (!gs) continue;
+      const as = line.match(ATOM_CORP);
+      if (!as) continue;
+      for (const g of new Set(gs)) {
+        if (!rowAtoms.has(g)) rowAtoms.set(g, new Set());
+        for (const a of as) rowAtoms.get(g).add(a.toUpperCase());
+      }
+    }
+  }
+
+  const stories = [];
+  for (const g of groups) {
+    let ids;
+    if (!corporate) {
+      ids = [...defined].filter((id) => id.startsWith(`${g}-`)).sort();
+    } else if (rowAtoms.has(g)) {
+      ids = [...rowAtoms.get(g)].sort();
+    } else {
+      // No row states this group's atoms. A document that lists them inside the
+      // use-case section instead is still readable; section containment is the
+      // fallback, not the rule.
+      ids = [
+        ...new Set(
+          secs
+            .filter((s) => s.body.join("\n").includes(g) || s.title.includes(g))
+            .flatMap((s) => s.body.join("\n").match(ATOM_CORP) || []),
+        ),
+      ].sort();
+    }
+    if (ids.length === 0) continue;
+    // The template titles a use-case section with the group's own id, so a title
+    // match is the accurate answer where one exists. The hit count is the
+    // fallback, and on a consolidated table it names the same section for every
+    // group - a cosmetic limit, since the title is a label and the group is the
+    // identity.
+    const titled = secs.find((s) => s.title.includes(g));
+    const best = titled
+      ? { s: titled, n: 1 }
+      : secs
+          .map((s) => ({
+            s,
+            n: ids.filter((id) => s.body.join("\n").toUpperCase().includes(id)).length,
+          }))
+          .sort((a, b) => b.n - a.n)[0];
+    stories.push({
+      kind: "story",
+      title: best && best.n > 0 ? `${best.s.number} ${best.s.title}` : g,
+      group: g,
+      sourceIds: ids,
+      label: identityLabel(prefix, docId, [g, ...ids]),
+      subtasks: (prefs.subtaskRoles || []).map((role) => ({
+        kind: "subtask",
+        role,
+        title: role,
+        sourceIds: ids,
+        label: identityLabel(prefix, docId, [g, ...ids, role]),
+      })),
+    });
+  }
+
+  if (stories.length === 0 && defined.size === 0) {
+    const storySections = secs.filter((sec) => /^4\.\d+$/.test(sec.number));
+    for (const sec of storySections) {
+      if (!sec.body.join("").trim()) continue;
+      stories.push({
+        kind: "story",
+        title: `${sec.number} ${sec.title}`,
+        group: sec.number,
+        sourceIds: [],
+        derivedFrom: "section",
+        label: identityLabel(prefix, docId, [sec.number]),
+        subtasks: (prefs.subtaskRoles || []).map((role) => ({
+          kind: "subtask",
+          role,
+          title: role,
+          sourceIds: [],
+          label: identityLabel(prefix, docId, [sec.number, role]),
+        })),
+      });
+    }
+  }
+
+  const coverage = coverageOf(defined, stories, corporate);
+
+  return {
+    document: {
+      id: docId,
+      profile,
+      mode: fm.mode || "full",
+      feature: fm.feature || null,
+    },
+    coverage,
+    prefsUsed: {
+      projectKey: prefs.projectKey ?? null,
+      epicIssueType: prefs.epicIssueType ?? "Epic",
+      storyIssueType: prefs.storyIssueType ?? "Story",
+      subtaskIssueType: prefs.subtaskIssueType ?? null,
+      subtaskRoles: prefs.subtaskRoles ?? [],
+      labelPrefix: prefix,
+      channelComponents: prefs.channelComponents ?? {},
+      channelTeams: prefs.channelTeams ?? {},
+    },
+    nodes: stories,
+    writeCount: stories.reduce((n, s) => n + 1 + s.subtasks.length, 0),
+  };
+}
+
+function main() {
+  if (!file) return die("usage: analysis-story-tree.mjs <analysis.md> [--json] [--prefs FILE]", 3);
+  if (!existsSync(file)) return die(`analysis-story-tree: no such file: ${file}`, 3);
+  const text = readFileSync(file, "utf8");
+
+  // The marker gate, before anything else and before any network call. A
+  // document with an open placeholder is not a plan, and turning it into a tree
+  // publishes the gap as work somebody is now assigned.
+  const open = openItems(text);
+  if (open.length) {
+    process.stderr.write(
+      `analysis-story-tree: the document is not issue-ready (${open.length} open item(s))\n`,
+    );
+    for (const m of open.slice(0, 5)) process.stderr.write(`  ${m}\n`);
+    process.stderr.write("  run /multi-agent:analysis-resolve to close them first\n");
+    process.exitCode = 4;
+    return;
+  }
+
+  const prefs = readPrefs();
+  // A declared setting that changes nothing is worse than no setting: it reads
+  // as a control and is not one.
+  if (prefs.enabled === false) {
+    process.stderr.write(
+      "analysis-story-tree: prefs.global.issueTree.enabled is false on this machine\n",
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const result = plan(text, prefs);
+  if (result.nodes.length === 0) {
+    process.stderr.write("analysis-story-tree: no stories could be derived from this document\n");
+    process.exitCode = 2;
+    return;
+  }
+
+  if (JSON_OUT) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  const c = result.coverage;
+  process.stdout.write(
+    `analysis: ${result.document.feature || result.document.id} (${result.document.profile}, ${result.document.mode})\n`,
+  );
+  // The verdict gets its own line whatever it is. A reader scanning a preview
+  // sees "unverifiable" in the same place they would have seen "ok".
+  process.stdout.write(
+    `coverage: ${c.verdict}${c.reason ? `  -  ${c.reason}` : ` (${c.atomsCovered}/${c.atomsDefined} atoms)`}\n`,
+  );
+  if (c.uncovered.length) process.stdout.write(`  not in any story: ${c.uncovered.join(", ")}\n`);
+  if (c.invented.length) process.stdout.write(`  cited but undefined: ${c.invented.join(", ")}\n`);
+  process.stdout.write(`\n${result.writeCount} issue(s) would be created:\n`);
+  for (const s of result.nodes) {
+    process.stdout.write(`  ${result.prefsUsed.storyIssueType}  ${s.title}\n`);
+    process.stdout.write(
+      `      sources: ${s.sourceIds.length ? s.sourceIds.join(", ") : "(none - derived from the section heading)"}\n`,
+    );
+    process.stdout.write(`      label:   ${s.label}\n`);
+    for (const t of s.subtasks) {
+      process.stdout.write(`      subtask  ${t.role}  [${t.label}]\n`);
+    }
+  }
+  // Every field's provenance, so a wrong setting is visible here rather than in
+  // Jira after the writes have happened.
+  process.stdout.write("\nfrom prefs.global.issueTree:\n");
+  for (const [k, v] of Object.entries(result.prefsUsed)) {
+    const shown = typeof v === "object" ? JSON.stringify(v) : String(v);
+    process.stdout.write(`  ${k.padEnd(20)} ${shown === "null" ? "(not set)" : shown}\n`);
+  }
+}
+
+const isDirectRun = process.argv[1] && process.argv[1].endsWith("analysis-story-tree.mjs");
+if (isDirectRun) main();