@mmerterden/multi-agent-pipeline 20.12.0 → 20.13.0

package/pipeline/scripts/confluence-readback.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * confluence-readback.mjs  -  verify a published analysis page by reading it back.
+ *
+ * The publisher reports what it sent; this reads what the page holds. Every
+ * heading of the markdown must be on the page, and every local image the
+ * markdown embeds must be attached to it. A mismatch is reported, never retried:
+ * whether to republish is the caller's decision.
+ *
+ * Auth follows md2confluence-v3.py: CONFLUENCE_BASE_URL, and the token from the
+ * credential store under prefs .global.keychainMapping.confluence, else
+ * CONFLUENCE_TOKEN. The token travels only in the Authorization header.
+ *
+ * Usage:
+ *   confluence-readback.mjs --page-id ID --markdown FILE
+ *
+ * Prints a JSON report. Exit: 0 match, 1 mismatch, 2 usage or auth, 5 a call failed.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { runMain } from "../lib/fatal.mjs";
+
+function arg(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function resolveToken() {
+  const home = homedir();
+  const store = join(home, ".claude", "lib", "credential-store.sh");
+  const prefsPath = join(home, ".claude", "multi-agent-preferences.json");
+  if (existsSync(store) && existsSync(prefsPath)) {
+    try {
+      const key = JSON.parse(readFileSync(prefsPath, "utf8"))?.global?.keychainMapping?.confluence;
+      if (key) {
+        const r = spawnSync("bash", [store, "get", key], { encoding: "utf8" });
+        const token = (r.stdout || "").trim();
+        if (r.status === 0 && token) return token;
+      }
+    } catch {
+      // fall through to the environment
+    }
+  }
+  return process.env.CONFLUENCE_TOKEN || null;
+}
+
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+const decode = (s) =>
+  s
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&([a-z]+);/gi, (m, e) => ENTITIES[e.toLowerCase()] ?? m);
+const norm = (s) => s.replace(/\s+/g, " ").trim();
+
+/** Heading texts of the markdown, outside fenced code. */
+export function markdownHeadings(md) {
+  const out = [];
+  let fenced = false;
+  for (const line of md.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
+    if (fenced) continue;
+    const m = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (!m) continue;
+    const text = norm(
+      m[1]
+        .replace(/<!--.*?-->/g, "")
+        .replace(/[*_`]/g, "")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1"),
+    );
+    if (text) out.push(text);
+  }
+  return out;
+}
+
+/** File names of the local images the markdown embeds. */
+export function markdownImages(md) {
+  const names = new Set();
+  for (const m of md.matchAll(/!\[[^\]]*\]\(([^)\s]+)[^)]*\)/g)) {
+    if (!/^[a-z]+:\/\//i.test(m[1])) names.add(basename(m[1]));
+  }
+  return [...names];
+}
+
+/** Heading texts of a storage-format body. */
+export function pageHeadings(storage) {
+  return [...storage.matchAll(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi)].map((m) =>
+    norm(decode(m[2].replace(/<[^>]+>/g, ""))),
+  );
+}
+
+async function getJson(base, token, path) {
+  const res = await fetch(`${base}${path}`, {
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+  });
+  if (!res.ok) throw new Error(`GET ${path} -> ${res.status}`);
+  return res.json();
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const pageId = arg(argv, "--page-id");
+  const mdPath = arg(argv, "--markdown");
+  if (!pageId || !mdPath || !existsSync(mdPath)) {
+    process.stderr.write("usage: confluence-readback.mjs --page-id ID --markdown FILE\n");
+    process.exitCode = 2;
+    return;
+  }
+  const base = (process.env.CONFLUENCE_BASE_URL || "").replace(/\/+$/, "");
+  const token = resolveToken();
+  if (!base || !token) {
+    process.stderr.write(
+      "ERR: CONFLUENCE_BASE_URL and a Confluence token (credential store or CONFLUENCE_TOKEN) are required\n",
+    );
+    process.exitCode = 2;
+    return;
+  }
+  const md = readFileSync(mdPath, "utf8");
+  const id = encodeURIComponent(pageId);
+  let content;
+  let attachments;
+  try {
+    content = await getJson(base, token, `/rest/api/content/${id}?expand=body.storage,version`);
+    attachments = await getJson(base, token, `/rest/api/content/${id}/child/attachment?limit=500`);
+  } catch (err) {
+    process.stderr.write(`ERR: ${err.message}\n`);
+    process.exitCode = 5;
+    return;
+  }
+  const onPage = new Set(pageHeadings(content?.body?.storage?.value || ""));
+  const attached = new Set((attachments?.results || []).map((a) => a.title));
+  const missingHeadings = markdownHeadings(md).filter((h) => !onPage.has(h));
+  const missingAttachments = markdownImages(md).filter((n) => !attached.has(n));
+  const ok = missingHeadings.length === 0 && missingAttachments.length === 0;
+  process.stdout.write(
+    `${JSON.stringify({
+      ok,
+      pageId,
+      version: content?.version?.number ?? null,
+      missingHeadings,
+      missingAttachments,
+    })}\n`,
+  );
+  if (!ok) process.exitCode = 1;
+}
+
+runMain("confluence-readback", main);

package/pipeline/scripts/jira-wiki-escape.mjs

@@ -72,6 +72,46 @@ export function findUnescaped(text) {
   return hits;
 }
 
+// Every character that opens wiki markup: macros {..}, links and mentions [..],
+// table cells |, images !..!, and inline formatting * _ ^ ~ + - #.
+const MARKUP = /[\\{}[\]|!*_^~+\-#]/g;
+
+/**
+ * Escape plain text taken from a document so Jira renders it literally. The
+ * generator writes its own markup around the result; nothing inside the result
+ * can open a macro, a mention, an image, a link or formatting.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeJiraWiki(text) {
+  const escaped = String(text ?? "")
+    .replace(MARKUP, (c) => `\\${c}`)
+    .replace(/^(h[1-6]|bq)\./gm, "$1\\.");
+  return escapeJiraEmoticons(escaped);
+}
+
+/**
+ * A wiki link to an http(s) URL, or the escaped label alone for any other
+ * scheme. The URL is percent-encoded where a character would end the link.
+ *
+ * @param {string} label
+ * @param {string} url
+ * @returns {string}
+ */
+export function wikiLink(label, url) {
+  const text = escapeJiraWiki(label);
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return text;
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return text;
+  const safe = u.href.replace(/[|[\]{}!\s]/g, (c) => encodeURIComponent(c));
+  return `[${text}|${safe}]`;
+}
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);

package/pipeline/scripts/validate-analysis-doc.mjs

@@ -42,6 +42,15 @@
 
 import { readFileSync } from "node:fs";
 import { runMain } from "../lib/fatal.mjs";
+import { redesignSections, sectionBody, tableDataRows } from "../lib/analysis-sections.mjs";
+import {
+  businessLayerTechnical,
+  citedUndefined,
+  designFrameUnmapped,
+  exceptionFlow,
+  missingInputsFinal,
+  scopeOverlap,
+} from "../lib/analysis-quality.mjs";
 
 // A repo-less run (Locked 34) still splits by channel, derived from the evidence:
 // "mobile" and "web" are its platform values. "none" is the narrower case where the
@@ -51,7 +60,7 @@ const KNOWN_PLATFORMS = new Set(["ios", "android", "web", "backend", "mobile", "
 const REQUIRED_FM = ["feature", "platform", "language", "mode", "template_version"];
 
 // Never-omitted sections (Locked 2), matched by bilingual title keyword so the
-// re-flowed section numbering does not matter.
+// profile's own numbering does not matter.
 const REQUIRED_SECTIONS = [
   { key: "summary", any: ["Summary", "Özet", "Ozet"] },
   { key: "goals", any: ["Goals", "Hedefler"] },
@@ -108,6 +117,43 @@ const BANNED_PUNCT = [
 // that blocked a correctly closed document. English has the same trap in
 // "reopened" and "opened".
 const OPEN_STATUS = ["açık", "acik", "open", "girdi bekleniyor", "pending input"];
+// Words that make a requirement untestable because they carry no threshold.
+// Matched as whole words in either language, case-insensitively.
+const VAGUE_WORDS = [
+  "appropriate",
+  "appropriately",
+  "as needed",
+  "as appropriate",
+  "user-friendly",
+  "fast",
+  "quickly",
+  "etc.",
+  "and/or",
+  "various",
+  "if possible",
+  "reasonable",
+  "uygun şekilde",
+  "gerektiğinde",
+  "gerekirse",
+  "hızlı",
+  "hızlıca",
+  "vb.",
+  "vs.",
+  "çeşitli",
+  "mümkünse",
+  "kullanıcı dostu",
+  "makul",
+];
+
+function vagueWords(text) {
+  const found = [];
+  for (const w of VAGUE_WORDS) {
+    const esc = w.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    if (new RegExp(`(?<![\\p{L}\\p{N}])${esc}(?![\\p{L}\\p{N}])`, "iu").test(text)) found.push(w);
+  }
+  return found;
+}
+
 function isOpenStatus(cell) {
   return String(cell)
     .split("/")
@@ -141,51 +187,6 @@ function parseFrontMatter(text) {
   return { fm, bodyStart: end + 1 };
 }
 
-function sectionBody(lines, keywords, level = 2) {
-  // Opened by a heading at exactly `level`; closed by the next heading at that
-  // level OR ANY SHALLOWER one. A sub-section that is the last of its parent has
-  // no sibling after it, so terminating only on equal depth runs the body into
-  // the following section and audits its rows as if they belonged here.
-  const open = new RegExp(`^#{${level}}\\s+\\d+(\\.\\d+)*\\.?\\s`);
-  const close = new RegExp(`^#{1,${level}}\\s`);
-  let start = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (open.test(lines[i]) && keywords.some((k) => lines[i].includes(k))) {
-      start = i;
-      break;
-    }
-  }
-  if (start < 0) return null;
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (close.test(lines[i])) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start + 1, end);
-}
-
-// Data rows are the pipe-rows that follow a table's separator row, which is the
-// only shape that distinguishes them from the header without guessing at cell text.
-function tableDataRows(bodyLines) {
-  const rows = [];
-  let afterSeparator = false;
-  for (const line of bodyLines) {
-    const t = line.trim();
-    if (!t.startsWith("|")) {
-      afterSeparator = false;
-      continue;
-    }
-    if (/^\|[\s\-:|]+\|$/.test(t)) {
-      afterSeparator = true;
-      continue;
-    }
-    if (afterSeparator) rows.push(t);
-  }
-  return rows;
-}
-
 // The report registry. `--report` prints one line per check, and the reason a
 // check did not run is part of the answer: the traceability matrix is corporate
 // only, so on a global document it never executes - and until this existed the
@@ -763,29 +764,42 @@ function main() {
 
   mark("rule-to-test");
 
+  // 2g-2. Vague wording. A requirement two readers can pass differently is not
+  // testable, and these words carry no threshold. Only id-bearing requirement
+  // rows are read; summary prose may speak loosely. Code spans are skipped.
+  {
+    const ROW_ID = /\b(BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+|IG-\d{2,3}|FG-\d{2,3})\b/i;
+    for (const line of allLines) {
+      const t = line.trim();
+      if (!t.startsWith("|")) continue;
+      const id = t.match(ROW_ID);
+      if (!id) continue;
+      const words = vagueWords(t.replace(/`[^`]*`/g, ""));
+      if (words.length) {
+        warns.push(
+          `vague wording in ${id[1]}: ${words.map((w) => `"${w}"`).join(", ")} - state a threshold, a list or a condition instead`,
+        );
+      }
+    }
+    mark("vague-wording");
+  }
+
   // 2h. Redesign mode (Locked 36). Eight checks, live only when the front-matter
   // opts in. The contract they enforce is analysis/redesign.md, which loads only
   // on a redesign run; what is here is the enforcement, not the explanation.
   const redesign = String(parsed?.fm?.redesign || "false").toLowerCase() === "true";
-  const cbBody = sectionBody(
-    allLines,
-    ["Mevcut Davranış", "Mevcut Davranis", "Current Behaviour", "Current Behavior"],
-    3,
-  );
-  const epBody = sectionBody(
-    allLines,
-    ["Endpoint Eşlemesi", "Endpoint Eslemesi", "Endpoint Mapping"],
-    3,
-  );
-  const dlBody = sectionBody(allLines, ["Fark Listesi", "Difference List"], 3);
+  const rd = redesignSections(allLines, profile);
+  const cbBody = rd.cb.body;
+  const epBody = rd.ep.body;
+  const dlBody = rd.dl.body;
   if (redesign) {
     // 1. The sections themselves. Without this every row check below passes over
     // nothing, which is the specific defect that shows a gate green on an empty
     // document - the same shape the corporate matrix check guards against.
     for (const [body, name] of [
-      [cbBody, "4.5 Current Behaviour"],
-      [epBody, "4.6 Endpoint Mapping"],
-      [dlBody, "9.5 Difference List"],
+      [cbBody, rd.cb.label],
+      [epBody, rd.ep.label],
+      [dlBody, rd.dl.label],
     ]) {
       if (!body) errors.push(`redesign: true but Section ${name} is missing (Locked 36)`);
     }
@@ -866,7 +880,7 @@ function main() {
       const cellCount = (line) =>
         line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").length;
       if (!header) {
-        errors.push("Section 4.6 has no v1/v2 header row (Locked 36)");
+        errors.push(`Section ${rd.ep.label} has no v1/v2 header row (Locked 36)`);
       } else {
         const cols = cellCount(header);
         for (const row of tableDataRows(epBody)) {
@@ -883,8 +897,8 @@ function main() {
     //
     // The heading match alone is not enough to say that. sectionBody tests the
     // keyword as a raw substring of the heading line - deliberately, since Locked
-    // 2 re-flows section numbers and the corporate profile numbers them
-    // differently - so an unrelated `### 4.9 Notes on the old Current Behaviour
+    // 2 drops sections and the corporate profile numbers them differently - so
+    // an unrelated `### 4.9 Notes on the old Current Behaviour
     // audit process` matched, and Phase 3 runs --strict, which turns this warning
     // into a blocked document. The artefact itself is the honest signal: a
     // rendered current-behaviour table always carries `CB-<slug>-NN` ids, and a
@@ -900,6 +914,43 @@ function main() {
     mark("redesign-artifacts", "not a redesign");
   }
 
+  // 2e. Document quality (analysis-quality.mjs): each check returns its own
+  // errors and warnings, so it is testable without this file.
+  {
+    const isFinal = (parsed?.fm?.status || "draft").toLowerCase() === "final";
+    const corporate = profile === "corporate";
+    const run = (id, check, skipped) => {
+      if (!skipped) {
+        const r = check();
+        errors.push(...r.errors);
+        warns.push(...r.warns);
+      }
+      mark(id, skipped);
+    };
+    run(
+      "exception-flow",
+      () => exceptionFlow(allLines, { final: isFinal }),
+      corporate ? undefined : "global profile",
+    );
+    run("scope-overlap", () => scopeOverlap(allLines));
+    run("cited-undefined", () => citedUndefined(allLines));
+    run(
+      "design-frame-unmapped",
+      () => designFrameUnmapped(allLines),
+      corporate ? undefined : "global profile",
+    );
+    run(
+      "business-layer-technical",
+      () => businessLayerTechnical(allLines),
+      corporate ? "corporate profile" : undefined,
+    );
+    run(
+      "missing-inputs",
+      () => missingInputsFinal(allLines, { final: isFinal }),
+      isFinal ? undefined : "draft document",
+    );
+  }
+
   // 3. Humanizer punctuation. Scope mirrors the humanizer pass exactly
   // (analysis/render.md): front-matter, fenced code blocks, table rows and
   // URLs are exempt there, so flagging them here would raise an ERROR that no
@@ -937,11 +988,10 @@ function main() {
 
   // 4b. Locked 2's numbering half.
   //
-  // It is NOT "numbering re-flows 1..N", which could not hold: Locked 30
-  // threads ids across the document by section
-  // NUMBER ("Section 15.1 scenario", "Section 4.4", "Section 3/5 layout cells"),
-  // so a re-flowed document sends every one of those references to the wrong
-  // section. No emitted document ever re-flowed. The rule was the wrong half.
+  // Rendered sections keep their canonical template numbers and may leave
+  // gaps, because Locked 30 threads ids across the document by section NUMBER
+  // ("Section 15.1 scenario", "Section 4.4", "Section 3/5 layout cells"), and
+  // renumbering would send every one of those references to the wrong section.
   //
   // What holds instead: a rendered section keeps its canonical template number,
   // so gaps are correct and `1, 2, 4, 9, 13, 14, 21` is a valid document. Two
@@ -1018,8 +1068,8 @@ function main() {
   // audited - "used subset" means nothing without the set it is a subset of.
   let inVariant = false;
   for (const line of text.split("\n")) {
-    // Keyed on the heading text, not the number: Locked 2 re-flows numbering, so
-    // a literal "6.X" match silently stops running the moment the section moves.
+    // Keyed on the heading text, not the number: the corporate profile numbers
+    // this section differently, so a literal "6.X" match would skip it there.
     if (/^#{2,3}\s+\d+(\.[0-9X]+)*\.?\s/.test(line) && /Varyant|Variant/i.test(line)) {
       inVariant = true;
       continue;

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-29T13:31:43Z",
+  "generatedAt": "2026-10-01T20:47:44Z",
   "skillCount": 218,
   "entries": [
     {
@@ -13,7 +13,7 @@
     },
     {
       "path": "shared/core/multi-agent-analysis-jira/SKILL.md",
-      "sha256": "8c5916a32156bc4c75f97cac1b57dbfe9e49f16027178128d12e50f6e326ae12"
+      "sha256": "130543d1017115de351a1175b6b179778642ba0b3207034b54114b39d0546407"
     },
     {
       "path": "shared/core/multi-agent-analysis-resolve/SKILL.md",
@@ -21,7 +21,7 @@
     },
     {
       "path": "shared/core/multi-agent-analysis/SKILL.md",
-      "sha256": "fff7f2c2d4aa769a5c08beb776a848f91caf485c1d84dd5a4a3571ff02c35e0e"
+      "sha256": "a7cf677df00433583d5e2e1578223d1e1797a1bd4d07ff0d1d8596d94baa013a"
     },
     {
       "path": "shared/core/multi-agent-autopilot-off/SKILL.md",
@@ -37,7 +37,7 @@
     },
     {
       "path": "shared/core/multi-agent-autopilot/SKILL.md",
-      "sha256": "426158ddbb5e8d6e594cd2e02aceb197e1769d692602dfbd2a368a6707081bd3"
+      "sha256": "a9731771fbc1f45260f214f069b976eff16e7b25e2f1375b0d9a213575271bc6"
     },
     {
       "path": "shared/core/multi-agent-build-optimize/SKILL.md",
@@ -65,7 +65,7 @@
     },
     {
       "path": "shared/core/multi-agent-doctor/SKILL.md",
-      "sha256": "1b1450ead2c6ee6ff64a8cfd4fcefeba1084a46f2a2e5d8a8a1077b7ec3f4130"
+      "sha256": "2f6222cdef9c6b2b4e2e330ba0acee33ab0fb797029bb16c50bbb244be5fcbe6"
     },
     {
       "path": "shared/core/multi-agent-feedback/SKILL.md",
@@ -145,7 +145,7 @@
     },
     {
       "path": "shared/core/multi-agent-review-analysis/SKILL.md",
-      "sha256": "f55d3b28266001d150d0438e92f8bb5dfa9cdce517892cf12fe94beee8440c07"
+      "sha256": "5f90d2da227e1ffb7fedd00c3a0d094bb0e0e32a26aa25a7ec503ff6e4865503"
     },
     {
       "path": "shared/core/multi-agent-review-issue/SKILL.md",
@@ -157,7 +157,7 @@
     },
     {
       "path": "shared/core/multi-agent-review/SKILL.md",
-      "sha256": "23b38684ac14c65522ff3f1889ae2f8bab89f10a62db1d7f01f6b46228136157"
+      "sha256": "f1bad66314a55f35b7ac056a2f97e44c30702bebfbacc886b8efe7887eec5685"
     },
     {
       "path": "shared/core/multi-agent-route-off/SKILL.md",
@@ -201,7 +201,7 @@
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "f73388e0a64ba8a1606e3364441b078f3df6f7e99e589fb9bc8b93269a2733b2"
+      "sha256": "38fdbe979ab2da87dcee55d1ce988cbda5bab92f5f751f448e2e64b18113c50e"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",

package/pipeline/skills/shared/core/multi-agent-analysis/SKILL.md

@@ -15,6 +15,11 @@ Produces a stakeholder-ready, platform-agnostic feature-spec document set (one m
 
 > **Language**: Per `refs/rules.md` Language Application matrix - instruction prose stays English. `AskUserQuestion.question`, `.options[].label` and `.options[].description` follow `outputLanguage`; only `header` stays English (<=12-char chip). The emitted document body follows `outputLanguage` (`tr` or `en`).
 
+## Gotchas
+
+- Design is fetched only inside this command (Locked 29). A variant missing from the document is added by re-running analysis, never by a later phase.
+- `status: final` fails the validator while any `AS-NN` is still open; publish drafts as `draft`.
+
 ## When to use
 
 - Before kicking off a new feature: design + API + business rules + architecture plan + test strategy crystallized into one per-platform document set
@@ -40,7 +45,7 @@ One run emits one profile. A missing input never blocks either: the gap is writt
 
 The template has 23 main sections plus footer (Glossary, Changelog). The rendered set is chosen from evidence by the omission table (Locked 2), not by a mode: a section with no evidence drops, and 19 Alternatives, 22 Glossary and 18 Rollout are default-drop.
 
-**Section omission**: zero-evidence sections are dropped entirely (no "TBD" placeholder); numbering re-flows to stay sequential. Sections 1, 2, 4, 9, 13, 14, 20, 21 are never omitted.
+**Section omission**: zero-evidence sections are dropped entirely (no "TBD" placeholder); a rendered section keeps its canonical template number, so the rendered set has gaps. Sections 1, 2, 4, 9, 13, 14, 20, 21 are never omitted.
 
 **Two-pass render**: Pass A computes the shared logical content once; Pass B projects it onto each selected platform using conventions extracted from the repos (Phase 1c, seven pattern groups with confidence levels). Every projected cell carries an evidence footnote. A convention preview gate lets the user approve or override cells before any file renders.
 

package/pipeline/skills/shared/core/multi-agent-analysis-jira/SKILL.md

@@ -2,7 +2,7 @@
 name: multi-agent-analysis-jira
 description: "Turn a rendered analysis document into a Jira story tree: derive stories from the document's own rule ids, check coverage both ways, preview every byte, then create only what does not already exist. Use when an analysis is final and the work needs tickets."
 user-invocable: true
-argument-hint: "[analysis.md] [--project KEY]  -  optional; with no argument, pick from the documents this run emitted"
+argument-hint: "[analysis.md] [--project KEY] [--epic KEY]  -  optional; with no argument, pick from the documents this run emitted"
 metadata:
   language: en
   not-for: create-jira, jira
@@ -18,13 +18,26 @@ invents a story: every node comes from an id the document defines.
 Contract, severities and reasoning:
 `$HOME/.claude/multi-agent-refs/features/analysis-jira.md`.
 
+## Gotchas
+
+- An issue whose label already exists is skipped, never updated. Editing the document and re-running creates only what is missing; existing tickets keep their old text.
+- A document with no `BR-`/`FG-` ids still plans, from its `4.N` sub-sections, but its coverage verdict is `unverifiable`: there is nothing to check the tree against.
+- An open `EKLENECEK`/`TBD` marker or an open Section 20 row stops planning with exit 4. Resolve them with `/multi-agent-analysis-resolve` first.
+- The epic must already exist: stories are linked to it, never an epic created. On Server/Data Center the Epic Link field is discovered from the site; when none is found the stories are created unlinked and the writer says so.
+- Channel clones (`issueTree.cloneByChannel`) carry their own labels and are searched like stories, so a re-run never doubles them or their links.
+- Story bodies hold only document text. A body warning (no user story, fewer than 2 criteria, no negative criterion) is a gap in the document; fix the document, not the ticket.
+
 ## Phase 1 - Plan, offline
 
 ```bash
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json > /tmp/ma-plan.json
-node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>"
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json $PAGE > /tmp/ma-plan.json
+node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" $PAGE
 ```
 
+`$PAGE` is `--page-url <url>` when the document was published (the run's
+`outputs.confluencePages[]`); without it the front-matter `confluence_url` is
+used, and with neither the story bodies carry no analysis link.
+
 Exit 4 means the document still carries an open placeholder. Stop and report it:
 the step is `/multi-agent:analysis-resolve`, and a tree built from an open
 question publishes the gap as work somebody is now assigned.
@@ -48,12 +61,19 @@ what makes a preview meaningful:
 - every field beside the pref key it came from, so a wrong setting shows here
   rather than in Jira afterwards
 - the write count
+- every story's full description, as it will be written, with its body
+  warnings; `--brief` gives the one-line-per-node view
+
+Then ask for the epic, once. `AskUserQuestion`:
+
+- **Link to an existing epic** - the user types its key (`--epic <KEY>`)
+- **No epic** - the stories are created unlinked
 
 Then the dry run, which is what proves the writer agrees with the plan:
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>" --dry-run
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"] --dry-run
 ```
 
 ## Phase 3 - Approve
@@ -79,11 +99,14 @@ be reachable.
 invented id means the plan cites something the document does not define - treat
 that as a defect in the plan, not a warning to click past.
 
+Body warnings are printed before the question too. They do not block: the
+ticket says only what the document says, and the warning names the gap.
+
 ## Phase 4 - Write
 
 ```bash
 bash "$HOME/.claude/lib/analysis-jira-write.sh" \
-  --plan /tmp/ma-plan.json --project "<KEY>"
+  --plan /tmp/ma-plan.json --project "<KEY>" [--epic "<EPIC>"]
 ```
 
 It searches by label first and skips what exists. Re-running is safe and is the
@@ -93,9 +116,36 @@ findable rather than duplicable.
 **Never pass `--force`-like flags, and never update an existing node.** Jira has
 no backup path for fields other than description.
 
+### Write the tickets back
+
+The document lists what it produced. Local and idempotent: the table sits
+between `<!-- tickets:start -->` and `<!-- tickets:end -->`, a re-run replaces
+it, and only nodes with a key appear.
+
+```bash
+LEDGER="$HOME/.claude/logs/multi-agent/_analysis-jira/$(jq -r '.document.id // "unidentified"' /tmp/ma-plan.json).jsonl"
+node "$HOME/.claude/scripts/analysis-tickets-writeback.mjs" \
+  --doc "<analysis.md>" --ledger "$LEDGER" --plan /tmp/ma-plan.json
+```
+
+When the document has a Confluence page, updating it is a **separate**
+`AskUserQuestion`, never part of the tree approval:
+
+- **Update the Confluence page** - publish the document with its new table
+- **Keep it local** - the page stays as it is
+
+```bash
+python3 "$HOME/.claude/lib/md2confluence-v3.py" update \
+  --page-id "<pageId>" --title "<page title>" \
+  --markdown "<analysis.md>" --attachments-dir "$(dirname "<analysis.md>")"
+```
+
+Read its JSON envelope as the analysis render step does, and surface any
+missing-attachment warning.
+
 ## Phase 5 - Report
 
-Keys created, keys skipped, the coverage verdict, and the ledger path. If the
+Keys created, keys skipped, the epic linked (or none), the coverage verdict, and the ledger path. If the
 verdict was `unverifiable`, say that in the report too - not only at approval
 time, because the report is what gets pasted elsewhere.
 

package/pipeline/skills/shared/core/multi-agent-autopilot/SKILL.md

@@ -13,6 +13,12 @@ metadata:
 
 Run the task end-to-end with no confirmations.
 
+## Gotchas
+
+- The guard decides within a 5-second internal deadline and fails closed when unattended. On a heavily loaded machine a correct command can be refused for time, not for policy.
+- An unattended run never pushes or opens a PR itself: it records the request in `pr-request.json` and the runner publishes it.
+- An unattended run cannot run `/multi-agent-stack` or write `.claude/` in the repo; a missing stack toolkit is read from a local marketplace clone instead.
+
 ## What changes
 
 | Phase | Normal | Autopilot |